CharmmContext.h File Reference

Declares the C ABI molecular-context interface. More...

Typedefs
typedef struct apo_charmm_context	apo_charmm_context
	Opaque owning handle for a native CharmmContext.

Functions
apo_status	apo_charmm_context_create (apo_charmm_context **out, const apo_force_manager *force_manager)
	Creates a CharmmContext from a ForceManager.
apo_status	apo_charmm_context_create_from_psf_parameters (apo_charmm_context **out, const apo_charmm_psf *psf, const apo_charmm_parameters *parameters)
	Creates a CharmmContext from a PSF and CHARMM parameters.
void	apo_charmm_context_destroy (apo_charmm_context *context)
	Destroys an owned CharmmContext handle.
apo_status	apo_charmm_context_set_prm (apo_charmm_context *context, apo_charmm_parameters *parameters)
	Sets the context's CHARMM parameter set.
apo_status	apo_charmm_context_set_psf (apo_charmm_context *context, apo_charmm_psf *psf)
	Sets the context's PSF and imports atom charges and masses.
apo_status	apo_charmm_context_set_force_manager (apo_charmm_context *context, apo_force_manager *force_manager)
	Sets the context's ForceManager.
apo_status	apo_charmm_context_set_coordinates_charges (apo_charmm_context *context, const double *xyzq, const size_t xyzq_len)
	Sets coordinates and charges from a flat host buffer.
apo_status	apo_charmm_context_set_coordinates_from_array (apo_charmm_context *context, const double *xyz, const size_t xyz_len)
	Sets coordinates from a flat host buffer.
apo_status	apo_charmm_context_set_coordinates (apo_charmm_context *context, const apo_charmm_crd *crd)
	Sets coordinates from a CharmmCrd handle.
apo_status	apo_charmm_context_set_charges (apo_charmm_context *context, const double *charges, const size_t charges_len)
	Sets per-atom charges from a host buffer.
apo_status	apo_charmm_context_set_velocities_inverse_masses (apo_charmm_context *context, const double *xyzm, const size_t xyzm_len)
	Sets velocities and inverse masses from a flat host buffer.
apo_status	apo_charmm_context_set_velocities (apo_charmm_context *context, const double *xyz, const size_t xyz_len)
	Sets velocities while preserving inverse masses.
apo_status	apo_charmm_context_set_velocities_from_charmm_velocity_file (apo_charmm_context *context, const char *path)
	Loads velocities from a CHARMM velocity file.
apo_status	apo_charmm_context_set_masses (apo_charmm_context *context, const double *masses, const size_t masses_len)
	Sets masses and stores their reciprocals.
apo_status	apo_charmm_context_set_temperature (apo_charmm_context *context, const double temperature)
	Sets the stored target temperature.
apo_status	apo_charmm_context_set_periodic_boundary_condition (apo_charmm_context *context, const apo_pbc pbc)
	Sets the periodic boundary condition.
apo_status	apo_charmm_context_set_box_dimensions (apo_charmm_context *context, const double *box_dimensions, const size_t box_dimensions_len)
	Sets orthorhombic box dimensions.
apo_status	apo_charmm_context_set_random_seed (apo_charmm_context *context, const uint64_t seed)
	Sets the random seed used for generated velocities.
apo_status	apo_charmm_context_use_holonomic_constraints (apo_charmm_context *context, const bool useHolonomicConstraints)
	Selects constrained degree-of-freedom accounting.
apo_status	apo_charmm_context_set_kappa (apo_charmm_context *context, const double kappa)
	Sets the Ewald splitting parameter.
apo_status	apo_charmm_context_set_cutoff (apo_charmm_context *context, const double cutoff)
	Sets the direct-space cutoff.
apo_status	apo_charmm_context_set_ctonnb (apo_charmm_context *context, const double ctonnb)
	Sets the nonbonded distance exposed as ctonnb.
apo_status	apo_charmm_context_set_ctofnb (apo_charmm_context *context, const double ctofnb)
	Sets the nonbonded distance exposed as ctofnb.
apo_status	apo_charmm_context_set_fft_grid (apo_charmm_context *context, const int *grid, const size_t grid_len)
	Sets the three-dimensional PME FFT grid.
apo_status	apo_charmm_context_set_pme_spline_order (apo_charmm_context *context, const int order)
	Sets the PME interpolation spline order.
apo_status	apo_charmm_context_set_vdw_type (apo_charmm_context *context, const int vdw_type)
	Sets the van der Waals model identifier.
apo_status	apo_charmm_context_get_num_atoms (int *num_atoms, const apo_charmm_context *context)
	Returns the context atom count.
apo_status	apo_charmm_context_get_num_degrees_of_freedom (int *ndegf, const apo_charmm_context *context)
	Returns the current degree-of-freedom count.
apo_status	apo_charmm_context_get_coordinates_charges (double *xyzq, const size_t xyzq_len, const apo_charmm_context *context)
	Copies double-precision coordinates and charges to a host buffer.
apo_status	apo_charmm_context_get_velocity_mass (double *xyzm, const size_t xyzm_len, const apo_charmm_context *context)
	Copies velocities and inverse masses to a host buffer.
apo_status	apo_charmm_context_get_periodic_boundary_condition (apo_pbc *pbc, const apo_charmm_context *context)
	Returns the periodic boundary condition.
apo_status	apo_charmm_context_get_box_dimensions (double *box_dimensions, const size_t box_dimensions_len, const apo_charmm_context *context)
	Copies the three box dimensions.
apo_status	apo_charmm_context_get_random_seed (uint64_t *seed, const apo_charmm_context *context)
	Returns the random seed.
apo_status	apo_charmm_context_get_volume (double *volume, const apo_charmm_context *context)
	Returns the orthorhombic box volume.
apo_status	apo_charmm_context_get_kappa (double *kappa, const apo_charmm_context *context)
	Returns the stored Ewald splitting parameter.
apo_status	apo_charmm_context_get_cutoff (double *cutoff, const apo_charmm_context *context)
	Returns the stored direct-space cutoff.
apo_status	apo_charmm_context_get_ctonnb (double *ctonnb, const apo_charmm_context *context)
	Returns the distance exposed as ctonnb.
apo_status	apo_charmm_context_get_ctofnb (double *ctofnb, const apo_charmm_context *context)
	Returns the distance exposed as ctofnb.
apo_status	apo_charmm_context_get_fft_grid (int *grid, const size_t grid_len, const apo_charmm_context *context)
	Copies the stored three-dimensional PME FFT grid.
apo_status	apo_charmm_context_get_pme_spline_order (int *order, const apo_charmm_context *context)
	Returns the stored PME interpolation spline order.
apo_status	apo_charmm_context_get_vdw_type (int *vdw_type, const apo_charmm_context *context)
	Returns the stored van der Waals model identifier.
apo_status	apo_charmm_context_get_force_manager (apo_force_manager **out, const apo_charmm_context *context)
	Creates an owned C handle for the context's ForceManager.
apo_status	apo_charmm_context_assign_velocities_at_temperature (apo_charmm_context *context, const double temperature)
	Assigns sampled velocities at a temperature.
apo_status	apo_charmm_context_compute_temperature (double *temperature, apo_charmm_context *context)
	Computes the instantaneous kinetic temperature.
apo_status	apo_charmm_context_calculate_potential_energy (apo_charmm_context *context, const bool reset, const bool print)
	Computes forces, potential energy, and virial.

Detailed Description

Declares the C ABI molecular-context interface.

Typedef Documentation

apo_charmm_context

typedef struct apo_charmm_context apo_charmm_context

Opaque owning handle for a native CharmmContext.

A non-NULL handle owns one shared native context and retains shared native references to collaborators needed to preserve its lifetime. Input context handles accepted by status-returning functions are borrowed and must contain a live native object.

Every status-returning function clears the calling thread's previous diagnostic at entry. APO_STATUS_OK therefore leaves no stale diagnostic. On failure, apo_last_error() returns a borrowed pointer to the current thread's diagnostic until the next C ABI call on that thread or thread exit.

Native ApoCharmmErrorCode values map to their corresponding apo_status values. Legacy std::invalid_argument maps to APO_STATUS_INVALID_ARGUMENT; other standard or unknown exceptions map to APO_STATUS_RUNTIME_ERROR. No exception escapes a status-returning C ABI entry point.

Context mutation is not transactional. A failure from native or CUDA work can leave earlier context-side changes observable. The handle and its native object provide no internal thread synchronization.

Function Documentation

apo_charmm_context_assign_velocities_at_temperature()

apo_status apo_charmm_context_assign_velocities_at_temperature	(	apo_charmm_context *	context,
		const double	temperature
	)

Assigns sampled velocities at a temperature.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	temperature	Sampling temperature in kelvin. It must be finite and non-negative.

Return values

APO_STATUS_OK	Velocities were generated and transferred.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or temperature is non-finite or negative.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	The velocity transfer failed.

apo_charmm_context_calculate_potential_energy()

apo_status apo_charmm_context_calculate_potential_energy	(	apo_charmm_context *	context,
		const bool	reset,
		const bool	print
	)

Computes forces, potential energy, and virial.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	reset	Requests force reset behavior. The current native ForceManager rejects true.
[in]	print	true to write a CHARMM-style energy table to standard output.

Return values

APO_STATUS_OK	The force, energy, and virial evaluation completed.
APO_STATUS_INVALID_ARGUMENT	The context handle or native object is NULL.
APO_STATUS_NOT_INITIALIZED	The force manager is missing or not initialized.
APO_STATUS_NOT_IMPLEMENTED	reset is true or printing is requested for a composite force manager.
APO_STATUS_CUDA_ERROR	Force calculation, transfer, or synchronization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	Energy-table formatting or another uncategorized native operation failed.

apo_charmm_context_compute_temperature()

apo_status apo_charmm_context_compute_temperature	(	double *	temperature,
		apo_charmm_context *	context
	)

Computes the instantaneous kinetic temperature.

Parameters

[out]	temperature	Non-NULL output pointer receiving kelvin.
[in,out]	context	Borrowed non-NULL context handle. Kinetic-energy bookkeeping and host mirrors can be updated.

Return values

APO_STATUS_OK	*temperature was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	Atom or velocity storage is inconsistent, or the degree-of-freedom count is not positive.
APO_STATUS_CUDA_ERROR	Kinetic-energy clearing, launch, synchronization, or transfer failed.

Postcondition

On failure, *temperature is unchanged.

apo_charmm_context_create()

apo_status apo_charmm_context_create	(	apo_charmm_context **	out,
		const apo_force_manager *	force_manager
	)

Creates a CharmmContext from a ForceManager.

The input handle is borrowed. The new context and its C handle retain shared native ownership of the force manager and any imported collaborators.

Parameters

[out]	out	Non-NULL pointer to the caller's handle slot. The slot is set to NULL before input validation and receives a newly owned handle on success.
[in]	force_manager	Borrowed non-NULL force-manager handle containing a live native object. The C handle itself is not retained.

Return values

APO_STATUS_OK	The context was created and *out owns it.
APO_STATUS_INVALID_ARGUMENT	out is NULL, force_manager is NULL, its native object is NULL, or imported native configuration is invalid.
APO_STATUS_CUDA_ERROR	GPU setup or triggered native initialization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	Handle allocation or another uncategorized native construction operation failed.

Postcondition

On any failure after out validation, *out remains NULL.

See also

apo_charmm_context_destroy

apo_charmm_context_create_from_psf_parameters()

apo_status apo_charmm_context_create_from_psf_parameters	(	apo_charmm_context **	out,
		const apo_charmm_psf *	psf,
		const apo_charmm_parameters *	parameters
	)

Creates a CharmmContext from a PSF and CHARMM parameters.

The input handles are borrowed. Their native objects are retained through shared ownership by the returned context handle.

Parameters

[out]	out	Non-NULL pointer to the caller's handle slot. The slot is set to NULL before input validation and receives a newly owned handle on success.
[in]	psf	Borrowed non-NULL PSF handle containing a live native object.
[in]	parameters	Borrowed non-NULL parameter handle containing a live native object.

Return values

APO_STATUS_OK	The context was created and *out owns it.
APO_STATUS_INVALID_ARGUMENT	out is NULL, either input handle or native object is NULL, or imported native state is invalid.
APO_STATUS_CUDA_ERROR	GPU setup, per-atom storage, or triggered native initialization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	Handle allocation, topology or parameter preparation, or another uncategorized native operation failed.

Postcondition

On any failure after out validation, *out remains NULL.

See also

apo_charmm_context_destroy

apo_charmm_context_destroy()

void apo_charmm_context_destroy

(

apo_charmm_context *

context

)

Destroys an owned CharmmContext handle.

Parameters

[in]

context

Owned handle to destroy. NULL is accepted and has no effect.

The function is non-throwing across the C ABI. Successful destruction does not clear or replace an existing thread-local diagnostic because destruction uses the dedicated non-throwing cleanup guard.

apo_charmm_context_get_box_dimensions()

apo_status apo_charmm_context_get_box_dimensions	(	double *	box_dimensions,
		const size_t	box_dimensions_len,
		const apo_charmm_context *	context
	)

Copies the three box dimensions.

Parameters

[out]	box_dimensions	Caller-owned output buffer for X, Y, Z lengths in angstroms. It must be non-NULL.
[in]	box_dimensions_len	Number of available double elements. It must be at least three.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	Three values were written.
APO_STATUS_INVALID_ARGUMENT	The context is invalid, the output buffer is NULL, or its capacity is less than three.
APO_STATUS_RUNTIME_ERROR	The native context returns a vector whose size is not exactly three.

Postcondition

On failure, the output buffer is unchanged.

apo_charmm_context_get_coordinates_charges()

apo_status apo_charmm_context_get_coordinates_charges	(	double *	xyzq,
		const size_t	xyzq_len,
		const apo_charmm_context *	context
	)

Copies double-precision coordinates and charges to a host buffer.

The output is N consecutive [x, y, z, charge] records. Coordinates use angstroms and charges use elementary-charge units. Device storage is transferred to the context's host mirror before copying.

Parameters

[out]	xyzq	Caller-owned output buffer. It may be NULL only when the required output length is zero.
[in]	xyzq_len	Number of available double elements. It must be at least 4 * N.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	Exactly 4 * N elements were written.
APO_STATUS_INVALID_ARGUMENT	The context is invalid, the buffer is NULL when output is required, or xyzq_len is too small.
APO_STATUS_CUDA_ERROR	The device-to-host transfer failed.

Postcondition

On a validation or transfer failure, the caller's output buffer is unchanged.

apo_charmm_context_get_ctofnb()

apo_status apo_charmm_context_get_ctofnb	(	double *	ctofnb,
		const apo_charmm_context *	context
	)

Returns the distance exposed as ctofnb.

Parameters

[out]	ctofnb	Non-NULL output pointer receiving angstroms.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*ctofnb was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *ctofnb is unchanged.

apo_charmm_context_get_ctonnb()

apo_status apo_charmm_context_get_ctonnb	(	double *	ctonnb,
		const apo_charmm_context *	context
	)

Returns the distance exposed as ctonnb.

Parameters

[out]	ctonnb	Non-NULL output pointer receiving angstroms.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*ctonnb was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *ctonnb is unchanged.

apo_charmm_context_get_cutoff()

apo_status apo_charmm_context_get_cutoff	(	double *	cutoff,
		const apo_charmm_context *	context
	)

Returns the stored direct-space cutoff.

Parameters

[out]	cutoff	Non-NULL output pointer receiving angstroms.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*cutoff was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *cutoff is unchanged.

apo_charmm_context_get_fft_grid()

apo_status apo_charmm_context_get_fft_grid	(	int *	grid,
		const size_t	grid_len,
		const apo_charmm_context *	context
	)

Copies the stored three-dimensional PME FFT grid.

Parameters

[out]	grid	Caller-owned integer buffer in X, Y, Z order. It must be non-NULL.
[in]	grid_len	Number of available integer elements. It must be at least three.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	Three grid dimensions were written.
APO_STATUS_INVALID_ARGUMENT	The context is invalid, grid is NULL, or grid_len is less than three.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.
APO_STATUS_RUNTIME_ERROR	The native manager returns a grid whose size is not exactly three.

Postcondition

On failure, the output buffer is unchanged.

apo_charmm_context_get_force_manager()

apo_status apo_charmm_context_get_force_manager	(	apo_force_manager **	out,
		const apo_charmm_context *	context
	)

Creates an owned C handle for the context's ForceManager.

The returned handle shares the existing native manager; it does not clone force state. Destroying either handle does not invalidate the other native owner.

Parameters

[out]	out	Non-NULL pointer to the caller's force-manager handle slot. The slot is set to NULL before context validation.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*out owns a newly allocated C handle sharing the native force manager.
APO_STATUS_INVALID_ARGUMENT	out is NULL or the context handle or native object is NULL.
APO_STATUS_NOT_INITIALIZED	The context has no force manager.
APO_STATUS_RUNTIME_ERROR	Allocation of the new C handle failed.

Postcondition

On any failure after out validation, *out remains NULL.

See also

apo_force_manager_destroy

apo_charmm_context_get_kappa()

apo_status apo_charmm_context_get_kappa	(	double *	kappa,
		const apo_charmm_context *	context
	)

Returns the stored Ewald splitting parameter.

Parameters

[out]	kappa	Non-NULL output pointer receiving inverse angstroms.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*kappa was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *kappa is unchanged.

apo_charmm_context_get_num_atoms()

apo_status apo_charmm_context_get_num_atoms	(	int *	num_atoms,
		const apo_charmm_context *	context
	)

Returns the context atom count.

Parameters

[out]	num_atoms	Non-NULL output pointer. On success it receives the dimensionless atom count.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*num_atoms was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer, handle, or native object is NULL.

Postcondition

On failure, *num_atoms is unchanged.

apo_charmm_context_get_num_degrees_of_freedom()

apo_status apo_charmm_context_get_num_degrees_of_freedom	(	int *	ndegf,
		const apo_charmm_context *	context
	)

Returns the current degree-of-freedom count.

Parameters

[out]	ndegf	Non-NULL output pointer. On success it receives the dimensionless count.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*ndegf was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer, handle, or native object is NULL.

Postcondition

On failure, *ndegf is unchanged.

apo_charmm_context_get_periodic_boundary_condition()

apo_status apo_charmm_context_get_periodic_boundary_condition	(	apo_pbc *	pbc,
		const apo_charmm_context *	context
	)

Returns the periodic boundary condition.

Parameters

[out]	pbc	Non-NULL output pointer receiving the mapped apo_pbc value.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*pbc was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer, handle, or native object is NULL, or the native PBC value is not representable by apo_pbc.

Postcondition

On failure, *pbc is unchanged.

apo_charmm_context_get_pme_spline_order()

apo_status apo_charmm_context_get_pme_spline_order	(	int *	order,
		const apo_charmm_context *	context
	)

Returns the stored PME interpolation spline order.

Parameters

[out]	order	Non-NULL output pointer receiving the dimensionless order.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*order was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *order is unchanged.

apo_charmm_context_get_random_seed()

apo_status apo_charmm_context_get_random_seed	(	uint64_t *	seed,
		const apo_charmm_context *	context
	)

Returns the random seed.

Parameters

[out]	seed	Non-NULL output pointer receiving the unsigned 64-bit seed.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*seed was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer, handle, or native object is NULL.

Postcondition

On failure, *seed is unchanged.

apo_charmm_context_get_vdw_type()

apo_status apo_charmm_context_get_vdw_type	(	int *	vdw_type,
		const apo_charmm_context *	context
	)

Returns the stored van der Waals model identifier.

Parameters

[out]	vdw_type	Non-NULL output pointer receiving the native model code.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*vdw_type was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer or context is invalid.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Postcondition

On failure, *vdw_type is unchanged.

apo_charmm_context_get_velocity_mass()

apo_status apo_charmm_context_get_velocity_mass	(	double *	xyzm,
		const size_t	xyzm_len,
		const apo_charmm_context *	context
	)

Copies velocities and inverse masses to a host buffer.

Despite the function name, the fourth value is inverse mass, not mass. The output is N consecutive [vx, vy, vz, inverse_mass] records. Velocity uses angstroms per AKMA time unit and inverse mass uses reciprocal atomic mass units.

Parameters

[out]	xyzm	Caller-owned output buffer. It may be NULL only when the required output length is zero.
[in]	xyzm_len	Number of available double elements. It must be at least 4 * N.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	Exactly 4 * N elements were written.
APO_STATUS_INVALID_ARGUMENT	The context is invalid, the buffer is NULL when output is required, or xyzm_len is too small.
APO_STATUS_CUDA_ERROR	The device-to-host transfer failed.

Postcondition

On a validation or transfer failure, the caller's output buffer is unchanged.

apo_charmm_context_get_volume()

apo_status apo_charmm_context_get_volume	(	double *	volume,
		const apo_charmm_context *	context
	)

Returns the orthorhombic box volume.

Parameters

[out]	volume	Non-NULL output pointer receiving cubic angstroms.
[in]	context	Borrowed non-NULL context handle.

Return values

APO_STATUS_OK	*volume was written.
APO_STATUS_INVALID_ARGUMENT	An output pointer, handle, or native object is NULL.
APO_STATUS_NOT_INITIALIZED	Valid positive box dimensions have not been set.

Postcondition

On failure, *volume is unchanged.

apo_charmm_context_set_box_dimensions()

apo_status apo_charmm_context_set_box_dimensions	(	apo_charmm_context *	context,
		const double *	box_dimensions,
		const size_t	box_dimensions_len
	)

Sets orthorhombic box dimensions.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	box_dimensions	Borrowed contiguous three-element double buffer containing X, Y, Z lengths in angstroms. It must be non-NULL.
[in]	box_dimensions_len	Number of elements. It must equal three.

Return values

APO_STATUS_OK	The dimensions were copied and propagated.
APO_STATUS_INVALID_ARGUMENT	A handle or buffer is NULL, the length is not three, a dimension is not positive, an attached manager rejects a non-finite dimension, or the cutoff exceeds half the X length.
APO_STATUS_CUDA_ERROR	Triggered initialization, image centering, synchronization, or neighbor-list rebuilding failed.

apo_charmm_context_set_charges()

apo_status apo_charmm_context_set_charges	(	apo_charmm_context *	context,
		const double *	charges,
		const size_t	charges_len
	)

Sets per-atom charges from a host buffer.

Charges use elementary-charge units. Existing coordinates are preserved. The values are copied; the caller retains ownership of the buffer.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	charges	Borrowed contiguous double buffer with one element per atom. It must be non-NULL.
[in]	charges_len	Number of charge elements. It must equal the context atom count.

Return values

APO_STATUS_OK	Charges were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, or charges_len differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	Either host-to-device transfer failed.

apo_charmm_context_set_coordinates()

apo_status apo_charmm_context_set_coordinates	(	apo_charmm_context *	context,
		const apo_charmm_crd *	crd
	)

Sets coordinates from a CharmmCrd handle.

Coordinates are copied from the input object's double-precision storage. The input handle and native object are not retained. Existing charges are preserved.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	crd	Borrowed non-NULL coordinate handle containing a live native object.

Return values

APO_STATUS_OK	Coordinates were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or native object is NULL, or the coordinate count differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	Transfer, image centering, synchronization, or neighbor-list rebuilding failed.

apo_charmm_context_set_coordinates_charges()

apo_status apo_charmm_context_set_coordinates_charges	(	apo_charmm_context *	context,
		const double *	xyzq,
		const size_t	xyzq_len
	)

Sets coordinates and charges from a flat host buffer.

The buffer contains N consecutive [x, y, z, charge] records. Coordinates use angstroms and charges use elementary-charge units. The values are copied; the caller retains ownership of the buffer.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	xyzq	Borrowed contiguous double buffer. It must be non-NULL.
[in]	xyzq_len	Number of scalar double elements. It must be nonzero, divisible by four, and exactly 4 * N.

Return values

APO_STATUS_OK	Coordinates and charges were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, the length is zero or not divisible by four, or the record count differs from the context or initialized force-manager atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	Transfer, image centering, synchronization, or neighbor-list rebuilding failed.

apo_charmm_context_set_coordinates_from_array()

apo_status apo_charmm_context_set_coordinates_from_array	(	apo_charmm_context *	context,
		const double *	xyz,
		const size_t	xyz_len
	)

Sets coordinates from a flat host buffer.

The buffer contains N consecutive [x, y, z] records in angstroms. Existing charges are preserved. The values are copied; the caller retains ownership of the buffer.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	xyz	Borrowed contiguous double buffer. It must be non-NULL.
[in]	xyz_len	Number of scalar elements. It must be nonzero, divisible by three, and exactly 3 * N.

Return values

APO_STATUS_OK	Coordinates were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, the length is zero or not divisible by three, or the record count differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	Transfer, image centering, synchronization, or neighbor-list rebuilding failed.

apo_charmm_context_set_ctofnb()

apo_status apo_charmm_context_set_ctofnb	(	apo_charmm_context *	context,
		const double	ctofnb
	)

Sets the nonbonded distance exposed as ctofnb.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	ctofnb	Finite, positive distance in angstroms. The value is converted to native float.

Return values

APO_STATUS_OK	The stored value was updated.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or the converted value is non-finite or not positive.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

The current backend forwards this value as ron. Configure it before force-manager initialization.

apo_charmm_context_set_ctonnb()

apo_status apo_charmm_context_set_ctonnb	(	apo_charmm_context *	context,
		const double	ctonnb
	)

Sets the nonbonded distance exposed as ctonnb.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	ctonnb	Finite, positive distance in angstroms. The value is converted to native float.

Return values

APO_STATUS_OK	The stored value was updated.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or the converted value is non-finite or not positive.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

The current backend forwards this value as roff. Configure it before force-manager initialization.

apo_charmm_context_set_cutoff()

apo_status apo_charmm_context_set_cutoff	(	apo_charmm_context *	context,
		const double	cutoff
	)

Sets the direct-space cutoff.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	cutoff	Finite, positive distance in angstroms. The value is converted to native float.

Return values

APO_STATUS_OK	The stored cutoff was updated.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or the converted cutoff is non-finite or not positive.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

Configure this value before force-manager initialization.

apo_charmm_context_set_fft_grid()

apo_status apo_charmm_context_set_fft_grid	(	apo_charmm_context *	context,
		const int *	grid,
		const size_t	grid_len
	)

Sets the three-dimensional PME FFT grid.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	grid	Borrowed contiguous array containing X, Y, Z grid sizes. It must be non-NULL.
[in]	grid_len	Number of integer elements. It must equal three.

Return values

APO_STATUS_OK	The three positive dimensions were stored.
APO_STATUS_INVALID_ARGUMENT	The context or buffer is invalid, the length is not three, or any dimension is not positive.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

Configure the grid before force-manager initialization.

apo_charmm_context_set_force_manager()

apo_status apo_charmm_context_set_force_manager	(	apo_charmm_context *	context,
		apo_force_manager *	force_manager
	)

Sets the context's ForceManager.

The input handle is borrowed. On success, the context handle retains shared native ownership of the manager and any PSF or parameters imported from it.

Parameters

[in,out]	context	Borrowed non-NULL context handle to modify.
[in]	force_manager	Borrowed non-NULL force-manager handle containing a live native object.

Return values

APO_STATUS_OK	The manager was retained and state was reconciled.
APO_STATUS_INVALID_ARGUMENT	A handle or native object is NULL, or reconciled force configuration is invalid.
APO_STATUS_CUDA_ERROR	State synchronization or initialization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	Force initialization failed for another runtime condition.

apo_charmm_context_set_kappa()

apo_status apo_charmm_context_set_kappa	(	apo_charmm_context *	context,
		const double	kappa
	)

Sets the Ewald splitting parameter.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	kappa	Finite, non-negative value in inverse angstroms. The value is converted to native float.

Return values

APO_STATUS_OK	The stored value was updated.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or the converted value is non-finite or negative.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

Configure this value before force-manager initialization.

apo_charmm_context_set_masses()

apo_status apo_charmm_context_set_masses	(	apo_charmm_context *	context,
		const double *	masses,
		const size_t	masses_len
	)

Sets masses and stores their reciprocals.

Each mass uses atomic mass units. The context stores 1.0 / mass with the corresponding velocity record. Values are copied.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	masses	Borrowed contiguous double buffer with one mass per atom. It must be non-NULL.
[in]	masses_len	Number of masses. It must equal the context atom count.

Return values

APO_STATUS_OK	Reciprocal masses were stored and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, or masses_len differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	The host-to-device transfer failed.

Warning

The current native implementation does not reject zero, negative, infinite, or NaN mass values before division.

apo_charmm_context_set_periodic_boundary_condition()

apo_status apo_charmm_context_set_periodic_boundary_condition	(	apo_charmm_context *	context,
		const apo_pbc	pbc
	)

Sets the periodic boundary condition.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	pbc	One of APO_PBC_NONE, APO_PBC_P1, or APO_PBC_P21.

Return values

APO_STATUS_OK	The boundary condition was stored and propagated.
APO_STATUS_INVALID_ARGUMENT	The context is invalid, pbc is not a declared apo_pbc value, or completed force configuration is invalid.
APO_STATUS_CUDA_ERROR	Triggered initialization, image centering, synchronization, or neighbor-list rebuilding failed.

apo_charmm_context_set_pme_spline_order()

apo_status apo_charmm_context_set_pme_spline_order	(	apo_charmm_context *	context,
		const int	order
	)

Sets the PME interpolation spline order.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	order	Positive dimensionless spline order.

Return values

APO_STATUS_OK	The order was stored.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or order is not positive.
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

Configure the order before force-manager initialization.

apo_charmm_context_set_prm()

apo_status apo_charmm_context_set_prm	(	apo_charmm_context *	context,
		apo_charmm_parameters *	parameters
	)

Sets the context's CHARMM parameter set.

The input handle is borrowed. On success, the context handle retains shared native ownership of the parameter object, so the caller may destroy the original parameter handle.

Parameters

[in,out]	context	Borrowed non-NULL context handle to modify.
[in]	parameters	Borrowed non-NULL parameter handle containing a live native object.

Return values

APO_STATUS_OK	The parameter object was retained.
APO_STATUS_INVALID_ARGUMENT	A handle or native object is NULL, or completed force configuration is invalid.
APO_STATUS_CUDA_ERROR	Triggered force-manager initialization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	Parameter or force initialization failed for another runtime condition.

apo_charmm_context_set_psf()

apo_status apo_charmm_context_set_psf	(	apo_charmm_context *	context,
		apo_charmm_psf *	psf
	)

Sets the context's PSF and imports atom charges and masses.

The input handle is borrowed. On success, the context handle retains shared native ownership of the PSF object.

Parameters

[in,out]	context	Borrowed non-NULL context handle to modify.
[in]	psf	Borrowed non-NULL PSF handle containing a live native object.

Return values

APO_STATUS_OK	The PSF was retained and its atom data was imported.
APO_STATUS_INVALID_ARGUMENT	A handle or native object is NULL, or the PSF atom count conflicts with the context's established atom count.
APO_STATUS_CUDA_ERROR	Per-atom resizing, transfer, or triggered force initialization failed in CUDA.
APO_STATUS_RUNTIME_ERROR	PSF or force initialization failed for another runtime condition.

apo_charmm_context_set_random_seed()

apo_status apo_charmm_context_set_random_seed	(	apo_charmm_context *	context,
		const uint64_t	seed
	)

Sets the random seed used for generated velocities.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	seed	Unsigned 64-bit dimensionless seed.

Return values

APO_STATUS_OK	The seed was stored.
APO_STATUS_INVALID_ARGUMENT	The context handle or native object is NULL.

apo_charmm_context_set_temperature()

apo_status apo_charmm_context_set_temperature	(	apo_charmm_context *	context,
		const double	temperature
	)

Sets the stored target temperature.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	temperature	Temperature in kelvin. It must be finite and non-negative.

Return values

APO_STATUS_OK	The stored temperature was updated.
APO_STATUS_INVALID_ARGUMENT	The context handle or native object is NULL, or temperature is non-finite or negative.

apo_charmm_context_set_vdw_type()

apo_status apo_charmm_context_set_vdw_type	(	apo_charmm_context *	context,
		const int	vdw_type
	)

Sets the van der Waals model identifier.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	vdw_type	Native model code in the inclusive range [1, 6].

Return values

APO_STATUS_OK	The model identifier was stored.
APO_STATUS_INVALID_ARGUMENT	The context is invalid or vdw_type is outside [1, 6].
APO_STATUS_NOT_INITIALIZED	No force manager is attached.

Warning

Configure the model before force-manager initialization.

apo_charmm_context_set_velocities()

apo_status apo_charmm_context_set_velocities	(	apo_charmm_context *	context,
		const double *	xyz,
		const size_t	xyz_len
	)

Sets velocities while preserving inverse masses.

The buffer contains N consecutive [vx, vy, vz] records in angstroms per AKMA time unit. Values are copied.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	xyz	Borrowed contiguous double buffer. It must be non-NULL.
[in]	xyz_len	Number of scalar elements. It must be nonzero, divisible by three, and exactly 3 * N.

Return values

APO_STATUS_OK	Velocities were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, the length is zero or not divisible by three, or the record count differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	The host-to-device transfer failed.

apo_charmm_context_set_velocities_from_charmm_velocity_file()

apo_status apo_charmm_context_set_velocities_from_charmm_velocity_file	(	apo_charmm_context *	context,
		const char *	path
	)

Loads velocities from a CHARMM velocity file.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	path	Borrowed non-NULL, nonempty, null-terminated path. The string is copied into native storage for the duration of the call and is not retained.

Return values

APO_STATUS_OK	All velocity records were parsed and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle is NULL, path is NULL or empty, or the file atom count differs from the context atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_RUNTIME_ERROR	The file cannot be opened or its atom count or a velocity record cannot be read or parsed.
APO_STATUS_CUDA_ERROR	The final host-to-device transfer failed.

apo_charmm_context_set_velocities_inverse_masses()

apo_status apo_charmm_context_set_velocities_inverse_masses	(	apo_charmm_context *	context,
		const double *	xyzm,
		const size_t	xyzm_len
	)

Sets velocities and inverse masses from a flat host buffer.

The buffer contains N consecutive [vx, vy, vz, inverse_mass] records. Velocity uses angstroms per AKMA time unit and inverse mass uses reciprocal atomic mass units. Values are copied.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	xyzm	Borrowed contiguous double buffer. It must be non-NULL.
[in]	xyzm_len	Number of scalar elements. It must be nonzero, divisible by four, and exactly 4 * N.

Return values

APO_STATUS_OK	Values were copied and transferred.
APO_STATUS_INVALID_ARGUMENT	A handle or pointer is NULL, the length is zero or not divisible by four, or the record count differs from the atom count.
APO_STATUS_NOT_INITIALIZED	The context atom count is not positive.
APO_STATUS_CUDA_ERROR	The host-to-device transfer failed.

apo_charmm_context_use_holonomic_constraints()

apo_status apo_charmm_context_use_holonomic_constraints	(	apo_charmm_context *	context,
		const bool	useHolonomicConstraints
	)

Selects constrained degree-of-freedom accounting.

Parameters

[in,out]	context	Borrowed non-NULL context handle.
[in]	useHolonomicConstraints	true to subtract water and SHAKE constraints from the reported degree-of-freedom count.

Return values

APO_STATUS_OK	The flag and degree-of-freedom count were updated.
APO_STATUS_INVALID_ARGUMENT	The context handle or native object is NULL.
APO_STATUS_NOT_INITIALIZED	The native context has no PSF or no force manager.