Extensions¶
icgym.location ¶
The location game: applicants choose where to connect, then what to request.
Each applicant picks a placement from its finite menu: a bus, or a vector of
proportions over buses for a load split across sites. Given the placements,
the request stage under the uniform rule with a per-MW commitment below the
value has the unique equilibrium w(sigma), the max-min fair point of the
placements' batch region (paper: max-min fair equilibrium), so applicant i
earns (V - kappa) w_i(sigma). The location game is the game over
placements with these payoffs.
On a downward-closed network region (counterflow treated as non-firm) it has a
strong pure equilibrium and every sequence of improving moves is finite: each
move raises the sorted vector of shares lexicographically (paper: location
game). :meth:LocationGame.improving_moves and
:meth:LocationGame.best_response_dynamics check both on any instance.
A move counts as improving if it raises the mover's share by more than
tol (default 1e-4, in the region's units, MW for network regions), which
keeps solver noise out of the counts.
LocationGame ¶
LocationGame(menus: Sequence[Sequence[Placement]], region_for: Callable[[Profile], object] | None = None, margin: float | Sequence[float] = 1.0, table: dict | None = None, scale: float | None = None, names: Sequence[str] | None = None)
Location game over placements, with shares from the request-stage equilibrium.
region_for(profile) returns the batch region (a :class:Region or an
implicit region such as :class:icgym.DCOPFRegion) whose column i
is applicant i at profile[i]. Shares are cached by the multiset of
placements, so applicants at the same placement are interchangeable;
margin is V - kappa (payoff per MW served).
scale
property
¶
scale: float
A share scale for normalizing rewards (largest single-placement hosting capacity, if known).
from_bus_region
classmethod
¶
from_bus_region(region: Region, menus, margin=1.0) -> LocationGame
Placements on a region over buses (columns of region are buses).
A placement is a bus index or a vector of proportions over buses
(summing to one); applicant i at m loads limit c by
(A m)_c per MW. Needs region downward closed over all buses,
which :class:Region is.
from_network
classmethod
¶
from_network(net, menu: Sequence[str], n: int, margin=1.0, **region_kw) -> LocationGame
n applicants choosing buses of menu on a DC network (exact DCOPF regions).
Each new multiset of placements costs a few water-filling LPs (seconds on a 2,000-bus network); results are cached.
from_table
classmethod
¶
from_table(menus, table: dict, margin=1.0) -> LocationGame
A game whose shares were computed beforehand: table[profile] = w.
payoff ¶
payoff(i: int, x, profile) -> float
Applicant i's payoff when it takes placement x and the others keep profile.
potential ¶
potential(profile) -> np.ndarray
Shares sorted in increasing order; every improving move raises it lexicographically.
best_response ¶
best_response(i: int, profile, tol: float = 0.0001) -> tuple[Placement, float]
Best placement of applicant i against the others, and its payoff.
Keeps the current placement unless another raises the share by more than tol.
exploitability ¶
exploitability(profile, tol: float = 0.0001) -> np.ndarray
Each applicant's payoff gain from its best move (0 at a pure equilibrium).
is_equilibrium ¶
is_equilibrium(profile, tol: float = 0.0001) -> bool
Whether no applicant gains more than tol (MW of share) by moving.
pure_equilibria ¶
pure_equilibria(tol: float = 0.0001) -> list[tuple]
All pure equilibria, by enumerating every profile (prod |menu_i| of them).
improving_moves ¶
improving_moves(tol: float = 0.0001) -> dict
Every unilateral improving move, and how many fail to raise the sorted shares.
The theory says violations == 0 on a downward-closed region.
best_response_dynamics ¶
best_response_dynamics(start, max_rounds: int = 100, order: str = 'cyclic', seed: int | None = None, tol: float = 0.0001)
Best-response dynamics in rounds; returns (profile, path, rounds).
rounds is the number of rounds with a move, or None if the
profile did not settle within max_rounds.
activsg2000_location ¶
activsg2000_location(margin: float = 1.0) -> LocationGame
The paper's ACTIVSg2000 location game: three applicants, six buses spanning the hosting-capacity range.
Shares of all 216 placements were computed with :class:icgym.DCOPFRegion
on the five representative days and ship with the package.
icgym.devices ¶
On-site generation, storage, and non-firm service (paper: on-site generation and non-firm service).
The limits bind only in peak periods (nu per day, dt hours each). A
generator of capacity G_i <= gamma r_i with a daily run-hour budget h
shaves theta G_i from every peak period, theta = min(1, h / (nu dt));
a battery of power P_i and duration eta does the same with
theta_S = min(1, eta / (nu dt)). Who keeps the capacity a device frees is
the operator's choice:
rule='gross': one common level on served load; the net loads(s - theta G)^+must fit the peak region, so the freed room is shared.rule='credit': the uniform rule on net requestsr - theta G, plustheta G_icredited to its owner.
Curtailable (non-firm) load is a device with theta = 1, no capital cost,
and a fuel cost equal to the peak value forgone. :class:NonFirmGame has the
two-tier rule (firm requests on the peak region, non-firm requests on the
off-peak room left) and the gross rule (a curtailable fraction phi_i of a
common level).
Every game here has two-part strategies X[i] = (request, second);
:meth:TwoPartGame.best_response searches both parts numerically and
:meth:predicted_equilibrium returns the theory's answer.
TwoPartGame ¶
Games whose strategies are X[i] = (request, second part).
payoff ¶
payoff(i: int, x, strategies) -> float
Applicant i's payoff when it plays x and the others play strategies.
best_response ¶
best_response(i: int, strategies, grid: int = 120, second_grid: int = 11, fix_second: bool = False) -> tuple[np.ndarray, float]
Best (request, second) of applicant i against strategies, by grid search and refinement.
With fix_second=True only the request moves (the second part stays
at X[i, 1]).
hosting_capacity ¶
hosting_capacity(i: int) -> float
Scale of applicant i's request (its hosting capacity, with its own device at the cap).
strategy_from_action ¶
strategy_from_action(i: int, action, request_cap: float = 2.0) -> np.ndarray
Map an action in [0, 1]^2 to (request, second part).
The request is action[0] * request_cap * hosting_capacity(i); the second
part is action[1] times its own cap (gamma r_i for a device,
gamma for a curtailable fraction, request_cap times the
off-peak hosting capacity for a non-firm request).
best_response_dynamics ¶
best_response_dynamics(strategies, max_rounds: int = 30, tol: float | None = None, gain_tol: float | None = None, grid: int = 60, second_grid: int = 6)
Applicants best-respond in turn, each once per round.
Returns (strategies, history, rounds), where rounds counts the
rounds with a change, or None if the profile did not settle within
max_rounds. A round settles only if no strategy moved by more than
tol and no applicant could gain more than gain_tol (defaults
scale with the hosting capacities), as in
:meth:icgym.BatchGame.best_response_dynamics.
exploitability ¶
exploitability(strategies, fix_second: bool = False, **kw) -> np.ndarray
Each applicant's gain from its best unilateral deviation (0 at an equilibrium).
Device
dataclass
¶
Device(theta: float, gamma: float, cost: float, name: str = 'generator')
A device that shaves theta of its capacity from every peak period.
gamma caps the capacity at gamma * request; cost is the cost per
MW of capacity (capital plus peak-period fuel).
generator
classmethod
¶
generator(run_hours: float, nu: int, gamma: float, capital: float, fuel_cost: float = 0.0, peak_weight: float = 0.0, dt: float = 1.0) -> Device
Generator with a daily run-hour budget; fuel F = theta * fuel_cost * peak_weight per MW.
storage
classmethod
¶
storage(duration: float, nu: int, gamma: float, power_cost: float, energy_cost: float, dt: float = 1.0) -> Device
Battery of the given duration charged off-peak (paper: storage remark); cost kappa^P + eta kappa^B.
GenerationGame ¶
GenerationGame(region: Region, device: Device, value: float = 1.0, kappa: float = 0.4, rule: str = 'gross', beta: float = 0.0, enforce_cap: bool = True)
Bases: TwoPartGame
Requests and on-site devices on a peak-period region; X[i] = (r_i, G_i).
Payoff V s_i - kappa_C r_i - cost G_i; G_i is clipped to
gamma r_i unless enforce_cap=False (the theorem's part 1 sets the
cap aside).
allocate ¶
allocate(strategies) -> np.ndarray
Served loads under the game's rule (gross or credit); devices are clipped to the cap.
shares_given_devices ¶
shares_given_devices(G) -> np.ndarray
w(G): the unique equilibrium of the requests with devices fixed (cap set aside).
scrapper_margins ¶
scrapper_margins() -> np.ndarray
mu-_i = theta (V - kappa_C) a_i / sum_j a_j - cost on a single limit.
predicted_equilibrium ¶
predicted_equilibrium() -> dict
The theory's equilibrium: any region under crediting, one limit under the gross rule.
NonFirmGame ¶
NonFirmGame(peak: Region, offpeak: Region | None = None, value: float = 1.0, peak_value: float = 0.2, kappa: float = 0.4, rule: str = 'two_tier', gamma: float = 0.5)
Bases: TwoPartGame
Firm and non-firm connections (paper: firm and non-firm connections).
peak and offpeak are the batch regions of the peak and the other
periods (offpeak=None: unconstrained off peak). peak_value is
V^p, the value of the load in the peak periods; V^o = V - V^p.
rule='two_tier':X[i] = (firm request, non-firm request).rule='gross':X[i] = (request, curtailable fraction phi_i <= gamma).
gross_region ¶
gross_region(phi) -> Region
Served loads whose peak net loads (1 - phi) s and off-peak loads s fit.
allocate ¶
allocate(strategies)
Served loads: (firm, non-firm) per applicant for the two-tier rule, s for the gross rule.
payoffs ¶
payoffs(strategies) -> np.ndarray
Each applicant's payoff under the two-tier or the gross rule.
predicted_equilibrium ¶
predicted_equilibrium() -> dict
The theory's equilibrium: any network under the two-tier rule, single limits under the gross rule.
peak_theta ¶
peak_theta(hours: float, nu: int, dt: float = 1.0) -> float
Share of capacity a device can shave from each of nu peak periods: min(1, hours / (nu dt)).
water_fill_offset ¶
water_fill_offset(region: Region, requests, offset, active=None) -> np.ndarray
Water-filling on {s >= 0 : A (s - offset)^+ <= b}, the served loads whose net loads fit.
Served loads rise at a common level, each capped by its request, and an
applicant stops when a limit it would load further is tight. With a zero
offset this is :func:icgym.water_fill. Exact (breakpoint search per stage).
icgym.network_devices ¶
Devices dispatched over the network's real day: generators, batteries, and curtailment.
:class:DeviceRegion is the exact batch region of served loads when the
applicants also operate devices at their buses, every hour of every day:
- a per-period load scale
m[t, i]multiplies applicanti's served load in periodt:1 - phi_iin the peak periods for a curtailable fractionphi_i, or0for non-firm load that is only served off peak; - on-site generators of capacity
G_irun each hour within a daily energy budget ofrun_hours * G_iMWh, never export, and (split= 'proportional', the gross rule) run in proportion to their capacities, so the capacity they free is shared; - batteries of power
P_iandstorage_hoursof energy cycle within each day (charged when the network has room, discharged when it is tight).
Applicant i's net load in period t is m[t, i] x_i - g[t, i] -
d[t, i] + c[t, i] >= 0, and the net loads must fit that period's DCOPF after
the existing generators are redispatched. Devices couple the hours of a day, so
days, not periods, enter the LPs lazily, and branch limits enter lazily within
each period. The region plugs into every rule and game, like
:class:icgym.DCOPFRegion. Unlike the constant-theta peak model of
:mod:icgym.devices, the capacity a generator frees per MW follows the real
daily load shape.
DeviceRegion ¶
DeviceRegion(net: DCNetwork, buses, load_scale=None, generators=None, run_hours: float | None = None, split: str = 'proportional', storage_power=None, storage_hours: float = 4.0, day_length: int = 24, applicant_names=None, initial_days: int = 1)
Bases: DCOPFRegion
Batch region of new loads at buses with on-site devices dispatched hour by hour.
load_scale is a (periods, n) array (default all ones);
generators the capacities G_i (MW); run_hours the daily energy
budget in hours (None: no budget); storage_power the battery powers
P_i (MW) with storage_hours of energy. Days are day_length
consecutive periods.
contains ¶
contains(s, tol: float = 1e-06) -> bool
Whether served loads s can be hosted every day, with the devices dispatched.
dispatch ¶
dispatch(s, period_weights=None) -> dict
Device dispatch serving loads s with the least weighted generator output.
Returns per-period arrays generation, charge, discharge
((periods, n)) and each applicant's weighted generator energy
fuel_energy (sum_t w_t g[t, i], MWh weighted; w defaults to 1).
NetworkGenerationGame ¶
NetworkGenerationGame(net: DCNetwork, buses, value: float, kappa: float, gamma: float = 0.5, run_hours: float | None = 2.0, capital: float = 0.0, fuel_cost: float = 0.0, period_weights=None, rule: str = 'gross', beta: float = 0.0, day_length: int = 24)
Bases: TwoPartGame
Requests and on-site generators dispatched over the network's real days; X[i] = (r_i, G_i).
Generators (G_i <= gamma r_i) run within run_hours per day. Rules:
'gross': one common level on served load; generators run in proportion to their capacities, so the capacity they free is shared;'credit': the extra total load all generators unlock together is split among their owners in proportion to capacity, and the uniform rule serves the requests net of these credits.
Payoff: V s_i - kappa r_i - capital G_i - fuel_cost * fuel_i, where
fuel_i is the period-weighted energy of i's generator in the
least-fuel dispatch that serves s.
credits ¶
credits(G) -> np.ndarray
Each owner's credit: the jointly unlocked total load split by capacity.
payoffs ¶
payoffs(strategies) -> np.ndarray
V s_i - kappa r_i - capital G_i - fuel_cost * fuel_i for each applicant.
unlocking_ratio ¶
unlocking_ratio(i: int = 0, size: float = 100.0) -> float
MW of extra hosting capacity per MW of generator, for applicant i alone (theta).
predicted_equilibrium ¶
predicted_equilibrium() -> dict
No closed form on a real network (the unlocking ratio varies with load); use grids.
NetworkNonFirmGame ¶
NetworkNonFirmGame(net: DCNetwork, buses, peak, value: float, peak_value: float, kappa: float, rule: str = 'two_tier', gamma: float = 0.05, day_length: int = 24)
Bases: TwoPartGame
Firm and non-firm service on the network, with peak periods taken from the load shape.
peak lists the peak periods (see :func:peak_periods); value is
V and peak_value is V^p, the value of the load in the peak
periods. Rules:
'two_tier':X[i] = (firm request, non-firm request); firm requests are water-filled over all periods, non-firm requests over the off-peak periods with the firm loads fixed;'gross':X[i] = (request, curtailable fraction phi_i <= gamma); one common level, net loads(1 - phi_i) s_iin the peak periods.
nonfirm_region ¶
nonfirm_region(firm) -> DeviceRegion
Region of non-firm loads (served off peak only) with the firm loads fixed.
gross_region ¶
gross_region(phi) -> DeviceRegion
Served loads with curtailable fractions phi in the peak periods.
allocate ¶
allocate(strategies)
Served loads: (firm, non-firm) per applicant for the two-tier rule, s for the gross rule.
payoffs ¶
payoffs(strategies) -> np.ndarray
Each applicant's payoff under the two-tier or the gross rule.
predicted_equilibrium ¶
predicted_equilibrium() -> dict
Two-tier rule: firm w^p (all periods) and non-firm w^n (off peak, firm fixed).
peak_periods ¶
peak_periods(net: DCNetwork, per_day: int, day_length: int = 24) -> list[int]
The per_day periods of highest total demand in each day.
curtailment_scale ¶
curtailment_scale(net: DCNetwork, n: int, peak, phi) -> np.ndarray
Load scale for curtailable fractions phi (per applicant) in the peak periods.
with_added_load ¶
with_added_load(net: DCNetwork, buses, mw, periods=None) -> DCNetwork
A copy of net whose demand includes mw at buses (in periods, default all).
Used to fix one tier of load (for example the firm loads) while another is allocated.
icgym.prices ¶
Energy charged at locational marginal prices (LMPs).
:func:lmp solves a period's least-cost DCOPF with the new loads and returns
the price at every bus from the LP's duals. :class:EnergyCharge is a fee
that charges each applicant its served energy at its bus's price in every
period, weighted by the period weights. Combine it with a commitment by
:class:FeeSum. The theory says the uniform rule's max-min fair point is then
an epsilon-equilibrium, with epsilon set by how far one applicant can move
its own price (paper: locational prices).
EnergyCharge
dataclass
¶
EnergyCharge(net: DCNetwork, buses: list, period_weights: ndarray, share: float = 1.0, _cache: dict = dict(), _rows: dict = dict())
Bases: Fee
Served energy charged at the LMP of the applicant's bus, sum_t w_t LMP_t s_i.
period_weights converts one MW in period t into weighted MWh (hours
times the represented days, times any annuity); share scales the charge
(the paper's chi). Prices depend on everyone's served load, so each new
profile solves one LP per period (cached).
has_energy_charge
property
¶
has_energy_charge: bool
Marks fees whose cost depends on prices (the theory then gives an epsilon-equilibrium).
FeeSum
dataclass
¶
FeeSum(fees: tuple)
Bases: Fee
Several fees paid together, for example a commitment plus energy at the LMP.
lmp ¶
lmp(net: DCNetwork, buses, served, period: int, active: set | None = None) -> np.ndarray
Prices ($/MWh) at every bus of net in period with loads served at buses.
Least-cost redispatch of the existing generators (net.gen_cost) with
branch limits added lazily; the price at bus k is the balance dual plus
the branch duals times the PTDF column of k.