Scripts reference

Every runnable entry point lives in scripts/. Each prints the JAX devices it uses and writes into results/. Run them from the repo root with PYTHONPATH=src (or via the examples/*.sh wrappers).

scripts/run.py — train one solver on one env

PYTHONPATH=src python3 scripts/run.py --env relay_discrete --solver ppo \
    --N 8 --seeds 16 --horizon 60 --iters 300 --nu 0.0 --delay 0 --topology line

flag	default	meaning
--env	relay_discrete	world: relay_discrete | robot_consensus
--solver	ppo	reinforce | ppo | grpo | trpo | recurrent
--N	8	number of actors/agents
--seeds	16	parallel episodes (vmap); more = smoother, GPU-friendly
--horizon	60	steps per episode
--iters	300	training iterations
--nu	0.0	target drift rate (0 = static control; >0 = moving target)
--delay	0	message staleness in hops (partial observability)
--topology	line	line | ring | star | grid | tree

Writes results/<env>/<solver>.json (+ .npz, .png).

scripts/compare.py — all solvers, comparison table

PYTHONPATH=src python3 scripts/compare.py --Ns 4 8 16 --iters 400 --seeds 32 --nu 0.2 --delay 2

Runs every registered solver across --envs × --Ns under the given condition, computes the random floor and oracle ceiling per cell, and writes results/compare/comparison.md (a Markdown table) + comparison.json. Key flags: --envs, --Ns, --seeds, --horizon, --iters, --nu, --delay.

scripts/sweep_N.py — collapse vs network size

PYTHONPATH=src python3 scripts/sweep_N.py --env relay_discrete --Ns 3 5 8 12 16 \
    --seeds 16 --horizon 60 --iters 250 --nu 0.2 --delay 2

For each N runs two conditions — static (nu=0, delay=0) and wall (your nu, delay) — recording random / REINFORCE / oracle. Writes results/sweeps/<env>_sweep_N.{json,png}. Shows the oracle ceiling sinking as N grows.

scripts/surface_delay_nu.py — 3-D collapse surface

PYTHONPATH=src python3 scripts/surface_delay_nu.py --env relay_discrete \
    --Ns 4 8 16 --delays 0 1 2 3 4 5 --nus 0.0 0.1 0.2 0.3 0.4 0.5 --seeds 32

Grids the achievable (oracle) reward over delay × drift, one surface per N. Uses the oracle only (no learning) so it is exact and cheap. Writes results/surfaces/<env>_surface_delay_nu.{json,png}.

scripts/build_docs.py — regenerate this website

PYTHONPATH=src python3 scripts/build_docs.py    # rewrites docs/*.html from the source

examples/*.sh — one-line wrappers

01_train_single.sh, 02_sweep_N.sh, 03_surface_delay_nu.sh, 04_compare_solvers.sh, and jlse_job.sh (a GPU-cluster template). Each takes a couple of positional arguments; see examples/README.md.