apocharmm.dcd_subscriber.DcdSubscriber Class Reference

Writes periodic coordinate snapshots to a CHARMM DCD file. More...

Inheritance diagram for apocharmm.dcd_subscriber.DcdSubscriber:

Public Member Functions
None	__init__ (self, FilePath path, int|None report_frequency=None)
	Constructs and owns a native DCD writer.
None	close (self)
	Releases the owned concrete C handle and clears its base view.
Public Member Functions inherited from apocharmm.subscriber.Subscriber
ctypes.c_void_p	subscriber_handle (self)
	Returns the borrowed C base-subscriber pointer.
None	setReportFrequency (self, int report_frequency)
	Sets the native reporting interval.
int	getReportFrequency (self)
	Returns the native reporting interval.

Detailed Description

Writes periodic coordinate snapshots to a CHARMM DCD file.

Construction immediately creates or truncates the binary output. During propagation, each scheduled native update writes single-precision X, Y, and Z coordinates in atom order and box lengths in angstroms. Charges are not written. Coordinate output copies device data to host and synchronizes the current CUDA device.

The wrapper owns the concrete C handle. Its subscriber_handle property is a borrowed view into that handle. Use the object as a context manager or call close() exactly through the wrapper; never destroy the borrowed view.

Warning

Unsubscribe before closing the wrapper. Closing invalidates the C base view even when the native integrator still retains the underlying C++ subscriber.

DCD updates are not transactional. A native write failure can leave a partial trajectory file after some dynamics steps have completed.

See also

subscriber

Constructor & Destructor Documentation

__init__()

None apocharmm.dcd_subscriber.DcdSubscriber.__init__	(		self,
		FilePath	path,
		int | None	report_frequency = None
	)

Constructs and owns a native DCD writer.

path is converted with os.fsencode() through the package helper and copied by native construction. Accepted path objects are str, bytes, os.PathLike[str], and os.PathLike[bytes]. The original Python object is retained in _path, but native file access does not borrow it.

report_frequency=None selects the native default of 1000 steps. An explicit ordinary Python int must fit a signed 32-bit C int and be positive. Boolean values follow Python integer conversion: True becomes one and False is rejected by native validation.

Parameters

[in]	path	Filesystem path to create or truncate. It must encode to a nonempty native path; when the path has a nonempty parent path, that parent path must exist. Encoded bytes are passed as a null-terminated C string, so an embedded null byte truncates the path observed by native code.
[in]	report_frequency	Optional positive, dimensionless number of propagated steps between DCD frames.

Exceptions

TypeError	If path is not accepted by os.fsencode(), or an explicit frequency cannot be compared with integer bounds or converted by ctypes.c_int.
UnicodeEncodeError	If the platform filesystem encoding cannot encode a string path.
ValueError	If an explicit frequency is outside the signed 32-bit C int range.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if native construction rejects the path or frequency, or APO_STATUS_RUNTIME_ERROR if file opening, allocation, base-view conversion, or an unexpected native exception fails.
RuntimeError	If a native function reports success but returns a null concrete or base handle.

Postcondition

On success, the file has been created or truncated and this wrapper owns both the concrete handle and a live borrowed base view.

Reimplemented from apocharmm.subscriber.Subscriber.

Member Function Documentation

close()

None apocharmm.dcd_subscriber.DcdSubscriber.close

(

self

)

Releases the owned concrete C handle and clears its base view.

The inherited close operation is idempotent. On the first call it invokes apo_dcd_subscriber_destroy, then this override clears the borrowed subscriber_handle regardless of whether the concrete handle had already been released.

Returns

None.

Postcondition

Later subscriber operations raise RuntimeError.

Warning

Call CudaIntegrator.unsubscribe(self) before closure. Native unsubscription requires the borrowed base view that this method clears.