entities.molecule.SelectionManager

entities.molecule.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	Molecule	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.
find	Find an existing selection created from a given selection string.
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.
node	Get a Named Attribute node for a selection, creating it if needed.
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.molecule.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.molecule.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.

find

entities.molecule.SelectionManager.find(
    selection,
    *,
    updating=True,
    periodic=True,
)

Find an existing selection created from a given selection string.

Unlike :meth:get, which looks up a selection by its name (the attribute name, e.g. "selection_0"), this searches by the MDAnalysis selection string that created it.

The updating and periodic flags form part of the match, because a static selection and a per-frame updating one built from the same string are not interchangeable.

Parameters

Name	Type	Description	Default
selection	str	MDAnalysis selection string to search for, e.g. "protein".	required
updating	bool	Only match selections with this updating flag.	True
periodic	bool	Only match selections with this periodic flag.	True

Returns

Name	Type	Description
	TrajectorySelectionItem | None	The first matching selection, or None if there is no match.

Examples

import molecularnodes as mn

canvas = mn.Canvas()
mol = mn.Molecule.fetch("4ozs")

print(mol.selections.find("protein"))
item = mol.selections.from_string("protein")
print(mol.selections.find("protein").name)

None
selection_0

Selections made in the Blender UI are found too, and the flags are part of the match:

print(mol.selections.find("protein", updating=False))

None

See Also

get : Look a selection up by its name rather than its selection string. node : Find or create a selection and return a node for it.

from_atomgroup

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

Create a selection from an existing MDAnalysis AtomGroup.

Create a selection on the Molecule 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.molecule.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.molecule.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.

node

entities.molecule.SelectionManager.node(
    selection,
    *,
    updating=True,
    periodic=True,
    name=None,
)

Get a Named Attribute node for a selection, creating it if needed.

This is the bridge between the selection API and the node tree API. It resolves selection to a managed selection - reusing an existing one where possible - and returns a node whose boolean output can be plugged straight into a style node’s Selection input.

Existing selections are reused so that repeated calls (a style rebuilt in a loop, say) do not pile up duplicate selections and mesh attributes. Reuse is matched on the selection string together with the updating and periodic flags, or on name when one is given. An AtomGroup is always stored as a new selection, since two groups cannot be compared cheaply.

Parameters

Name	Type	Description	Default
selection	str | AtomGroup	An MDAnalysis selection string, or an AtomGroup.	required
updating	bool	If True, the selection is re-evaluated each frame where required, for example for distance-based selections. Ignored when selection is an AtomGroup, where updating is a property of the group itself.	True
periodic	bool	Consider periodic boundary conditions for geometric selections. Ignored when selection is an AtomGroup.	True
name	str	Name for the selection, used as the mesh attribute name. When given, an existing selection with this name is reused. Auto-generated otherwise.	None

Returns

Name	Type	Description
	NamedAttribute	A Named Attribute node reading the selection’s boolean attribute.

Notes

Like every node, this must be created inside an active node tree context - either a with mol.tree: block, or the callable passed to add_style. Calling it outside one raises a RuntimeError.

Examples

The main use is inside a callable passed to add_style, which is evaluated inside the tree context:

import molecularnodes as mn
from molecularnodes.nodes import geometry as g

canvas = mn.Canvas()
mol = mn.Molecule.fetch("8H1B")
mol.add_style("cartoon")
mol.add_style(
    lambda: g.StyleSpheres(
        selection=mol.selections.node("not protein"),
        sphere="Instance",
    )
)
canvas.look_at(mol)
canvas.snapshot()

It works the same inside an explicit tree context:

with mol.tree.reset() as (atoms, join):
    atoms >> g.StyleCartoon(selection=mol.selections.node("protein")) >> join
    atoms >> g.StyleSticks(selection=mol.selections.node("not protein")) >> join

canvas.look_at(mol)
canvas.snapshot()

Selections are reused rather than duplicated, so calling it in a loop is safe:

before = len(mol.selections)
with mol.tree:
    for _ in range(5):
        mol.selections.node("protein")
print(f"{before} selections before, {len(mol.selections)} after")

2 selections before, 2 after

A static selection is a different selection to an updating one, and gets its own attribute:

with mol.tree:
    mol.selections.node("around 5 resname LYS")
    mol.selections.node("around 5 resname LYS", updating=False)
print([item.name for item in mol.selections.ui_items])

['selection_0', 'selection_1', 'selection_2', 'selection_3']

An AtomGroup can be used instead of a selection string:

with mol.tree:
    node = mol.selections.node(mol.universe.select_atoms("resid 1:20"))
print(node.node.inputs["Name"].default_value)

selection_4

See Also

find : Look up an existing selection by its selection string. from_string : Always create a new selection from a selection string. from_atomgroup : Always create a new selection from an AtomGroup. molecularnodes.ui.props.TrajectorySelectionItem.node : The per-item equivalent.

remove

entities.molecule.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.molecule.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.molecule.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.