entities.trajectory.selections.Selection

entities.trajectory.selections.Selection(trajectory, name='selection_0')

Represents an atom selection for a trajectory in Blender.

A Selection wraps an MDAnalysis AtomGroup and provides synchronization between the MDAnalysis selection and Blender UI properties. It manages the selection string, updating behavior, and conversion to boolean masks for geometry node attributes.

Parameters

Name	Type	Description	Default
trajectory	Trajectory	The parent Trajectory object this selection belongs to.	required
name	str	Unique name for this selection. Default is “selection_0”.	`'selection_0'`

Attributes

Name	Type	Description
trajectory	Trajectory	Reference to the parent trajectory.
mask_array	npt.NDArray[np.bool_]	Cached boolean mask representing which atoms are selected.

Methods

Name	Description
add_selection_property	Initialize the selection with a UI property and create the atom group.
apply_selection_string	Apply a selection string and update the atom group.
ensure_valid	Raise an exception if the selection is in an invalid state.
from_atomgroup	Create a Selection from an existing MDAnalysis AtomGroup.
invalidate_ui_cache	Invalidate the cached UI property reference.
is_valid	Check if the selection is in a valid state.
set_atom_group	Create or update the MDAnalysis AtomGroup from a selection string.
set_selection	Store the selection mask as a named attribute in Blender.
sync_from_ui	Synchronize selection state from the UI property to computed state.
sync_to_blender_attribute	Synchronize the selection mask to Blender geometry attributes.
to_mask	Get the selection as a boolean mask array.
validate_selection_string	Validate a selection string without side effects.

add_selection_property

entities.trajectory.selections.Selection.add_selection_property(
    string='all',
    updating=True,
    periodic=True,
)

Initialize the selection with a UI property and create the atom group.

Creates a Blender UI property item for this selection and sets up the MDAnalysis AtomGroup based on the provided selection string.

Parameters

Name	Type	Description	Default
string	str	MDAnalysis selection string. Default is “all”.	`'all'`
updating	bool	Whether the selection should update dynamically during trajectory playback. Default is True.	`True`
periodic	bool	Whether to consider periodic boundary conditions in the selection. Default is True.	`True`

apply_selection_string

entities.trajectory.selections.Selection.apply_selection_string(string)

Apply a selection string and update the atom group.

This method validates the selection string and, if valid, creates the AtomGroup and updates the cached mask array.

Parameters

Name	Type	Description	Default
string	str	MDAnalysis selection string to apply.	required

Returns

Name	Type	Description
	bool	True if the selection was successfully applied, False otherwise.

Notes

Unlike set_atom_group, this method returns a success status and handles errors gracefully by storing them in the message property.

ensure_valid

entities.trajectory.selections.Selection.ensure_valid()

Raise an exception if the selection is in an invalid state.

Useful for catching bugs early in development or providing clear error messages when a selection becomes corrupted.

Raises

Name	Type	Description
	`SelectionError`	If the selection is missing required components or is otherwise invalid.

Examples

>>> sel.ensure_valid()  # Raises if invalid
>>> # Continue with valid selection operations

from_atomgroup

entities.trajectory.selections.Selection.from_atomgroup(
    trajectory,
    atomgroup,
    name='',
)

Create a Selection from an existing MDAnalysis AtomGroup.

This factory method creates a Selection object from an existing AtomGroup, automatically detecting whether it’s an UpdatingAtomGroup and extracting the selection string and periodic settings if available.

Parameters

Name	Type	Description	Default
trajectory	Trajectory	The parent trajectory this selection belongs to.	required
atomgroup	`mda`.`AtomGroup`	An MDAnalysis AtomGroup or UpdatingAtomGroup to wrap.	required
name	str	Name for the selection. If empty, uses the selection string or a default name based on atom count.	`''`

Returns

Name	Type	Description
	Selection	A new Selection object wrapping the provided AtomGroup.

Notes

If atomgroup is an UpdatingAtomGroup, extracts the selection string and periodic settings from it.
The selection is marked as immutable to prevent user modification.
The selection is automatically registered with the trajectory’s SelectionManager.
Creates the Python wrapper FIRST and registers it BEFORE creating the UI property, to avoid race conditions with update handlers.

invalidate_ui_cache

entities.trajectory.selections.Selection.invalidate_ui_cache()

Invalidate the cached UI property reference.

Call this if the UI item is recreated or the selection is renamed. The next access to ui_item will fetch a fresh reference.

is_valid

entities.trajectory.selections.Selection.is_valid()

Check if the selection is in a valid state.

Verifies that all required components are present: the AtomGroup, the mask array, and the UI property.

Returns

Name	Type	Description
	bool	True if the selection is valid and usable, False otherwise.

Examples

>>> if not sel.is_valid():
...     print("Selection needs reinitialization")

set_atom_group

entities.trajectory.selections.Selection.set_atom_group(
    string,
    raise_on_error=False,
)

Create or update the MDAnalysis AtomGroup from a selection string.

Parses the selection string using MDAnalysis and creates an AtomGroup (static or updating depending on the updating property). Updates the cached mask array if successful.

Parameters

Name	Type	Description	Default
string	str	MDAnalysis selection string to parse.	required
raise_on_error	bool	If True, raises SelectionError on failure. If False, stores error in message and returns False. Default is False.	`False`

Returns

Name	Type	Description
	bool	True if successful, False if failed (only when raise_on_error=False).

Raises

Name	Type	Description
	`SelectionError`	If raise_on_error=True and the selection string is invalid.

Notes

This method is maintained for backward compatibility. New code should prefer apply_selection_string() for better error handling.

set_selection

entities.trajectory.selections.Selection.set_selection()

Store the selection mask as a named attribute in Blender.

.. deprecated:: Use sync_to_blender_attribute() instead for clearer intent.

Notes

This method is maintained for backward compatibility.

sync_from_ui

entities.trajectory.selections.Selection.sync_from_ui()

Synchronize selection state from the UI property to computed state.

Pulls the current state from the Blender UI property and updates the computed AtomGroup if the selection string has changed.

Notes

This is called by update handlers when the user modifies the selection through Blender’s UI. It ensures the Python-side state reflects the PropertyGroup state.

sync_to_blender_attribute

entities.trajectory.selections.Selection.sync_to_blender_attribute()

Synchronize the selection mask to Blender geometry attributes.

Converts the current selection to a boolean mask and stores it as a geometry node attribute on the trajectory object. Only applies if updating=True.

Notes

This pushes the Python-side selection state to Blender’s geometry system, making it available for use in geometry nodes.

to_mask

entities.trajectory.selections.Selection.to_mask()

Get the selection as a boolean mask array.

Returns the cached mask array. If updating=True, recomputes the mask from the current frame’s AtomGroup state before returning.

Returns

Name	Type	Description
	npt.NDArray[np.bool_]	1D boolean array indicating which atoms are selected.

validate_selection_string

entities.trajectory.selections.Selection.validate_selection_string(string)

Validate a selection string without side effects.

Tests whether the selection string can be parsed by MDAnalysis without actually storing the result.

Parameters

Name	Type	Description	Default
string	str	MDAnalysis selection string to validate.	required

Returns

Name	Type	Description
	tuple[bool, str]	A tuple of (is_valid, error_message). If valid, error_message is empty.

Examples

>>> is_valid, error = sel.validate_selection_string("name CA")
>>> if is_valid:
...     sel.apply_selection_string("name CA")