ForceManager.h File Reference

Declares the C ABI force-manager interface. More...

Typedefs
typedef struct apo_force_manager	apo_force_manager
	Represents an opaque owning ForceManager handle.

Functions
apo_status	apo_force_manager_create (apo_force_manager **out, const apo_charmm_psf *psf, const apo_charmm_parameters *parameters)
	Creates an owning ForceManager handle.
void	apo_force_manager_destroy (apo_force_manager *force_manager)
	Destroys an owning ForceManager handle.
apo_status	apo_force_manager_set_box_dimensions (apo_force_manager *force_manager, const double *box_dimensions, const size_t box_dimensions_len)
	Sets three orthorhombic box dimensions.
apo_status	apo_force_manager_set_kappa (apo_force_manager *force_manager, const double kappa)
	Sets the Ewald splitting parameter.
apo_status	apo_force_manager_set_cutoff (apo_force_manager *force_manager, const double cutoff)
	Sets the direct-space pair-list cutoff.
apo_status	apo_force_manager_set_ctonnb (apo_force_manager *force_manager, const double ctonnb)
	Sets the outer switching distance exposed as ctonnb.
apo_status	apo_force_manager_set_ctofnb (apo_force_manager *force_manager, const double ctofnb)
	Sets the inner switching distance exposed as ctofnb.
apo_status	apo_force_manager_set_fft_grid (apo_force_manager *force_manager, const int *grid, const size_t grid_len)
	Sets the three PME FFT grid dimensions.
apo_status	apo_force_manager_set_pme_spline_order (apo_force_manager *force_manager, const int order)
	Sets the PME interpolation spline order.
apo_status	apo_force_manager_set_periodic_boundary_condition (apo_force_manager *force_manager, const apo_pbc pbc)
	Sets the periodic boundary condition.
apo_status	apo_force_manager_set_vdw_type (apo_force_manager *force_manager, const int vdw_type)
	Sets the native van der Waals model code.
apo_status	apo_force_manager_set_print_energy_decomposition (apo_force_manager *force_manager, const bool flag)
	Enables or disables native energy-decomposition printing.
apo_status	apo_force_manager_get_num_atoms (int *num_atoms, const apo_force_manager *force_manager)
	Returns the PSF atom count.
apo_status	apo_force_manager_is_initialized (bool *flag, const apo_force_manager *force_manager)
	Reports whether native initialization completed.
apo_status	apo_force_manager_get_box_dimensions (double *box_dimensions, const size_t box_dimensions_len, const apo_force_manager *force_manager)
	Copies the three stored box dimensions.
apo_status	apo_force_manager_get_kappa (double *kappa, const apo_force_manager *force_manager)
	Returns the stored Ewald splitting parameter.
apo_status	apo_force_manager_get_cutoff (double *cutoff, const apo_force_manager *force_manager)
	Returns the stored pair-list cutoff.
apo_status	apo_force_manager_get_ctonnb (double *ctonnb, const apo_force_manager *force_manager)
	Returns the outer switching distance exposed as ctonnb.
apo_status	apo_force_manager_get_ctofnb (double *ctofnb, const apo_force_manager *force_manager)
	Returns the inner switching distance exposed as ctofnb.
apo_status	apo_force_manager_get_fft_grid (int *grid, const size_t grid_len, const apo_force_manager *force_manager)
	Copies the three stored PME FFT dimensions.
apo_status	apo_force_manager_get_pme_spline_order (int *order, const apo_force_manager *force_manager)
	Returns the PME interpolation spline order.
apo_status	apo_force_manager_get_periodic_boundary_condition (apo_pbc *pbc, const apo_force_manager *force_manager)
	Returns the stored periodic boundary condition.
apo_status	apo_force_manager_get_vdw_type (int *vdw_type, const apo_force_manager *force_manager)
	Returns the native van der Waals model code.
apo_status	apo_force_manager_is_composite (bool *flag, const apo_force_manager *force_manager)
	Reports whether the native manager is composite.

Detailed Description

Declares the C ABI force-manager interface.

Typedef Documentation

apo_force_manager

typedef struct apo_force_manager apo_force_manager

Represents an opaque owning ForceManager handle.

A handle created by apo_force_manager_create owns a native manager and retains native shared ownership of the PSF and parameter set used to create it. The original PSF and parameter C handles may therefore be destroyed without invalidating the manager.

Release an owned handle exactly once with apo_force_manager_destroy. Inputs named force_manager in other functions are borrowed for the duration of the call.

Status-returning functions clear the calling thread's previous native diagnostic on entry. A successful call leaves that diagnostic empty. A failed call leaves nonempty thread-local text available through apo_last_error until the next guarded C ABI call on the same thread or until thread exit. Handles provide no internal synchronization for concurrent host mutation or force-manager use.

Function Documentation

apo_force_manager_create()

apo_status apo_force_manager_create	(	apo_force_manager **	out,
		const apo_charmm_psf *	psf,
		const apo_charmm_parameters *	parameters
	)

Creates an owning ForceManager handle.

The function retains the native PSF and parameter objects and constructs an uninitialized native manager. No force backends are initialized by this call.

Parameters

[out]	out	Non-null output slot. It is set to NULL before collaborator validation and receives a newly owned handle on success.
[in]	psf	Borrowed non-null live PSF handle.
[in]	parameters	Borrowed non-null live parameter handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if out, psf, or parameters is NULL, or if either collaborator handle contains no native object.

APO_STATUS_CUDA_ERROR if native manager construction fails while allocating or initializing CUDA-backed virial storage.

APO_STATUS_RUNTIME_ERROR if handle, manager, or native shared-state allocation fails or another uncategorized standard exception is caught.

Postcondition

On success, *out is non-null and owned by the caller.

On failure after validating out, *out remains NULL.

Success clears the calling thread's diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_destroy()

void apo_force_manager_destroy

(

apo_force_manager *

force_manager

)

Destroys an owning ForceManager handle.

Parameters

[in]

force_manager

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

Postcondition

Native destruction is contained within a non-throwing C ABI boundary.

A normal call preserves the calling thread's previous apo_last_error diagnostic rather than clearing it.

Note

Do not use the handle after this call.

apo_force_manager_get_box_dimensions()

apo_status apo_force_manager_get_box_dimensions	(	double *	box_dimensions,
		const size_t	box_dimensions_len,
		const apo_force_manager *	force_manager
	)

Copies the three stored box dimensions.

Parameters

[out]	box_dimensions	Non-null output buffer with capacity for at least three double values. The first three elements receive [x, y, z] lengths in angstroms. Elements beyond index 2 are untouched.
[in]	box_dimensions_len	Capacity of box_dimensions; it must be at least 3.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle or output buffer is invalid or box_dimensions_len is less than 3.

APO_STATUS_RUNTIME_ERROR if copying the native box vector or another uncategorized standard operation fails.

Postcondition

On failure, output-buffer contents remain unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_ctofnb()

apo_status apo_force_manager_get_ctofnb	(	double *	ctofnb,
		const apo_force_manager *	force_manager
	)

Returns the inner switching distance exposed as ctofnb.

Parameters

[out]	ctofnb	Non-null output pointer receiving the value in angstroms.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or ctofnb is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *ctofnb remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_ctonnb()

apo_status apo_force_manager_get_ctonnb	(	double *	ctonnb,
		const apo_force_manager *	force_manager
	)

Returns the outer switching distance exposed as ctonnb.

Parameters

[out]	ctonnb	Non-null output pointer receiving the value in angstroms.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or ctonnb is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *ctonnb remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_cutoff()

apo_status apo_force_manager_get_cutoff	(	double *	cutoff,
		const apo_force_manager *	force_manager
	)

Returns the stored pair-list cutoff.

Parameters

[out]	cutoff	Non-null output pointer receiving the value in angstroms as a double.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or cutoff is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *cutoff remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_fft_grid()

apo_status apo_force_manager_get_fft_grid	(	int *	grid,
		const size_t	grid_len,
		const apo_force_manager *	force_manager
	)

Copies the three stored PME FFT dimensions.

Parameters

[out]	grid	Non-null output buffer with capacity for at least three int values. The first three elements receive [nfftx, nffty, nfftz]; trailing elements are untouched.
[in]	grid_len	Capacity of grid; it must be at least 3.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle or output buffer is invalid or grid_len is less than 3.

APO_STATUS_RUNTIME_ERROR if native vector allocation or another uncategorized standard operation fails.

Postcondition

On failure, output-buffer contents remain unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_kappa()

apo_status apo_force_manager_get_kappa	(	double *	kappa,
		const apo_force_manager *	force_manager
	)

Returns the stored Ewald splitting parameter.

Parameters

[out]	kappa	Non-null output pointer receiving the value in inverse angstroms as a double.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or kappa is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *kappa remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_num_atoms()

apo_status apo_force_manager_get_num_atoms	(	int *	num_atoms,
		const apo_force_manager *	force_manager
	)

Returns the PSF atom count.

Parameters

[out]	num_atoms	Non-null output pointer. It is set to 0 before the manager handle is validated, then replaced with the PSF atom count on success.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if num_atoms is NULL or the handle is invalid.

APO_STATUS_NOT_INITIALIZED if the native manager has no PSF.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On success, *num_atoms contains the current native count.

On failure after validating num_atoms, *num_atoms is 0.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_periodic_boundary_condition()

apo_status apo_force_manager_get_periodic_boundary_condition	(	apo_pbc *	pbc,
		const apo_force_manager *	force_manager
	)

Returns the stored periodic boundary condition.

Parameters

[out]	pbc	Non-null output pointer receiving a declared apo_pbc value.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle or output pointer is invalid, or if the native manager contains an unknown PBC value.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *pbc remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_pme_spline_order()

apo_status apo_force_manager_get_pme_spline_order	(	int *	order,
		const apo_force_manager *	force_manager
	)

Returns the PME interpolation spline order.

Parameters

[out]	order	Non-null output pointer receiving the dimensionless order.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or order is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *order remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_get_vdw_type()

apo_status apo_force_manager_get_vdw_type	(	int *	vdw_type,
		const apo_force_manager *	force_manager
	)

Returns the native van der Waals model code.

Parameters

[out]	vdw_type	Non-null output pointer receiving the stored integer code.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or vdw_type is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *vdw_type remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_is_composite()

apo_status apo_force_manager_is_composite	(	bool *	flag,
		const apo_force_manager *	force_manager
	)

Reports whether the native manager is composite.

Parameters

[out]	flag	Non-null output pointer receiving the native result.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or flag is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, *flag remains unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_is_initialized()

apo_status apo_force_manager_is_initialized	(	bool *	flag,
		const apo_force_manager *	force_manager
	)

Reports whether native initialization completed.

Parameters

[out]	flag	Non-null output pointer receiving the native initialized flag on success.
[in]	force_manager	Borrowed non-null live manager handle.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or flag is NULL.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On failure, the previous contents of *flag remain unchanged.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_box_dimensions()

apo_status apo_force_manager_set_box_dimensions	(	apo_force_manager *	force_manager,
		const double *	box_dimensions,
		const size_t	box_dimensions_len
	)

Sets three orthorhombic box dimensions.

The values are copied before return. Existing native and subscribed force objects receive the update when present.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	box_dimensions	Non-null buffer of exactly three double values in [x, y, z] order, in angstroms.
[in]	box_dimensions_len	Number of elements in box_dimensions; it must be exactly 3.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle or buffer is invalid, the length is not 3, or any value is non-finite or not positive.

APO_STATUS_CUDA_ERROR if an existing native or subscribed force reports a categorized CUDA failure while receiving the box.

APO_STATUS_RUNTIME_ERROR if temporary native vector allocation or another uncategorized native operation fails.

Postcondition

On success, the manager stores the copied dimensions.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

Warning

A downstream force failure can occur after the manager and earlier force objects have accepted the new box.

apo_force_manager_set_ctofnb()

apo_status apo_force_manager_set_ctofnb	(	apo_force_manager *	force_manager,
		const double	ctofnb
	)

Sets the inner switching distance exposed as ctofnb.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	ctofnb	Finite positive distance in angstroms. The C double is narrowed to native float.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or the narrowed value is non-finite or not positive.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

Note

The current native backend uses this as the distance at which switching begins and does not validate its ordering relative to ctonnb.

apo_force_manager_set_ctonnb()

apo_status apo_force_manager_set_ctonnb	(	apo_force_manager *	force_manager,
		const double	ctonnb
	)

Sets the outer switching distance exposed as ctonnb.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	ctonnb	Finite positive distance in angstroms. The C double is narrowed to native float.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or the narrowed value is non-finite or not positive.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

Note

The current native backend uses this as the distance at which switching reaches zero and does not validate its ordering relative to ctofnb.

apo_force_manager_set_cutoff()

apo_status apo_force_manager_set_cutoff	(	apo_force_manager *	force_manager,
		const double	cutoff
	)

Sets the direct-space pair-list cutoff.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	cutoff	Finite positive distance in angstroms. The C double is narrowed to native float.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or the narrowed cutoff is non-finite or not positive.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

Note

Native initialization later requires the cutoff not to exceed half the X box length.

apo_force_manager_set_fft_grid()

apo_status apo_force_manager_set_fft_grid	(	apo_force_manager *	force_manager,
		const int *	grid,
		const size_t	grid_len
	)

Sets the three PME FFT grid dimensions.

The input values are copied before return.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	grid	Non-null buffer of exactly three positive int values in [x, y, z] axis order.
[in]	grid_len	Number of elements in grid; it must be exactly 3.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle or buffer is invalid, the length is not 3, or any grid value is not positive.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_kappa()

apo_status apo_force_manager_set_kappa	(	apo_force_manager *	force_manager,
		const double	kappa
	)

Sets the Ewald splitting parameter.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	kappa	Finite non-negative value in inverse angstroms. The C double is narrowed to native float before validation and storage.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or the narrowed value is non-finite or negative.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_periodic_boundary_condition()

apo_status apo_force_manager_set_periodic_boundary_condition	(	apo_force_manager *	force_manager,
		const apo_pbc	pbc
	)

Sets the periodic boundary condition.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	pbc	One of APO_PBC_NONE, APO_PBC_P1, or APO_PBC_P21.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or pbc is not a declared apo_pbc value.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

On success, the native manager's initialized flag is cleared.

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_pme_spline_order()

apo_status apo_force_manager_set_pme_spline_order	(	apo_force_manager *	force_manager,
		const int	order
	)

Sets the PME interpolation spline order.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	order	Positive dimensionless spline order.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or order is not positive.

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_print_energy_decomposition()

apo_status apo_force_manager_set_print_energy_decomposition	(	apo_force_manager *	force_manager,
		const bool	flag
	)

Enables or disables native energy-decomposition printing.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	flag	Whether energy-producing native force calculations should print their decomposition to standard output.

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid.

APO_STATUS_RUNTIME_ERROR if an uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.

apo_force_manager_set_vdw_type()

apo_status apo_force_manager_set_vdw_type	(	apo_force_manager *	force_manager,
		const int	vdw_type
	)

Sets the native van der Waals model code.

Parameters

[in]	force_manager	Borrowed non-null live manager handle.
[in]	vdw_type	Integer model code in [1, 6].

Returns

APO_STATUS_OK on success.

APO_STATUS_INVALID_ARGUMENT if the handle is invalid or vdw_type is outside [1, 6].

APO_STATUS_RUNTIME_ERROR if native diagnostic construction or another uncategorized standard operation fails.

Postcondition

Success clears the thread-local diagnostic; failure leaves a nonempty diagnostic available through apo_last_error.