Artifacts¶

Generated data lives under exports/ and is intentionally not versioned. The environment registry supplies the canonical root.

exports/<family>/<environment>/
exports/<family>/<environment>/<n_agents>/   # Gathering, Pursuit, Congestion

Examples:

exports/matrix/chicken/
exports/gridworlds/pursuit/2/
exports/gridworlds/congestion/4/

Variant roots keep isolated studies away from the canonical artifacts:

<root>/model_variants/<name>/          # model_variant=<name>, e.g. private-reward runs
exports/ablations/<env>/<ablation>/    # WM/OM strength ablations

Environment Root Layout¶

<root>/
├── wm/
│   ├── D.pkl
│   ├── legal_joint_graph.pkl
│   ├── legal_joint_graph.metadata.pkl
│   ├── successor_world_model.pt          # wm_variant=successor (default)
│   ├── successor_training_report.json
│   ├── world_model.pt                    # wm_variant=bit_mlp
│   ├── env_transition_graph.pkl
│   ├── models.pkl
│   ├── wm_history.pkl
│   ├── wm_report.{json,txt}
│   └── transition_tv_report.{json,txt}   # once an exact graph exists
├── om/
│   ├── iop_stack.pt
│   ├── policy_after_imagination.pt
│   ├── *_report.{json,txt}
│   └── agents/player_<i>/iop_stack.pt    # extra shielded roles
├── shield/
│   ├── transition_shield_bundle.pkl
│   ├── transition_shield_bundle_player_<i>.pkl
│   ├── oracle_iop_transition_shield_bundle*.pkl
│   └── *_report.{json,txt}
├── true_shield/
│   ├── true_transition_graph.pkl
│   ├── true_transition_graph.metadata.pkl
│   └── exact_anytime/
│       ├── certificate.pkl
│       └── report.json
├── experiments/
│   ├── histories/*.pkl
│   ├── tables/*.csv.gz
│   ├── metrics/*.{json,csv.gz}
│   ├── diagnostics/*.{json,txt}
│   ├── checkpoints/*.pkl
│   ├── manifests/*.json
│   ├── traces/*.jsonl.gz
│   ├── runs/<tag>/...
│   │   └── final_policy/<artifact>_run<N>.json
│   └── *.png
├── timings.json
└── timings_hardware.json

Not every run creates every file. Baseline-only experiments do not need model or shield artifacts, and exact/learned graph outputs may be absent when a stage has not completed. The oracle bundle and transition_tv_report appear only once true_shield/true_transition_graph.pkl exists, because they compare the learned models with the exact one.

Cache Validity¶

Legal and true-transition graph caches have metadata sidecars. Learned shield bundles package metadata with the pickle. Identity checks cover relevant source semantics, environment dimensions, builder parameters, artifact modification metadata, focal agent, and value-iteration settings. Rebuild upstream artifacts after changing agent count, state layout, action semantics, safety labels, world-model variant, or graph construction.

Because identity includes modification metadata, preserve modification times when copying wm/, om/, and shield/ between machines (for example with tar or rsync -t); otherwise the shield bundle is treated as stale and rebuilt.

The shield cache always holds the point-kernel bundle. A padded shield (shield_padding_radius > 0) pads that bundle in memory, so padded and unpadded runs share one cache file.

The exact_anytime/ pair is created only by the opt-in arbitrary-opponent diagnostic. report.json is the portable paper-facing summary; certificate.pkl contains the checked state values, exact robust action risks, and worst-case opponent witnesses used by the strict runtime wrapper.

Histories and Figures¶

Canonical algorithm histories live in experiments/histories/ with names such as ippo_histories.pkl, cpo_histories.pkl, and ippo_shielded_histories.pkl. Non-default shield conditions receive stable suffixes, for example ippo_shielded_egalitarian_mixed_histories.pkl or ippo_shielded_padded_r0p15_histories.pkl.

The normal figure set includes cumulative and episodic views, post-WM timeline variants, no-legend copies, shield telemetry, Bayesian opponent-level views, and structured per-metric episode graphs. Separate legend assets live under exports/legends/.

Every completed algorithm condition also writes compressed episode tables, optimizer/update metrics, aggregate JSON/text diagnostics, final checkpoints, and a manifest. The manifest is published last, so report readers do not treat partially written condition artifacts as complete. Raw trace files appear only when verbose_data=true. Coordinated multi-role runs add tables/<artifact>_per_agent_episodes.csv.gz.

Checkpoints¶

Final checkpoints use schema version 3. Each records the algorithm, trainer seed, configuration, a restorable inference policy for every agent, and the optimizer state. For OmSh it also records the post-training controller state: opponent posterior, monotone floor, patience counters, and credible-schedule state. That state is what lets a frozen OmSh policy be evaluated as it was deployed; see Final-Policy Evaluation.

Tagged Campaigns and Reports¶

Setting experiment_tag redirects histories, diagnostics, checkpoints, final-policy reports, manifests, timings, and aggregate figures to experiments/runs/<normalized-tag>/. It does not overwrite the corresponding canonical stage outputs.

Cross-environment outputs live at the top of exports/:

Only conditions with their final manifest are counted as complete. See Analysis and Audits for the scripts.

Timing Sidecars¶

timings.json stores stage totals and per-run entries. Each entry references a deduplicated hardware record in timings_hardware.json. Hardware describes the resources available to the process: CPU affinity/scheduler allocation, enforced memory limit, and visible GPUs, not the whole physical cluster node.

Writers use per-file locks, merge stage keys with the latest file, and replace the JSON atomically so concurrent algorithm jobs do not discard one another's records. Opponent-model jobs for several roles still run one after another, because they share the environment-root timing file.