Skip to content

Matrix Smoke-Run Tool

The repository now has a small matrix-only smoke runner at:

  • scripts/run_matrix_smoke.py

It exists for quick end-to-end validation when the full Marimo notebooks would be too heavy to run interactively.

What it runs

The runner defaults to the primary Stag Hunt matrix suite:

  • sustained_stag

The secondary Stag Hunt sketches can still be selected explicitly with --suites handshake both_modes, but they are treated as alt/ experiments rather than primary run targets.

For each selected suite it runs the enabled matrix algorithms independently:

  • IPPO
  • IQL
  • NASHQ

This is intentional. Running algorithms independently means one trainer failure does not abort the entire suite, so smoke runs can still populate exports for the algorithms that worked while clearly reporting the ones that failed.

By default the runner also removes the target suite directory before starting. That prevents timing sidecars and exported arrays from accumulating stale data from previous smoke attempts.

Smoke defaults

The current smoke profile is deliberately small:

  • num_env_steps = 4096
  • num_runs = 1
  • quick NashConv enabled
  • final satisfaction verification disabled
  • eval_episodes = 4
  • br_train_iters = 1
  • br_batch_steps = 64

Trainer blocks are also reduced to keep runtime bounded:

  • num_envs = 32
  • num_steps = 128
  • PPO minibatches/epochs reduced to 1
  • IQL hidden size and replay batch size reduced

These settings are only meant to exercise the training, checkpoint, NashConv, plotting, and report-export paths. They are not benchmark settings.

Artifact Names

The smoke runner follows the same export naming convention as the experiment notebooks:

  • algorithm directories write runs.npy, nash.npy, nash_report.json, satisfaction.npy, satisfaction_report.json, objective_satisfaction_by_agent.png, and objective_satisfaction_by_agent_legend.png
  • suite directories write avg_agent_best_algos.png, avg_agent_all_algos.png, best_agent_best_algos.png, best_agent_all_algos.png, their *_legend.png variants, and per-agent summary/agent_1_best_algos.png, summary/agent_1_all_algos.png, etc.

For Stag Hunt, both players receive the same symmetric temporal objective. The per-agent satisfaction histories can therefore be identical, so player_0 and player_1 curves may be exactly overlapping in objective_satisfaction_by_agent*.png.

GPU caveat

On this machine, JAX CUDA initialization can fail before training starts when the GPU is already heavily occupied by unrelated processes. In that case JAX raises during backend/device initialization with CUDA out-of-memory rather than inside one specific trainer.

For smoke runs, the reliable fallback is to force CPU:

PYTHONPATH=/var/home/omar/Projects/amethyst/pltlf \
JAX_PLATFORMS=cpu \
XLA_PYTHON_CLIENT_PREALLOCATE=false \
MPLBACKEND=Agg \
uv run python scripts/run_matrix_smoke.py

This keeps the export path working even when the GPU is unavailable due to external pressure.