Defines the scheduled output interface used by CUDA integrators. More...

#include <Subscriber.h>

Inheritance diagram for Subscriber:

Public Member Functions
	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.

virtual void	update (void)=0
	Writes one subscriber-specific report.

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.

Protected Attributes
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

Defines the scheduled output interface used by CUDA integrators.

A subscriber owns one host output stream, stores a positive report frequency, and can retain shared ownership of one CharmmContext and one CudaIntegrator. CudaIntegrator::subscribe() attaches those collaborators, retains the subscriber, and snapshots its current report frequency. During propagation, the integrator invokes update synchronously on the calling thread after each matching dynamics step.

The base class is abstract. It is not copyable because it owns a std::fstream, and its user-declared destructor prevents implicit move operations. The class performs no internal locking; callers must serialize stream access, attachment, frequency changes, updates, and destruction.

Warning: A subscribed integrator and subscriber retain each other through std::shared_ptr. Call CudaIntegrator::unsubscribe() before releasing the final external owners.; Configure the file path and report frequency before subscription. The integrator caches the frequency and does not observe later changes.

See also: subscriber

Constructor & Destructor Documentation

◆ Subscriber() [1/3]

Subscriber::Subscriber ( void )

Constructs an unattached subscriber with no output file.

Postcondition: The report frequency is 1000, the file path is empty, the stream is closed, and no context or integrator is retained.

◆ Subscriber() [2/3]

Subscriber::Subscriber ( const std::filesystem::path & filePath )

Constructs a subscriber and opens a text output file.

The path is copied, any nonempty parent path is checked with std::filesystem::exists(), and the file is opened with std::ios::out. An existing file is truncated.

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.

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

Postcondition: On success, the report frequency is 1000 and the text stream is open at filePath.

◆ Subscriber() [3/3]

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

Constructs a subscriber with an explicit reporting interval.

The frequency is validated before the path is stored or the file is opened. The output is opened as a truncating text stream.

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 updates.

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

Postcondition: On success, the text stream is open at filePath and getReportFrequency() == reportFrequency.

◆ ~Subscriber()

virtual Subscriber::~Subscriber ( void )

virtualdefaultnoexcept

Destroys the stream and releases retained collaborators.

Destruction is non-throwing. All references returned by getFilePath are invalid after destruction.

Member Function Documentation

◆ addCommentSection()

void Subscriber::addCommentSection ( const std::string & commentLines )

Appends and flushes one newline-terminated comment section.

The input is copied. A final newline is appended when the supplied string does not already end with one.

Parameters

[in] commentLines Nonempty text copied to the current output stream.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `commentLines` is empty.
ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if the output stream is not open.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` if the write or flush leaves the stream in a failed state.

Postcondition: On success, the file contains the supplied text followed by at least one newline and the stream has been flushed.

Warning: A runtime failure can leave partial text in the output file.

◆ checkPath()

void Subscriber::checkPath ( const std::filesystem::path & filePath )

Checks whether the parent portion of an output path exists.

A path with no parent component returns without a filesystem query. Otherwise, the parent path is checked with std::filesystem::exists(). The current implementation checks existence, not whether the result is a directory.

Parameters

[in] filePath Path whose parent component is inspected. The path is borrowed for the call and is not retained.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if the parent does not exist or its filesystem status cannot be queried.

Postcondition: The subscriber and filesystem are unchanged.

◆ getFilePath() [1/2]

std::filesystem::path & Subscriber::getFilePath ( void )

Returns mutable access to the logical output-file path.

Returns: Borrowed mutable alias to the subscriber-owned file-system path. The reference remains valid until the subscriber is destroyed.

Warning: Mutation bypasses empty-path and parent-path validation and does not reopen or retarget the current stream.

◆ getFilePath() [2/2]

const std::filesystem::path & Subscriber::getFilePath ( void ) const

Returns the logical output-file path.

Returns: Borrowed const alias to the subscriber-owned file-system path. The reference remains valid until the path is modified or the subscriber is destroyed. No file operation is performed.

◆ getReportFrequency()

int Subscriber::getReportFrequency ( void ) const

Returns the configured reporting interval.

Returns: Positive, dimensionless number of propagated steps between scheduled updates.

◆ openFile()

virtual void Subscriber::openFile ( void )

virtual

Opens the stored path as a truncating text output stream.

An already-open stream is closed before the new open is attempted. The stream state is cleared, and the stored path is revalidated.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if the stored file path 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 writing.

Postcondition: On success, the stream is open at the stored path and any previous file contents have been truncated.

Warning: A failed reopen can leave the previous stream closed.

Note: DcdSubscriber overrides this operation to use binary mode and to reset DCD frame metadata.

Reimplemented in DcdSubscriber.

◆ setCharmmContext()

void Subscriber::setCharmmContext ( std::shared_ptr< CharmmContext > ctx )

Retains the context exposed to subscriber implementations.

Parameters

[in] ctx Shared context owner to retain. A null shared pointer is accepted and leaves the subscriber unattached.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if a non-null context is already retained.

Postcondition: On success, the subscriber stores the supplied shared pointer. The native context is not copied, initialized, or otherwise modified.

◆ setFilePath()

void Subscriber::setFilePath ( const std::filesystem::path & filePath )

Sets the logical output-file path without reopening the stream.

Parameters

[in] filePath Output path copied by the subscriber. The value must be nonempty; when it contains /, its nonempty parent path must exist.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if filePath is empty or its checked parent path does not exist.

Postcondition: On success, both overloads of getFilePath return filePath. The current stream, if any, remains attached to its previous file.

Warning: Call openFile explicitly after changing the path when output should move to the new path.

◆ setIntegrator()

void Subscriber::setIntegrator ( std::shared_ptr< CudaIntegrator > integrator )

Retains the integrator exposed to subscriber implementations.

Parameters

[in] integrator Shared integrator owner to retain. A null shared pointer is accepted and leaves the subscriber unattached.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if a non-null integrator is already retained.

Postcondition: On success, the subscriber stores the supplied shared pointer. The native integrator is not copied or modified.

◆ setReportFrequency()

void Subscriber::setReportFrequency ( const int reportFrequency )

Sets the number of propagated steps between scheduled updates.

Parameters

[in] reportFrequency Positive, dimensionless reporting interval.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if reportFrequency is not positive.

Postcondition: On success, getReportFrequency() == reportFrequency. A rejected value leaves the previous frequency unchanged.

Warning: An attached integrator schedules from the value cached during subscription. Changing this property afterward does not update that cache.

◆ update()

virtual void Subscriber::update ( void )

pure virtual

Writes one subscriber-specific report.

CudaIntegrator invokes this virtual operation synchronously after a propagated step whose local step index is divisible by the frequency cached at subscription. Direct callers are responsible for establishing every state precondition of the concrete subscriber.

Precondition: The concrete subscriber's required file, context, integrator, and force-manager state has been initialized.

Warning: Implementations can perform host/device transfers, device-wide synchronization, force or energy evaluation, and irreversible file I/O. Exceptions do not roll back an already propagated step or partial output.

Implemented in DcdSubscriber, and RestartSubscriber.

Member Data Documentation

◆ m_CharmmContext

std::shared_ptr<CharmmContext> Subscriber::m_CharmmContext

protected

Retains the context queried by concrete subscriber updates.

The pointer can be null. No public operation clears a non-null attachment.

◆ m_FilePath

std::filesystem::path Subscriber::m_FilePath

protected

Stores the logical output path owned by the subscriber.

The value can differ from the file currently associated with m_FileStream after a path change that is not followed by openFile.

◆ m_FileStream

std::fstream Subscriber::m_FileStream

protected

Owns the host file stream used by concrete reporters.

The stream has no internal synchronization and can represent text or binary output according to the concrete subscriber's open operation.

◆ m_Integrator

std::shared_ptr<CudaIntegrator> Subscriber::m_Integrator

protected

Retains the integrator queried by concrete subscriber updates.

The pointer can be null. While subscribed, this strong reference and the integrator's strong subscriber reference form an ownership cycle.

◆ m_ReportFrequency

int Subscriber::m_ReportFrequency

protected

Stores the positive, dimensionless reporting interval.

The default is 1000. An integrator copies this value into its parallel scheduling array during subscription.

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Subscriber() [1/3]

◆ Subscriber() [2/3]

◆ Subscriber() [3/3]

◆ ~Subscriber()

Member Function Documentation

◆ addCommentSection()

◆ checkPath()

◆ getFilePath() [1/2]

◆ getFilePath() [2/2]

◆ getReportFrequency()

◆ openFile()

◆ setCharmmContext()

◆ setFilePath()

◆ setIntegrator()

◆ setReportFrequency()

◆ update()

Member Data Documentation

◆ m_CharmmContext

◆ m_FilePath

◆ m_FileStream

◆ m_Integrator

◆ m_ReportFrequency