apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce Class Reference

Configures an owned native harmonic group-center restraint. More...

Inherits _ApoObject.

Public Member Functions
None	__init__ (self, int num_atoms)
	Constructs a restraint for a fixed atom count.
str	default_force_tag (self)
	Returns the default force-manager energy tag.
None	setSelection (self, AtomSelection selection)
	Copies the nonempty selection used to define the group center.
None	setForceConstant (self, float force_constant)
	Sets the scalar harmonic force constant.
None	setReferencePosition (self, Sequence[float] reference_position, Sequence[int]|None reference_mask=None)
	Copies the Cartesian reference position and component mask.
None	setReferenceDistance (self, float reference_distance)
	Sets the target radial distance from the reference position.
None	setMasses (self, Sequence[float] masses)
	Copies per-atom masses and enables mass weighting.
None	setMassWeighting (self, bool flag)
	Enables configured mass weights or restores uniform weights.

Protected Member Functions
None	_subscribe_to_force_manager (self, ForceManager force_manager, str|None force_tag=None)
	Implements the ForceManager.subscribe() callback.
None	_unsubscribe_from_force_manager (self, ForceManager force_manager)
	Implements the ForceManager.unsubscribe() callback.

Detailed Description

Configures an owned native harmonic group-center restraint.

The selected atoms define a uniformly weighted geometric center by default or a mass-weighted center after masses are supplied or mass weighting is enabled. The native force applies periodic CONS HMCM-style energy and gradient behavior described on the subsystem page.

This wrapper owns one C handle for the native HarmonicCenterOfMassRestraintForce<long long int, float> specialization. Python iterables are materialized, converted to native scalar types, copied into temporary contiguous ctypes arrays, and copied again into native storage. No caller iterable or buffer is retained.

ForceManager.subscribe() retains this wrapper only after native subscription succeeds. The native manager independently retains the restraint and its CUDA resources. Unsubscribe before calling close(): closing a subscribed wrapper destroys the identifying C handle but does not remove the native subscription, and the closed wrapper can no longer be used for normal unsubscription.

close(), destroy(), context-manager exit, and finalization release the owned C handle. Explicit closure is idempotent. Methods that access self.handle after closure raise RuntimeError; default_force_tag remains available because it is Python-owned text.

The wrapper and native object provide no internal synchronization. Do not overlap configuration, manager operations, calculation, or closure across threads.

See also

harmonic_center_of_mass_restraint_force

Constructor & Destructor Documentation

__init__()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.__init__	(		self,
		int	num_atoms
	)

Constructs a restraint for a fixed atom count.

num_atoms is checked with isinstance(value, int), range-checked for signed 32-bit C int, and passed to native construction. The wrapper owns the returned handle and sets default_force_tag to "hmcm".

Parameters

[in]

num_atoms

Positive dimensionless atom count representable by signed 32-bit C int. Because Python bool is an int subclass, True reaches native construction as one and False is rejected natively as zero.

Exceptions

TypeError	If num_atoms is not a Python int.
ValueError	If num_atoms is outside the signed 32-bit C int range.
ApoCharmmError	If native validation rejects a non-positive value, CUDA setup fails, or native allocation fails.
RuntimeError	If native construction reports success but returns a NULL handle.
MemoryError	If Python or ctypes bookkeeping cannot allocate storage.

Postcondition

On success, this wrapper owns a live native handle and default_force_tag == "hmcm".

Member Function Documentation

_subscribe_to_force_manager()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce._subscribe_to_force_manager (   self, ForceManager  force_manager, str | None   force_tag = None  )

protected

Implements the ForceManager.subscribe() callback.

None selects default_force_tag; otherwise force_tag must be a Python str. The selected text is encoded as UTF-8 and passed as a temporary null-terminated C string. Native subscription retains the restraint and its CUDA resources, not this Python wrapper or its C handle. The public manager method retains this wrapper only after this callback succeeds.

Parameters

[in]	force_manager	Live ForceManager receiving the restraint.
[in]	force_tag	None or a Python string. The encoded string must be nonempty after C-string interpretation.

Exceptions

TypeError	If force_manager is not a ForceManager or force_tag is neither None nor str.
UnicodeEncodeError	If UTF-8 encoding rejects the string.
RuntimeError	If either native wrapper is closed.
ApoCharmmError	If native handle validation, tag validation, duplicate detection, immediate initialization, or manager allocation fails.

Postcondition

On success, the native manager owns independent shared references to the restraint and its resources.

Warning

An embedded NUL character truncates the tag at the C ABI boundary.

_unsubscribe_from_force_manager()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce._unsubscribe_from_force_manager (   self, ForceManager  force_manager  )

protected

Implements the ForceManager.unsubscribe() callback.

Native unsubscription removes the matching restraint by object identity and releases manager-owned shared references. The public manager method removes its retained Python reference only after this callback succeeds.

Parameters

[in]

force_manager

Live ForceManager that currently owns the native subscription.

Exceptions

RuntimeError	If this wrapper or force_manager is closed.
ApoCharmmError	If native handle validation fails or the restraint is not subscribed to that manager.

Postcondition

On success, the restraint no longer participates in manager calculation or box propagation.

default_force_tag()

str apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.default_force_tag

(

self

)

Returns the default force-manager energy tag.

This property reads Python-owned text and does not access the native handle, so it remains available after close().

Returns

The Python string "hmcm".

setForceConstant()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setForceConstant	(		self,
		float	force_constant
	)

Sets the scalar harmonic force constant.

force_constant is converted with float() and then to C double. The value uses kilocalories per mole per square angstrom. Zero disables evaluation.

Parameters

[in]

force_constant

Any Python object accepted by float(). The converted value must be finite and non-negative.

Exceptions

TypeError	If float(force_constant) rejects the object.
ValueError	If Python floating-point conversion rejects the value.
OverflowError	If conversion to Python float overflows.
RuntimeError	If this wrapper has been closed.
ApoCharmmError	If native validation rejects the converted value.

setMasses()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setMasses	(		self,
		Sequence[float]	masses
	)

Copies per-atom masses and enables mass weighting.

masses is consumed as an iterable, every element is converted with float(), and the result is copied through a temporary contiguous C double array. Native code copies the complete atom-order array and rebuilds selected device weights. No caller iterable or buffer is retained.

Values normally use atomic mass units. Only relative selected masses affect the normalized center. Every mass must be finite and non-negative, and selected masses must have positive total weight.

Parameters

[in]

masses

Iterable producing exactly one value per atom, in atom order. Every element must be accepted by float().

Exceptions

TypeError	If masses is not iterable or an element cannot be converted with float().
ValueError	If element conversion rejects a value.
OverflowError	If conversion to Python float overflows.
MemoryError	If the temporary list or C array cannot be allocated.
RuntimeError	If this wrapper has been closed.
ApoCharmmError	If native length, finite-value, non-negativity, or positive-total-weight validation fails, or a native CUDA update fails.

Postcondition

On success, mass weighting is enabled.

Warning

A native failure after mutation begins can leave new masses or a new weighting mode paired with older selected device arrays.

setMassWeighting()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setMassWeighting	(		self,
		bool	flag
	)

Enables configured mass weights or restores uniform weights.

The implementation passes flag to ctypes.c_bool without an explicit Python type check. False-valued objects disable mass weighting and true-valued objects enable it. Native selected weights are rebuilt and copied to device storage; disabling does not discard stored masses.

Parameters

[in]

flag

Object whose truth value can initialize ctypes.c_bool. Use an actual Python bool for an unambiguous API call.

Exceptions

Exception	If custom truth-value conversion raises an exception.
RuntimeError	If this wrapper has been closed.
ApoCharmmError	If enabling produces zero selected total mass, a native allocation fails, or the native CUDA update fails.

Warning

A native failure after the mode flag changes can leave the weighting mode and selected device arrays inconsistent.

setReferenceDistance()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setReferenceDistance	(		self,
		float	reference_distance
	)

Sets the target radial distance from the reference position.

reference_distance is converted with float() and then to C double. Zero selects k * r^2; a positive value selects k * (r - reference_distance)^2.

Parameters

[in]

reference_distance

Any Python object accepted by float(). The converted distance must be finite, non-negative, and is measured in angstroms.

Exceptions

TypeError	If float(reference_distance) rejects the object.
ValueError	If Python floating-point conversion rejects the value.
OverflowError	If conversion to Python float overflows.
RuntimeError	If this wrapper has been closed.
ApoCharmmError	If native validation rejects the converted value.

Note

For a positive target and exactly zero current displacement, the native implementation assigns a zero gradient at the nondifferentiable point.

setReferencePosition()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setReferencePosition	(		self,
		Sequence[float]	reference_position,
		Sequence[int] | None	reference_mask = None
	)

Copies the Cartesian reference position and component mask.

reference_position is consumed as an iterable and every value is converted with float(). It must produce exactly three values in [x, y, z] order and angstrom units.

When reference_mask is None, all three components are active. A supplied mask is consumed as an iterable and every value is converted with int(), then narrowed through ctypes.c_int, before native validation. Integer conversion can truncate non-integral numeric objects, and narrowing can change an out-of-range integer; the resulting C values must each be zero or one and at least one must be one.

Both converted lists are copied into temporary contiguous ctypes arrays and copied again into native host scalar state. No caller object or buffer is retained. For example, setReferencePosition((0.0, 0.0, 0.0), (1, 1, 0)) restrains only the X and Y components.

Parameters

[in]	reference_position	Iterable of exactly three values accepted by float(), in [x, y, z] order. Converted values must be finite.
[in]	reference_mask	None or an iterable of exactly three values accepted by int(). Converted values must form an active zero-or-one mask in [x, y, z] order.

Exceptions

TypeError	If either supplied object is not iterable or an element cannot be converted by float() or int().
ValueError	If scalar conversion rejects a value.
OverflowError	If scalar conversion overflows.
MemoryError	If a temporary list or C array cannot be allocated.
RuntimeError	If this wrapper has been closed.
ApoCharmmError	If native length, finite-value, mask-value, or active-component validation fails.

setSelection()

None apocharmm.harmonic_center_of_mass_restraint_force.HarmonicCenterOfMassRestraintForce.setSelection	(		self,
		AtomSelection	selection
	)

Copies the nonempty selection used to define the group center.

The native selection is copied; this wrapper retains no Python reference to selection. Native selected-index and selected-weight arrays are rebuilt and copied to device memory.

Parameters

[in]

selection

Live AtomSelection with the same atom count as this restraint and at least one selected atom.

Exceptions

TypeError	If selection is not an AtomSelection.
RuntimeError	If this wrapper or selection has been closed.
ApoCharmmError	If native handle, atom-count, nonempty-selection, or positive-total-weight validation fails, native allocation fails, or the native CUDA update fails.

Warning

A native failure after mutation begins can leave newer selection state paired with older selected device arrays.