Supported Environments¶

All environments implement the PettingZoo parallel API and use discrete action spaces. Experiment notebooks wrap them with a LabelledEnv subclass so reward and focal-agent safety cost are recorded independently.

Environment Matrix¶

"Agents" describes the maintained training/export workflows, which may be narrower than the raw class constructor. The full cluster matrix runs Pursuit at two and three agents.

Notebook Defaults and Campaign Settings¶

Notebook defaults suit local runs. The published campaign overrides several of them; see Reproduce the Campaign Protocol.

Congestion episodes are capped at 64 steps, so its frozen evaluation uses horizons (1, 2, 10, 64) rather than the default (1, 10, 50, 100, 200).

Pursuit's default 0.16 is the first clean budget above the successor world model's reset demand (about 0.1515); the earlier product-Bernoulli world model needed only 0.11.

Congestion Fleet Sizes¶

Congestion is a merge network on a ring. With an even fleet, alternating early and late slots lets every vehicle take the direct route safely. An odd ring cannot alternate, so every safe outcome routes at least one vehicle through the bypass and the coordinated optimum is asymmetric.

The environment accepts any n_agents >= 2. The generic discovery registry lists the even counts 2, 4, 6, and 8; odd fleets work when passed to the notebooks directly. The maintained scaling series is 2, 3, and 4 vehicles. At 6 vehicles, opponent-model training is the measured compute limit (about 11 days per role), and 8 is not maintained.

The campaign shields both roles at two vehicles (shielded_agent_ids=player_0,player_1); each role needs its own opponent model.

Canonical Classes¶

Agent-Count Consistency¶

Congestion, Gathering, and Pursuit include n_agents in their canonical export root. Pass the same value to WM, OM, and experiment stages. A graph or opponent checkpoint from another agent count has incompatible state/action dimensions and must not be reused.

Markov Stag Hunt's raw environment accepts additional agents, but the maintained notebook export root does not include the count. Treat the standard workflow as two-agent unless the notebook/export scheme is extended first.

Reward Variants¶

Bertrand and Chicken accept reward_game_variant. The default keeps the symmetric payoff matrices. private_heterogeneous gives player_1 a distinct payoff table while leaving the focal payoff and unsafe event unchanged; it is used by the private-reward ablation.

Retired Environments¶

An earlier matrix-road environment also called Congestion was retired after a fresh safety-first screen. The active congestion slug refers only to the merge-network benchmark above, which passed its five-seed reward–safety gate. Its early runs used the export path gridworlds/convention_merge/2; scripts that re-evaluate those runs accept an explicit --export-dir.

Ice Duel, Dynamic Public Goods, Inspection, and the earlier matrix-road implementation remain recoverable from Git history and are maintained as general-purpose environments in rl-engine, but they are not discoverable or launchable from this repository.

Discovery¶

notebooks.env_discovery discovers classes exported from src.environments and applies the maintained slug, alias, count, and export-path metadata. Use its get_env_spec(...), instantiate_env(...), and export_root(...) helpers in generic notebooks rather than duplicating registries.