DcdSubscriber Class Reference

Writes periodic coordinate snapshots in CHARMM DCD format. More...

#include <DcdSubscriber.h>

Inheritance diagram for DcdSubscriber:

Public Member Functions
	DcdSubscriber (const std::filesystem::path &filePath)
	Constructs a DCD writer with the default reporting interval.
	DcdSubscriber (const std::filesystem::path &filePath, const int reportFrequency)
	Constructs a DCD writer with an explicit reporting interval.
	~DcdSubscriber (void) noexcept override=default
	Destroys the writer and closes its output stream.
void	update (void) override
	Appends one DCD coordinate frame and updates header metadata.
void	openFile (void) override
	Opens the stored path as a truncating binary DCD output stream.
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.
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

Writes periodic coordinate snapshots in CHARMM DCD format.

Construction immediately creates or truncates a binary output file. The first successful update writes a native-endian DCD header, title block, atom count, and one frame. Later updates append frames and patch the header's frame and step counters.

Each frame contains one six-double unit-cell record followed by separate X, Y, and Z blocks of single-precision coordinates in atom order. Coordinates and box lengths use angstroms. Charges are not written. Coordinate output transfers the complete single-precision coordinate/charge container from the CUDA device to host memory and synchronizes the current CUDA device.

Warning

The binary representation uses native integer size, floating-point representation, and byte order. The implementation performs no endian conversion.

Reporting frequency is cached by the integrator at subscription but read again by DCD metadata generation. Changing it after subscription can make callback spacing and recorded metadata disagree.

A failed frame write is not transactional and can leave a partial or internally inconsistent DCD file.

See also

Subscriber

subscriber

Constructor & Destructor Documentation

DcdSubscriber() [1/2]

DcdSubscriber::DcdSubscriber

(

const std::filesystem::path &

filePath

)

Constructs a DCD writer with the default reporting interval.

Parameters

[in]

filePath

File-system path copied by the subscriber. The value must be nonempty; when it has a nonempty paren 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 binary output file cannot be opened for writing.

Postcondition

The file has been created or truncated, no DCD header has been written, and getReportFrequency() == 1000.

DcdSubscriber() [2/2]

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

Constructs a DCD writer with an explicit reporting interval.

Parameters

[in]	filePath	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 scheduled DCD frames.

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 binary output file cannot be opened for writing.

Postcondition

The file has been created or truncated, no DCD header has been written, and getReportFrequency() == reportFrequency.

~DcdSubscriber()

DcdSubscriber::~DcdSubscriber ( void  )

overridedefaultnoexcept

Destroys the writer and closes its output stream.

Destruction is non-throwing.

Member Function Documentation

openFile()

void DcdSubscriber::openFile ( void  )

overridevirtual

Opens the stored path as a truncating binary DCD output stream.

An already-open stream is closed first. Successful opening resets the frame count to zero and marks the header as unwritten.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the stored file name is empty.
ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if the checked parent path does not exist.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the file cannot be opened for binary output.

Postcondition

On success, prior file contents are truncated and the next update writes a fresh header.

Warning

A failed reopen can leave the previous stream closed while the stored logical file path remains unchanged.

Reimplemented from Subscriber.

update()

void DcdSubscriber::update ( void  )

overridevirtual

Appends one DCD coordinate frame and updates header metadata.

On the first update, the method writes the header before the unit-cell and coordinate records. It then patches NFILE at byte offset 8 and NSTEP at byte offset 20, flushes the stream, and increments the in-memory frame count only after the final stream-state check succeeds.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the logical file path is empty, no context or integrator is attached, the stream is closed, the context does not contain exactly three positive box lengths, or the atom count is not positive.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the next frame count or derived step count exceeds signed int, or if header/frame output or flushing fails.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if transferring coordinates from device to host or synchronizing the current CUDA device fails.

Precondition

The context's single-precision coordinate/charge container has one element per atom and valid device storage.

Postcondition

On success, one complete frame has been appended and the DCD header reflects the new in-memory frame count.

Warning

On failure, already-written bytes remain observable and the file may require deletion rather than reuse.

Implements Subscriber.