AtomSelector.h File Reference

Declares the C ABI atom-selection parser interface. More...

Typedefs
typedef struct apo_atom_selector	apo_atom_selector
	Represents an owned atom-selection evaluator in the C ABI.

Functions
apo_status	apo_atom_selector_create (apo_atom_selector **out, const apo_charmm_psf *psf)
	Creates an atom selector for a PSF.
void	apo_atom_selector_destroy (apo_atom_selector *selector)
	Destroys an owned atom-selector handle.
apo_status	apo_atom_selector_select (apo_atom_selection **out, const apo_atom_selector *selector, const char *selection_string)
	Evaluates one atom-selection expression.
apo_status	apo_atom_selector_select_atom (apo_atom_reference **out, const apo_atom_selector *selector, const char *selection_string)
	Evaluates one expression that must select exactly one atom.

Detailed Description

Declares the C ABI atom-selection parser interface.

Typedef Documentation

apo_atom_selector

typedef struct apo_atom_selector apo_atom_selector

Represents an owned atom-selection evaluator in the C ABI.

A selector shares ownership of the native PSF supplied at construction. The PSF handle is borrowed by apo_atom_selector_create and may be destroyed after creation; the selector keeps the native topology alive independently. The topology is shared rather than cloned, so mutation through another native owner can affect later selections.

Selection calls read host-resident PSF metadata. The set-valued apo_atom_selector_select operation produces an independently owned apo_atom_selection containing zero or more atoms. The exact-one apo_atom_selector_select_atom operation requires exactly one selected atom and produces an independently owned apo_atom_reference that keeps the native PSF alive. No CUDA allocation, transfer, stream work, or synchronization is performed by the selector.

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. Do not overlap destruction with another call, and keep the shared PSF immutable during selection.

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

apo_status apo_atom_selector_create	(	apo_atom_selector **	out,
		const apo_charmm_psf *	psf
	)

Creates an atom selector for a PSF.

Parameters

[out]	out	Non-NULL address receiving a newly owned selector handle. The function stores NULL before validating psf and leaves *out == NULL on every failure path. Release a successful result with apo_atom_selector_destroy.
[in]	psf	Borrowed live PSF handle. The public handle is not retained, but its native shared object is retained by the new selector. The pointer may not be NULL and must contain an initialized native PSF.

Return values

APO_STATUS_OK	A new owned selector was stored in *out.
APO_STATUS_INVALID_ARGUMENT	out is NULL, psf is NULL, or the PSF handle contains no native object.
APO_STATUS_NOT_INITIALIZED	The native PSF atom count is negative.
APO_STATUS_RUNTIME_ERROR	Allocating the handle, selector, shared ownership, or a diagnostic failed, or another unexpected standard or nonstandard C++ exception crossed the boundary.

Postcondition

On success, *out owns one selector 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_selector_destroy()

void apo_atom_selector_destroy

(

apo_atom_selector *

selector

)

Destroys an owned atom-selector handle.

Parameters

[in]

selector

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

apo_status apo_atom_selector_select	(	apo_atom_selection **	out,
		const apo_atom_selector *	selector,
		const char *	selection_string
	)

Evaluates one atom-selection expression.

selection_string is parsed as a null-terminated byte string. Keywords and dotted operators use ASCII spellings and case-insensitive matching. The C interface cannot represent an embedded null byte; bytes after the first null are not part of the expression. See Atom Selection and Atom References for fields, wildcards, ranges, precedence, and expansion operators.

Parameters

[out]	out	Non-NULL address receiving a newly owned selection handle. The function stores NULL before validating other arguments and leaves *out == NULL on every failure path. Release a successful result with apo_atom_selection_destroy.
[in]	selector	Borrowed live selector handle. The pointer may not be NULL and is not retained.
[in]	selection_string	Borrowed nonempty, null-terminated expression. The bytes are copied during tokenization and are not retained.

Return values

APO_STATUS_OK	A new owned selection was stored in *out.
APO_STATUS_INVALID_ARGUMENT	out is NULL, selector is NULL, the selector handle contains no native object, selection_string is NULL or empty, the expression has a lexical, syntax, operator, range, or parenthesis error, or a stored PSF bonded-neighbor index is out of range.
APO_STATUS_RUNTIME_ERROR	The shared PSF violates parser residue, group, or bonded-connectivity invariants; an internal parser invariant failed; allocation failed; or another unexpected standard or nonstandard C++ exception crossed the boundary.

Precondition

Per-atom PSF metadata arrays remain consistent with the PSF atom count.

Postcondition

On success, *out owns an immutable selection independent of the selector and PSF lifetimes.

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

apo_status apo_atom_selector_select_atom	(	apo_atom_reference **	out,
		const apo_atom_selector *	selector,
		const char *	selection_string
	)

Evaluates one expression that must select exactly one atom.

The same native tokenizer, parser, fields, wildcards, ranges, precedence, and expansion operators used by apo_atom_selector_select are applied. Native AtomSelector code creates a temporary set-valued AtomSelection, validates that its cardinality is exactly one, and then returns the topology-aware atom identity. The temporary selection is destroyed before this function returns.

Parameters

[out]	out	Non-NULL address receiving a newly owned atom-reference handle. The function stores NULL before validating other arguments and leaves *out == NULL on every failure path. Release a successful result with apo_atom_reference_destroy.
[in]	selector	Borrowed live selector handle. The pointer may not be NULL and is not retained.
[in]	selection_string	Borrowed nonempty, null-terminated expression. The bytes are copied during tokenization and are not retained.

Return values

APO_STATUS_OK	A new owned atom reference was stored in *out.
APO_STATUS_INVALID_ARGUMENT	out is NULL, selector is NULL, the selector handle contains no native object, selection_string is NULL or empty, the expression is invalid, a stored PSF bonded-neighbor index is out of range, or the result contains zero or more than one atom.
APO_STATUS_RUNTIME_ERROR	The shared PSF violates parser residue, group, or bonded-connectivity invariants; an internal parser invariant failed; allocation failed; or another unexpected standard or nonstandard C++ exception crossed the boundary.

Precondition

Per-atom PSF metadata arrays remain consistent with the PSF atom count.

Postcondition

On success, *out owns one immutable topology-aware atom reference that remains valid after the selector and public PSF handles are destroyed.

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.