Getting Started¶
The project uses uv for Python dependency management and command execution.
Install Dependencies¶
From the repository root:
The dependency set includes GPU-oriented JAX and PyTorch packages, Marimo, plotting libraries, and the documentation toolchain. A first sync can be large. The gridworld substrates are native code and do not install Melting Pot or Lab2D.
Preview The Documentation¶
The docs are built with Zensical. The Markdown source lives in docs/, and generated HTML is written to site/.
The preview server listens on localhost:8000 by default and reloads when docs change.
To build the static site:
The generated site/ directory is ignored by git and should not be committed.
Run A Notebook¶
Experiment entrypoints are Marimo notebooks stored as Python files. Open one with:
or run it headlessly:
Most training notebooks define a visible config block near the top. The common knobs are:
num_env_steps: total training steps.seed: base seed for repeated runs.num_runs: number of seeds to evaluate.run_*: algorithm toggles.calculate_conv: whether to estimate NashConv.calculate_alpharank: whether to compute AlphaRank.calculate_satisfaction: whether to run final satisfaction rollouts.save_dir: export directory for reports, checkpoints, and plots.
Some top-level config values can be overridden from the CLI through the notebook helper:
uv run marimo run notebooks/matrix/stag_hunt/SustainedStag_2_mo.py -- --num_env_steps 100000 --num_runs 1
Nested algorithm blocks such as ippo, iql, and nashq are usually edited in the notebook.
A Small First Run¶
For a lightweight introduction, start with the matrix Stag Hunt notebook:
For gridworld inspection before training, use one of the play notebooks:
Play notebooks are useful for checking action maps, labels, temporal atoms, and whether a formula describes the behavior you intend.