apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
 
Loading...
Searching...
No Matches
Typedefs | Functions
AtomSelection.h File Reference

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

Typedefs

typedef struct apo_atom_selection apo_atom_selection
 Represents an owned, immutable atom-selection result in the C ABI.
 

Functions

void apo_atom_selection_destroy (apo_atom_selection *selection)
 Destroys an owned atom-selection handle.
 
apo_status apo_atom_selection_get_num_atoms (size_t *num_atoms, const apo_atom_selection *selection)
 Returns the number of atoms represented by a selection.
 
apo_status apo_atom_selection_get_num_selected (size_t *num_selected, const apo_atom_selection *selection)
 Returns the number of selected atoms.
 
apo_status apo_atom_selection_get_atom_indices (int *atom_indices, const size_t len, const apo_atom_selection *selection)
 Copies all selected atom indices into a caller-owned buffer.
 
apo_status apo_atom_selection_contains (bool *is_selected, const apo_atom_selection *selection, const int atom_index)
 Tests whether one zero-based atom index is selected.
 

Detailed Description

Declares the C ABI atom-selection result interface.

Typedef Documentation

◆ apo_atom_selection

typedef struct apo_atom_selection apo_atom_selection

Represents an owned, immutable atom-selection result in the C ABI.

A successful apo_atom_selector_select call creates one handle. The handle owns shared native selection storage until apo_atom_selection_destroy is called. Accessors borrow the live handle for the duration of one call and never transfer ownership.

Atom counts and indices are dimensionless. Indices are zero-based and are returned in ascending order. The current C API exposes no mutating operation, CUDA storage, transfer, stream, or synchronization for a selection.

A non-NULL pointer must designate a live handle created by apoCHARMM. Passing a dangling, already-destroyed, or foreign pointer has undefined behavior. Do not overlap destruction with an accessor on another thread.

Status-returning accessors 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_selection_contains()

apo_status apo_atom_selection_contains ( bool *  is_selected,
const apo_atom_selection *  selection,
const int  atom_index 
)

Tests whether one zero-based atom index is selected.

Parameters
[out]is_selectedNon-NULL output pointer. The function stores false before validating the handle or index, then stores the query result on success.
[in]selectionBorrowed live selection handle. The pointer may not be NULL and is not retained.
[in]atom_indexZero-based, dimensionless atom index. The value must be in [0, atom_count).
Return values
APO_STATUS_OK*is_selected contains the selection state.
APO_STATUS_INVALID_ARGUMENTis_selected is NULL, selection is NULL, the handle contains no native object, or atom_index is outside the represented atom range.
APO_STATUS_RUNTIME_ERRORAn unexpected standard or nonstandard C++ exception crossed the query boundary.
Postcondition
On failure after a valid is_selected pointer is accepted, *is_selected == 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_selection_destroy()

void apo_atom_selection_destroy ( apo_atom_selection *  selection)

Destroys an owned atom-selection handle.

Parameters
[in]selectionOwned 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_selection_get_atom_indices()

apo_status apo_atom_selection_get_atom_indices ( int *  atom_indices,
const size_t  len,
const apo_atom_selection *  selection 
)

Copies all selected atom indices into a caller-owned buffer.

The required element count is the value returned by apo_atom_selection_get_num_selected. Exactly that many int elements are written in strictly ascending, zero-based order. Elements at offsets greater than or equal to the required count are left unchanged.

Parameters
[out]atom_indicesBuffer receiving zero-based atom indices. A non-NULL buffer must contain at least len writable int elements. The pointer may be NULL only when the selection contains zero atoms.
[in]lenDimensionless capacity of atom_indices, measured in int elements. The value may exceed the required count.
[in]selectionBorrowed live selection handle. The pointer may not be NULL and is not retained.
Return values
APO_STATUS_OKEvery selected index was copied. For an empty selection, atom_indices == NULL is accepted for any len value and no element is written.
APO_STATUS_INVALID_ARGUMENTselection is NULL, the handle contains no native object, a nonempty result has a NULL buffer, or len is smaller than the selected-atom count.
APO_STATUS_RUNTIME_ERRORAllocating the temporary native index vector failed, or another unexpected standard or nonstandard C++ exception crossed the boundary.
Postcondition
On any verified failure path, caller buffer contents remain unchanged.
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_selection_get_num_atoms()

apo_status apo_atom_selection_get_num_atoms ( size_t *  num_atoms,
const apo_atom_selection *  selection 
)

Returns the number of atoms represented by a selection.

Parameters
[out]num_atomsNon-NULL output pointer. When this pointer is valid, the function stores zero before validating selection, then stores the dimensionless atom count on success.
[in]selectionBorrowed live selection handle. The pointer may not be NULL and is not retained.
Return values
APO_STATUS_OKThe atom count was written to *num_atoms.
APO_STATUS_INVALID_ARGUMENTnum_atoms is NULL, selection is NULL, or the handle contains no native selection object.
APO_STATUS_RUNTIME_ERRORAn unexpected standard or nonstandard C++ exception crossed the accessor boundary.
Postcondition
On failure after a valid num_atoms pointer is accepted, *num_atoms == 0.
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_selection_get_num_selected()

apo_status apo_atom_selection_get_num_selected ( size_t *  num_selected,
const apo_atom_selection *  selection 
)

Returns the number of selected atoms.

Parameters
[out]num_selectedNon-NULL output pointer. When this pointer is valid, the function stores zero before validating selection, then stores a dimensionless value in [0, atom_count] on success.
[in]selectionBorrowed live selection handle. The pointer may not be NULL and is not retained.
Return values
APO_STATUS_OKThe selected-atom count was written to *num_selected.
APO_STATUS_INVALID_ARGUMENTnum_selected is NULL, selection is NULL, or the handle contains no native selection object.
APO_STATUS_RUNTIME_ERRORAn unexpected standard or nonstandard C++ exception crossed the accessor boundary.
Postcondition
On failure after a valid num_selected pointer is accepted, *num_selected == 0.
Note
The function clears the previous thread-local diagnostic at entry. Success leaves it empty; failure leaves text available through apo_last_error.