Core

EnsembleSelector(ensemble, run_id=None, is_negated=False)

A fluent API for building complex selection queries on an Ensemble's data.

Allows chaining of selection criteria with logical .AND(), .OR(), and .NOT() operations. The selection is lazy, meaning the actual computation happens only when get_mask() is called.

Initializes the EnsembleSelector for a specific ensemble and run.

PARAMETER	DESCRIPTION
ensemble	The Ensemble object to perform selections on. TYPE: Ensemble
run_id	The ID of the run within the ensemble for which to generate masks. TYPE: str | None DEFAULT: None
is_negated	Any filter after this specific instance will be negated. TYPE: bool DEFAULT: False

AND()

Sets the logical operator for the next chained filter to AND. This is the default behavior if no logical operator is explicitly called.

NOT()

Returns a new EnsembleSelector instance where the next added filter will be negated. This handles select().NOT().atom_types(...).

OR()

Sets the logical operator for the next chained filter to OR. The next filter added will be OR'd with the current expression tree.

atom_types(atom_types)

Selects atoms whose atom type is present in the provided list.

PARAMETER	DESCRIPTION
atom_types	A list of string atom types (e.g., "C", "N", "H") to select. TYPE: list[str]

RETURNS	DESCRIPTION
EnsembleSelector	The EnsembleSelector instance for chaining.

get_mask(micro_id=None)

Executes the built selection query and yields atom-level boolean masks, one for each microstate.

The mask for each microstate will have a length equal to the number of atoms in that microstate, indicating which atoms meet the criteria.

PARAMETER	DESCRIPTION
micro_id	Specifies the microstate IDs for which to generate masks. Can be an integer, a slice, or None (to get masks for all microstates). TYPE: OptionalSliceSpec DEFAULT: None

RETURNS	DESCRIPTION
Iterator[NDArray[bool]]	1D boolean NumPy arrays representing the atom selection mask for that microstate.

molecule_ids(mol_ids)

Selects atoms whose molecule ID is present in the provided list.

PARAMETER	DESCRIPTION
mol_ids	A list of integer molecule IDs to select. TYPE: list[int]

RETURNS	DESCRIPTION
EnsembleSelector	The EnsembleSelector instance for chaining.

within_distance(from_atoms, dist)

Selects atoms within a specified radial distance from a given center atom index. This filter is applied per microstate.

PARAMETER	DESCRIPTION
from_atoms	The 0-based index of the atom to use as the center. TYPE: SliceSpec | Self
radius	The maximum distance (inclusive) from the center atom in the same units as coordinates.

RETURNS	DESCRIPTION
EnsembleSelector	The EnsembleSelector instance for chaining.