apocharmm.force_manager.ForceManager Class Reference

More...

Inherits _ApoObject.

Public Member Functions
None	__init__ (self, CharmmPsf psf, CharmmParameters parameters)
	Constructs an owning Python ForceManager wrapper.
None	close (self)
	Releases the owned native manager handle.
None	subscribe (self, _SubscribableForce force, str|None force_tag=None)
	Subscribes a native or protocol-compatible force.
None	unsubscribe (self, _SubscribableForce force)
	Unsubscribes a native or protocol-compatible force.
None	setBoxDimensions (self, Sequence[float] box_dimensions)
	Sets three orthorhombic box dimensions.
None	setKappa (self, float kappa)
	Sets the Ewald splitting parameter.
None	setCutoff (self, float cutoff)
	Sets the direct-space pair-list cutoff.
None	setCtonnb (self, float ctonnb)
	Sets the outer switching distance exposed as ctonnb.
None	setCtofnb (self, float ctofnb)
	Sets the inner switching distance exposed as ctofnb.
None	setFFTGrid (self, Sequence[int] grid)
	Sets the three PME FFT grid dimensions.
None	setPmeSplineOrder (self, int order)
	Sets the PME interpolation spline order.
None	setPeriodicBoundaryCondition (self, PeriodicBoundaryCondition|int pbc)
	Sets the periodic boundary condition.
None	setVdwType (self, VdwType|int vdw_type)
	Sets the native van der Waals model.
None	setPrintEnergyDecomposition (self, bool flag=True)
	Enables or disables native energy-decomposition printing.
int	getNumAtoms (self)
	Returns the atom count reported by the native PSF.
bool	isInitialized (self)
	Reports whether native force initialization completed.
tuple[float, float, float]	getBoxDimensions (self)
	Returns the three stored box dimensions.
float	getKappa (self)
	Returns the stored Ewald splitting parameter.
float	getCutoff (self)
	Returns the stored pair-list cutoff.
float	getCtonnb (self)
	Returns the outer switching distance exposed as ctonnb.
float	getCtofnb (self)
	Returns the inner switching distance exposed as ctofnb.
tuple[int, int, int]	getFFTGrid (self)
	Returns the three stored PME FFT dimensions.
int	getPmeSplineOrder (self)
	Returns the stored PME interpolation spline order.
PeriodicBoundaryCondition	getPeriodicBoundaryCondition (self)
	Returns the stored periodic boundary condition.
VdwType	getVdwType (self)
	Returns the stored native van der Waals model.
bool	isComposite (self)
	Reports whether the wrapped native manager is composite.

Protected Member Functions
"ForceManager"	_from_handle (cls, ctypes.c_void_p handle)
	Wraps an already owned C ForceManager handle.

Detailed Description

Configures and owns a native apoCHARMM ForceManager.

Construct the wrapper from a live CharmmPsf and CharmmParameters. The wrapper owns its C handle, while the C handle retains native shared ownership of both collaborators. The Python wrapper also retains the collaborator wrappers.

Configuration methods copy Python scalar or sequence data through the C ABI. Force backends are initialized when the manager is attached to a sufficiently configured CharmmContext, or through direct native C++ initialization; initialization is not exposed as a Python method.

subscribe() retains each force wrapper after its subscription callback succeeds. close() releases the manager handle, clears retained subscribed forces, and is idempotent. Public methods that access self.handle after closure raise RuntimeError.

Native status failures are raised as ApoCharmmError. The wrapper and native manager provide no internal synchronization for concurrent host access.

See also

force_manager

Constructor & Destructor Documentation

__init__()

None apocharmm.force_manager.ForceManager.__init__	(		self,
		CharmmPsf	psf,
		CharmmParameters	parameters
	)

Constructs an owning Python ForceManager wrapper.

The native manager retains shared ownership of the underlying PSF and parameter objects but remains uninitialized. This wrapper also keeps strong references to psf and parameters.

Parameters

[in]	psf	Live CharmmPsf wrapper.
[in]	parameters	Live CharmmParameters wrapper.

Exceptions

TypeError	If psf is not a CharmmPsf or parameters is not a CharmmParameters.
RuntimeError	If either collaborator wrapper is closed or native construction reports success but produces a NULL handle.
ApoCharmmError	If native handle validation, allocation, or CUDA-backed manager construction fails.

Member Function Documentation

_from_handle()

"ForceManager" apocharmm.force_manager.ForceManager._from_handle (   cls, ctypes.c_void_p  handle  )

protected

Wraps an already owned C ForceManager handle.

This internal constructor takes ownership of handle. It is used for a newly owned handle returned by another C ABI object, such as CharmmContext.getForceManager(). It does not reconstruct or retain Python PSF and parameter wrappers because their native lifetimes are already preserved by the C handle.

Parameters

[in]

handle

Non-NULL newly owned ctypes.c_void_p. The caller must not destroy or wrap the same ownership again.

Returns

New owning ForceManager wrapper.

Exceptions

RuntimeError

If handle is NULL.

close()

None apocharmm.force_manager.ForceManager.close

(

self

)

Releases the owned native manager handle.

The operation is idempotent. After native destruction, retained subscribed-force references are cleared. Retained PSF and parameter wrapper attributes are not cleared by this override.

Postcondition

Public operations that access self.handle raise RuntimeError.

getBoxDimensions()

tuple[float, float, float] apocharmm.force_manager.ForceManager.getBoxDimensions

(

self

)

Returns the three stored box dimensions.

The native values are copied into a new fixed-size C buffer and then into a new Python tuple.

Returns

New (x, y, z) tuple in angstroms.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If native handle or output-buffer validation fails.

getCtofnb()

float apocharmm.force_manager.ForceManager.getCtofnb

(

self

)

Returns the inner switching distance exposed as ctofnb.

Returns

Python float in angstroms.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

getCtonnb()

float apocharmm.force_manager.ForceManager.getCtonnb

(

self

)

Returns the outer switching distance exposed as ctonnb.

Returns

Python float in angstroms.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

getCutoff()

float apocharmm.force_manager.ForceManager.getCutoff

(

self

)

Returns the stored pair-list cutoff.

Returns

Python float in angstroms.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

getFFTGrid()

tuple[int, int, int] apocharmm.force_manager.ForceManager.getFFTGrid

(

self

)

Returns the three stored PME FFT dimensions.

Returns

New (nfftx, nffty, nfftz) tuple of Python integers. Before explicit configuration or successful native initialization, the base defaults are (-1, -1, -1).

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If native handle or output-buffer validation fails.

getKappa()

float apocharmm.force_manager.ForceManager.getKappa

(

self

)

Returns the stored Ewald splitting parameter.

Returns

Python float in inverse angstroms.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

getNumAtoms()

int apocharmm.force_manager.ForceManager.getNumAtoms

(

self

)

Returns the atom count reported by the native PSF.

Returns

New Python int.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native manager has no PSF or output validation fails.

Warning

This function will be deprecated in the future.

getPeriodicBoundaryCondition()

PeriodicBoundaryCondition apocharmm.force_manager.ForceManager.getPeriodicBoundaryCondition

(

self

)

Returns the stored periodic boundary condition.

Returns

PeriodicBoundaryCondition enum value.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native handle is invalid or the native PBC value cannot be converted by the C ABI.

getPmeSplineOrder()

int apocharmm.force_manager.ForceManager.getPmeSplineOrder

(

self

)

Returns the stored PME interpolation spline order.

The native value is an integer. The current wrapper implementation converts it to a Python float despite this method's int return annotation.

Returns

Python float containing the dimensionless order.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

getVdwType()

VdwType apocharmm.force_manager.ForceManager.getVdwType

(

self

)

Returns the stored native van der Waals model.

Returns

Corresponding VdwType enum value.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.
ValueError	If native state contains an integer not declared by VdwType.

isComposite()

bool apocharmm.force_manager.ForceManager.isComposite

(

self

)

Reports whether the wrapped native manager is composite.

Returns

Python bool. A directly constructed base ForceManager returns False.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native getter fails.

isInitialized()

bool apocharmm.force_manager.ForceManager.isInitialized

(

self

)

Reports whether native force initialization completed.

Returns

New Python bool.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If native handle or output validation fails.

setBoxDimensions()

None apocharmm.force_manager.ForceManager.setBoxDimensions	(		self,
		Sequence[float]	box_dimensions
	)

Sets three orthorhombic box dimensions.

Every element is converted with float(), copied into a temporary contiguous ctypes.c_double buffer, and copied again by the native manager.

Parameters

[in]

box_dimensions

Iterable containing exactly three finite positive values in [x, y, z] order, in angstroms.

Exceptions

TypeError	If box_dimensions is not iterable or an element cannot be converted with float().
ValueError	If element conversion fails.
OverflowError	If conversion to a Python float overflows.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native length or value validation fails, or a native or subscribed force rejects the update.

setCtofnb()

None apocharmm.force_manager.ForceManager.setCtofnb	(		self,
		float	ctofnb
	)

Sets the inner switching distance exposed as ctofnb.

The current native backend uses this value as the distance at which switching begins.

Parameters

[in]

ctofnb

Value accepted by ctypes.c_double, in angstroms. The narrowed native value must be finite and positive.

Exceptions

TypeError	If ctofnb cannot initialize ctypes.c_double.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If native value validation fails.

setCtonnb()

None apocharmm.force_manager.ForceManager.setCtonnb	(		self,
		float	ctonnb
	)

Sets the outer switching distance exposed as ctonnb.

The current native backend uses this value as the distance at which the switching function reaches zero.

Parameters

[in]

ctonnb

Value accepted by ctypes.c_double, in angstroms. The narrowed native value must be finite and positive.

Exceptions

TypeError	If ctonnb cannot initialize ctypes.c_double.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If native value validation fails.

setCutoff()

None apocharmm.force_manager.ForceManager.setCutoff	(		self,
		float	cutoff
	)

Sets the direct-space pair-list cutoff.

Parameters

[in]

cutoff

Value accepted by ctypes.c_double, in angstroms. The narrowed native value must be finite and positive.

Exceptions

TypeError	If cutoff cannot initialize ctypes.c_double.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If native cutoff validation fails.

setFFTGrid()

None apocharmm.force_manager.ForceManager.setFFTGrid	(		self,
		Sequence[int]	grid
	)

Sets the three PME FFT grid dimensions.

Every element is converted with int(), copied into a temporary contiguous ctypes.c_int buffer, and copied by the native manager.

Parameters

[in]

grid

Iterable containing exactly three positive values in [nfftx, nffty, nfftz] order. Each value is converted with int().

Exceptions

TypeError	If grid is not iterable or an element cannot be converted with int().
ValueError	If integer conversion fails.
OverflowError	If Python integer conversion overflows.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If the native length or positivity validation fails.

setKappa()

None apocharmm.force_manager.ForceManager.setKappa	(		self,
		float	kappa
	)

Sets the Ewald splitting parameter.

The value is converted to ctypes.c_double and narrowed to native float.

Parameters

[in]

kappa

Finite non-negative value in inverse angstroms.

Exceptions

TypeError	If kappa cannot initialize ctypes.c_double.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If the narrowed native value is non-finite or negative, or native validation otherwise fails.

setPeriodicBoundaryCondition()

None apocharmm.force_manager.ForceManager.setPeriodicBoundaryCondition	(		self,
		PeriodicBoundaryCondition | int	pbc
	)

Sets the periodic boundary condition.

pbc is first converted to PeriodicBoundaryCondition, then forwarded as its integer C representation.

Parameters

[in]

pbc

PeriodicBoundaryCondition or integer value 0, 1, or 2, selecting NONE, P1, or P21.

Exceptions

ValueError	If pbc is not a declared enum value.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If native handle or enum validation fails.

Postcondition

On success, the native manager's initialized flag is cleared.

setPmeSplineOrder()

None apocharmm.force_manager.ForceManager.setPmeSplineOrder	(		self,
		int	order
	)

Sets the PME interpolation spline order.

Parameters

[in]

order

Positive dimensionless value accepted by ctypes.c_int.

Exceptions

TypeError	If order cannot initialize ctypes.c_int.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If the resulting native order is not positive.

setPrintEnergyDecomposition()

None apocharmm.force_manager.ForceManager.setPrintEnergyDecomposition	(		self,
		bool	flag = True
	)

Enables or disables native energy-decomposition printing.

flag is converted with ctypes.c_bool; the wrapper does not require that its runtime type be exactly bool.

Parameters

[in]

flag

Truth-valued object selecting output. Omitting the argument enables printing.

Exceptions

RuntimeError	If this wrapper is closed.
ApoCharmmError	If native handle validation fails.

setVdwType()

None apocharmm.force_manager.ForceManager.setVdwType	(		self,
		VdwType | int	vdw_type
	)

Sets the native van der Waals model.

vdw_type is normalized through VdwType. Operational native values are VdwType.VSH through VdwType.DBEXP, with integer values 1 through 6. VdwType.NONE is representable by the Python enum but is rejected by the native setter.

Parameters

[in]

vdw_type

VdwType or corresponding integer.

Exceptions

ValueError	If vdw_type is not declared by VdwType.
RuntimeError	If this wrapper is closed.
ApoCharmmError	If the normalized value is VdwType.NONE or the native setter otherwise rejects it.

subscribe()

None apocharmm.force_manager.ForceManager.subscribe	(		self,
		_SubscribableForce	force,
		str | None	force_tag = None
	)

Subscribes a native or protocol-compatible force.

force must provide _subscribe_to_force_manager(force_manager, force_tag). The callback runs before this wrapper retains a strong reference. On successful return, the reference prevents the force wrapper from being collected while it remains subscribed.

Native _ApoObject forces perform empty-tag and duplicate validation at the native boundary. Pure Python protocol objects are checked in this method before their callback runs.

Parameters

[in]	force	Native force wrapper or protocol-compatible Python object.
[in]	force_tag	Optional tag. It must be a str when supplied. None lets a native force select its default tag.

Exceptions

TypeError	If force_tag is not a str, or force does not expose a callable subscription method.
ValueError	If a pure Python force uses an empty tag or is already retained by identity.
RuntimeError	If this manager or a native force wrapper is closed.
ApoCharmmError	If a native subscription rejects a null resource, empty tag, duplicate force, or other native setup.

unsubscribe()

None apocharmm.force_manager.ForceManager.unsubscribe	(		self,
		_SubscribableForce	force
	)

Unsubscribes a native or protocol-compatible force.

The object's _unsubscribe_from_force_manager(force_manager) callback runs before this wrapper removes its retained reference. The retained reference is removed only after the callback succeeds.

Parameters

[in]

force

Force object to remove by Python object identity.

Exceptions

TypeError	If force does not expose a callable unsubscription method.
ValueError	If a pure Python force is not currently retained.
RuntimeError	If this manager or a native force wrapper is closed.
ApoCharmmError	If native unsubscription rejects the object or reports another failure.