RestartSubscriber Class Reference

Replaces a CHARMM-style restart file with the latest simulation state. More...

#include <RestartSubscriber.h>

Inheritance diagram for RestartSubscriber:

Public Member Functions
	RestartSubscriber (void)
	Constructs an unattached restart writer without an output file.
	RestartSubscriber (const std::filesystem::path &filePath)
	Constructs a restart writer with the default reporting interval.
	RestartSubscriber (const std::filesystem::path &filePath, const int reportFrequency)
	Constructs a restart writer with an explicit reporting interval.
	~RestartSubscriber (void) noexcept override=default
	Destroys the writer and closes its stream.
void	update (void) override
	Replaces the output with one restart snapshot.
Public Member Functions inherited from Subscriber
	Subscriber (void)
	Constructs an unattached subscriber with no output file.
	Subscriber (const std::filesystem::path &filePath)
	Constructs a subscriber and opens a text output file.
	Subscriber (const std::filesystem::path &filePath, const int reportFrequency)
	Constructs a subscriber with an explicit reporting interval.
virtual	~Subscriber (void) noexcept=default
	Destroys the stream and releases retained collaborators.
void	setReportFrequency (const int reportFrequency)
	Sets the number of propagated steps between scheduled updates.
void	setFilePath (const std::filesystem::path &filePath)
	Sets the logical output-file path without reopening the stream.
void	setCharmmContext (std::shared_ptr< CharmmContext > ctx)
	Retains the context exposed to subscriber implementations.
void	setIntegrator (std::shared_ptr< CudaIntegrator > integrator)
	Retains the integrator exposed to subscriber implementations.
int	getReportFrequency (void) const
	Returns the configured reporting interval.
const std::filesystem::path &	getFilePath (void) const
	Returns the logical output-file path.
std::filesystem::path &	getFilePath (void)
	Returns mutable access to the logical output-file path.
void	checkPath (const std::filesystem::path &filePath)
	Checks whether the parent portion of an output path exists.
virtual void	openFile (void)
	Opens the stored path as a truncating text output stream.
void	addCommentSection (const std::string &commentLines)
	Appends and flushes one newline-terminated comment section.

Additional Inherited Members
Protected Attributes inherited from Subscriber
int	m_ReportFrequency
	Stores the positive, dimensionless reporting interval.
std::filesystem::path	m_FilePath
	Stores the logical output path owned by the subscriber.
std::fstream	m_FileStream
	Owns the host file stream used by concrete reporters.
std::shared_ptr< CharmmContext >	m_CharmmContext
	Retains the context queried by concrete subscriber updates.
std::shared_ptr< CudaIntegrator >	m_Integrator
	Retains the integrator queried by concrete subscriber updates.

Detailed Description

Replaces a CHARMM-style restart file with the latest simulation state.

Each successful update writes version-50 text containing periodic-box state, integrator counters and random state, energy/statistics placeholders, double-precision coordinates, velocities, and the integrator's previous coordinate-delta state. The file is intended for CudaIntegrator::initializeFromRestartFile() on supported integrators.

Box lengths and coordinates use angstroms. Context velocities use angstroms per AKMA time unit. Average temperature uses kelvin. Arrays are written in atom order with X, Y, and Z components on each line. Several CHARMM energy and statistics fields are currently emitted as zeros.

Updating transfers all required CUDA containers to host memory. Each transfer synchronizes all previously requested work on the current CUDA device; no subscriber-specific stream is used.

Warning

Updates support only CudaNoseHooverIntegrator, CudaLangevinPistonIntegrator, and CudaLangevinThermostatIntegrator.

Each update truncates the target before all sections are generated. A later failure can destroy a previously usable restart and leave a partial replacement.

See also

Subscriber

subscriber

Constructor & Destructor Documentation

RestartSubscriber() [1/3]

RestartSubscriber::RestartSubscriber

(

void

)

Constructs an unattached restart writer without an output file.

Postcondition

The report frequency is 1000, the logical file path is empty, and the stream is closed.

RestartSubscriber() [2/3]

RestartSubscriber::RestartSubscriber

(

const std::filesystem::path &

filePath

)

Constructs a restart writer with the default reporting interval.

Construction creates or truncates the text output immediately. A complete restart is not written until update is invoked.

Parameters

[in]

filePath

Output file-system path copied by the subscriber. The value must be nonempty; when it has a nonempty parent path, that parent path must exist.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if filePath is empty or its checked parent path does not exist.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the text output file cannot be opened for writing.

Postcondition

The file has been created or truncated and getReportFrequency() == 1000.

RestartSubscriber() [3/3]

RestartSubscriber::RestartSubscriber	(	const std::filesystem::path &	filePath,
		const int	reportFrequency
	)

Constructs a restart writer with an explicit reporting interval.

Construction validates the frequency, then creates or truncates the text output. A complete restart is not written until update is invoked.

Parameters

[in]	filePath	Output file-system path copied by the subscriber. The value must be nonempty; when it has a nonempty parent path, that parent path must exist.
[in]	reportFrequency	Positive, dimensionless number of propagated steps between restart replacements.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if reportFrequency is not positive, filePath is empty, or its checked parent path does not exist.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the text output file cannot be opened for writing.

Postcondition

The file has been created or truncated and getReportFrequency() == reportFrequency.

~RestartSubscriber()

RestartSubscriber::~RestartSubscriber ( void  )

overridedefaultnoexcept

Destroys the writer and closes its stream.

Destruction is non-throwing.

Member Function Documentation

update()

void RestartSubscriber::update ( void  )

overridevirtual

Replaces the output with one restart snapshot.

The method validates the attached collaborators and box before reopening the path in truncating text mode. It writes one complete restart and closes the stream before checking the final stream state.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the logical file path is empty, no context or integrator is attached, the integrator has no context, or the context does not contain exactly three positive box lengths.
ApoCharmmError	With code ApoCharmmErrorCode::NotImplemented if the attached integrator is not a supported Nose-Hoover, Langevin-piston, or Langevin-thermostat integrator.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the subscriber and integrator retain different context objects, the file cannot be reopened, or closing detects failed output.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if any required device-to-host transfer or device-wide synchronization fails.

Precondition

Context per-atom arrays and every integrator-specific state container required by the selected integrator have valid lengths and device storage.

Postcondition

On success, the stream is closed and the path contains one complete restart representing the state observed during this call.

Warning

The operation is not transactional. Output and host mirrors updated before a failure remain observable.

Implements Subscriber.