Skip to content

Notebooks

Marimo notebooks are the main interactive interface for configuring training, play-testing environments, inspecting labels, and regenerating plots.

Training Notebooks

Training notebooks define a visible config dictionary, construct an environment-specific experiment spec, call a shared suite helper, and render the returned reports and plots.

Active suites:

notebooks/matrix/stag_hunt/SustainedStag_2_mo.py
notebooks/gridworlds/pursuit/Classic_2_mo.py
notebooks/gridworlds/pursuit/Capture_2_mo.py
notebooks/gridworlds/pursuit/Classic_3_mo.py
notebooks/gridworlds/pursuit/Capture_3_mo.py
notebooks/gridworlds/coins/OwnCoinFirst_2_mo.py
notebooks/gridworlds/harvest/SafeHarvest_4_mo.py
notebooks/gridworlds/territory/RoleClaim_2_mo.py

Alternative objectives are kept in each suite's alt/ directory and are not included in all-environment cluster sweeps. Chemistry Food/FoodThenXY and Gift Refinements Consume/RefinedThenConsume also remain runnable by direct path, but reward-optimisation evidence removed them from the curated sweep.

Play And Label Notebooks

Play notebooks let you inspect action maps and dynamics before launching an expensive run. Labelled variants also display the atoms used by temporal formulas.

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

For the native gridworlds, ordinary play notebooks render RGB; the factories also expose low-memory structured observations when render_mode=None.

Generic Utilities

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
  • regraph_mo.py discovers exports/**/runs.npy and regenerates suite plots.
  • timings_report_mo.py aggregates timing sidecars and allocated hardware.
  • legend_mo.py exports standalone paper-figure legends.
  • spaces_mo.py inspects structured and visual environment spaces.
  • gpu_mo.py checks accelerator visibility.

Config Shape

Every training notebook exposes the complete 15-algorithm selection surface:

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
run_hc_ippo          run_hc_pr2_ippo
run_hc_iql           run_hc_pr2_iql
run_hc_nashq

Other shared fields include:

  • run shape: num_agents, num_env_steps, seed, num_runs, progress_chunks;
  • verification: calculate_conv, calculate_conv_quick, calculate_alpharank, calculate_satisfaction, eval_episodes, satisfaction_eval_episodes, nashconv_delta, satisfaction_delta;
  • continuation: nashconv_auto_resume, nashconv_auto_resume_threshold, nashconv_auto_resume_step_fraction, resume_partial_runs;
  • output: just_vis, save_dir;
  • nested algorithm blocks: ippo, iql, and nashq.

PR2 and handcrafted variants reuse the corresponding IPPO, IQL, or Nash-Q block. Nested block values are edited in the notebook rather than overridden recursively from the CLI.

Running Locally

Open an editable notebook:

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

Serve it as a read-only app:

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

Top-level values can be overridden after --:

uv run marimo run notebooks/gridworlds/territory/RoleClaim_2_mo.py -- \
  --num-runs=1 --num-env-steps=50000 --run-ippo=true

CLI names are case-insensitive and hyphens normalize to underscores. Unknown keys fail early. For unattended runs, use the cluster launchers, which explicitly isolate selected algorithms and enable validated partial resume.