Skip to content

AlphaRank Cross-Play Verification

src.verify.alpha_rank provides the optional AlphaRank path used by the generic temporal-game experiment helpers and their environment adapters.

Strategy source

Each completed training run contributes one strategy per player population.

For a run with label like run_2_seed_1:

  • player_0 gets that run's player_0 train state
  • player_1 gets that run's player_1 train state
  • and so on for larger populations

AlphaRank then evaluates the full cross-play empirical game over all joint profiles formed by mixing those per-run strategies across players.

For R runs and N agents, each payoff tensor has shape:

  • (R, R, ..., R) with N axes

Each cell stores that agent's objective-satisfaction success probability under the selected cross-play profile.

Package layout

The package mirrors the NashConv split:

  • common.py: shared cross-play payoff construction, OpenSpiel import, result summarization, and JSON report writing
  • ippo.py
  • pr2_ippo.py
  • iql.py
  • pr2_iql.py
  • nashq.py

Each algorithm wrapper reuses its existing rollout helper from src.verify.nash_conv.* so AlphaRank and NashConv evaluate policies through the same inference codepaths.

Optional dependency behavior

AlphaRank depends on OpenSpiel's Python AlphaRank implementation.

The import is intentionally lazy:

  • notebooks and experiment helpers still import cleanly when open_spiel is not installed
  • the failure only happens when calculate_alpharank=True
  • the dependency check happens before building the cross-play payoff tables, so a missing backend fails fast instead of spending time on evaluation first

Result and report shape

Raw AlphaRank results keep the data that is useful for notebook inspection and future downstream analysis:

  • payoff_tables
  • strategy_labels
  • pi
  • ranked_profiles
  • alpha
  • eval_episodes
  • eval_seed0
  • success_threshold
  • payoff_kind

save_alpharank_report(...) writes a compact JSON report and intentionally omits the full payoff tensors. The report keeps:

  • aggregate metrics
  • top_profile
  • ranked_profiles
  • strategy_labels
  • optional metadata

Each algorithm directory stores the full raw result as alpharank.npy and the compact report as alpharank_report.json when AlphaRank is enabled.