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.

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 AtomSelection that remains valid after this selector is closed. 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 select() 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.

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 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 AtomSelection independent of this selector and the source PSF wrapper.

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.