Declares the C ABI CHARMM PSF interface. More...

Typedefs
typedef struct apo_charmm_psf	apo_charmm_psf
	Represents an opaque owning handle to parsed CHARMM PSF state.

Functions
apo_status	apo_charmm_psf_create (apo_charmm_psf *out, const char path)
	Creates an owning PSF handle from one file.

void	apo_charmm_psf_destroy (apo_charmm_psf *psf)
	Destroys an owning PSF handle.

apo_status	apo_charmm_psf_get_num_atoms (size_t num_atoms, const apo_charmm_psf psf)
	Returns the atom count.

apo_status	apo_charmm_psf_get_num_bonds (size_t num_bonds, const apo_charmm_psf psf)
	Returns the bond count.

apo_status	apo_charmm_psf_get_num_angles (size_t num_angles, const apo_charmm_psf psf)
	Returns the angle count.

apo_status	apo_charmm_psf_get_num_dihedrals (size_t num_dihedrals, const apo_charmm_psf psf)
	Returns the proper-dihedral count.

apo_status	apo_charmm_psf_get_num_impropers (size_t num_impropers, const apo_charmm_psf psf)
	Returns the improper-dihedral count.

apo_status	apo_charmm_psf_get_num_cross_terms (size_t num_cross_terms, const apo_charmm_psf psf)
	Returns the CMAP cross-term count.

apo_status	apo_charmm_psf_get_segment_identifiers (char segis, const size_t len, const apo_charmm_psf psf)
	Copies fixed-width per-atom segment identifiers.

apo_status	apo_charmm_psf_get_residue_identifiers (int resis, const size_t len, const apo_charmm_psf psf)
	Copies per-atom residue identifiers.

apo_status	apo_charmm_psf_get_residue_names (char resns, const size_t len, const apo_charmm_psf psf)
	Copies fixed-width per-atom residue names.

apo_status	apo_charmm_psf_get_atom_names (char anams, const size_t len, const apo_charmm_psf psf)
	Copies fixed-width per-atom atom names.

apo_status	apo_charmm_psf_get_atom_types (char atyps, const size_t len, const apo_charmm_psf psf)
	Copies fixed-width per-atom CHARMM atom types.

apo_status	apo_charmm_psf_get_charges (double charges, const size_t len, const apo_charmm_psf psf)
	Copies all per-atom partial charges.

apo_status	apo_charmm_psf_get_masses (double masses, const size_t len, const apo_charmm_psf psf)
	Copies all per-atom masses.

apo_status	apo_charmm_psf_get_net_charge (double net_charge, const apo_charmm_psf psf)
	Computes and returns the net partial charge.

apo_status	apo_charmm_psf_get_total_mass (double total_mass, const apo_charmm_psf psf)
	Computes and returns the total mass.

apo_status	apo_charmm_psf_get_file_name (char file_name, const size_t len, const apo_charmm_psf psf)
	Copies the stored PSF path into a caller-owned character buffer.

Detailed Description

Declares the C ABI CHARMM PSF interface.

Typedef Documentation

◆ apo_charmm_psf

typedef struct apo_charmm_psf apo_charmm_psf

Represents an opaque owning handle to parsed CHARMM PSF state.

A handle returned by apo_charmm_psf_create owns one shared native CharmmPSF object. Release the handle exactly once with apo_charmm_psf_destroy. Inputs named psf in other C ABI functions are borrowed for the duration of the call and are never retained by those getter functions.

ForceManager and CharmmContext handles created from this PSF copy native shared ownership. Destroying the source PSF handle therefore does not invalidate those already-created collaborators.

Every status-returning function clears the calling thread's previous diagnostic on entry. Success leaves an empty diagnostic. Failure leaves nonempty thread-local text available through apo_last_error until the next guarded C ABI call on the same thread or thread exit. Copy the diagnostic before making another status-returning call.

Handles provide no internal synchronization. Do not destroy a handle concurrently with a call that uses it.

See also: charmm_psf

Function Documentation

◆ apo_charmm_psf_create()

apo_status apo_charmm_psf_create	(	apo_charmm_psf **	out,
		const char *	path
	)

Creates an owning PSF handle from one file.

The borrowed C string is copied into a native string before return. Parsing occurs synchronously. The file-name extension is not validated. The native parser requires the supported PSF sections described on CharmmPSF and constructs derived residue, water, connected-component, and exclusion state.

Parameters

[out]	out	Non-NULL output slot. It is set to `NULL` before path validation and receives a newly owned handle on success.
[in]	path	Borrowed non-NULL, non-empty, null-terminated PSF path. The pointer and its storage are not retained.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if out is NULL, or if path is NULL or empty.; APO_STATUS_RUNTIME_ERROR if the file cannot be opened or read, a required section or record is missing, a numeric field or record shape is invalid, a topology index or count is unsupported, host allocation fails, or another uncategorized C++ exception is caught.; APO_STATUS_CUDA_ERROR if construction of derived CudaContainer state encounters a CUDA allocation, copy, launch, or cleanup failure.

Postcondition: On success, *out is non-NULL and owned by the caller.; On failure after out is validated, *out remains NULL.; The returned status and the calling thread's apo_last_error follow the diagnostic contract documented for apo_charmm_psf.

◆ apo_charmm_psf_destroy()

void apo_charmm_psf_destroy ( apo_charmm_psf * psf )

Destroys an owning PSF handle.

Parameters

[in] psf Owned handle to destroy, or NULL. Passing NULL is accepted and has no effect.

Postcondition: No exception crosses the C ABI boundary.; A normally returning call preserves the calling thread's previous apo_last_error diagnostic instead of clearing it.

Note: Do not use the handle after this call. The underlying native PSF can remain alive while a previously created ForceManager or CharmmContext retains shared ownership.

◆ apo_charmm_psf_get_atom_names()

apo_status apo_charmm_psf_get_atom_names	(	char *	anams,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies fixed-width per-atom atom names.

Parameters

[out]	anams	Borrowed caller-owned output buffer containing at least `8 * num_atoms` `char` elements. Atom `i` occupies one eight-byte field. Fields are right-padded with ASCII spaces, are not null-terminated, and are silently truncated to eight bytes. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `char` elements available in `anams`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with anams == NULL or len < 8 * num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the required prefix contains the fixed-width fields; any elements beyond that prefix are unchanged.; On failure, the caller's buffer contents remain unchanged.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_atom_types()

apo_status apo_charmm_psf_get_atom_types	(	char *	atyps,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies fixed-width per-atom CHARMM atom types.

Parameters

[out]	atyps	Borrowed caller-owned output buffer containing at least `8 * num_atoms` `char` elements. Atom `i` occupies one eight-byte field. Fields are right-padded with ASCII spaces, are not null-terminated, and are silently truncated to eight bytes. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `char` elements available in `atyps`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with atyps == NULL or len < 8 * num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the required prefix contains the fixed-width fields; any elements beyond that prefix are unchanged.; On failure, the caller's buffer contents remain unchanged.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_charges()

apo_status apo_charmm_psf_get_charges	(	double *	charges,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies all per-atom partial charges.

Parameters

[out]	charges	Borrowed caller-owned output buffer containing at least `num_atoms` `double` elements. Values are written in atom-record order and use elementary-charge units. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `double` elements available in `charges`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with charges == NULL or len < num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the first num_atoms elements contain copied charges; any additional elements are unchanged.; On failure, the caller's buffer remains unchanged and can contain stale values.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_file_name()

apo_status apo_charmm_psf_get_file_name	(	char *	file_name,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies the stored PSF path into a caller-owned character buffer.

Parameters

[out]	file_name	Borrowed caller-owned buffer containing at least `stored_path_length` `char` elements. The function writes exactly `len` elements: the path bytes first and ASCII spaces in all remaining positions. No null terminator is written. `NULL` is accepted only when the stored path is empty.
[in]	len	Number of `char` elements available in `file_name`. The value must be at least the stored path length.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty path is requested with file_name == NULL or len smaller than the stored path length.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, all len output elements have been overwritten.; On failure, the caller's buffer remains unchanged and can contain stale values.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

Warning: The current C ABI exposes no companion function that returns the required path-buffer length.

◆ apo_charmm_psf_get_masses()

apo_status apo_charmm_psf_get_masses	(	double *	masses,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies all per-atom masses.

Parameters

[out]	masses	Borrowed caller-owned output buffer containing at least `num_atoms` `double` elements. Values are written in atom-record order and use atomic mass units. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `double` elements available in `masses`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with masses == NULL or len < num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the first num_atoms elements contain copied masses; any additional elements are unchanged.; On failure, the caller's buffer remains unchanged and can contain stale values.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_net_charge()

apo_status apo_charmm_psf_get_net_charge	(	double *	net_charge,
		const apo_charmm_psf *	psf
	)

Computes and returns the net partial charge.

Parameters

[out]	net_charge	Non-NULL output slot. It is set to `0.0` before handle validation and receives the sum in elementary-charge units on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if net_charge is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_NOT_INITIALIZED if the native atom count is negative.; APO_STATUS_RUNTIME_ERROR if the native charge-vector length differs from the atom count or another uncategorized C++ exception is caught.

Postcondition: On success, *net_charge contains the computed net charge.; On failure after net_charge is validated, *net_charge remains 0.0.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_angles()

apo_status apo_charmm_psf_get_num_angles	(	size_t *	num_angles,
		const apo_charmm_psf *	psf
	)

Returns the angle count.

Parameters

[out]	num_angles	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless angle count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_angles is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native angle count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_angles contains the nonnegative angle count.; On failure after num_angles is validated, *num_angles remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_atoms()

apo_status apo_charmm_psf_get_num_atoms	(	size_t *	num_atoms,
		const apo_charmm_psf *	psf
	)

Returns the atom count.

Parameters

[out]	num_atoms	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless atom count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_atoms is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native atom count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_atoms contains the nonnegative atom count.; On failure after num_atoms is validated, *num_atoms remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_bonds()

apo_status apo_charmm_psf_get_num_bonds	(	size_t *	num_bonds,
		const apo_charmm_psf *	psf
	)

Returns the bond count.

Parameters

[out]	num_bonds	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless bond count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_bonds is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native bond count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_bonds contains the nonnegative bond count.; On failure after num_bonds is validated, *num_bonds remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_cross_terms()

apo_status apo_charmm_psf_get_num_cross_terms	(	size_t *	num_cross_terms,
		const apo_charmm_psf *	psf
	)

Returns the CMAP cross-term count.

Parameters

[out]	num_cross_terms	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless cross-term count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_cross_terms is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native cross-term count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_cross_terms contains the nonnegative count.; On failure after num_cross_terms is validated, *num_cross_terms remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_dihedrals()

apo_status apo_charmm_psf_get_num_dihedrals	(	size_t *	num_dihedrals,
		const apo_charmm_psf *	psf
	)

Returns the proper-dihedral count.

Parameters

[out]	num_dihedrals	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless proper-dihedral count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_dihedrals is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native proper-dihedral count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_dihedrals contains the nonnegative count.; On failure after num_dihedrals is validated, *num_dihedrals remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_num_impropers()

apo_status apo_charmm_psf_get_num_impropers	(	size_t *	num_impropers,
		const apo_charmm_psf *	psf
	)

Returns the improper-dihedral count.

Parameters

[out]	num_impropers	Non-NULL output slot. It is set to zero before handle validation and receives the dimensionless improper-dihedral count on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if num_impropers is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_RUNTIME_ERROR if the native improper-dihedral count is negative or an uncategorized C++ exception is caught.

Postcondition: On success, *num_impropers contains the nonnegative count.; On failure after num_impropers is validated, *num_impropers remains zero.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_residue_identifiers()

apo_status apo_charmm_psf_get_residue_identifiers	(	int *	resis,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies per-atom residue identifiers.

Parameters

[out]	resis	Borrowed caller-owned output buffer containing at least `num_atoms` `int` elements. Values are dimensionless and are written in atom-record order. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `int` elements available in `resis`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with resis == NULL or len < num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the first num_atoms elements contain the identifiers; any additional elements are unchanged.; On failure, the caller's buffer contents remain unchanged and can therefore contain stale values.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_residue_names()

apo_status apo_charmm_psf_get_residue_names	(	char *	resns,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies fixed-width per-atom residue names.

Parameters

[out]	resns	Borrowed caller-owned output buffer containing at least `8 * num_atoms` `char` elements. Atom `i` occupies one eight-byte field. Fields are right-padded with ASCII spaces, are not null-terminated, and are silently truncated to eight bytes. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `char` elements available in `resns`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with resns == NULL or len < 8 * num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the required prefix contains the fixed-width fields; any elements beyond that prefix are unchanged.; On failure, the caller's buffer contents remain unchanged.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_segment_identifiers()

apo_status apo_charmm_psf_get_segment_identifiers	(	char *	segis,
		const size_t	len,
		const apo_charmm_psf *	psf
	)

Copies fixed-width per-atom segment identifiers.

Parameters

[out]	segis	Borrowed caller-owned output buffer containing at least `8 * num_atoms` `char` elements. Atom `i` occupies `segis[8 * i]` through `segis[8 * i + 7]`. Fields are right-padded with ASCII spaces, are not null-terminated, and are silently truncated to eight bytes. `NULL` is accepted only when the native vector is empty.
[in]	len	Number of `char` elements available in `segis`.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if psf is invalid, or if a nonempty result is requested with segis == NULL or len < 8 * num_atoms.; APO_STATUS_RUNTIME_ERROR if construction of a validation diagnostic or another uncategorized C++ operation throws.

Postcondition: On success, the required prefix contains the fixed-width fields; any elements beyond that prefix are unchanged.; On failure, the caller's buffer contents remain unchanged and can therefore contain stale values.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

◆ apo_charmm_psf_get_total_mass()

apo_status apo_charmm_psf_get_total_mass	(	double *	total_mass,
		const apo_charmm_psf *	psf
	)

Computes and returns the total mass.

Parameters

[out]	total_mass	Non-NULL output slot. It is set to `0.0` before handle validation and receives the sum in atomic mass units on success.
[in]	psf	Borrowed live PSF handle.

Returns: APO_STATUS_OK on success.; APO_STATUS_INVALID_ARGUMENT if total_mass is NULL, psf is NULL, or the handle has no native object.; APO_STATUS_NOT_INITIALIZED if the native atom count is negative.; APO_STATUS_RUNTIME_ERROR if the native mass-vector length differs from the atom count or another uncategorized C++ exception is caught.

Postcondition: On success, *total_mass contains the computed total mass.; On failure after total_mass is validated, *total_mass remains 0.0.; Status and apo_last_error follow the apo_charmm_psf diagnostic contract.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ apo_charmm_psf

Function Documentation

◆ apo_charmm_psf_create()

◆ apo_charmm_psf_destroy()

◆ apo_charmm_psf_get_atom_names()

◆ apo_charmm_psf_get_atom_types()

◆ apo_charmm_psf_get_charges()

◆ apo_charmm_psf_get_file_name()

◆ apo_charmm_psf_get_masses()

◆ apo_charmm_psf_get_net_charge()

◆ apo_charmm_psf_get_num_angles()

◆ apo_charmm_psf_get_num_atoms()

◆ apo_charmm_psf_get_num_bonds()

◆ apo_charmm_psf_get_num_cross_terms()

◆ apo_charmm_psf_get_num_dihedrals()

◆ apo_charmm_psf_get_num_impropers()

◆ apo_charmm_psf_get_residue_identifiers()

◆ apo_charmm_psf_get_residue_names()

◆ apo_charmm_psf_get_segment_identifiers()

◆ apo_charmm_psf_get_total_mass()