Skip to content

Visualization

The repository renders environments, transition graphs, learning curves, shield diagnostics, legends, and conceptual diagrams.

Experiment Figures

Experiment notebooks export cumulative and episodic reward/safety comparisons. The standard names are:

  • cumulative.png and episodic.png, including the world-model pretraining prefix where available,
  • cumulative_post.png and episodic_post.png, starting at policy training,
  • matching _no_legend.png files for paper layout, and
  • shield_telemetry.png plus its no-legend variant, and
  • om_bayesian_levels*.png, which overlays the unconstrained Bayesian posterior mode with the monotone shield floor.

Shielded curves are drawn with the world-model pretraining prefix ahead of the shielded timeline, for every seed, so their x-axis counts every environment step OmSh consumed. Plots truncate algorithms to a shared horizon when requested so a longer run does not distort the comparison. Structured graphs/... outputs use completed EpisodeLog rows at their actual t_end values.

Condition Labels

Reports and figures share condition labels: IPPO (unshielded), IPPO-Lagrangian, CPO, and OmSh-Monotone for the primary methods, and TrueShielded for the oracle reference. Shield variants add their mode to the label, for example OmSh-Credible, OmSh-Egalitarian-Mixed, or OmSh-Monotone-Padded-r0.15. Every OmSh variant, including the coordinated two-role shield, uses OmSh's colour family rather than a baseline's. Paper table generators take environment names and row order from PAPER_ENVIRONMENT_LABELS, so generated tables need no hand editing.

Shield Telemetry

Telemetry separates policy behavior from shield intervention. It can show override and unsafe-proposal counts, missing coverage, proposed/final risk, opponent-level raises, and budget evolution. An apparently safe reward curve is not enough to tell whether the base policy learned safety or the shield replaced many actions.

The Bayesian-level figure deliberately does not call the posterior mode a ground-truth reasoning level. Downward posterior changes and time spent below the irreversible shield floor are diagnostics of the modelling assumption, not violations of the monotone runtime rule.

Experiment runs also export tabular calibration and aggregate diagnostics. World-model reports cover held-out state/reward quality; opponent reports cover observed-action prediction; shield reports cover convergence, coverage, feasibility, and learned-versus-exact agreement where an exact graph is already available. These reports should accompany reward/safety plots when diagnosing a poor condition.

plot_floor_by_seed and plot_belief_and_floor in src.visualisation.levels draw the appendix view of how the monotone floor rises during training: Pursuit's per-seed floors, and Markov Stag Hunt's posterior mean level against its floor.

Re-exporting the Paper Figures

scripts/export_paper_figures.py --tag <tag> re-renders every paper figure from a campaign's saved histories, without retraining: each environment's learning curves and shield telemetry (into its tagged run directory, as the notebooks' visualisation cells write them), the standalone legends (exports/legends/), and the floor-progression panels (exports/reports/<tag>/floor_progression/). It needs no GPU: the six campaign environments took 7 minutes on one gpucluster training node in October 2026 (job 295720), submitted from $HOME as

submit -p training --gres=none --mem=24G --cpus-per-task=2 --time=03:00:00 \
  ~/py.sh omsh/scripts/export_paper_figures.py venv=omsh tag=successor_campaign_v1

py.sh resolves the script path before its own git pull, so pull the cluster checkout first when the script is new. The training partition still attaches one GPU despite --gres=none.

Environment and Graph Rendering

Environment renderers live beside the implementations under src/environments/. Shared gridworld and matrix drawing helpers provide common tiles, panels, score boxes, and overlays. Exact/learned joint graphs can be exported to Graphviz DOT through src.joint_graph.visualise.

Diagram Notebooks

notebooks/diagrams/ contains world-model, IOP, and shielding diagrams. Shared helpers provide graph slicing, state summaries, Graphviz styles, and notebook fallbacks when the dot executable is unavailable. Use these notebooks for explanatory figures without running full training.

Styling and Legends

src.visualisation.styling contains paper, panel, and presentation styles. Paper figures are drawn on a PAPER_FIGSIZE (5.8 x 2.3 in) canvas that the paper prints at 0.45\textwidth, so their text prints at 6-7 pt; see docs/AI/experiments/visualisation-styling.md. notebooks/generic/legend_mo.py exports reusable algorithm legends into exports/legends/, which lets paper figures omit repeated in-panel legends.