apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
 
Loading...
Searching...
No Matches
Typedefs | Enumerations | Functions
DistanceRestraintForce.h File Reference

Declares the C ABI for distance restraint configuration. More...

Typedefs

typedef struct apo_distance_restraint_force apo_distance_restraint_force
 Represents an owned distance-restraint force in the C ABI.
 
typedef enum apo_distance_restraint_condition apo_distance_restraint_condition
 Selects the one-sided activation mode for one restraint term.
 

Enumerations

enum  apo_distance_restraint_condition { APO_DISTANCE_RESTRAINT_CONDITION_NONE = 0 , APO_DISTANCE_RESTRAINT_CONDITION_POSITIVE = 1 , APO_DISTANCE_RESTRAINT_CONDITION_NEGATIVE = -1 }
 Selects the one-sided activation mode for one restraint term. More...
 

Functions

apo_status apo_distance_restraint_force_create (apo_distance_restraint_force **out, const int num_atoms)
 Creates an owned distance-restraint handle.
 
void apo_distance_restraint_force_destroy (apo_distance_restraint_force *restraint)
 Destroys an owned distance-restraint handle.
 
apo_status apo_distance_restraint_force_set_scale (apo_distance_restraint_force *restraint, const double scale)
 Sets the global scale applied to every active restraint term.
 
apo_status apo_distance_restraint_force_add_restraint (apo_distance_restraint_force *restraint, const apo_atom_reference *const *first_atom_references, const size_t first_atom_references_len, const apo_atom_reference *const *second_atom_references, const size_t second_atom_references_len, const double *coefficients, const size_t coefficients_len, const double force_constant, const double reference_value, const int distance_exponent, const int energy_exponent, const apo_distance_restraint_condition condition)
 Appends one distance-restraint term from AtomReference endpoint arrays.
 
apo_status apo_distance_restraint_force_reset (apo_distance_restraint_force *restraint)
 Removes every restraint term and restores the global scale to one.
 
apo_status apo_force_manager_subscribe_distance_restraint_force (apo_force_manager *force_manager, apo_distance_restraint_force *restraint, const char *force_tag)
 Subscribes a distance-restraint force to a force manager.
 
apo_status apo_force_manager_unsubscribe_distance_restraint_force (apo_force_manager *force_manager, apo_distance_restraint_force *restraint)
 Unsubscribes a distance-restraint force by object identity.
 

Detailed Description

Declares the C ABI for distance restraint configuration.

Typedef Documentation

◆ apo_distance_restraint_condition

typedef enum apo_distance_restraint_condition apo_distance_restraint_condition

Selects the one-sided activation mode for one restraint term.

The explicit values map one-to-one to the native DistanceRestraintCondition enumeration.

◆ apo_distance_restraint_force

typedef struct apo_distance_restraint_force apo_distance_restraint_force

Represents an owned distance-restraint force in the C ABI.

A successful apo_distance_restraint_force_create call returns one newly owned handle. Release it with apo_distance_restraint_force_destroy. Configuration functions borrow a live handle for one call. Functions that accept atom-reference arrays borrow every handle for that call, copy only the extracted zero-based indices and coefficients into force-owned storage, and retain no caller pointer, atom-reference handle, or source PSF.

One native object may own multiple restraint terms. For term t, pair j has coefficient c_tj, raw primary-coordinate distance r_tj, distance exponent IVAL_t, reference value RVAL_t, force constant KVAL_t, and energy exponent EVAL_t. An active term uses:

D_t = sum_j(c_tj * r_tj^IVAL_t) - RVAL_t
U_t = SCALE * (KVAL_t / EVAL_t) * D_t^EVAL_t

Stored terms accumulate additively. The supported native specialization uses raw primary-coordinate pair distances for the characterized nonperiodic and orthorhombic P1 behavior. A stored manager box does not replace those distances with minimum-image distances. Uncharacterized exponent values are rejected. Behavior for nonorthorhombic, non-P1, and other uncharacterized periodic configurations is not claimed.

Every evaluated exact zero-distance pair is rejected before exponentiation or gradient formation. A zero global scale returns zero contribution before pair geometry is read.

A successful force-manager subscription retains independent native shared ownership of the restraint, CUDA stream holder, force array, and energy-virial object. Destroying this C handle therefore does not remove an existing subscription. Unsubscribe before destruction when later explicit unsubscription is needed.

The C ABI exposes configuration and manager subscription, not direct kernel invocation or output access. Use ForceManager or CharmmContext to drive force, energy, and virial calculation.

A non-NULL pointer must designate a live handle created by apoCHARMM. Passing a dangling, already-destroyed, or foreign pointer has undefined behavior. The handle and native object provide no internal synchronization; callers must serialize mutation, manager operations, calculation, unsubscription, and destruction.

Every status-returning function clears the calling thread's previous diagnostic at entry. Success leaves it empty. On failure, call apo_last_error immediately on the same thread. Its borrowed pointer is valid only until another diagnostic-changing C ABI call on that thread.

See also
DistanceRestraintForce

Enumeration Type Documentation

◆ apo_distance_restraint_condition

enum apo_distance_restraint_condition

Selects the one-sided activation mode for one restraint term.

The explicit values map one-to-one to the native DistanceRestraintCondition enumeration.

Enumerator
APO_DISTANCE_RESTRAINT_CONDITION_NONE 

Applies no one-sided activation gate.

APO_DISTANCE_RESTRAINT_CONDITION_POSITIVE 

Activates the term exactly when its deviation satisfies D >= 0.

APO_DISTANCE_RESTRAINT_CONDITION_NEGATIVE 

Activates the term exactly when its deviation satisfies D <= 0.

Function Documentation

◆ apo_distance_restraint_force_add_restraint()

apo_status apo_distance_restraint_force_add_restraint ( apo_distance_restraint_force *  restraint,
const apo_atom_reference *const *  first_atom_references,
const size_t  first_atom_references_len,
const apo_atom_reference *const *  second_atom_references,
const size_t  second_atom_references_len,
const double *  coefficients,
const size_t  coefficients_len,
const double  force_constant,
const double  reference_value,
const int  distance_exponent,
const int  energy_exponent,
const apo_distance_restraint_condition  condition 
)

Appends one distance-restraint term from AtomReference endpoint arrays.

Element j of first_atom_references, second_atom_references, and coefficients defines one atom pair and its algebraic coefficient. The three arrays are parallel and must have matching lengths.

Every atom-reference handle and native AtomReference is borrowed only for this call. Native code copies the AtomReference values into temporary pair storage, and DistanceRestraintForce extracts and stores only their zero-based atom indices. No public handle, AtomReference object, or source CharmmPSF is retained after this function returns.

Topology provenance is deliberately ignored. Pair endpoints may originate from different native PSF objects. Their extracted indices must be valid for the restraint's fixed atom count and must be distinct. Endpoints from different topologies with the same extracted index are therefore rejected.

Every coefficient must be finite and nonzero. Repeated pairs are accepted and accumulate algebraically. The force constant must be finite and nonzero; positive and negative values are accepted. The reference value must be finite.

The supported distance-exponent set is {-2, -1, 0, 1, 2, 6, 7}. The supported energy-exponent set is {1, 2, 3, 4}. Other values are rejected. The activation condition must be one of the declared enumeration values.

Parameters
[in,out]restraintBorrowed live restraint handle.
[in]first_atom_referencesNon-NULL pointer to first_atom_references_len borrowed live AtomReference handles.
[in]first_atom_references_lenNumber of elements in first_atom_references.
[in]second_atom_referencesNon-NULL pointer to second_atom_references_len borrowed live AtomReference handles.
[in]second_atom_references_lenNumber of elements in second_atom_references. It must equal first_atom_references_len.
[in]coefficientsNon-NULL pointer to coefficients_len contiguous pair coefficients.
[in]coefficients_lenNumber of coefficient elements.
[in]force_constantFinite nonzero term force constant.
[in]reference_valueFinite term reference value.
[in]distance_exponentInteger exponent applied to pair distances.
[in]energy_exponentInteger exponent applied to the term deviation.
[in]conditionOne-sided activation mode.
Return values
APO_STATUS_OKThe term was appended.
APO_STATUS_INVALID_ARGUMENTA required pointer, handle, or native object is NULL; endpoint-array lengths differ; pair and coefficient counts differ; an extracted index is outside the force-local range; both endpoints map to the same index; a coefficient or scalar parameter is invalid; an exponent is unsupported; or condition is not declared.
APO_STATUS_RUNTIME_ERRORTemporary or persistent allocation failed, or another standard or nonstandard C++ operation failed.
Postcondition
On success, no caller pointer, AtomReference, or source topology is retained.
On failure, previously stored restraint definitions and scale remain unchanged.
Note
The function clears the calling thread's previous diagnostic at entry.

◆ apo_distance_restraint_force_create()

apo_status apo_distance_restraint_force_create ( apo_distance_restraint_force **  out,
const int  num_atoms 
)

Creates an owned distance-restraint handle.

The native object uses fixed-point long long int force storage and single-precision pair-gradient conversion. It has the requested fixed atom count, no restraint terms, global scale one, unset box dimensions, an atom-sized force array, one energy-virial object, and one private CUDA stream.

Parameters
[out]outNon-NULL pointer to the caller's handle slot. The function stores NULL in *out before native construction and stores a newly owned handle on success.
[in]num_atomsDimensionless atom count. The value must be greater than zero and is already represented as C int by the function signature.
Return values
APO_STATUS_OK*out contains a newly owned handle that must be released with apo_distance_restraint_force_destroy.
APO_STATUS_INVALID_ARGUMENTout is NULL or num_atoms is not positive.
APO_STATUS_CUDA_ERRORNative CUDA-backed output allocation, force allocation, or stream creation failed.
APO_STATUS_RUNTIME_ERRORHandle allocation, native shared ownership, host-storage allocation, diagnostic construction, or another standard or nonstandard C++ operation failed.
Postcondition
On every failure after a valid out pointer is accepted, *out == NULL.
Note
The function clears the calling thread's previous diagnostic at entry. Success leaves it empty; failure leaves nonempty text available through apo_last_error.

◆ apo_distance_restraint_force_destroy()

void apo_distance_restraint_force_destroy ( apo_distance_restraint_force *  restraint)

Destroys an owned distance-restraint handle.

Deleting the handle releases its native shared owner. A force manager that already subscribed the restraint retains an independent owner, so the native restraint can remain active after this call.

Parameters
[in]restraintOwned handle to release. NULL is accepted and is a no-op. A non-NULL pointer is invalid after this call returns.
Postcondition
No C++ exception escapes the C ABI boundary.
Note
A normally returning destruction preserves the calling thread's existing apo_last_error diagnostic. An internally caught destruction failure can replace that diagnostic but cannot be returned by this void API.
Warning
Do not destroy the same handle twice or use it after destruction.
Unsubscribe before destroying the handle when later explicit unsubscription is required.

◆ apo_distance_restraint_force_reset()

apo_status apo_distance_restraint_force_reset ( apo_distance_restraint_force *  restraint)

Removes every restraint term and restores the global scale to one.

Reset changes stored configuration only. It does not clear force, energy, or virial output accumulated by an earlier calculation.

Parameters
[in,out]restraintBorrowed live restraint handle. The handle is not retained.
Return values
APO_STATUS_OKEvery term was removed and the scale was restored.
APO_STATUS_INVALID_ARGUMENTrestraint is NULL or the handle contains no native object.
APO_STATUS_RUNTIME_ERRORReset-storage allocation, diagnostic construction, or another standard or nonstandard C++ operation failed.
Postcondition
On success, the object owns no terms and has global scale one. New terms may be appended normally.
Note
The function clears the calling thread's previous diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_distance_restraint_force_set_scale()

apo_status apo_distance_restraint_force_set_scale ( apo_distance_restraint_force *  restraint,
const double  scale 
)

Sets the global scale applied to every active restraint term.

Positive, zero, and negative finite values are accepted. The scale is native host scalar state and does not alter stored term definitions. Appending a term preserves the active scale.

Parameters
[in,out]restraintBorrowed live restraint handle. The handle is not retained.
[in]scaleFinite global multiplicative scale.
Return values
APO_STATUS_OKThe scale was updated.
APO_STATUS_INVALID_ARGUMENTrestraint is NULL, the handle contains no native object, or scale is NaN or infinite.
APO_STATUS_RUNTIME_ERRORDiagnostic construction or another standard or nonstandard C++ operation failed.
Postcondition
On validation failure, the prior scale remains unchanged.
Note
Requiring a finite value is the current apoCHARMM API policy. External CHARMM magnitude limits remain unresolved outside the characterized cases.
The function clears the calling thread's previous diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_force_manager_subscribe_distance_restraint_force()

apo_status apo_force_manager_subscribe_distance_restraint_force ( apo_force_manager *  force_manager,
apo_distance_restraint_force *  restraint,
const char *  force_tag 
)

Subscribes a distance-restraint force to a force manager.

On success, the manager retains native shared ownership of the restraint, CUDA stream holder, force array, and energy-virial object. The two C handles remain owned by their callers.

If the manager is initialized, subscription first verifies the restraint's fixed atom count and installs the manager's orthorhombic box dimensions. Otherwise, manager initialization performs that hook later. Duplicate tags are permitted, but the same native restraint object may not be subscribed twice to one manager.

Parameters
[in,out]force_managerBorrowed live manager handle. The handle is not retained.
[in]restraintBorrowed live restraint handle. The manager retains the underlying native object on success but does not retain this C handle.
[in]force_tagBorrowed non-NULL, nonempty, null-terminated byte string. Native code copies the bytes and retains no caller pointer.
Return values
APO_STATUS_OKThe manager retained the restraint and its resources.
APO_STATUS_INVALID_ARGUMENTEither handle is NULL, either handle contains no native object, force_tag is NULL or empty, the restraint is already subscribed, or immediate initialization detects an atom-count or box mismatch.
APO_STATUS_RUNTIME_ERRORCopying the tag, growing manager subscription storage, diagnostic construction, or another standard or nonstandard C++ operation failed.
Postcondition
On success, destroying the restraint C handle alone does not remove the subscribed native object.
Note
The function clears the calling thread's previous diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.
Warning
Manager subscription state is held in parallel vectors. Allocation failure during vector growth is not guaranteed to leave every vector at the same prior length.

◆ apo_force_manager_unsubscribe_distance_restraint_force()

apo_status apo_force_manager_unsubscribe_distance_restraint_force ( apo_force_manager *  force_manager,
apo_distance_restraint_force *  restraint 
)

Unsubscribes a distance-restraint force by object identity.

The manager removes the first matching native object from all parallel subscription vectors and releases its shared references. It does not clear, deinitialize, or destroy the restraint while another owner exists.

Parameters
[in,out]force_managerBorrowed live manager handle. The handle is not retained.
[in]restraintBorrowed live restraint handle identifying the native object to remove. The handle itself is not retained or destroyed.
Return values
APO_STATUS_OKThe matching subscription was removed.
APO_STATUS_INVALID_ARGUMENTEither handle is NULL, either handle contains no native object, or the restraint is not subscribed to the manager.
APO_STATUS_RUNTIME_ERRORDiagnostic construction or another standard or nonstandard C++ operation failed.
Postcondition
On success, the restraint no longer participates in manager box propagation, clearing, force evaluation, force aggregation, energy aggregation, or virial aggregation.
On lookup or validation failure, manager subscription state is unchanged.
Note
The function clears the calling thread's previous diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.