Skip to content

Notebooks

Marimo notebooks are the main user interface for running experiments, play-testing environments, plotting results, and inspecting artifacts.

Training Notebooks

Training notebooks usually follow this structure:

  1. Import project helpers and environment-specific constraints.
  2. Define a visible config dictionary.
  3. Build a TemporalGameExperimentSpec or environment-specific wrapper spec.
  4. Call the experiment suite helper.
  5. Plot satisfaction curves and comparison summaries.
  6. Print artifact paths.

Primary examples:

notebooks/matrix/stag_hunt/SustainedStag_2_mo.py
notebooks/gridworlds/territory/RoleClaim_2_mo.py
notebooks/gridworlds/harvest/SafeHarvest_4_mo.py
notebooks/gridworlds/gift_refinements/Consume_6_mo.py

Play And Label Notebooks

Play notebooks let you manually inspect environment dynamics and controls before launching expensive training runs.

Examples:

notebooks/matrix/stag_hunt/play_mo.py
notebooks/gridworlds/chemistry/play_labelled_mo.py
notebooks/gridworlds/territory/play_labelled_mo.py
notebooks/gridworlds/gift_refinements/play_labelled_mo.py

Labelled play notebooks are especially useful for checking whether the atoms used in a formula fire when expected.

Generic Utility Notebooks

The generic notebooks support analysis and inspection:

notebooks/generic/regraph_mo.py
notebooks/generic/timings_report_mo.py
notebooks/generic/legend_mo.py
notebooks/generic/spaces_mo.py
notebooks/generic/gpu_mo.py

Use them to regenerate plots from saved artifacts, inspect timings, export legends, inspect observation/action spaces, and check GPU availability.

Config Shape

Common top-level fields:

  • num_agents
  • num_env_steps
  • seed
  • num_runs
  • progress_chunks
  • run_ippo
  • run_ippo_cer
  • run_pr2_ippo
  • run_pr2_ippo_cer
  • run_iql
  • run_iql_cer
  • run_pr2_iql
  • run_pr2_iql_cer
  • run_nashq
  • run_nashq_cer
  • calculate_conv
  • calculate_alpharank
  • calculate_satisfaction
  • calculate_conv_quick
  • save_dir

Nested blocks hold algorithm hyperparameters:

"ippo": {...}
"iql": {...}
"nashq": {...}

The suite helper validates keys, so unexpected top-level config names usually fail early.

Running From The CLI

Open a notebook:

uv run marimo edit notebooks/gridworlds/territory/RoleClaim_2_mo.py

Run a notebook:

uv run marimo run notebooks/gridworlds/territory/RoleClaim_2_mo.py

Override supported top-level values:

uv run marimo run notebooks/gridworlds/territory/RoleClaim_2_mo.py -- --num_runs 1 --num_env_steps 50000

For long experiments, keep save_dir stable and use notebooks that enable partial resume so completed seeds can be reused.