SelectionParser Class Reference

Evaluates tokenized CHARMM-style atom-selection expressions. More...

#include <SelectionParser.h>

Static Public Member Functions
static AtomSelection	parse (std::shared_ptr< const CharmmPSF > psf, std::vector< SelectionToken > tokens)
	Parses a complete token vector against a PSF.

Detailed Description

Evaluates tokenized CHARMM-style atom-selection expressions.

The parser is instantiated for one call to parse(). It retains the supplied PSF and token vector while building a result, constructs atom-to-residue and atom-to-group lookup arrays, and evaluates the expression with separate operator and selection stacks. .AND. binds more tightly than .OR.; operators of equal precedence are reduced left to right. Prefix operators are applied after their primary selection or parenthesized expression is read.

Field values come from host-resident CharmmPSF arrays. TYPE maps to PSF atom names, CHEM to atom types, SEGI to segment identifiers, RESI to decimal residue identifiers, RESN to residue names, and BYNU to one-based atom numbers. The parser performs no CUDA allocation, transfer, stream work, or synchronization.

The parser provides no internal locking. The PSF must remain immutable and internally consistent throughout parsing. The public entry point is intended to consume the complete vector returned by SelectionTokenizer, including its terminal SelectionTokenType::End token.

See also

atom_selection

Member Function Documentation

parse()

static AtomSelection SelectionParser::parse ( std::shared_ptr< const CharmmPSF >  psf, std::vector< SelectionToken >  tokens  )

static

Parses a complete token vector against a PSF.

The shared pointer and token vector are passed by value, then moved into a temporary parser. The returned AtomSelection owns independent host storage and retains neither the parser, the token vector, nor the PSF.

Parameters

[in]	psf	Shared pointer to the topology whose host metadata and derived tables are read. The pointer is retained only until parsing finishes and may not be null.
[in]	tokens	Complete token sequence, normally produced by SelectionTokenizer::tokenize. The vector must contain one reachable terminal token after the expression.

Returns

A newly owned selection whose atom count equals psf->getNumAtoms().

Exceptions

ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument if psf is null, the tokens encode an invalid expression or range, or a PSF bonded-neighbor index lies outside the atom range.
ApoCharmmError	With ApoCharmmErrorCode::NotInitialized if the PSF atom count is negative.
ApoCharmmError	With ApoCharmmErrorCode::Runtime if token-stack, operator-stack, residue, group, bonded-connectivity, or field-token invariants fail.
std::bad_alloc	If retained ownership, lookup arrays, stacks, selections, field text, or diagnostics cannot allocate storage.
std::length_error	If a parser container, string, selection, or diagnostic exceeds an implementation-defined limit.

Precondition

Every per-atom PSF metadata array used by the requested fields has at least psf->getNumAtoms() elements.

Residue and group records use inclusive zero-based atom ranges, and direct bonded-connectivity entries contain valid zero-based indices.

Postcondition

On success, the supplied PSF object is unchanged.

Warning

A token vector with no reachable terminal token is an internal-use contract violation and can report ApoCharmmErrorCode::Runtime rather than a user syntax error.