Skip to content

IOP Diagram Notebooks

The marimo notebook under notebooks/diagrams/iop/graphviz_level_mo.py uses the shared notebook environment registry instead of hard-coded environment classes and export paths.

Shared helper

Reusable helper code lives under notebooks/diagrams/iop/core/.

  • core/notebook_support.py contains notebook-only path and agent-count helpers.
  • agent_selection_config(spec) computes the default N_AGENTS value, slider bounds or discrete steps, and the UI note shown in the notebook.
  • resolve_iop_notebook_artifacts(spec, num_agents=...) resolves the trained artifact paths for:
  • wm/env_transition_graph.pkl
  • om/iop_stack.pt
  • instantiate_notebook_env(...) keeps notebook env construction aligned with notebooks/env_discovery.py.
  • core/iop_graphviz_level.py and core/iop_viz.py contain the reusable rendering and visualization logic.

Output paths

Diagram exports are now rooted under:

  • exports/diagrams/om/<family>/<slug>/...

If the environment stores artifacts per agent count, the diagram path mirrors that and inserts /<n_agents>/ before the notebook-specific subdirectory.

This keeps diagram outputs aligned with the same NotebookEnvSpec metadata used for training and history notebooks, and avoids collisions for environments like pursuit, gathering, and congestion.

Within each export folder, Graphviz artifacts are split by role:

  • dot/: Graphviz source files (.gv)
  • png/ (or another format directory matching cfg.fmt): rendered outputs

Examples:

  • levels/dot/state_00675_L2.gv
  • levels/png/state_00675_L2.png

This avoids mixing source and rendered files in the same directory and makes it obvious which files are editable DOT source versus viewer-ready outputs.

Notebook behavior

The interactive notebooks now follow the same pattern:

  • environment dropdown populated from notebooks/env_discovery.py
  • N_AGENTS slider driven by NotebookEnvSpec
  • artifact status panel showing the resolved world-model / opponent-model paths
  • mo.stop(...) gate when required artifacts are missing

That last point matters because many workspaces only have the export directory layout checked in, not the actual trained .pkl / .pt artifacts. The notebooks should therefore stay explorable without immediately crashing on import.

Matrix artifact validation

Diagram helpers require stored graph state widths to match the live environment's observation channels. A mismatched cache raises a schema error and must be rebuilt before it can be visualized.

Graphviz runtime fallback

The notebook depends on two separate Graphviz pieces:

  • the Python graphviz package to build DOT objects
  • the system dot executable to render previews and exported files

If dot is missing from PATH, the notebooks now stay runnable and show a preview warning instead of crashing during the preview cell.

Export buttons still require a working local Graphviz installation, because file export ultimately shells out to dot.

Inline preview still uses dot.pipe(format="svg") because marimo can embed the SVG directly in the notebook, but the exported artifact bundle defaults to PNG for easier sharing outside the notebook.

Current notebook

  • graphviz_level_mo.py: per-level / mixture preview plus selected, sampled, and bulk export flows

Follow-up

The older state-level renderer (iop_graphviz.py and graphviz_mo.py) was removed after the level-based notebook absorbed the useful workflow. If more diagram notebooks need the same selection pattern, prefer extending core/notebook_support.py instead of reintroducing a parallel IOP Graphviz surface.