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.

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. The returned object does not retain this selector or its PSF.

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. 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.