entities.trajectory.SelectionManager

entities.trajectory.SelectionManager(trajectory)

Manages atom selections for a trajectory.

Coordinates between MDAnalysis AtomGroup objects, Blender UI properties, and geometry node attributes. Selections are stored as boolean attributes on the trajectory object for use in geometry nodes.

The CollectionProperty is the ‘source of truth’ for managing selections for the trajectory. If an AtomGroup doesn’t have a matching UI Item in the collection property, it will be discarded. New AtomGroup objects are created for new UI Items.

The collection is registered and available under mn_trajectory_selections on an object inside of Blender. It can be accessed on this class via :attr:ui_items and individual items via self.ui_items.get('name').

bpy.types.Object.mn_trajectory_selections = CollectionProperty(
    type=props.TrajectorySelectionItem
)

Parameters

Name	Type	Description	Default
trajectory	Trajectory	Parent trajectory object.	required

Attributes

Name	Type	Description
atomgroups	dict[str, AtomGroup]	Cached AtomGroup objects keyed by selection name.
ui_index	IntObjectMNProperty	Property descriptor for current UI selection index.

Methods

Name	Description
ag_is_updating	Check if an AtomGroup is an UpdatingAtomGroup.
ag_to_attribute	Convert and store an AtomGroup as a boolean attribute.
from_atomgroup	Create a selection from an existing MDAnalysis AtomGroup.
from_string	Create a selection from an MDAnalysis selection string.
get	Try and get a selection UI Item by name.
remove	Remove a selection by name or index.
ui_item_to_ag	Generate an AtomGroup from a TrajectorySelectionItem.
update_attributes	Synchronize UI items, AtomGroups, and named attributes.

ag_is_updating

entities.trajectory.SelectionManager.ag_is_updating(atomgroup)

Check if an AtomGroup is an UpdatingAtomGroup.

UpdatingAtomGroup objects recalculate their members each frame based on geometric criteria (e.g., distance-based selections).

Parameters

Name	Type	Description	Default
atomgroup	AtomGroup	The atom group to check.	required

Returns

Name	Type	Description
	bool	True if the AtomGroup updates dynamically, False if static.

Notes

Uses class name comparison since UpdatingAtomGroup is a subclass of AtomGroup.

ag_to_attribute

entities.trajectory.SelectionManager.ag_to_attribute(ag, name)

Convert and store an AtomGroup as a boolean attribute.

Converts an AtomGroup to a boolean mask into the original Universe that would return the selected atoms in the AtomGroup. This array is then stored as a boolean attribute on the mesh that represents the Universe inside of Blender.

Parameters

Name	Type	Description	Default
ag	AtomGroup	The atom group to convert.	required
name	str	Name for the attribute.	required

See Also

_ag_to_bool : Helper function that performs the AtomGroup to boolean conversion. update_attributes : Calls this method to sync selections to geometry attributes.

from_atomgroup

entities.trajectory.SelectionManager.from_atomgroup(atomgroup, *, name=None)

Create a selection from an existing MDAnalysis AtomGroup.

Create a selection on the Trajectory from an already created AtomGroup rather than just using a string selection input. The selection string displayed is non-editable in the GUI.

Parameters

Name	Type	Description	Default
atomgroup	AtomGroup	Pre-existing AtomGroup (static or updating).	required
name	str	Name for the selection. Auto-generated if not provided via :meth:_unique_selection_name.	None

Returns

Name	Type	Description
	TrajectorySelectionItem	The created UI item for the selection with item.from_atomgroup = True.

Notes

Sets item.from_atomgroup = True to prevent string editing in UI. The string representation is stored for display purposes only.

See Also

from_string : Create selection from MDAnalysis selection string. ag_to_attribute : Called to immediately store the selection as an attribute.

from_string

entities.trajectory.SelectionManager.from_string(
    string,
    *,
    updating=True,
    periodic=True,
    name=None,
)

Create a selection from an MDAnalysis selection string.

This uses the MDAnalysis selection language to create an AtomGroup and stores the selection of which atoms are in the AtomGroup as a boolean attribute on the mesh inside of Blender.

Parameters

Name	Type	Description	Default
string	str	MDAnalysis selection string (e.g., "protein", "resid 1-10").	required
updating	bool	If True, selection potentially updates each frame if required (e.g., distance-based selections). If False, creates a static selection.	True
periodic	bool	Consider periodic boundary conditions for geometric selections (e.g., "around").	True
name	str	Name for the selection, used as the attribute name when storing on the mesh. Auto-generated if not provided via :meth:_unique_selection_name.	None

Returns

Name	Type	Description
	TrajectorySelectionItem	The created UI item for the selection.

See Also

from_atomgroup : Create selection from pre-existing AtomGroup. update_attributes : Called after item creation to generate the AtomGroup. _unique_selection_name : Generates unique names when not provided.

get

entities.trajectory.SelectionManager.get(name)

Try and get a selection UI Item by name.

Parameters

Name	Type	Description	Default
name	str	Name of the UI item to retrieve.	required

Returns

Name	Type	Description
	TrajectorySelectionItem or None	The matching UI item, or None if no match was found.

remove

entities.trajectory.SelectionManager.remove(value)

Remove a selection by name or index.

Cleans up the UI item, cached AtomGroup, and geometry attribute. Silently handles cases where attribute or AtomGroup don’t exist.

Parameters

Name	Type	Description	Default
value	int or str	Selection name (str) or index (int) in ui_items collection.	required

Raises

Name	Type	Description
	ValueError	If name not found in ui_items or value is neither int nor str.

See Also

update_attributes : Automatically removes orphaned AtomGroups.

ui_item_to_ag

entities.trajectory.SelectionManager.ui_item_to_ag(item)

Generate an AtomGroup from a TrajectorySelectionItem.

Uses the item’s string, updating, and periodic properties to create the corresponding AtomGroup from the trajectory’s Universe.

Parameters

Name	Type	Description	Default
item	TrajectorySelectionItem	The UI item containing selection parameters (string, updating, periodic).	required

Returns

Name	Type	Description
	AtomGroup	AtomGroup (or UpdatingAtomGroup) created from the item’s parameters.

See Also

update_attributes : Calls this method to create missing AtomGroups.

update_attributes

entities.trajectory.SelectionManager.update_attributes()

Synchronize UI items, AtomGroups, and named attributes.

This is the core update method called when selections change. The following steps are carried out:

1. Creates missing AtomGroup objects for UI items
2. Removes orphaned AtomGroup objects with no matching UI item
3. Create new AtomGroup objects when selection strings change on the UI item
4. Update the named attributes on the mesh for updating or new selections

Any errors in creation are stored as item.message which will be reflected in the UI with a warning and the error message.

Notes

Skipped when manager is frozen via :class:FrozenUpdates context when creating new UI items.

See Also

ui_item_to_ag : Creates AtomGroups from UI items. ag_to_attribute : Stores AtomGroups as geometry attributes. from_string : Calls this after creating UI item.