HarmonicCenterOfMassRestraintForce.h File Reference

Declares the C ABI for harmonic center-of-mass restraints. More...

Typedefs
typedef struct apo_harmonic_center_of_mass_restraint_force	apo_harmonic_center_of_mass_restraint_force
	Represents an owned harmonic center-of-mass restraint in the C ABI.

Functions
apo_status	apo_harmonic_center_of_mass_restraint_force_create (apo_harmonic_center_of_mass_restraint_force **out, const int num_atoms)
	Creates an owned harmonic center-of-mass restraint handle.
void	apo_harmonic_center_of_mass_restraint_force_destroy (apo_harmonic_center_of_mass_restraint_force *restraint)
	Destroys an owned harmonic center-of-mass restraint handle.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_selection (apo_harmonic_center_of_mass_restraint_force *restraint, const apo_atom_selection *selection)
	Copies the nonempty atom selection used to define the group center.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_force_constant (apo_harmonic_center_of_mass_restraint_force *restraint, const double force_constant)
	Sets the scalar harmonic force constant.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_reference_position (apo_harmonic_center_of_mass_restraint_force *restraint, const double *reference_position, const size_t reference_position_len, const int *reference_mask, const size_t reference_mask_len)
	Copies the Cartesian reference position and component mask.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_reference_distance (apo_harmonic_center_of_mass_restraint_force *restraint, const double reference_distance)
	Sets the non-negative target distance from the reference position.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_masses (apo_harmonic_center_of_mass_restraint_force *restraint, const double *masses, const size_t masses_len)
	Copies per-atom masses and enables mass weighting.
apo_status	apo_harmonic_center_of_mass_restraint_force_set_mass_weighting (apo_harmonic_center_of_mass_restraint_force *restraint, const bool flag)
	Enables mass weighting or restores uniform selected weights.
apo_status	apo_force_manager_subscribe_harmonic_center_of_mass_restraint_force (apo_force_manager *force_manager, apo_harmonic_center_of_mass_restraint_force *restraint, const char *force_tag)
	Subscribes a harmonic center-of-mass restraint to a force manager.
apo_status	apo_force_manager_unsubscribe_harmonic_center_of_mass_restraint_force (apo_force_manager *force_manager, apo_harmonic_center_of_mass_restraint_force *restraint)
	Unsubscribes a harmonic center-of-mass restraint by object identity.

Detailed Description

Declares the C ABI for harmonic center-of-mass restraints.

Typedef Documentation

apo_harmonic_center_of_mass_restraint_force

typedef struct apo_harmonic_center_of_mass_restraint_force apo_harmonic_center_of_mass_restraint_force

Represents an owned harmonic center-of-mass restraint in the C ABI.

A successful apo_harmonic_center_of_mass_restraint_force_create call returns one newly owned handle. Release it with apo_harmonic_center_of_mass_restraint_force_destroy. Configuration functions borrow a live handle for one call and copy all supplied selections and arrays.

A successful manager subscription retains an independent native shared owner 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, 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 on the same thread. Its borrowed pointer remains valid only until another diagnostic-changing C ABI call on that thread.

See also

harmonic_center_of_mass_restraint_force

Function Documentation

apo_force_manager_subscribe_harmonic_center_of_mass_restraint_force()

apo_status apo_force_manager_subscribe_harmonic_center_of_mass_restraint_force	(	apo_force_manager *	force_manager,
		apo_harmonic_center_of_mass_restraint_force *	restraint,
		const char *	force_tag
	)

Subscribes a harmonic center-of-mass restraint 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 atom count and installs the manager's orthorhombic box. 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_manager	Borrowed live manager handle. The handle is not retained.
[in]	restraint	Borrowed live restraint handle. The manager retains the underlying native object on success but does not retain this C handle.
[in]	force_tag	Borrowed non-NULL, nonempty, null-terminated byte string. Native code copies the bytes into std::string and retains no caller pointer.

Return values

APO_STATUS_OK	The manager retained the restraint and its resources.
APO_STATUS_INVALID_ARGUMENT	Either 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 mismatch.
APO_STATUS_RUNTIME_ERROR	Copying the tag, growing manager subscription storage, constructing a diagnostic, 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_harmonic_center_of_mass_restraint_force()

apo_status apo_force_manager_unsubscribe_harmonic_center_of_mass_restraint_force	(	apo_force_manager *	force_manager,
		apo_harmonic_center_of_mass_restraint_force *	restraint
	)

Unsubscribes a harmonic center-of-mass restraint 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_manager	Borrowed live manager handle. The handle is not retained.
[in]	restraint	Borrowed live restraint handle identifying the native object to remove. The handle itself is not retained or destroyed.

Return values

APO_STATUS_OK	The matching subscription was removed.
APO_STATUS_INVALID_ARGUMENT	Either handle is NULL, either handle contains no native object, or the restraint is not subscribed to the manager.
APO_STATUS_RUNTIME_ERROR	Diagnostic 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.

apo_harmonic_center_of_mass_restraint_force_create()

apo_status apo_harmonic_center_of_mass_restraint_force_create	(	apo_harmonic_center_of_mass_restraint_force **	out,
		const int	num_atoms
	)

Creates an owned harmonic center-of-mass restraint handle.

The native object uses fixed-point long long int force storage and single-precision gradient-distribution arithmetic. All atoms begin selected, weighting is uniform, all stored masses are one, the force constant and reference distance are zero, the reference position is (0, 0, 0), all Cartesian mask components are active, and box dimensions are unset.

Parameters

[out]	out	Non-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_atoms	Dimensionless 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_harmonic_center_of_mass_restraint_force_destroy.
APO_STATUS_INVALID_ARGUMENT	out is NULL or num_atoms is not positive.
APO_STATUS_CUDA_ERROR	Native CUDA allocation, transfer, synchronization, force allocation, or stream creation failed.
APO_STATUS_RUNTIME_ERROR	Handle allocation, host 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_harmonic_center_of_mass_restraint_force_destroy()

void apo_harmonic_center_of_mass_restraint_force_destroy

(

apo_harmonic_center_of_mass_restraint_force *

restraint

)

Destroys an owned harmonic center-of-mass 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]

restraint

Owned 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_harmonic_center_of_mass_restraint_force_set_force_constant()

apo_status apo_harmonic_center_of_mass_restraint_force_set_force_constant	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const double	force_constant
	)

Sets the scalar harmonic force constant.

The value is retained in native host scalar state. This operation performs no CUDA transfer or synchronization.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	force_constant	Finite, non-negative coefficient in kilocalories per mole per square angstrom. Zero disables evaluation.

Return values

APO_STATUS_OK	The scalar force constant was updated.
APO_STATUS_INVALID_ARGUMENT	restraint is NULL, the handle contains no native object, or force_constant is negative, NaN, or infinite.
APO_STATUS_RUNTIME_ERROR	Diagnostic construction or another standard or nonstandard C++ operation failed.

Postcondition

On validation failure, the prior force constant remains 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.

apo_harmonic_center_of_mass_restraint_force_set_mass_weighting()

apo_status apo_harmonic_center_of_mass_restraint_force_set_mass_weighting	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const bool	flag
	)

Enables mass weighting or restores uniform selected weights.

Enabling uses the masses most recently supplied to the restraint. Disabling assigns every selected atom dimensionless weight one without discarding the stored mass array. Selected weights are rebuilt and copied to device storage.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	flag	true to use configured masses or false to use uniform selected weights.

Return values

APO_STATUS_OK	The selected weighting mode and device weights were updated.
APO_STATUS_INVALID_ARGUMENT	restraint is NULL, the handle contains no native object, or flag is true and selected masses sum to zero.
APO_STATUS_CUDA_ERROR	Selected-index, selected-weight, partial-sum, or state storage could not be allocated, transferred, cleared, or synchronized.
APO_STATUS_RUNTIME_ERROR	Allocating temporary storage, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

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

Failure after the native mode flag changes can leave the mode and selected device arrays inconsistent.

apo_harmonic_center_of_mass_restraint_force_set_masses()

apo_status apo_harmonic_center_of_mass_restraint_force_set_masses	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const double *	masses,
		const size_t	masses_len
	)

Copies per-atom masses and enables mass weighting.

Only relative selected masses affect the normalized center. The complete array and rebuilt selected weights are copied to owned device storage. No caller buffer is retained.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	masses	Non-NULL pointer to masses_len contiguous double values in atom order, normally in atomic mass units. Every value must be finite and non-negative.
[in]	masses_len	Dimensionless number of values in masses. It must equal the restraint atom count, and selected values must have positive total weight.

Return values

APO_STATUS_OK	Masses were copied, mass weighting was enabled, and selected device weights were rebuilt.
APO_STATUS_INVALID_ARGUMENT	restraint or masses is NULL, the handle contains no native object, the length differs from the atom count, a mass is negative, NaN, or infinite, or selected masses sum to zero.
APO_STATUS_CUDA_ERROR	Mass or selected-weight storage could not be allocated, transferred, cleared, or synchronized.
APO_STATUS_RUNTIME_ERROR	Copying the C array, allocating temporary storage, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition

On success, no caller pointer is retained and mass weighting is active.

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

Failure after native mutation begins can leave new masses or an enabled weighting mode paired with older selected device arrays.

apo_harmonic_center_of_mass_restraint_force_set_reference_distance()

apo_status apo_harmonic_center_of_mass_restraint_force_set_reference_distance	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const double	reference_distance
	)

Sets the non-negative target distance from the reference position.

Zero selects the potential k * r^2; a positive value selects k * (r - reference_distance)^2. The value is copied into native host scalar state and no CUDA transfer occurs.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	reference_distance	Finite, non-negative target distance in angstroms.

Return values

APO_STATUS_OK	The reference distance was updated.
APO_STATUS_INVALID_ARGUMENT	restraint is NULL, the handle contains no native object, or reference_distance is negative, NaN, or infinite.
APO_STATUS_RUNTIME_ERROR	Diagnostic construction or another standard or nonstandard C++ operation failed.

Postcondition

On validation failure, the prior reference distance remains 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.

apo_harmonic_center_of_mass_restraint_force_set_reference_position()

apo_status apo_harmonic_center_of_mass_restraint_force_set_reference_position	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const double *	reference_position,
		const size_t	reference_position_len,
		const int *	reference_mask,
		const size_t	reference_mask_len
	)

Copies the Cartesian reference position and component mask.

Active components are minimum-imaged during evaluation; inactive components contribute neither energy nor gradient. Position and mask values are copied into native host scalar state. No caller buffer is retained and no CUDA transfer occurs.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	reference_position	Non-NULL pointer to reference_position_len contiguous double values in [x, y, z] order and angstrom units. The array is borrowed for the call and copied.
[in]	reference_position_len	Dimensionless number of scalar elements in reference_position. It must equal three.
[in]	reference_mask	Non-NULL pointer to reference_mask_len contiguous C int values in [x, y, z] order. Every value must be zero or one.
[in]	reference_mask_len	Dimensionless number of scalar elements in reference_mask. It must equal three, and at least one element must be one.

Return values

APO_STATUS_OK	The position and mask were copied.
APO_STATUS_INVALID_ARGUMENT	restraint, reference_position, or reference_mask is NULL; the handle contains no native object; either length is not three; a position is NaN or infinite; a mask value is not zero or one; or all mask values are zero.
APO_STATUS_RUNTIME_ERROR	Allocating temporary vectors, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition

On success, the restraint retains no caller pointer.

On validation failure, the prior position and mask remain 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.

apo_harmonic_center_of_mass_restraint_force_set_selection()

apo_status apo_harmonic_center_of_mass_restraint_force_set_selection	(	apo_harmonic_center_of_mass_restraint_force *	restraint,
		const apo_atom_selection *	selection
	)

Copies the nonempty atom selection used to define the group center.

Selected indices and either uniform or mass-based selected weights are rebuilt and copied to device storage. No C handle or caller selection storage is retained.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	selection	Borrowed live selection handle with the same atom count as restraint and at least one selected atom. The native selection is copied.

Return values

APO_STATUS_OK	The selection and selected device arrays were updated.
APO_STATUS_INVALID_ARGUMENT	Either handle is NULL, either handle contains no native object, atom counts differ, the selection is empty, or mass weighting is active and selected masses sum to zero.
APO_STATUS_CUDA_ERROR	Selected-index, selected-weight, partial-sum, or state storage could not be allocated, transferred, cleared, or synchronized.
APO_STATUS_RUNTIME_ERROR	Copying selection or temporary storage, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition

On success, the restraint owns an independent selection copy.

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

Failure after native mutation begins can leave the copied selection or selected count newer than the device index and weight arrays.