|
apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
|
|
|
apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
|
|
Configures an owned native absolute harmonic 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 manager energy tag. | |
| None | setSelection (self, AtomSelection selection) |
| Copies the atom selection used by the restraint. | |
| None | setForceConstant (self, float force_constant) |
| Sets one force constant for all selected atoms. | |
| None | setForceConstants (self, Sequence[float] force_constants) |
| Copies one force constant per atom. | |
| None | setReferenceCoordinates (self, Sequence[Sequence[float]] reference_coordinates) |
| Copies absolute Cartesian reference coordinates. | |
| None | setMasses (self, Sequence[float] masses) |
| Copies one mass or restraint weight per atom. | |
| None | setBoxDimensions (self, Sequence[float] box_dimensions) |
| Copies three orthogonal box lengths. | |
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. | |
Configures an owned native absolute harmonic restraint.
The restraint applies one absolute Cartesian reference position, force constant, and mass or weight per atom. See the subsystem page for the energy equation, force-array sign convention, data layout, and units.
This wrapper owns one C handle for the native HarmonicRestraintForce<long long int, float> specialization. Python sequences are converted to float, copied into temporary contiguous ctypes buffers, and copied again into native storage. No caller sequence or buffer is retained.
ForceManager.subscribe() retains this wrapper after native subscription succeeds. The native manager independently retains the restraint and its calculation resources. Unsubscribe before calling close(): closing a subscribed wrapper destroys the C handle but does not remove the native subscription, and the closed wrapper can no longer identify that subscription 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.
The wrapper and native object provide no internal synchronization. Do not overlap configuration, manager subscription changes, calculation, or closure across threads.
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.__init__ | ( | self, | |
| int | num_atoms | ||
| ) |
Constructs a restraint for a fixed atom count.
num_atoms is checked as a Python int, converted to signed C int, and passed to the native constructor. The wrapper owns the newly returned handle and sets default_force_tag to "harm".
| [in] | num_atoms | Dimensionless positive atom count representable by signed 32-bit C int. The current isinstance(value, int) check also accepts Python bool; True reaches native construction as one and False is rejected natively as zero. |
| 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, native CUDA setup fails, or native allocation fails. |
| RuntimeError | If native construction reports success but produces a NULL handle. |
| MemoryError | If Python or ctypes bookkeeping cannot allocate storage. |
default_force_tag == "harm".
|
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 borrowed null-terminated C string. Native code copies the tag and retains the restraint and calculation resources on success.
This callback performs the native subscription. The calling ForceManager.subscribe() method retains this Python wrapper only after the callback succeeds.
| [in] | force_manager | Live ForceManager receiving the restraint. |
| [in] | force_tag | Python str tag, or None to use "harm". |
| TypeError | If force_manager is not a ForceManager or a non-None tag is not a str. |
| UnicodeEncodeError | If force_tag cannot be encoded as UTF-8. |
| RuntimeError | If this wrapper or force_manager has been closed. |
| ApoCharmmError | If the tag is empty, either native handle is invalid, the restraint is already subscribed, initialization detects a mismatch, or native allocation or CUDA setup fails. |
|
protected |
Implements the ForceManager.unsubscribe() callback.
Native unsubscription releases the manager's retained restraint, stream, force-array, and energy owners. After this callback succeeds, the calling ForceManager.unsubscribe() method releases its retained Python reference.
| [in] | force_manager | Live ForceManager currently containing this restraint. |
| RuntimeError | If this wrapper or force_manager has been closed. |
| ApoCharmmError | If either native handle is invalid, this restraint is not subscribed to the manager, or an unexpected native runtime failure occurs. |
| str apocharmm.harmonic_restraint_force.HarmonicRestraintForce.default_force_tag | ( | self | ) |
Returns the default manager energy tag.
This property reads Python-owned text and does not access the native handle, so it remains available after close().
"harm". | None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setBoxDimensions | ( | self, | |
| Sequence[float] | box_dimensions | ||
| ) |
Copies three orthogonal box lengths.
The method consumes box_dimensions as an iterable, converts every value with float(), and copies the resulting list through a temporary C double buffer. Exactly three finite, positive values are required in [x, y, z] order and angstrom units.
The current restraint kernel stores but does not use these dimensions. Changing them does not wrap displacements or rescale references.
| [in] | box_dimensions | Iterable of exactly three box lengths. |
| TypeError | If the object is not iterable or a value cannot be converted with float(). |
| ValueError | If value conversion fails. |
| OverflowError | If value conversion overflows. |
| MemoryError | If the temporary list or C buffer cannot be allocated. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If native length or value validation fails or a changed box cannot be transferred to the device. |
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setForceConstant | ( | self, | |
| float | force_constant | ||
| ) |
Sets one force constant for all selected atoms.
force_constant is converted with float() and then to C double. Unselected atoms receive zero. With masses in atomic mass units, the value has units of kilocalories per mole per square angstrom per atomic mass unit.
| [in] | force_constant | Any Python object accepted by float(). The resulting value must be finite and non-negative. |
| TypeError | If float(force_constant) rejects the object. |
| ValueError | If Python conversion rejects the value. |
| OverflowError | If Python conversion overflows. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If native validation rejects the converted value or the native CUDA update fails. |
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setForceConstants | ( | self, | |
| Sequence[float] | force_constants | ||
| ) |
Copies one force constant per atom.
The method consumes force_constants as an iterable, converts every element with float(), materializes a new Python list, and copies that list into a temporary contiguous C double array. Native code then copies the array again.
The iterable must produce exactly one value per atom. Only currently selected values are validated and used; unselected values are ignored and their native constants are zero.
| [in] | force_constants | Iterable of values accepted by float(), in atom order. Selected values must be finite and non-negative. |
| TypeError | If the object is not iterable or an element cannot be converted with float(). |
| ValueError | If element conversion fails. |
| OverflowError | If element conversion overflows. |
| MemoryError | If the temporary list or C buffer cannot be allocated. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If the native length or selected-value contract is violated or the native CUDA update fails. |
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setMasses | ( | self, | |
| Sequence[float] | masses | ||
| ) |
Copies one mass or restraint weight per atom.
The method consumes masses as an iterable, converts every element with float(), materializes a new Python list, and copies it into a temporary contiguous C double buffer. Native code copies the values again.
Values normally use atomic mass units. Every value must be finite and non-negative. Zero is accepted and suppresses that atom's harmonic contribution.
| [in] | masses | Iterable producing exactly one mass or weight per atom, in atom order. |
| TypeError | If masses is not iterable or an element cannot be converted with float(). |
| ValueError | If element conversion fails. |
| OverflowError | If element conversion overflows. |
| MemoryError | If the temporary list or C buffer cannot be allocated. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If the native length or value contract is violated or the native CUDA transfer fails. |
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setReferenceCoordinates | ( | self, | |
| Sequence[Sequence[float]] | reference_coordinates | ||
| ) |
Copies absolute Cartesian reference coordinates.
The method consumes an outer iterable of coordinate rows. Every row is consumed as an iterable, every element is converted with float(), and each converted row must contain exactly three values in [x, y, z] order. Rows are flattened into a newly allocated row-major C double buffer.
The outer iterable must produce exactly one row per atom. Coordinates use angstroms and are not minimum-image wrapped or rescaled when the box changes.
| [in] | reference_coordinates | Iterable of three-element coordinate iterables in atom order. Every converted value must be finite. |
| TypeError | If an outer or inner value is not iterable or a scalar cannot be converted with float(). |
| ValueError | If scalar conversion fails or a converted row does not contain exactly three elements. |
| OverflowError | If scalar conversion overflows. |
| MemoryError | If the flattened list or C buffer cannot be allocated. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If the native atom count is wrong, a converted coordinate is non-finite, or the native CUDA transfer fails. |
| None apocharmm.harmonic_restraint_force.HarmonicRestraintForce.setSelection | ( | self, | |
| AtomSelection | selection | ||
| ) |
Copies the atom selection used by the restraint.
The native selection is copied. This wrapper does not retain selection. Unselected atoms have their force constants set to zero; expanding the selection later does not restore constants that were previously zeroed.
| [in] | selection | Live AtomSelection with the same atom count as this restraint. |
| TypeError | If selection is not an AtomSelection. |
| RuntimeError | If this wrapper or selection has been closed. |
| ApoCharmmError | If native handle validation or atom-count validation fails, a native allocation fails, or the native host-to-device update fails. |
1.9.8