Skip to content

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).

n property

n: int

Number of applicants.

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.

shares

shares(profile) -> np.ndarray

Served loads w(sigma) at the request-stage equilibrium.

payoffs

payoffs(profile) -> np.ndarray

Each applicant's payoff margin_i * w_i(profile).

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.

profiles

profiles()

Every placement profile (the product of the menus).

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 requests r - theta G, plus theta G_i credited 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).

n property

n: int

Number of applicants.

allocate

allocate(strategies) -> np.ndarray

Served loads under the game's rule (gross or credit); devices are clipped to the cap.

payoffs

payoffs(strategies) -> np.ndarray

V s_i - kappa r_i - cost G_i for each applicant.

shares_given_devices

shares_given_devices(G) -> np.ndarray

w(G): the unique equilibrium of the requests with devices fixed (cap set aside).

builder_margin

builder_margin() -> float

mu+ = theta (V - kappa_C) - cost.

scrapper_margins

scrapper_margins() -> np.ndarray

mu-_i = theta (V - kappa_C) a_i / sum_j a_j - cost on a single limit.

no_carry

no_carry() -> bool

Whether theta gamma < 1 and the no-carry condition hold.

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).

n property

n: int

Number of applicants.

offpeak_value property

offpeak_value: float

Value of the load outside the peak periods, V - V^p.

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 applicant i's served load in period t: 1 - phi_i in the peak periods for a curtailable fraction phi_i, or 0 for non-firm load that is only served off peak;
  • on-site generators of capacity G_i run each hour within a daily energy budget of run_hours * G_i MWh, 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_i and storage_hours of 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.

n property

n: int

Number of applicants.

credits

credits(G) -> np.ndarray

Each owner's credit: the jointly unlocked total load split by capacity.

allocate

allocate(strategies) -> np.ndarray

Served loads under the rule.

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_i in the peak periods.

n property

n: int

Number of applicants.

offpeak_value property

offpeak_value: float

Value of the load outside the peak periods, V - V^p.

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).

prices

prices(served) -> np.ndarray

Price at each applicant's bus in every period, (periods, n).

cost

cost(requests, served)

share * sum_t w_t LMP_t(served) * served_i for each applicant.

FeeSum dataclass

FeeSum(fees: tuple)

Bases: Fee

Several fees paid together, for example a commitment plus energy at the LMP.

has_energy_charge property

has_energy_charge: bool

Whether any component charges energy at prices.

cost

cost(requests, served)

The sum of the components' costs.

marginal_request_cost

marginal_request_cost()

The sum of the components' marginal request costs.

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.