apocharmm.atom_selector.AtomSelector Class Reference

Evaluates atom-selection expressions against one native PSF. More...

Inherits _ApoObject.

Public Member Functions
None	__init__ (self, CharmmPsf psf)
	Constructs a selector for one parsed PSF.
AtomSelection	select (self, str selection_string)
	Evaluates an atom-selection string as a set-valued result.
AtomReference	selectAtom (self, str selection_string)
	Evaluates an expression that must match exactly one atom.

Detailed Description

Evaluates atom-selection expressions against one native PSF.

The wrapper retains the supplied CharmmPsf Python object in _psf. The native selector also shares ownership of the underlying native PSF, so closing the original PSF wrapper after construction does not invalidate the selector. The topology is shared rather than copied.

Each successful select() call returns a new owning set-valued AtomSelection that remains valid after this selector is closed. Each successful selectAtom() call requires exactly one selected atom and returns a new owning topology-aware AtomReference that retains shared native PSF ownership. Selection evaluation is host-only and performs no CUDA transfer or synchronization.

close(), destroy(), context-manager exit, or finalization releases the selector handle and is idempotent. Calling either selection method after closure raises RuntimeError. The wrapper provides no internal synchronization; do not overlap closure with selection from another thread.

See also

atom_selection

Constructor & Destructor Documentation

__init__()

None apocharmm.atom_selector.AtomSelector.__init__	(		self,
		CharmmPsf	psf
	)

Constructs a selector for one parsed PSF.

The wrapper retains psf as a Python reference and the C ABI copies shared native ownership. No topology data is copied or moved.

Parameters

[in]

psf

Live CharmmPsf instance whose atom metadata and derived topology tables define every future selection.

Exceptions

TypeError	If psf is not a CharmmPsf instance.
RuntimeError	If psf has been closed or if the C ABI reports success but returns a NULL selector handle.
ApoCharmmError	With native status APO_STATUS_NOT_INITIALIZED if the PSF atom count is not initialized, with APO_STATUS_INVALID_ARGUMENT if the native handle is invalid, or with APO_STATUS_RUNTIME_ERROR if native allocation fails.

Postcondition

On success, this wrapper owns one selector handle and retains psf.

Member Function Documentation

select()

AtomSelection apocharmm.atom_selector.AtomSelector.select	(		self,
		str	selection_string
	)

Evaluates an atom-selection string as a set-valued result.

The string is encoded as UTF-8 and passed to the null-terminated C ABI. Recognized keywords and dotted operators use ASCII spellings and case-insensitive matching. Native diagnostic positions are UTF-8 byte offsets, not Python character indices. See Atom Selection and Atom References for the complete language.

Example:

selector = apo.AtomSelector(psf)
alpha_carbons = selector.select("type CA")
indices = alpha_carbons.getAtomIndices()

Parameters

[in]

selection_string

Python str containing one complete expression. The encoded bytes are copied during the native call and are not retained.

Returns

A newly owned set-valued AtomSelection independent of this selector and the source PSF wrapper. Zero, one, or many atoms may be selected.

Exceptions

TypeError	If selection_string is not a str.
UnicodeEncodeError	If UTF-8 encoding rejects the string, such as for an unpaired surrogate.
RuntimeError	If this selector has been closed or if the C ABI reports success but returns a NULL selection handle.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the string is empty or the expression has a lexical, syntax, operator, range, or parenthesis error, or if a PSF bonded-neighbor index is out of range; or with APO_STATUS_RUNTIME_ERROR for malformed PSF state, allocation failure, or an internal parser failure.

Postcondition

This selector and its PSF are unchanged.

Warning

The current wrapper does not reject embedded "\\0" characters. Because the C ABI accepts a C string, only the prefix before the first embedded null byte is parsed. Avoid embedded null characters.

selectAtom()

AtomReference apocharmm.atom_selector.AtomSelector.selectAtom	(		self,
		str	selection_string
	)

Evaluates an expression that must match exactly one atom.

The method uses the same UTF-8 conversion and native grammar as select(). Cardinality is checked only by native AtomSelector::selectAtom(): zero or multiple matches are errors rather than Python-side special cases.

Example:

selector = apo.AtomSelector(psf)
alpha_carbon = selector.selectAtom("atom PROA 42 CA")
atom_index = alpha_carbon.getAtomIndex()

Parameters

[in]

selection_string

Python str containing one complete expression. The encoded bytes are copied during the native call and are not retained.

Returns

A newly owned AtomReference that retains shared native ownership of the selector's PSF and remains valid after the selector or source PSF wrapper is closed.

Exceptions

TypeError	If selection_string is not a str.
UnicodeEncodeError	If UTF-8 encoding rejects the string, such as for an unpaired surrogate.
RuntimeError	If this selector has been closed or if the C ABI reports success but returns a NULL atom-reference handle.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT if the string is empty, the expression is invalid, a stored PSF bonded-neighbor index is out of range, or the expression selects anything other than exactly one atom; or with APO_STATUS_RUNTIME_ERROR for malformed PSF state, allocation failure, or an internal parser failure.

Postcondition

This selector and its PSF are unchanged.

Warning

The current wrapper does not reject embedded "\\0" characters. Because the C ABI accepts a C string, only the prefix before the first embedded null byte is parsed. Avoid embedded null characters.