CodeEntropy.levels.nodes.beads module

Build bead (AtomGroup index) definitions for each molecule and hierarchy level.

This module defines the BuildBeadsNode, a static DAG node that constructs bead definitions once, in reduced-universe index space. These bead definitions are used by later frame-level nodes (e.g., covariance construction) without needing to re-run selection logic every frame.

Beads are stored as arrays of atom indices (in the reduced universe).

class CodeEntropy.levels.nodes.beads.BuildBeadsNode(hierarchy: HierarchyBuilder | None = None)

Bases: object

Build bead definitions once, in reduced-universe index space.

Output contract:

Writes shared_data[“beads”] with keys:

• (mol_id, “united_atom”, res_id) -> list[np.ndarray]

• (mol_id, “residue”) -> list[np.ndarray]

• (mol_id, “polymer”) -> list[np.ndarray]

Notes

United-atom beads are generated at the molecule level (preserving the underlying ordering provided by HierarchyBuilder.get_beads) and then grouped into residue buckets based on the heavy atom that defines the bead.

run(shared_data: dict[str, Any]) → dict[str, Any]

Build bead definitions for all molecules and levels.

Parameters:

shared_data – Shared data dictionary. Requires: - “reduced_universe”: MDAnalysis.Universe - “levels”: list[list[str]]

Returns:

Dict containing the “beads” mapping (also written into shared_data).

Raises:

KeyError – If required keys are missing from shared_data.

class CodeEntropy.levels.nodes.beads.UnitedAtomBead(residue_id: int, atom_indices: ndarray)

Bases: object

A united-atom bead associated with a residue bucket.

Variables:

• residue_id (int) – Local residue index within the molecule (0..n_residues-1).

• atom_indices (numpy.ndarray) – Atom indices (reduced-universe index space) belonging to the bead.

atom_indices: ndarray

residue_id: int