AtomSelector Class Reference

Evaluates CHARMM-style atom-selection expressions against a PSF. More...

#include <AtomSelector.h>

Public Member Functions
	AtomSelector (void)=delete
	Prevents construction without a topology.
	AtomSelector (std::shared_ptr< const CharmmPSF > psf)
	Constructs a selector that shares ownership of a PSF.
AtomSelection	select (const std::string_view selectionString) const
	Evaluates an atom-selection expression against the retained PSF.
AtomReference	selectAtom (const std::string_view selectionString) const
	Evaluates an expression that must select exactly one atom.

Detailed Description

Evaluates CHARMM-style atom-selection expressions against a PSF.

AtomSelector retains shared ownership of one const CharmmPSF and uses its host-resident atom metadata, residue and group intervals, and direct bonded-connectivity table. Each call to select() tokenizes and parses the supplied expression synchronously, then returns an independent AtomSelection. Each call to selectAtom() delegates to select(), requires exactly one selected atom, and returns an AtomReference. AtomSelection results retain neither this selector nor its PSF. AtomReference results share ownership of the same native PSF object.

The selector does not snapshot the topology. Mutating the shared PSF through another non-const owner can change later results or violate parser preconditions. No CUDA allocation, transfer, stream operation, or synchronization is performed by this class.

Compiler-generated copy operations share the same PSF; generated move operations transfer that shared pointer. The class provides no internal locking. Concurrent calls are valid only while the retained PSF remains immutable and no thread destroys the selector.

See also

atom_selection

SelectionTokenizer

SelectionParser

Constructor & Destructor Documentation

AtomSelector()

AtomSelector::AtomSelector ( std::shared_ptr< const CharmmPSF >  psf )

explicit

Constructs a selector that shares ownership of a PSF.

Parameters

[in]

psf

Shared pointer to the topology used by every future selection. The pointer is copied and retained; the PSF is not cloned and may not be null.

Exceptions

ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument if psf is null.
ApoCharmmError	With ApoCharmmErrorCode::NotInitialized if the PSF atom count is negative.
std::bad_alloc	If retained ownership or diagnostic allocation fails.
std::length_error	If a diagnostic exceeds an implementation-defined limit.

Postcondition

The selector retains shared ownership of the same native PSF object.

Member Function Documentation

select()

AtomSelection AtomSelector::select

(

const std::string_view

selectionString

)

const

Evaluates an atom-selection expression against the retained PSF.

Tokenization is case-insensitive for recognized keywords and dotted operators. Matching, ranges, precedence, expansion operators, and wildcard behavior are defined on Atom Selection and Atom References. The input view is borrowed only for this call; token text is copied before parsing and no view is retained.

Parameters

[in]

selectionString

Expression bytes to parse. The view may refer to non-null-terminated storage. Embedded control bytes, including \0, are rejected by the tokenizer.

Returns

A newly owned selection with the same atom count as the retained PSF. The result is independent of this selector and the PSF.

Exceptions

ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument for a lexical or syntax error, an unknown operator, an invalid BYNU range, unmatched parentheses, or an out-of-range neighbor stored in the PSF bonded-connectivity table.
ApoCharmmError	With ApoCharmmErrorCode::Runtime if retained PSF residue, group, or bonded-connectivity state violates parser invariants, or if an internal token or operator-stack invariant fails.
std::bad_alloc	If token, parser-stack, index, selection, result, or diagnostic allocation fails.
std::length_error	If token text, a parser container, a selection, the result, or a diagnostic exceeds an implementation-defined limit.

Precondition

The retained PSF remains alive, has a non-negative atom count, and has per-atom metadata arrays consistent with that count.

Postcondition

The retained PSF and this selector are unchanged.

Note

The parser reads the host mirrors of residue and group containers. It performs no host-to-device or device-to-host transfer and does not synchronize a CUDA stream.

selectAtom()

AtomReference AtomSelector::selectAtom

(

const std::string_view

selectionString

)

const

Evaluates an expression that must select exactly one atom.

This method delegates tokenization, parsing, and all selection-language behavior to select(). It requires exactly one selected atom, copies the sole zero-based index, releases the temporary AtomSelection storage, and returns an AtomReference that retains shared ownership of the selector's PSF.

Parameters

[in]

selectionString

Expression bytes to parse. The view has the same borrowing, termination, and control-byte behavior as for select().

Returns

A topology-aware reference to the sole selected atom. The result remains valid after this selector and the caller's other shared owners of the PSF are destroyed.

Exceptions

ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument for any lexical, syntax, range, or connectivity-index error reported by select(), or when the resulting selection contains zero or multiple atoms.
ApoCharmmError	With ApoCharmmErrorCode::Runtime for any malformed retained PSF or internal parser state reported by select().
std::bad_alloc	If token, parser-stack, selection, index-vector, or diagnostic allocation fails.
std::length_error	If token text, a parser container, selection storage, an index vector, or a diagnostic exceeds an implementation-defined limit.

Precondition

The retained PSF satisfies the same requirements as for select().

Postcondition

The retained PSF and this selector are unchanged.

No temporary AtomSelection or its bitset storage is retained by the returned reference.