CodeEntropy.levels.level_dag module

Hierarchy-level DAG orchestration and reduction.

This module defines the LevelDAG, which coordinates two stages of the hierarchy workflow:

  1. Static stage (runs once): - Detect molecules and available resolution levels. - Build beads for each (molecule, level) definition. - Initialise accumulators used during per-frame reduction. - Compute conformational state descriptors required later by entropy nodes.

  2. Frame stage (runs for each trajectory frame): - Execute the FrameGraph to produce frame-local covariance outputs. - Reduce frame-local outputs into running (incremental) means.

class CodeEntropy.levels.level_dag.LevelDAG(universe_operations: Any | None = None)[source]

Bases: object

Execute hierarchy detection, per-frame covariance calculation, and reduction.

The LevelDAG is responsible for:

  • Running a static DAG (once) to prepare shared inputs.

  • Running a per-frame DAG (for each frame) to compute frame-local outputs.

  • Reducing frame-local outputs into shared running means.

The reduction performed here is an incremental mean across frames (and across molecules within a group when frame nodes average within-frame first).

build() → LevelDAG[source]

Build the static and frame DAG topology.

This registers all static nodes and their dependencies, and builds the internal FrameGraph used for per-frame execution.

Returns:

Self, to allow fluent chaining.

execute(shared_data: dict[str, Any], *, progress: _RichProgressSink | None = None) → dict[str, Any][source]

Execute the full hierarchy workflow and mutate shared_data.

This method ensures required shared components exist, runs the static stage once, then iterates through trajectory frames to run the per-frame stage and reduce outputs into running means.

Parameters:

  • shared_data – Shared workflow data dict. This mapping is mutated in-place by both static and frame stages.

  • progress – Optional progress sink passed through to nodes and used for per-frame progress reporting when supported.

Returns:

The same shared_data mapping passed in, after mutation.