Skip to content

Tools

icgym.compare

Compare allocation rules and fees on one batch: what an operator would see.

:func:compare_rules finds each rule's equilibrium (the theory's answer where one is known, checked numerically; otherwise best-response dynamics from the max-min fair point) and reports what it serves, what it wastes, and how far it is from the planner's optimum. :func:report_html writes a self-contained page.

RuleReport dataclass

RuleReport(rule: str, method: str, requests: list = list(), served: list = list(), total_served: float = float('nan'), planner_total: float = float('nan'), efficiency: float = float('nan'), price_of_anarchy: float = float('nan'), poa_bound: float | None = None, max_inflation: float = float('nan'), unserved_requested_mw: float = float('nan'), commitment_on_unserved: float = float('nan'), payoffs: list = list(), exploitability: float = float('nan'), binding_limits: list = list(), rounds: int | None = None, note: str = '')

One rule's equilibrium on the batch (MW and the fee's money units).

compare_rules

compare_rules(region, rules=('uniform', 'proportional', 'utilitarian'), fee: Fee | None = None, value: float | ndarray = 1.0, beta: float = 0.5, slow: bool = False, max_rounds: int = 25, check: bool = True, grid: int = 120) -> list[RuleReport]

Equilibrium outcome of each rule on region.

rules are names from RULES or :class:AllocationRule objects. fee defaults to a per-MW commitment of 0.4 (in units of the value). check=True computes each equilibrium's exploitability by search (a theory answer should give zero); grid sets the best-response search (grid points plus local refinement). On an implicit region (DCOPFRegion) only closed-form equilibria are computed unless slow=True.

format_table

format_table(reports: list[RuleReport], applicant_names=None) -> str

Plain-text table, one row per rule, then served MW per applicant.

to_json

to_json(reports: list[RuleReport]) -> str

The reports as JSON (non-finite numbers as null).

report_html

report_html(reports: list[RuleReport], path, title: str = 'Allocation rule comparison', subtitle: str = '', applicant_names=None) -> None

Write a self-contained HTML report (table plus served-versus-requested bars per rule).

icgym.benchmarks

Benchmark tasks with known answers, three baselines, and a runner.

Each :class:Task is a game whose equilibrium the theory pins down (or proves absent), so a learner's final profile can be scored exactly:

  • exploitability: the largest gain any applicant has from deviating alone, over its value at its hosting capacity (0 at an equilibrium);
  • distance: the largest gap to the predicted equilibrium, per applicant, over its hosting capacity (served loads for the flat-fee band, where any profile in the band is an equilibrium; absent when none exists);
  • efficiency: total served over the planner's optimum (batch tasks) or the total share over the best total of any placement (location).

Baselines: best_response (best-response dynamics on the game, an oracle that sees payoffs), hedge (full-information multiplicative weights on a grid of actions; it sees the payoff of every action against the rivals' sampled play), and independent_pg (independent policy gradient, which sees only its own rewards, as an RL agent in the environments would).

from icgym.benchmarks import TASKS, run, run_suite, format_results
res = run_suite(["uniform-ieee14"], ["best_response", "independent_pg"], seeds=range(3))
print(format_results(res))

adapter

adapter(game, request_cap: float = 2.0)

The benchmark adapter of a game (batch, two-part, or location).

best_response

best_response(ad, rng, iterations=None)

Baseline: best-response dynamics from a random start.

hedge

hedge(ad, rng, iterations: int = 200, samples: int = 4, eta: float = 8.0, k1: int = 41, k2: int = 5)

Full-information multiplicative weights; returns each applicant's most likely grid action.

independent_pg

independent_pg(ad, rng, iterations: int = 400, batch: int = 128, lr: float = 0.3)

Independent policy gradient with a per-applicant baseline, from rewards only.

Box actions: a Gaussian in logit space, a = sigmoid(z), updated along the natural gradient (the mean moves by lr * sigma * E[adv * eps], as in evolution strategies, so steps shrink with the noise); discrete actions: softmax over the menu. Advantages are normalized per applicant and the step size decays linearly. Returns the mean (or most likely) action.

run

run(task: str, baseline: str, seed: int = 0, **kw) -> dict

Run one baseline on one task; returns the metrics of its final profile.

run_suite

run_suite(tasks=None, baselines=None, seeds=range(3), progress: bool = False) -> list[dict]

Run every (task, baseline, seed); returns one result dict per run.

format_results

format_results(results: list[dict]) -> str

Markdown table: mean (and max) over seeds for each task and baseline.

main

main(argv=None) -> None

icgym-bench: run baselines on the benchmark tasks and print a Markdown table.