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.