Declares the C ABI topology-aware atom-reference interface. More...

Typedefs
typedef struct apo_atom_reference	apo_atom_reference
	Represents one owned topology-aware atom identity in the C ABI.

Functions
apo_status	apo_atom_reference_create (apo_atom_reference *out, const apo_charmm_psf psf, const int atom_index)
	Creates a reference to one atom in one PSF.

void	apo_atom_reference_destroy (apo_atom_reference *reference)
	Destroys an owned atom-reference handle.

apo_status	apo_atom_reference_get_atom_index (int atom_index, const apo_atom_reference reference)
	Returns the stored zero-based atom index.

apo_status	apo_atom_reference_has_same_topology (bool has_same_topology, const apo_atom_reference reference, const apo_atom_reference *other)
	Tests whether two references retain the same native PSF object.

apo_status	apo_atom_reference_equals (bool equals, const apo_atom_reference reference, const apo_atom_reference *other)
	Tests AtomReference value equality.

Detailed Description

Declares the C ABI topology-aware atom-reference interface.

Typedef Documentation

◆ apo_atom_reference

typedef struct apo_atom_reference apo_atom_reference

Represents one owned topology-aware atom identity in the C ABI.

Each handle owns one native AtomReference. The native value retains shared const ownership of one CharmmPSF object and one validated zero-based atom index. The public PSF handle supplied to apo_atom_reference_create is borrowed for that call; destroying it afterward does not invalidate the reference. A reference returned by apo_atom_selector_select_atom is likewise independent of the selector and public PSF handle lifetimes.

Topology identity is native CharmmPSF object identity. Two separately parsed PSFs are different topologies even when they came from the same path or have identical contents. Equality requires both identical topology and identical atom index.

Atom indices are dimensionless and zero-based. A reference contains no coordinate, force, energy, CUDA allocation, device-transfer, stream, or synchronization state.

A non-NULL pointer must designate a live handle created by apoCHARMM. Passing a dangling, already-destroyed, or foreign pointer has undefined behavior. The implementation provides no internal locking. Concurrent read-only queries require every involved handle and its shared PSF to remain alive and immutable; do not overlap destruction with another call on the same handle.

Status-returning functions clear the calling thread's previous diagnostic at entry. On failure, call apo_last_error immediately on the same thread; its borrowed pointer remains valid only until another diagnostic-changing C ABI call on that thread.

See also: atom_selection

Function Documentation

◆ apo_atom_reference_create()

apo_status apo_atom_reference_create	(	apo_atom_reference **	out,
		const apo_charmm_psf *	psf,
		const int	atom_index
	)

Creates a reference to one atom in one PSF.

Parameters

[out]	out	Non-NULL address receiving a newly owned atom-reference handle. The function stores `NULL` before validating `psf` or `atom_index` and leaves `*out == NULL` on every failure path. Release a successful result with apo_atom_reference_destroy.
[in]	psf	Borrowed live PSF handle. The public handle is not retained, but its native shared ownership is copied into the new AtomReference. The pointer may not be `NULL` and must contain a native PSF object.
[in]	atom_index	Dimensionless zero-based atom index. The value must be in `[0, atom_count)`.

Return values

APO_STATUS_OK	A new owned atom-reference handle was stored in `*out`.
APO_STATUS_INVALID_ARGUMENT	`out` is `NULL`, `psf` is `NULL`, the PSF handle contains no native object, or `atom_index` is outside the native atom range.
APO_STATUS_NOT_INITIALIZED	The native PSF atom count is negative.
APO_STATUS_RUNTIME_ERROR	Handle or native-object allocation failed, or another unexpected standard or nonstandard C++ exception crossed the boundary.

Postcondition: On success, *out owns one reference that keeps the native PSF alive.; On failure with a valid out pointer, *out == NULL.

Note: The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_atom_reference_destroy()

void apo_atom_reference_destroy ( apo_atom_reference * reference )

Destroys an owned atom-reference handle.

Parameters

[in] reference 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 normal destruction preserves the calling thread's existing apo_last_error diagnostic. An internal destruction failure cannot be returned by this void API and may replace that diagnostic.

Warning: The caller must not destroy the same handle twice or use it after destruction.

◆ apo_atom_reference_equals()

apo_status apo_atom_reference_equals	(	bool *	equals,
		const apo_atom_reference *	reference,
		const apo_atom_reference *	other
	)

Tests AtomReference value equality.

Equality is true only when both references retain the same native CharmmPSF object and store the same zero-based atom index.

Parameters

[out]	equals	Non-NULL output pointer. When this pointer is valid, the function stores `false` before validating either handle, then stores the equality result on success.
[in]	reference	Borrowed live first atom-reference handle. The pointer may not be `NULL` and is not retained.
[in]	other	Borrowed live second atom-reference handle. The pointer may not be `NULL` and is not retained.

Return values

APO_STATUS_OK	The equality result was written to `*equals`.
APO_STATUS_INVALID_ARGUMENT	`equals` is `NULL`, either handle is `NULL`, or either handle contains no native AtomReference object.
APO_STATUS_RUNTIME_ERROR	Another unexpected standard or nonstandard C++ exception crossed the query boundary.

Postcondition: On failure after a valid output pointer is accepted, *equals == false.

Note: The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_atom_reference_get_atom_index()

apo_status apo_atom_reference_get_atom_index	(	int *	atom_index,
		const apo_atom_reference *	reference
	)

Returns the stored zero-based atom index.

Parameters

[out]	atom_index	Non-NULL output pointer. When this pointer is valid, the function stores `-1` before validating `reference`, then stores the dimensionless zero-based index on success. Valid atom indices are nonnegative, so `-1` is an invalid sentinel.
[in]	reference	Borrowed live atom-reference handle. The pointer may not be `NULL` and is not retained.

Return values

APO_STATUS_OK	The stored index was written to `*atom_index`.
APO_STATUS_INVALID_ARGUMENT	`atom_index` is `NULL`, `reference` is `NULL`, or the handle contains no native AtomReference object.
APO_STATUS_RUNTIME_ERROR	Another unexpected standard or nonstandard C++ exception crossed the query boundary.

Postcondition: On failure after a valid atom_index pointer is accepted, *atom_index == -1.

Warning: Callers must check the returned status before using *atom_index; the sentinel does not indicate success or replace status handling.

Note: The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

◆ apo_atom_reference_has_same_topology()

apo_status apo_atom_reference_has_same_topology	(	bool *	has_same_topology,
		const apo_atom_reference *	reference,
		const apo_atom_reference *	other
	)

Tests whether two references retain the same native PSF object.

This is a pointer-identity comparison of the retained native CharmmPSF objects. Atom indices do not affect the result.

Parameters

[out]	has_same_topology	Non-NULL output pointer. When this pointer is valid, the function stores `false` before validating either handle, then stores the topology-identity result on success.
[in]	reference	Borrowed live first atom-reference handle. The pointer may not be `NULL` and is not retained.
[in]	other	Borrowed live second atom-reference handle. The pointer may not be `NULL` and is not retained.

Return values

APO_STATUS_OK	The topology comparison was written to `*has_same_topology`.
APO_STATUS_INVALID_ARGUMENT	`has_same_topology` is `NULL`, either handle is `NULL`, or either handle contains no native AtomReference object.
APO_STATUS_RUNTIME_ERROR	Another unexpected standard or nonstandard C++ exception crossed the query boundary.

Postcondition: On failure after a valid output pointer is accepted, *has_same_topology == false.

Note: The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ apo_atom_reference

Function Documentation

◆ apo_atom_reference_create()

◆ apo_atom_reference_destroy()

◆ apo_atom_reference_equals()

◆ apo_atom_reference_get_atom_index()

◆ apo_atom_reference_has_same_topology()