|
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 distance restraint. More...
Inherits _ApoObject.
Public Member Functions | |
| None | __init__ (self, int num_atoms) |
| Constructs a distance restraint for a fixed atom count. | |
| str | default_force_tag (self) |
| Returns the default manager energy tag. | |
| None | setScale (self, float scale) |
| Sets the global scale applied to every stored restraint term. | |
| None | addRestraint (self, Sequence[Sequence[AtomReference]] atom_pairs, Sequence[float] coefficients, float force_constant, float reference_value, int distance_exponent, int energy_exponent, DistanceRestraintCondition condition) |
| Appends one distance-restraint term. | |
| None | reset (self) |
| Removes all stored restraint terms and restores native scale one. | |
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 distance restraint.
One object may own multiple restraint terms. For each term, native code forms the coefficient-weighted sum of powered pair distances, subtracts the reference value, applies the selected one-sided condition, and accumulates the normalized energy, gradient, and internal virial.
This wrapper owns one C handle for the native DistanceRestraintForce<long long int, float> specialization. Python pair and coefficient sequences are materialized into temporary contiguous ctypes arrays 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 CUDA 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.distance_restraint_force.DistanceRestraintForce.__init__ | ( | self, | |
| int | num_atoms | ||
| ) |
Constructs a distance 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 "resd".
| [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 == "resd".
|
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 "resd". |
| 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. |
| None apocharmm.distance_restraint_force.DistanceRestraintForce.addRestraint | ( | self, | |
| Sequence[Sequence[AtomReference]] | atom_pairs, | ||
| Sequence[float] | coefficients, | ||
| float | force_constant, | ||
| float | reference_value, | ||
| int | distance_exponent, | ||
| int | energy_exponent, | ||
| DistanceRestraintCondition | condition | ||
| ) |
Appends one distance-restraint term.
Every element of atom_pairs must contain exactly two live AtomReference objects. Raw integer endpoint pairs are not accepted.
Pair topology provenance is deliberately ignored. This wrapper does not compare endpoint topologies, and endpoints may originate from different native PSF objects.
The wrapper places the two endpoint-handle sequences and the materialized coefficient values in temporary contiguous arrays. The typed C ABI borrows every AtomReference handle for the call and copies temporary native AtomReference values. The native force then extracts, validates, and stores only their zero-based indices. Neither the Python wrappers, C handles, native AtomReference values, nor source PSFs are retained after successful addition.
Pair definitions and coefficients remain separate sequences, and their counts must match. Pair ordering and coefficient correspondence are preserved exactly. Repeated references and repeated pairs are supported.
| [in] | atom_pairs | Sequence of two-AtomReference sequences. |
| [in] | coefficients | Sequence containing one coefficient per pair. |
| [in] | force_constant | Value accepted by float(). |
| [in] | reference_value | Value accepted by float(). |
| [in] | distance_exponent | Required signed C int exponent. |
| [in] | energy_exponent | Required signed C int exponent. |
| [in] | condition | Required one-sided activation condition. |
| TypeError | If an endpoint is not an AtomReference, an exponent is not an int, an exponent is bool, condition has the wrong type, a supplied sequence is not iterable, or a scalar cannot be converted by float(). |
| ValueError | If a pair does not contain exactly two values, an exponent does not fit signed C int, or Python scalar conversion rejects a value. |
| OverflowError | If Python floating-point conversion overflows. |
| RuntimeError | If this wrapper or an endpoint AtomReference has been closed. |
| ApoCharmmError | If native validation or allocation fails. |
| str apocharmm.distance_restraint_force.DistanceRestraintForce.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().
"resd". | None apocharmm.distance_restraint_force.DistanceRestraintForce.reset | ( | self | ) |
Removes all stored restraint terms and restores native scale one.
The operation changes restraint configuration only. It does not replace force-manager output clearing.
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If the C ABI reports a failure. |
| None apocharmm.distance_restraint_force.DistanceRestraintForce.setScale | ( | self, | |
| float | scale | ||
| ) |
Sets the global scale applied to every stored restraint term.
scale is converted with float() and then to C double. Native validation defines the accepted finite values and preserves the stored restraint definitions.
| [in] | scale | Value accepted by float() and native scale validation. |
| TypeError | If float(scale) rejects the object. |
| ValueError | If Python conversion rejects the value. |
| OverflowError | If Python conversion overflows. |
| RuntimeError | If this wrapper has been closed. |
| ApoCharmmError | If the C ABI reports a failure. |
1.9.8