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.
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)
FlatFee
dataclass
¶
FlatFee(fee: float)
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.
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)
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 servingw; - proportional rule on one limit:
r_i = rho b / (n a_i).