Skip to content

Core

icgym.region

Batch regions: the served loads a network can host.

A region is the polytope {s >= 0 : A s <= b} over the applicants' served loads. Allocation rules and the equilibrium results assume it is downward closed, which holds exactly when A >= 0. A general polytope is reduced to its largest downward-closed subset by keeping the positive part of A, which treats counterflow between new loads as non-firm.

Region dataclass

Region(A: ndarray, b: ndarray, limit_names: tuple[str, ...] = (), applicant_names: tuple[str, ...] = ())

Downward-closed batch region {s >= 0 : A s <= b} with A >= 0.

Rows are shared limits (branches, spare generation, import limits); columns are applicants.

n property

n: int

Number of applicants (columns of A).

m property

m: int

Number of shared limits (rows of A).

downward_closed classmethod

downward_closed(A, b, **names) -> Region

Largest downward-closed subset of {x >= 0 : A x <= b} (Lemma 4.1).

Negative entries of A are relief one new load gives another (counterflow); dropping them keeps every single-bus hosting capacity.

single_limit classmethod

single_limit(loadings, capacity: float, **names) -> Region

One shared limit sum_i a_i s_i <= capacity.

contains

contains(s, tol: float = 1e-07) -> bool

Whether served loads s lie in the region, within tol.

hosting_capacities

hosting_capacities() -> np.ndarray

Single-bus hosting capacity h_i = max_{s in region} s_i.

restrict

restrict(applicants) -> Region

Region seen by a subset of applicants (the others served zero).

max_total

max_total() -> tuple[float, np.ndarray]

Planner's optimum: the largest total served load and a maximizer.

icgym.waterfill

Water-filling on a downward-closed region.

Serve each active applicant min(r_i, lambda_i * t) as a common level t rises; an applicant stops when it reaches its request or when a limit it loads becomes tight. With unit weights this is the uniform rule; with unbounded requests it returns the (weighted) max-min fair point.

Stage dataclass

Stage(level: float, applicants: tuple[int, ...], limits: tuple[int, ...])

One event of unbounded water-filling: the applicants that stop at a level.

water_fill

water_fill(region: Region, requests, weights=None, active=None, return_stages: bool = False)

Allocation U(r) of water-filling without the minimum allocation.

requests may contain np.inf. active masks applicants that take part (the others are served zero). With return_stages the stopping events are returned too.

max_min_fair_point

max_min_fair_point(region: Region, weights=None, return_stages: bool = False)

The (weighted) max-min fair point w = U(inf * 1) and its stages.

icgym.rules

Allocation rules an operator can apply to a batch of requests.

Every rule maps requests r to served loads s with 0 <= s <= r and s in the region. The minimum allocation beta drops an applicant served less than beta * r_i and recomputes the allocation for the rest.

AllocationRule

Bases: ABC

Base class: subclasses implement _allocate_active.

allocate

allocate(region: Region, requests) -> np.ndarray

Served loads for requests on region, with the minimum allocation applied.

UniformRule dataclass

UniformRule(beta: float = 0.0, weights: tuple[float, ...] | None = None, cut_order: str = 'largest_request')

Bases: AllocationRule

Water-filling with a common level (the paper's uniform rule).

With weights, applicant i rises at rate weights[i] (the weighted uniform rule); weights must be fixed before the requests are known.

ProportionalRule dataclass

ProportionalRule(beta: float = 0.0, cut_order: str = 'largest_loading')

Bases: AllocationRule

Scale every active request by one common fraction until a limit binds.

The minimum allocation drops the applicant that loads the binding limit most; dropping by MW instead can break the equilibrium (see the paper).

UtilitarianRule dataclass

UtilitarianRule(beta: float = 0.0, cut_order: str = 'largest_request')

Bases: AllocationRule

Serve the largest total load, max 1's subject to s <= r.

Ties among maximizers are broken by maximizing the smallest service fraction. The total is what a planner maximizes, but applicants then gain by inflating requests at sites that load the limits least.

icgym.fees

What applicants pay for their requests.

cost(r, s) returns each applicant's payment given requests r and served loads s. A fee that grows with the request is what disciplines requests under the uniform rule; a flat fee does not.

Fee

Bases: ABC

What applicants pay: subclasses define cost(requests, served).

marginal_request_cost

marginal_request_cost() -> float

Cost of one more MW of request that is not served (0 for a flat fee).

PerMWCommitment dataclass

PerMWCommitment(kappa: float)

Bases: Fee

Commitment kappa per MW requested, paid whether or not served.

cost

cost(requests, served)

kappa per MW requested, served or not.

marginal_request_cost

marginal_request_cost()

kappa.

FlatFee dataclass

FlatFee(fee: float)

Bases: Fee

A study fee f per applicant, independent of the request.

cost

cost(requests, served)

fee for each applicant with a positive request.

SecurityDeposit dataclass

SecurityDeposit(per_mw: float, carrying_rate: float = 0.0, forfeit_rate: float = 0.0, study_fee: float = 0.0)

Bases: Fee

A deposit per_mw per MW requested, returned except for a forfeit.

The applicant bears the carrying cost carrying_rate * per_mw per MW requested and forfeits forfeit_rate * per_mw per MW requested but not served (as when unused capacity is released), plus an optional flat study fee.

cost

cost(requests, served)

Carrying cost on the request, forfeit on unserved MW, and the study fee.

marginal_request_cost

marginal_request_cost()

The carrying cost per MW requested.

icgym.game

The batch request game: applicants choose requests, the rule serves them.

Applicant i earns V_i s_i - cost_i(r, s), where s is the rule's allocation of the requests r on the region. This is the reduced game of the paper (one site per applicant at a fixed bus, constant value per MW).

BatchGame dataclass

BatchGame(region: Region, rule: AllocationRule = UniformRule(), fee: Fee = (lambda: PerMWCommitment(0.4))(), value: float | ndarray = 1.0)

n property

n: int

Number of applicants.

allocate

allocate(requests) -> np.ndarray

Served loads under the game's rule.

payoffs

payoffs(requests, served=None) -> np.ndarray

Each applicant's payoff V_i s_i - cost_i(r, s); served skips the allocation.

payoff

payoff(i: int, x: float, requests) -> float

Applicant i's payoff when it requests x and the others keep requests.

predicted_equilibrium

predicted_equilibrium() -> dict

The theory's answer for this game (see :func:icgym.predicted_equilibrium).

best_response

best_response(i: int, requests, method: str = 'auto', grid: int = 400, interval: tuple[float, float] | None = None) -> tuple[float, float]

Best request of applicant i against the others' requests.

method='exact' uses the closed form when it applies (uniform rule, no minimum allocation, per-MW cost); 'search' maximizes the payoff numerically over [0, upper], which also finds deviations that get a rival cut. Returns (request, payoff). Under the minimum allocation the supremum may not be attained; the search returns the best point found. interval=(lo, hi) restricts the search (useful when each payoff is expensive, as with energy at the LMP).

exploitability

exploitability(requests, method: str = 'auto', grid: int = 400) -> np.ndarray

Each applicant's gain from its best unilateral deviation (0 at an equilibrium).

best_response_dynamics

best_response_dynamics(requests, max_rounds: int = 50, order: str = 'cyclic', tol: float = 1e-07, method: str = 'auto', seed: int | None = None, grid: int = 400, gain_tol: float | None = None)

Applicants best-respond in rounds, each once per round.

Returns (requests, history, rounds), where rounds counts the rounds in which some request changed, or None if the profile did not settle within max_rounds. A round settles only if no request moved by more than tol and no applicant could gain more than gain_tol (in payoff units; default 1e-9 * max |V h|) by deviating: under the minimum allocation a best response can be a vanishing undercut of a rival with a large gain, which is not an equilibrium.

grid_equilibria

grid_equilibria(game, strategy_sets, tol: float = 0.0)

All pure equilibria of game when applicant i may only play strategy_sets[i].

Works for any game with payoffs(profile): requests (BatchGame), (request, second) pairs (the device and non-firm games), or placements. A profile is an equilibrium when no applicant gains more than tol by switching to another strategy of its set. Returns (equilibria, table), where table maps index profiles to payoffs (prod |set_i| evaluations).

icgym.oracles

Ground truth from the theory: equilibria, efficiency, and their bounds.

These functions return what the paper proves, so that learned or observed behavior can be scored against it.

stages

stages(region: Region, weights=None)

Levels tau_k and blocked sets B_k of unbounded water-filling.

price_of_anarchy

price_of_anarchy(region: Region, served) -> float

Planner's best total over the total of served.

poa_bound

poa_bound(region: Region) -> float

(1 + nR)^2 / (4nR) with R the spread of hosting capacities (paper: price of anarchy).

proportional_inflation

proportional_inflation(n: int, value: float, kappa: float, beta: float) -> float

Request inflation rho of the proportional rule on one limit (paper: proportional rule).

predicted_equilibrium

predicted_equilibrium(game: BatchGame) -> dict

What the theory predicts for this game, or {'known': False}.

  • uniform (or weighted) rule with a per-MW cost below the value: the unique equilibrium is the (weighted) max-min fair point, served in full;
  • uniform rule with a flat fee: every profile in [w, w/beta] is an equilibrium, all serving w;
  • proportional rule on one limit: r_i = rho b / (n a_i).