Declares the C ABI for absolute harmonic restraint configuration. More...

Typedefs
typedef struct apo_harmonic_restraint_force	apo_harmonic_restraint_force
	Represents an owned absolute harmonic restraint in the C ABI.

Functions
apo_status	apo_harmonic_restraint_force_create (apo_harmonic_restraint_force **out, const int num_atoms)
	Creates an owned harmonic-restraint handle.

void	apo_harmonic_restraint_force_destroy (apo_harmonic_restraint_force *restraint)
	Destroys an owned harmonic-restraint handle.

apo_status	apo_harmonic_restraint_force_set_selection (apo_harmonic_restraint_force restraint, const apo_atom_selection selection)
	Copies the atom selection used by a harmonic restraint.

apo_status	apo_harmonic_restraint_force_set_force_constant (apo_harmonic_restraint_force *restraint, const double force_constant)
	Sets one force constant for every selected atom.

apo_status	apo_harmonic_restraint_force_set_force_constants (apo_harmonic_restraint_force restraint, const double force_constants, const size_t force_constants_len)
	Copies one force constant per atom.

apo_status	apo_harmonic_restraint_force_set_reference_coordinates (apo_harmonic_restraint_force restraint, const double reference_coordinates, const size_t reference_coordinates_len)
	Copies absolute Cartesian reference coordinates.

apo_status	apo_harmonic_restraint_force_set_masses (apo_harmonic_restraint_force restraint, const double masses, const size_t masses_len)
	Copies one non-negative mass or weight per atom.

apo_status	apo_harmonic_restraint_force_set_box_dimensions (apo_harmonic_restraint_force restraint, const double box_dimensions, const size_t box_dimensions_len)
	Copies three orthogonal box lengths.

apo_status	apo_force_manager_subscribe_harmonic_restraint_force (apo_force_manager force_manager, apo_harmonic_restraint_force restraint, const char *force_tag)
	Subscribes a harmonic restraint to a force manager.

apo_status	apo_force_manager_unsubscribe_harmonic_restraint_force (apo_force_manager force_manager, apo_harmonic_restraint_force restraint)
	Unsubscribes a harmonic restraint from a force manager.

Detailed Description

Declares the C ABI for absolute harmonic restraint configuration.

Typedef Documentation

◆ apo_harmonic_restraint_force

typedef struct apo_harmonic_restraint_force apo_harmonic_restraint_force

Represents an owned absolute harmonic restraint in the C ABI.

A successful apo_harmonic_restraint_force_create call returns one newly owned handle. The caller releases that handle with apo_harmonic_restraint_force_destroy. Configuration functions borrow a live handle for one call and copy all supplied selections and arrays.

A successful force-manager subscription retains an independent native shared owner of the restraint, stream, force array, and energy object. Destroying this C handle does not unsubscribe that retained native object. Unsubscribe before destruction when the caller will need to remove the force explicitly.

The C ABI exposes configuration and subscription but no direct force-kernel invocation or output access. Use ForceManager or CharmmContext to drive 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 associated native object provide no internal synchronization; callers must serialize mutation, subscription, 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: harmonic_restraint_force

Function Documentation

◆ apo_force_manager_subscribe_harmonic_restraint_force()

apo_status apo_force_manager_subscribe_harmonic_restraint_force	(	apo_force_manager *	force_manager,
		apo_harmonic_restraint_force *	restraint,
		const char *	force_tag
	)

Subscribes a harmonic restraint to a force manager.

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

If the manager is already initialized, subscription first initializes the restraint with the manager atom count and box dimensions. Otherwise, the manager initializes the retained restraint during its later initialization. Duplicate force 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 tag. The text is copied and no caller pointer is retained.

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 initialization detects an atom-count, box, or other invalid-argument mismatch.
APO_STATUS_CUDA_ERROR	Immediate restraint initialization or manager resource setup encounters a CUDA failure.
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 storage is maintained in parallel vectors. An allocation failure during vector growth is not guaranteed to preserve a completely unchanged manager subscription state.

◆ apo_force_manager_unsubscribe_harmonic_restraint_force()

apo_status apo_force_manager_unsubscribe_harmonic_restraint_force	(	apo_force_manager *	force_manager,
		apo_harmonic_restraint_force *	restraint
	)

Unsubscribes a harmonic restraint from a force manager.

The manager releases its retained native owners of the restraint, stream holder, force array, and energy-virial object. Other C, C++, or Python owners remain valid. The operation does not clear or otherwise reinitialize the restraint.

Parameters

[in,out]	force_manager	Borrowed live manager handle. The handle is not retained.
[in]	restraint	Borrowed live restraint handle identifying the exact native object to remove. The handle is not retained.

Return values

APO_STATUS_OK	The manager released the matching subscription.
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 unexpected standard or nonstandard C++ operation failed.

Postcondition: On success, the manager will not schedule later calculations for this restraint.

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_restraint_force_create()

apo_status apo_harmonic_restraint_force_create	(	apo_harmonic_restraint_force **	out,
		const int	num_atoms
	)

Creates an owned harmonic-restraint handle.

The created native restraint uses fixed-point long long int force storage and single-precision kernel arithmetic. All atoms begin selected, force constants and reference positions begin at zero, per-atom weights begin at one, and stored box dimensions begin at zero.

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 fit in C `int`.

Return values

APO_STATUS_OK	`*out` contains a newly owned handle that must be released with apo_harmonic_restraint_force_destroy.
APO_STATUS_INVALID_ARGUMENT	`out` is `NULL` or `num_atoms` is not positive.
APO_STATUS_CUDA_ERROR	Native CUDA allocation, initialization, transfer, synchronization, force allocation, or stream creation failed.
APO_STATUS_RUNTIME_ERROR	Handle allocation, shared ownership, host-storage allocation, 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_restraint_force_destroy()

void apo_harmonic_restraint_force_destroy ( apo_harmonic_restraint_force * restraint )

Destroys an owned harmonic-restraint handle.

Deleting the handle releases its native shared owner. A force manager that already subscribed the restraint retains an independent owner, so the 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_restraint_force_set_box_dimensions()

apo_status apo_harmonic_restraint_force_set_box_dimensions	(	apo_harmonic_restraint_force *	restraint,
		const double *	box_dimensions,
		const size_t	box_dimensions_len
	)

Copies three orthogonal box lengths.

The current restraint kernel stores but does not read these dimensions. The values do not apply minimum-image displacement or rescale reference positions.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	box_dimensions	Non-NULL pointer to three contiguous `double` lengths in `[x, y, z]` order and angstrom units. The array is borrowed for the call and copied.
[in]	box_dimensions_len	Dimensionless number of elements in `box_dimensions`. It must equal three.

Return values

APO_STATUS_OK	The box dimensions were stored; an unchanged box may complete without a CUDA transfer.
APO_STATUS_INVALID_ARGUMENT	`restraint` or `box_dimensions` is `NULL`, the handle contains no native object, the length is not three, or a length is non-positive, NaN, or infinite.
APO_STATUS_CUDA_ERROR	Copying or synchronizing a changed box failed.
APO_STATUS_RUNTIME_ERROR	Copying the C array, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition: On success, no caller pointer is retained.

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: A CUDA failure after host assignment can leave native host and device box mirrors divergent.

◆ apo_harmonic_restraint_force_set_force_constant()

apo_status apo_harmonic_restraint_force_set_force_constant	(	apo_harmonic_restraint_force *	restraint,
		const double	force_constant
	)

Sets one force constant for every selected atom.

All unselected atoms receive zero. With masses in atomic mass units, force_constant has units of kilocalories per mole per square angstrom per atomic mass unit.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	force_constant	Finite, non-negative scalar applied to every selected atom.

Return values

APO_STATUS_OK	Host and device constants were updated.
APO_STATUS_INVALID_ARGUMENT	`restraint` is `NULL`, the handle contains no native object, or `force_constant` is negative, NaN, or infinite.
APO_STATUS_CUDA_ERROR	Clearing, transferring, or synchronizing device constants failed.
APO_STATUS_RUNTIME_ERROR	Selected-index allocation, diagnostic construction, 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 native mutation begins can leave all constants zero or leave host and device constants divergent.

◆ apo_harmonic_restraint_force_set_force_constants()

apo_status apo_harmonic_restraint_force_set_force_constants	(	apo_harmonic_restraint_force *	restraint,
		const double *	force_constants,
		const size_t	force_constants_len
	)

Copies one force constant per atom.

The input is indexed in atom order. Only values at selected indices are validated and used; unselected input values are ignored and the corresponding stored constants are zero.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	force_constants	Non-NULL pointer to `force_constants_len` contiguous `double` values. The array is borrowed for the call and copied.
[in]	force_constants_len	Dimensionless number of elements in `force_constants`. It must equal the restraint atom count.

Return values

APO_STATUS_OK	The selected constants were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	`restraint` or `force_constants` is `NULL`, the handle contains no native object, the length differs from the atom count, or a selected value is negative, NaN, or infinite.
APO_STATUS_CUDA_ERROR	Clearing, transferring, or synchronizing device constants failed.
APO_STATUS_RUNTIME_ERROR	Copying the C array, allocating selected indices, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition: On success, selected atoms contain their corresponding input values and unselected atoms contain zero.

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 host and device constants at different stages.

◆ apo_harmonic_restraint_force_set_masses()

apo_status apo_harmonic_restraint_force_set_masses	(	apo_harmonic_restraint_force *	restraint,
		const double *	masses,
		const size_t	masses_len
	)

Copies one non-negative mass or weight per atom.

Values normally use atomic mass units. A zero value is accepted and suppresses that atom's harmonic contribution.

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. The array is borrowed for the call and copied.
[in]	masses_len	Dimensionless number of elements in `masses`. It must equal the restraint atom count.

Return values

APO_STATUS_OK	Masses were copied and transferred to the device.
APO_STATUS_INVALID_ARGUMENT	`restraint` or `masses` is `NULL`, the handle contains no native object, the length differs from the atom count, or a mass is negative, NaN, or infinite.
APO_STATUS_CUDA_ERROR	Transferring or synchronizing masses failed.
APO_STATUS_RUNTIME_ERROR	Copying the C array, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition: On success, the restraint retains no caller pointer and existing reference-position components are preserved.

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: Native validation and host mutation are interleaved. A later invalid mass can leave an earlier host prefix changed while the device mirror remains old.

◆ apo_harmonic_restraint_force_set_reference_coordinates()

apo_status apo_harmonic_restraint_force_set_reference_coordinates	(	apo_harmonic_restraint_force *	restraint,
		const double *	reference_coordinates,
		const size_t	reference_coordinates_len
	)

Copies absolute Cartesian reference coordinates.

The flat array contains one [x, y, z] record per atom in row-major atom order. Coordinates are absolute angstrom values and are not minimum-image wrapped.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained.
[in]	reference_coordinates	Non-NULL pointer to `reference_coordinates_len` contiguous `double` values. The input is borrowed for the call and copied.
[in]	reference_coordinates_len	Dimensionless scalar-element count. It must be nonzero, an exact multiple of three, and exactly `3 * atom_count`.

Return values

APO_STATUS_OK	Reference coordinates were copied and transferred to the device.
APO_STATUS_INVALID_ARGUMENT	`restraint` or `reference_coordinates` is `NULL`, the handle contains no native object, the length is zero or not a multiple of three, the derived atom count is wrong, or a coordinate is NaN or infinite.
APO_STATUS_CUDA_ERROR	Transferring or synchronizing reference coordinates failed.
APO_STATUS_RUNTIME_ERROR	Allocating the nested native copy, constructing a diagnostic, or another standard or nonstandard C++ operation failed.

Postcondition: On success, the restraint has copied every row and retains no caller pointer.

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: Native finite-value validation and host mutation are interleaved. A later invalid coordinate can leave an earlier host prefix changed while the device mirror remains old.

◆ apo_harmonic_restraint_force_set_selection()

apo_status apo_harmonic_restraint_force_set_selection	(	apo_harmonic_restraint_force *	restraint,
		const apo_atom_selection *	selection
	)

Copies the atom selection used by a harmonic restraint.

Every newly unselected atom has its stored force constant set to zero. Newly selected atoms do not recover constants that an earlier selection change zeroed.

Parameters

[in,out]	restraint	Borrowed live restraint handle. The handle is not retained by this call.
[in]	selection	Borrowed live atom-selection handle with the same atom count as `restraint`. The native selection is copied and no ownership is transferred or retained.

Return values

APO_STATUS_OK	The selection was copied and updated constants were transferred to the device.
APO_STATUS_INVALID_ARGUMENT	Either handle is `NULL`, either handle contains no native object, or the two atom counts differ.
APO_STATUS_CUDA_ERROR	Updating or synchronizing the device force-constant array failed.
APO_STATUS_RUNTIME_ERROR	Copying selection 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 selection state and host/device force constants representing different stages.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ apo_harmonic_restraint_force

Function Documentation

◆ apo_force_manager_subscribe_harmonic_restraint_force()

◆ apo_force_manager_unsubscribe_harmonic_restraint_force()

◆ apo_harmonic_restraint_force_create()

◆ apo_harmonic_restraint_force_destroy()

◆ apo_harmonic_restraint_force_set_box_dimensions()

◆ apo_harmonic_restraint_force_set_force_constant()

◆ apo_harmonic_restraint_force_set_force_constants()

◆ apo_harmonic_restraint_force_set_masses()

◆ apo_harmonic_restraint_force_set_reference_coordinates()

◆ apo_harmonic_restraint_force_set_selection()