apocharmm.cuda_integrator.CudaIntegrator Class Reference

Provides the common Python interface to native CUDA integrators. More...

Inheritance diagram for apocharmm.cuda_integrator.CudaIntegrator:

Public Member Functions
None	__init__ (self)
	Constructs an empty Python base-integrator view.
ctypes.c_void_p	integrator_handle (self)
	Returns the borrowed C base-integrator pointer.
None	close (self)
	Closes the concrete handle and invalidates the base view.
None	setTimeStep (self, float time_step)
	Sets the public integrator time step.
None	setCharmmContext (self, CharmmContext context)
	Attaches a context and initializes concrete native state.
None	subscribe (self, Subscriber subscriber)
	Subscribes one output wrapper.
None	unsubscribe (self, Subscriber subscriber)
	Removes one subscriber from native and Python scheduling state.
None	propagate (self, int num_steps)
	Propagates dynamics and scheduled subscribers.
None	initializeFromRestartFile (self, FilePath path)
	Initializes concrete state from a restart file.

Detailed Description

Provides the common Python interface to native CUDA integrators.

This base wrapper does not construct a native integrator itself. Concrete subclasses own a concrete C handle and install a borrowed base-integrator view in _integrator_handle.

The wrapper retains the successfully attached CharmmContext and each successfully subscribed Subscriber. It provides no internal synchronization; serialize operations involving the same integrator, context, or subscribers.

See also

cuda_integrators

Constructor & Destructor Documentation

__init__()

None apocharmm.cuda_integrator.CudaIntegrator.__init__

(

self

)

Constructs an empty Python base-integrator view.

This constructor allocates no native object. Concrete subclasses call it before creating their owned handle and borrowed base view.

Postcondition

integrator_handle raises RuntimeError until a concrete subclass installs a live view.

Reimplemented in apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator, apocharmm.cuda_langevin_thermostat_integrator.CudaLangevinThermostatIntegrator, and apocharmm.cuda_nose_hoover_integrator.CudaNoseHooverIntegrator.

Member Function Documentation

close()

None apocharmm.cuda_integrator.CudaIntegrator.close

(

self

)

Closes the concrete handle and invalidates the base view.

Closure is idempotent. The method destroys the owned concrete C handle, clears the borrowed base view, and releases retained Python context and subscriber references.

Returns

None.

Exceptions

RuntimeError

If a subclass has not configured a native destroy function.

Postcondition

Later handle access raises RuntimeError.

Warning

The method does not implicitly unsubscribe native subscribers. Unsubscribe before closure to avoid retaining a native ownership cycle.

initializeFromRestartFile()

None apocharmm.cuda_integrator.CudaIntegrator.initializeFromRestartFile	(		self,
		FilePath	path
	)

Initializes concrete state from a restart file.

path may be str, bytes, os.PathLike[str], or os.PathLike[bytes]. It is encoded with os.fsencode(), passed as a temporary null-terminated byte string, and not retained.

Parameters

[in]

path

Restart-file path.

Returns

None.

Exceptions

TypeError	If path is not accepted by os.fsencode().
ValueError	If path encoding rejects an embedded null byte.
OSError	If filesystem path conversion fails.
RuntimeError	If the wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT, APO_STATUS_NOT_INITIALIZED, APO_STATUS_NOT_IMPLEMENTED, APO_STATUS_CUDA_ERROR, or APO_STATUS_RUNTIME_ERROR according to restart validation, parsing, transfer, or concrete support.

Warning

Restart loading is not transactional.

integrator_handle()

ctypes.c_void_p apocharmm.cuda_integrator.CudaIntegrator.integrator_handle

(

self

)

Returns the borrowed C base-integrator pointer.

Returns

The live ctypes.c_void_p stored by this wrapper. It aliases an embedded view owned by the concrete C handle 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.

propagate()

None apocharmm.cuda_integrator.CudaIntegrator.propagate	(		self,
		int	num_steps
	)

Propagates dynamics and scheduled subscribers.

num_steps must fit a signed 32-bit C int. Python booleans follow integer rules: True becomes one, while False reaches native validation as zero. On the main Python thread, the wrapper temporarily installs the default SIGINT handler during the native call and restores the previous handler in a finally block.

Parameters

[in]

num_steps

Positive dimensionless number of steps.

Returns

None.

Exceptions

TypeError	If comparison or conversion to ctypes.c_int rejects the supplied object.
ValueError	If the value is outside the signed 32-bit C int range.
RuntimeError	If the wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT, APO_STATUS_NOT_INITIALIZED, APO_STATUS_NOT_IMPLEMENTED, APO_STATUS_CUDA_ERROR, or APO_STATUS_RUNTIME_ERROR according to the documented native failure.

Warning

Propagation is not transactional and native requested-step counters advance before the first concrete step.

setCharmmContext()

None apocharmm.cuda_integrator.CudaIntegrator.setCharmmContext	(		self,
		CharmmContext	context
	)

Attaches a context and initializes concrete native state.

The argument must be a live CharmmContext. The wrapper retains the same Python object only after the native call succeeds.

Parameters

[in]

context

Context wrapper to attach.

Returns

None.

Exceptions

TypeError	If context is not a CharmmContext.
RuntimeError	If this integrator or context has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT for null or duplicate attachment, APO_STATUS_NOT_INITIALIZED for missing context or concrete prerequisites, APO_STATUS_NOT_IMPLEMENTED for direct base initialization, APO_STATUS_CUDA_ERROR for CUDA initialization failure, or APO_STATUS_RUNTIME_ERROR for another native failure.

Postcondition

On success, _context retains context.

setTimeStep()

None apocharmm.cuda_integrator.CudaIntegrator.setTimeStep	(		self,
		float	time_step
	)

Sets the public integrator time step.

time_step is converted with ctypes.c_double and passed by value.

Parameters

[in]

time_step

Finite positive time step in picoseconds.

Returns

None.

Exceptions

TypeError	If time_step cannot be converted to a C double.
RuntimeError	If the wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the converted value is non-finite or not positive, or APO_STATUS_RUNTIME_ERROR for an unexpected native failure.

Warning

The native setter does not reinitialize attached constraint or concrete-integrator derived state.

subscribe()

None apocharmm.cuda_integrator.CudaIntegrator.subscribe	(		self,
		Subscriber	subscriber
	)

Subscribes one output wrapper.

The native integrator caches the subscriber's current reporting frequency and retains its native object. After native success, this wrapper appends the same Python subscriber to _subscribers.

Parameters

[in]

subscriber

Live concrete Subscriber wrapper.

Returns

None.

Exceptions

TypeError	If subscriber is not a Subscriber.
RuntimeError	If either wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT for null or duplicate attachment, APO_STATUS_NOT_INITIALIZED if shared native ownership is unavailable, or APO_STATUS_RUNTIME_ERROR for allocation or another native failure.
MemoryError	If the Python retention list cannot grow after native attachment.

Warning

A MemoryError after native success can leave native and Python retention state inconsistent.

unsubscribe()

None apocharmm.cuda_integrator.CudaIntegrator.unsubscribe	(		self,
		Subscriber	subscriber
	)

Removes one subscriber from native and Python scheduling state.

The native unsubscription runs first. On native success, the matching Python object is removed from _subscribers.

Parameters

[in]

subscriber

Live Subscriber wrapper identifying the native object to remove.

Returns

None.

Exceptions

TypeError	If subscriber is not a Subscriber.
RuntimeError	If either wrapper has been closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the subscriber is not attached or a handle is rejected, or APO_STATUS_RUNTIME_ERROR for another native failure.
ValueError	If native and Python retention state is inconsistent and the Python list does not contain subscriber.