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¶
| Environment | Slug | Notebook agents | Actions/agent | Export includes agents? | Safety objective |
|---|---|---|---|---|---|
| Congestion | congestion |
2, 4, 6, or 8 | 3 | Yes | A vehicle is unsafe after an adjacent same-slot merge collision. |
| Gathering | gathering |
2 by default; configurable ≥2 | 9 | Yes | Tagged-out/frozen agent is unsafe. |
| Markov Stag Hunt | markov_stag_hunt |
2 | 5 | No | A damaged agent is unsafe. |
| Pursuit Evasion | pursuit |
2 by notebook default; 2 or 3 supported | 5 | Yes | Unsafe once all intruders occupy goals. |
| Bertrand | bertrand |
2 | 2 | No | Price-war flag. |
| Chicken | chicken |
2 | 2 | No | Crash flag. |
“Notebook 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.
Canonical Classes¶
| Slug | Environment | Labelled wrapper | Safety model |
|---|---|---|---|
congestion |
CongestionNetwork |
LabelledCongestion |
CongestionSafetyModel |
gathering |
Gathering |
LabelledGathering |
GatheringSafetyModel |
markov_stag_hunt |
MarkovStagHunt |
LabelledMarkovStagHunt |
MarkovStagHuntSafetyModel |
pursuit |
Pursuit |
LabelledPursuit |
PursuitSafetyModel |
bertrand |
BertrandMatrix |
LabelledBertrand |
BertrandSafetyModel |
chicken |
ChickenMatrix |
LabelledChicken |
ChickenSafetyModel |
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.
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.
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.