apocharmm.subscriber.Subscriber Class Reference

Provides the common Python interface to a native subscriber. More...

Inheritance diagram for apocharmm.subscriber.Subscriber:

Public Member Functions
None	__init__ (self)
	Constructs an empty Python base-subscriber view.
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

Provides the common Python interface to a native subscriber.

The base wrapper does not create or own a native subscriber. Concrete subclasses own a concrete C handle and store a borrowed embedded base view in _subscriber_handle. That view is valid only until the concrete wrapper is closed.

A CudaIntegrator retains each successfully subscribed Python wrapper in its _subscribers list and the native integrator retains the native C++ subscriber. Unsubscribe before closing a concrete wrapper so its borrowed C view remains available to the native unsubscribe call.

The wrapper provides no internal synchronization. Do not overlap closure, frequency changes, subscription, or propagation involving the same object from multiple threads.

See also

subscriber

Constructor & Destructor Documentation

__init__()

None apocharmm.subscriber.Subscriber.__init__

(

self

)

Constructs an empty Python base-subscriber view.

This constructor allocates no native object. It is used by concrete subclasses before they install a borrowed base view.

Postcondition

subscriber_handle raises RuntimeError until a concrete subclass installs a live native view.

Reimplemented in apocharmm.dcd_subscriber.DcdSubscriber, and apocharmm.restart_subscriber.RestartSubscriber.

Member Function Documentation

getReportFrequency()

int apocharmm.subscriber.Subscriber.getReportFrequency

(

self

)

Returns the native reporting interval.

Returns

A positive, dimensionless Python int.

Exceptions

RuntimeError	If the concrete wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the base view is rejected, or APO_STATUS_RUNTIME_ERROR if an unexpected native exception occurs.

setReportFrequency()

None apocharmm.subscriber.Subscriber.setReportFrequency	(		self,
		int	report_frequency
	)

Sets the native reporting interval.

The current implementation accepts an ordinary Python int that fits a signed 32-bit C int. Boolean values are also accepted by Python's type rules: True becomes one, while False reaches native validation as zero. Configure the interval before subscription because the native integrator caches it when attaching the subscriber.

Parameters

[in]

report_frequency

Positive, dimensionless number of propagated steps between scheduled updates.

Returns

None.

Exceptions

TypeError	If comparison with integer bounds or conversion by ctypes.c_int rejects the supplied object.
ValueError	If the value is outside the signed 32-bit C int range.
RuntimeError	If the concrete wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the converted value is not positive, or APO_STATUS_RUNTIME_ERROR if an unexpected native exception occurs.

Postcondition

A native validation failure leaves the previous frequency unchanged.

subscriber_handle()

ctypes.c_void_p apocharmm.subscriber.Subscriber.subscriber_handle

(

self

)

Returns the borrowed C base-subscriber pointer.

Returns

The live ctypes.c_void_p stored by this wrapper. The returned object aliases wrapper state and must not be destroyed or retained past wrapper closure.

Exceptions

RuntimeError

If no concrete view has been installed or the wrapper has been closed.