Skip to content

NashConv Reporting

Every selected algorithm writes its NashConv artifacts inside its own exports/.../<algorithm>/ directory:

  • nash.npy: raw NashConv run payloads as a NumPy pickle-friendly array.
  • nash_report.json: aggregate metrics, per-agent averages, and JSON-safe raw run records.
  • a notebook console summary with mean, standard deviation, minimum, and maximum NashConv.

The reusable reporting logic now lives in src/verify/nash_conv/:

  • src/verify/nash_conv/common.py owns summarize_nashconv_runs(...) and save_nashconv_report(...).
  • src/verify/nash_conv/__init__.py reexports the public verifier entrypoints.
  • src/verify/approx_nash_conv.py remains as a compatibility reexport shim for active verifier entrypoints so older imports do not break.

Algorithm-specific approximate-best-response entrypoints now include:

  • approximate_nashconv_bernoulli_ippo(...)
  • approximate_nashconv_bernoulli_pr2_ippo(...)
  • approximate_nashconv_bernoulli_iql(...)
  • approximate_nashconv_bernoulli_pr2_iql(...)
  • approximate_nashconv_bernoulli_nashq(...)

Current aggregate metrics include:

  • number of evaluated runs
  • mean, standard deviation, min, max, and median NashConv
  • per-agent mean baseline success probability
  • per-agent mean best-response success probability
  • per-agent mean delta and mean/max positive delta
  • mean endpoints of the jointly covered approximate NashConv interval

Joint confidence

All approximate NashConv entrypoints accept delta (the temporal-game config uses nashconv_delta, default 0.05). Baseline and learned-best-response success bits are paired by evaluation episode, so each agent's deviation sample lies in [-1, 1]. For n episodes and m agents, equal Bonferroni allocation gives the two-sided Hoeffding half-width:

sqrt(2 * log(2 * m / delta) / n)

The resulting delta_joint_ci intervals cover every evaluated agent's deviation mean simultaneously with probability at least 1 - delta. Applying max(0, ยท) to each endpoint and summing produces nashconv_joint_ci. Per-run payloads also contain delta_joint_half_width and self-describing joint_confidence metadata. Existing baseline_ci95, br_ci95, and delta_ci95 fields remain unchanged.

The guarantee is only for rollout error conditional on the finite-budget learned best responses. It does not prove that no unsearched policy is a more profitable deviation and therefore is not a formal epsilon-Nash certificate. It also does not change training or evaluation budgets between decentralized learners. Auto-resume continues to compare the NashConv point estimate to its threshold.

This keeps the raw algorithm-specific approximate NashConv outputs intact while also producing a stable file that is easier to inspect, compare across runs, or ingest into downstream analysis scripts.

Legacy report payloads are normalized in memory with delta=0.05 when summarized, so old artifacts remain readable while new reports expose the joint fields.

Notebook progress

The approximate NashConv entrypoints now display tqdm.auto progress bars by default. The shared NashConvProgress helper in src/verify/nash_conv/common.py only forwards updates to tqdm when another 5% of the configured work has completed, so Marimo/Jupyter cells do not redraw on every evaluation episode.

Callers that need quiet execution can pass show_progress=False; callers that need a different redraw cadence can pass progress_refresh_percent=<percent>. Progress units cover the baseline rollout episodes, each agent's best-response rollout episodes, and one best-response training unit per agent.