Technical details¶
The other pages name methods in passing: support-function projection, lazy constraints, water-filling by LPs, exploitability, and so on. This page explains each of them. Every entry starts with a short plain-language summary, then gives the method, and ends with where it lives in the code.
Notation: n applicants, served loads s (MW, one entry per applicant),
requests r, value per MW V, commitment per MW kappa, minimum allocation
beta. A region is the set of served loads the network can host.
Batch regions from a DC network¶
Downward-closed regions and hosting capacity¶
In short. A region is downward closed if lowering any applicant's load
never makes a feasible point infeasible. The theory assumes this. An explicit
region is the polytope {s >= 0 : A s <= b}; it is downward closed exactly
when every entry of A is nonnegative. Each row is a shared limit (a branch,
spare generation), and A[c, i] is how much one MW of applicant i loads
limit c.
Method. Region rejects negative entries of A and negative b, and
rejects any applicant that loads no limit (its load would be unbounded). The
single-bus hosting capacity is the most applicant i can be served with
everyone else at zero: h_i = min over c with A[c, i] > 0 of b_c / A[c, i].
The planner's optimum is one LP, max sum(s) over the region.
Code. icgym.region.Region: hosting_capacities, max_total,
contains, restrict, and Region.downward_closed.
The period problem in PTDF form¶
In short. One period (one hour of a representative day) can host new
loads x at the batch's buses if the existing generators can be redispatched
to serve the base load plus x, with every branch flow within its limit. This
is a lossless DC optimal power flow (DCOPF) written with power transfer
distribution factors (PTDFs).
Method. DCNetwork.from_csv_dir builds the PTDF matrix from the in-service
branches: with incidence matrix C and branch susceptances 1/x_k, the bus
susceptance matrix is B = C' diag(1/x) C. Removing the reference bus (type 3)
gives PTDF = diag(1/x) C_r inv(B_rr), with a zero column for the reference
bus. PTDF[k, j] is the flow on branch k per MW injected at bus j and
withdrawn at the reference bus. In period t, with generator outputs p and
new loads x >= 0:
- power balance:
sum(p) - sum(x) = total demand in t; - branch limits:
|PTDF_gen p - PTDF_site x - PTDF d_t| <= limit, whered_tis the base demand at every bus; - generator bounds:
p_min <= p <= p_max.
Losses, reactive power, and voltages are ignored (see AC power flow for the full model). Active DC lines are not supported and raise an error.
Code. icgym.network.DCNetwork (from_csv_dir, period_problem) and
icgym.network.PeriodProblem.
Support LPs¶
In short. The support function of a region in direction d is the
largest value of d'x over the region. It is one LP, and its solution is a
point on the region's boundary.
Method. PeriodProblem.support(d) solves max d'x over x >= 0, the
redispatch p, and the period's constraints, and returns the value and the
maximizing x. Some coordinates can be held at zero (zero=). LPs are solved
by HiGHS through scipy.optimize.linprog. On numerical trouble the objective
is rescaled and the LP retried with the dual simplex, then the interior-point
method. An infeasible LP means the base case itself cannot be served; an
unbounded one means some bus loads no limit in this period.
Code. icgym.network.PeriodProblem.support, icgym.network._solve_lp.
Support-function projection¶
In short. The exporter needs the facets (the inequalities g'x <= h) of
each period's region in the space of the new loads only. The region is the
projection of a higher-dimensional polytope (loads plus every generator's
output), and projecting by eliminating the generator variables is expensive.
Instead, the exporter grows an inner approximation from boundary points found
by support LPs, until every facet of that approximation is confirmed to be a
facet of the true region.
Method. For one period, period_facets:
- Computes each bus's hosting capacity with a support LP in the coordinate
direction. Buses with zero capacity are fixed by a row
x_i <= 0and dropped. With one bus left, the region is the interval[0, h]. - Seeds a point set with feasible points only: the origin, each single-bus capacity point (other loads at zero), the maximizer of each coordinate direction, and the maximizer of the all-ones direction.
- Takes the convex hull of the points (Qhull, through
scipy.spatial.ConvexHull). Because every point is feasible and the region is convex, the hull lies inside the region. - For each hull facet with unit normal
gand offseth(skipping the facetsx_i >= 0), solves the support LP in directiong. If the support exceedshby more thantoltimes the largest hosting capacity, the maximizer is a new boundary point outside the hull, and it is added. If not, the facet is confirmed: no feasible point lies beyond it, so it is a facet of the true region. - Repeats from step 3 until a pass adds no point (at most
max_iter = 200passes).
Each pass costs one LP per unconfirmed hull facet, and confirmed facets are
not tested again. The number of facets grows fast with the number of buses,
which is why explicit regions are practical up to about three applicants on a
large network. With a relative gap, the loop stops once no support exceeds
a facet by more than gap times the largest capacity; the result is then the
hull itself, an inner approximation of the region. Periods are independent, so
export_region(..., workers=k) runs them in a process pool.
Code. icgym.network.period_facets, icgym.network.export_region.
Intersecting periods and pruning facets¶
In short. A batch must be hostable in every period, so the batch region is the intersection of the period regions. Stacking every period's facets gives many duplicate and redundant rows, which are removed.
Method. assemble_region stacks the facets of all periods. Rows are
normalized by their right-hand side and rounded to 9 digits to drop
duplicates. Then each row is tested for redundancy with one LP: maximize the
row over x >= 0 subject to all other kept rows. If the maximum does not
exceed the row's bound (within a small tolerance), the row is implied by the
others and is dropped. This costs one LP per row.
Code. icgym.network.assemble_region, _prune_signed, _prune.
Largest downward-closed subset and counterflow¶
In short. On a real network, one new load can relieve a branch that another loads, because their flows on that branch go in opposite directions. This relief is counterflow. It appears as a negative coefficient in a facet, and it makes the region not downward closed: reducing one load can remove relief the other relied on. The exporter drops the relief by keeping only the positive part of each facet. That treats counterflow as non-firm: no applicant is promised capacity that exists only while another applicant is connected.
Method. With the exact signed facets G x <= h, the returned region is
{x >= 0 : max(G, 0) x <= h}, pruned again. Clipping can only tighten a
row (each negative term was lowering the left side), so the result is a
subset of the exact region, and it is downward closed. A row involving one bus
alone is unchanged, so every single-bus hosting capacity is kept. The paper
shows this is the largest downward-closed subset (Lemma 4.1).
ExportedRegion keeps the exact signed facets (signed_A, signed_b) so
counterflow can be inspected; has_counterflow reports whether any exact
coefficient is negative.
Code. icgym.network.ExportedRegion, icgym.region.Region.downward_closed.
Implicit regions and lazy constraints¶
Lazy branch limits¶
In short. A 2,000-bus network has thousands of branches, but only a few limit any given load pattern. Lazy constraint generation solves the LP with the branches known to matter, checks all the others at the solution, and adds only those that are violated.
Method. Each PeriodProblem keeps an active set of branches (empty at
first). Each solve uses only the active rows; afterwards every branch flow is
computed from the solution, and any branch over its limit by more than
1e-7 * max(1, largest limit) MW joins the active set. The LP is re-solved
until no branch is violated. The result is the exact optimum: the reduced LP
is a relaxation of the full one, and its optimum satisfies every constraint of
the full one. The active set persists on the period, so later queries start
with the branches found so far.
Code. PeriodProblem.support (icgym.network), and the same loop in
DCOPFRegion._optimize, DCOPFRegion._feasible_lazy, and icgym.prices.lmp.
Lazy periods¶
In short. A region over 120 periods is the intersection of 120 period
regions, but only a few periods (usually the peak hours) bind. DCOPFRegion
solves each query with the periods found binding so far and adds a period
only when the answer violates it.
Method. DCOPFRegion._optimize solves one joint LP over y = (x, t) (the
new loads and one auxiliary scalar used by the queries below) and a separate
generator redispatch for each included period. It starts with the three
periods of highest total demand (initial_periods=3). After each solve:
- In the included periods, violated branches are added (lazy branch limits), and the LP is re-solved.
- Every period left out is checked with a feasibility LP at the solution
x(again with lazy branch rows). Periods that cannot hostxare added, and the LP is re-solved. - When no branch and no period was added, the solution is optimal for the full multi-period problem.
The binding periods and each period's active branches persist across queries,
so later queries are cheaper. Each LP is retried with the dual simplex and
interior point if HiGHS reports numerical trouble. lp_count counts the LPs
solved.
Code. icgym.dcopf_region.DCOPFRegion (_optimize, _joint_lp,
_feasible_lazy).
Queries on an implicit region¶
In short. DCOPFRegion never lists facets. Each question a rule asks is
an LP over the served loads and every period's redispatch.
Method. All queries call _optimize with a different objective and extra
constraints on y = (x, t):
| Query | LP |
|---|---|
hosting_capacities() |
max x_i with the other loads fixed at zero; one LP per applicant, cached |
max_total() |
max sum(x) (the planner's optimum) |
max_common_fraction(r) |
max t <= 1 with x = t r (the proportional rule) |
utilitarian(r) |
two stages (see the utilitarian rule) |
water_fill(r) |
a level LP and blocking tests per stage (see water-filling by LPs) |
contains(s) |
a feasibility LP per period at s * (1 - 1e-6) |
A uniform allocation of a few applicants on ACTIVSg2000 takes seconds, against
microseconds on an exported region. The rule cut_order='largest_loading'
needs explicit limit loadings and is not available on an implicit region.
Code. icgym.dcopf_region.DCOPFRegion.
Allocation rules as optimization¶
Water-filling and the max-min fair point¶
In short. The uniform rule raises every applicant's served load at the
same rate, like water rising in connected tanks. An applicant stops when it
reaches its request or when a limit it loads becomes full. With unbounded
requests the result is the max-min fair point w: the allocation whose
smallest share is as large as possible, then the second smallest, and so on.
Method. A common level t rises, and each rising applicant is served
lambda_i t (weights lambda, all one for the uniform rule). On an explicit
region each stage is computed in closed form:
- For each limit, the level at which it fills is
(b_c - load of stopped applicants) / (sum of A[c, i] lambda_i over rising i). - The stage level is the smallest of these levels and of the request levels
r_i / lambda_i. - Applicants that reached their request stop, and so do all rising applicants loading a limit that just filled.
At least one applicant stops per stage, so there are at most n stages. Each
stage is recorded as Stage(level, applicants, limits); these are the levels
tau_k and blocked sets B_k of the theory, and their number K sets the
2K bound on best-response rounds. Comparisons use a relative 1e-12 plus
an absolute 1e-9 (scaled by the largest b for limits).
Code. icgym.waterfill.water_fill, max_min_fair_point;
icgym.oracles.stages.
Water-filling by LPs¶
In short. On an implicit region there are no rows to compute fill levels from. Each stage instead finds the highest common level by an LP, then asks, applicant by applicant, whether it could still grow alone.
Method. At each stage of DCOPFRegion.water_fill:
- Level LP. Maximize
tsubject tox_i = lambda_i tfor the rising applicants, stopped applicants fixed at their served loads, andt <= min r_i / lambda_i. The rising applicants are set tolambda_i t. - Request test. An applicant within
1e-7 * scaleof its request stops (scaleis the largest hosting capacity, at least 1). - Blocking test. For every other rising applicant
i, maximizex_iwith every other load fixed. If the maximum exceeds the currents_iby at most1e-6 * scaleMW,iis blocked and stops.
On a convex region at least one applicant is blocked at the level LP's
optimum, so each stage stops someone. A stage costs one level LP plus one LP
per rising applicant, and there are at most n stages, so a full allocation
costs O(n^2) LPs, each with lazy periods and branches.
Code. icgym.dcopf_region.DCOPFRegion.water_fill.
Proportional rule: the common fraction¶
In short. The proportional rule serves every request scaled by one common
fraction alpha <= 1, the largest that fits.
Method. On an explicit region,
alpha = min(1, min over c of b_c / (A r)_c). On an implicit region it is one
LP: maximize t <= 1 with x = t r feasible.
Code. icgym.rules.ProportionalRule, DCOPFRegion.max_common_fraction.
Utilitarian rule and its tie-break¶
In short. The utilitarian rule serves the largest total load with no one
served above its request. The maximizer is usually not unique, so a second LP
picks, among the maximizers, the one whose smallest service fraction s_i/r_i
is largest.
Method. Stage 1: max sum(s) subject to the region and 0 <= s <= r,
giving the total T. Stage 2: maximize z <= 1 subject to the region,
0 <= s <= r, s_i >= z r_i for every positive request, and
sum(s) >= T minus a small relative slack (1e-9 on explicit regions, 1e-7
on implicit ones). If stage 2 fails, the stage-1 solution is returned.
Code. icgym.rules.UtilitarianRule, DCOPFRegion.utilitarian.
Minimum allocation and cut order¶
In short. With a minimum allocation beta, an applicant offered less
than beta of its request is dropped from the batch, and the rule is run
again for the rest. Only one applicant is dropped at a time; the cut order
says which.
Method. AllocationRule.allocate loops:
- Allocate among the active applicants.
- Mark as short every active applicant with
s_i < beta r_i(with a relative slack of1e-9). If none is short, stop. - Drop one short applicant and go back to step 1.
The cut orders:
largest_request(default for the uniform and utilitarian rules): drop the short applicant with the largest request.largest_loading(default for the proportional rule): find the most loaded limit, measured by(A r)_c / b_cover the short and served applicants, and drop the short applicant with the largestA[c, i] r_ion it. Dropping by MW instead can break the proportional rule's equilibrium.
Ties go to the lowest index. There are at most n cuts, each a full
re-allocation.
Code. icgym.rules.AllocationRule (allocate, _next_cut).
Batched allocation¶
In short. Learning needs many allocations. allocate_batch runs the
uniform and proportional rules on E request profiles at once with numpy.
Method. The same stages as above, computed on (E, n) arrays, with the
minimum-allocation loop applied row by row in vector form. Other rules and
implicit regions fall back to a Python loop.
Code. icgym.vector.allocate_batch, water_fill_batch.
Equilibria and how they are found¶
Exploitability¶
In short. Exploitability measures how far a profile is from an equilibrium: each applicant's largest payoff gain from changing its own strategy while the others keep theirs. It is zero at a pure equilibrium.
Method. For each applicant, max(0, best-response payoff - current
payoff), with the best response from the search below. The benchmarks divide
it by V_i h_i, the value of the applicant's hosting capacity. It is only as
good as the search: a positive number is a real deviation found, while a zero
means the search found none.
Code. BatchGame.exploitability, TwoPartGame.exploitability,
LocationGame.exploitability.
Best-response search¶
In short. A best response is the request that maximizes one applicant's payoff with the others fixed. Under the uniform rule without a minimum allocation it has a closed form. Elsewhere the payoff can jump (an applicant is cut, or overtakes a rival in the cut order), so it is found by a grid search with local refinement.
Method. BatchGame.best_response:
- Closed form (uniform rule,
beta = 0,0 < kappa < V_i, no forfeit): water-fill with applicanti's request set to infinity, and request exactly what that serves it. - Search otherwise: evaluate the payoff on
gridpoints (default 400) of[0, upper], plus the current request, the hosting capacity, and the "kinks": the requests where the requested load on a limit reachesb_c / beta, where applicantialone fills a limit, and where its request or loading ties a rival's, each also tried1e-9either side. The four best candidates are refined by bounded scalar minimization within one grid step. The upper end is the largest ofh_i,h_i / beta, the request that overtakes every rival in the cut order, and the largest current request, capped at20 h_i, plus 5%.
Under a minimum allocation the supremum may not be attained (a best response
can be a vanishing undercut of a rival); the search returns the best point
found. The two-part games (GenerationGame, NonFirmGame and their network
versions) search a two-dimensional grid of request and second part, then
refine the two coordinates in turn.
Code. BatchGame.best_response, _exact_best_response, _kinks,
_search_upper; TwoPartGame.best_response (icgym.devices).
Best-response dynamics¶
In short. Applicants take turns best-responding. If the profile stops changing, it is a pure equilibrium.
Method. In each round every applicant best-responds once, in index order
(order='cyclic') or a random permutation. A round settles only if no request
moved by more than tol and no applicant could gain more than gain_tol
(default 1e-9 * max |V_i h_i|). The second test matters under a minimum
allocation, where a profile can stand still while a large gain remains.
Returns the profile, the history, and the number of rounds with a change, or
None if it did not settle within max_rounds.
Code. BatchGame.best_response_dynamics,
TwoPartGame.best_response_dynamics, LocationGame.best_response_dynamics.
Equilibria on strategy grids¶
In short. When there is no closed form and the search is expensive (as on
a DeviceRegion), grid_equilibria restricts every applicant to a finite
list of strategies and finds every pure equilibrium of that finite game
exactly.
Method. It enumerates every profile in the product of the strategy sets.
A profile is an equilibrium if no applicant gains more than tol by switching
to another strategy in its own set. Payoffs are cached by index profile, so
the cost is at most prod |S_i| payoff evaluations, each one allocation. The
result is exact for the restricted game only: the grid must contain the
levels where an equilibrium can sit, or it is missed, and a grid profile can
be an equilibrium only because better deviations lie off the grid.
Code. icgym.game.grid_equilibria.
Equilibrium oracles¶
In short. The oracles return what the paper proves for a game, so learned
or searched behavior can be scored against it. They check the game's rule,
fee, and region and either return the answer or {"known": False}.
Method. predicted_equilibrium(game) for BatchGame:
- uniform rule (optionally weighted): compute
w, the (weighted) max-min fair point;- with a
FlatFee: the band fromwtow / beta(kind='band'); - with
0 < kappa < Vand no forfeit:w(kind='unique'), orkind='epsilon'when the fee includes an energy charge;
- with a
- proportional rule on a single limit, equal values,
kappa > 0:r_i = rho b / (n a_i)withrho = min(max((1 - 1/n) V / kappa, 1), 1/beta); - otherwise unknown.
The extension games have their own predicted_equilibrium methods
(GenerationGame, NonFirmGame, NetworkNonFirmGame with the two-tier
rule). NetworkGenerationGame returns unknown, because on a real network the
capacity a generator frees varies with load; use grids there.
Code. icgym.oracles.predicted_equilibrium, proportional_inflation.
Price of anarchy¶
In short. The price of anarchy compares the planner's best total with the total served at equilibrium.
Method. price_of_anarchy(region, s) = max_total / sum(s). The theory's
bound for the uniform rule is (1 + nR)^2 / (4nR), with R the ratio of the
largest to the smallest single-bus hosting capacity (poa_bound).
Code. icgym.oracles.price_of_anarchy, poa_bound.
Improving moves in the location game¶
In short. In the location game each applicant picks a placement, and its
payoff is its share of the max-min fair point of the resulting region. The
theory says every improving move raises the sorted vector of shares, so
best-response dynamics cannot cycle. improving_moves checks this on every
profile.
Method. Shares are computed once per multiset of placements (applicants
at the same placement are interchangeable) and cached. A move counts as
improving only if it raises the mover's share by more than tol (default
1e-4, in MW for network regions), which keeps solver noise out of the
counts. For each improving move, the sorted shares before and after are
compared at the first entry that differs by more than tol; a decrease
there, or no such entry, is a violation. pure_equilibria enumerates every
profile. On a network, LocationGame.from_network builds one DCOPFRegion
per new multiset.
Code. icgym.location.LocationGame (shares, potential,
improving_moves, pure_equilibria).
Learning baselines¶
In short. Three reference learners for the benchmark tasks.
Method.
best_response: best-response dynamics from a random start.hedge: multiplicative weights on a grid of actions (41 request levels; 17 times 5 for two-part actions; the menu for placements). Each round every applicant's weights move byetatimes the average payoff of each grid action against sampled rival actions (full information); the most likely action is returned.independent_pg: each applicant has a Gaussian policy in logit space (actionssigmoid(z)), updated from its own rewards only, with normalized advantages and a linearly decaying step; a softmax over the menu for placements.
Code. icgym.benchmarks (best_response, hedge, independent_pg).
Prices and devices¶
LMPs from LP duals¶
In short. The locational marginal price (LMP) at a bus is the cost of serving one more MW there. It equals the energy price plus the cost of the congestion that MW adds, and both come from the dual variables of the least-cost dispatch LP.
Method. lmp solves the least-cost redispatch of one period with the new
loads fixed, minimizing gen_cost' p subject to power balance, generator
bounds, and branch limits added lazily. The price at bus k is the dual of
the balance constraint plus, for each active branch, the difference of the
duals of its upper and lower flow limits times PTDF[branch, k]. Generator
costs come from marginal_cost_c1_per_mwh in generator_limits.csv.
Code. icgym.prices.lmp.
Energy charge and the epsilon-equilibrium¶
In short. EnergyCharge bills each applicant its served energy at its
own bus's LMP. Its own load moves that price, so the uniform rule's w is no
longer an exact equilibrium. It is an epsilon-equilibrium: no applicant gains
more than a small epsilon by deviating, with epsilon set by how far one
applicant can move its own price.
Method. cost_i = share * sum over t of w_t LMP_t(s) s_i, with period
weights w_t (hours times represented days, and any annuity). Each new
served profile costs one LP per period; prices are cached by the rounded
profile, and each period's active branches are reused. FeeSum adds it to a
commitment. predicted_equilibrium then returns kind='epsilon'. Searching
best responses is expensive here, which is why best_response accepts an
interval.
Code. icgym.prices.EnergyCharge, FeeSum.
Devices on the network¶
In short. DeviceRegion is the exact region when applicants also run
on-site generators, batteries, or curtailable load, dispatched hour by hour
over the network's real days. A device frees capacity only in the hours it
runs, so its value follows the daily load shape.
Method. For each period t and applicant i the LP has the
generator output g, battery charge c and discharge d, and state of
charge. The net load m[t, i] x_i - g + c - d must be nonnegative (no export)
and must fit the period's DCOPF after redispatch. The constraints:
- load scale
m[t, i]:1 - phi_iin the peak periods for a curtailable fractionphi_i, or0in the peak periods for non-firm load; - run-hour budget:
sum over the day of g[t, i] <= run_hours * G_i, with0 <= g <= G_i; - proportional split (
split='proportional', the gross rule): in every period all generators run at the same fraction of their capacities, so the room they free is shared;split='free'drops this; - storage cycles:
0 <= c, d <= P_i, state of charge between 0 andstorage_hours * P_i, andsoc[t+1] = soc[t] + c[t] - d[t]around each day, with the last hour wrapping to the first, so every day ends where it began (no round-trip losses are modeled).
Devices couple the hours of a day, so whole days enter lazily (starting with
the peak day), and branches enter lazily within each period, as in
DCOPFRegion. dispatch(s) finds, day by day, the dispatch that serves s
with the least weighted generator output, which gives each owner's fuel
energy. peak_periods and curtailment_scale build the load scale.
Code. icgym.network_devices.DeviceRegion, peak_periods,
curtailment_scale.
Gross rule and crediting¶
In short. Who keeps the capacity a device frees is the operator's choice. Under the gross rule the freed room joins the common pool and is shared. Under crediting it goes to the device's owner.
Method. In NetworkGenerationGame (strategies (r_i, G_i) with
G_i <= gamma r_i):
'gross': the uniform rule on theDeviceRegionwith these generators and the proportional split;'credit': the extra total load all generators unlock together,max_total(G) - max_total(0), is split among the owners in proportion toG_i; the uniform rule then serves the requests net of these credits on the region without generators, ands_i = min(r_i, credit_i + share_i).
unlocking_ratio measures the MW of hosting capacity one MW of generator
frees for one applicant alone (theta). On the explicit peak-period model
(GenerationGame), theta = min(1, run_hours / (nu dt)) for nu peak periods
of dt hours, and the gross rule is water-filling on
{s >= 0 : A (s - theta G)^+ <= b}, solved exactly by a breakpoint search in
water_fill_offset.
Code. icgym.network_devices.NetworkGenerationGame;
icgym.devices.GenerationGame, Device, peak_theta, water_fill_offset.
Non-firm service on the network¶
In short. Firm load is served in every hour; non-firm load only off peak. The two-tier rule allocates the two tiers one after the other.
Method. In NetworkNonFirmGame with rule='two_tier', firm requests are
water-filled on the region over all periods. The firm loads are then added to
the base demand, backed off by a relative 1e-9 so the binding period stays
feasible, and non-firm requests are water-filled on the off-peak region that
remains (load scale zero in the peak periods). With rule='gross', each
applicant picks a request and a curtailable fraction phi_i <= gamma, and one
common level is water-filled on the region with net loads (1 - phi_i) s_i in
the peak periods.
Code. icgym.network_devices.NetworkNonFirmGame, with_added_load;
icgym.devices.NonFirmGame for explicit regions.
Sequential batches and the operator¶
Residual region¶
In short. After a batch, served MW connect for good and use up capacity. The next batch sees only what is left.
Method. SequentialBatchGame works on a region over buses (column j is
one MW at bus j). The residual capacity of limit c is
b_c - (A connected)_c - growth_c * k after k batches, floored at zero. The
batch region takes the bus column of each queued applicant and drops limits
none of them loads. Served loads are also capped at each applicant's remaining
need.
Code. icgym.sequential.SequentialBatchGame (residual_b,
batch_region).
Myopic batch equilibrium¶
In short. The ground truth for each batch is the equilibrium of that batch alone: water-filling the residual region, with each applicant's request capped at its remaining need.
Method. myopic_equilibrium returns water_fill(batch_region, need). It
ignores the effect of today's request on later batches, which is why it is
called myopic.
Code. SequentialBatchGame.myopic_equilibrium.
Equilibrium response¶
In short. When the operator searches over designs, the applicants must
answer its choice of rule, beta, and kappa strategically.
equilibrium_response computes their answer.
Method.
- Applicants whose value is at most
kapparequest nothing. - Each remaining applicant's need is added as an extra limit
s_i <= need_i. wis water-filling on this capped region.- Unweighted uniform rule: the answer is
w; with a flat fee (orkappa = 0) andflat_fee_end='high', the band's high endw / beta. - Any other rule: best-response dynamics from
w, with the search (grid=80, at most 15 rounds). The last profile is returned even if the dynamics did not settle.
The operator's reward (Objective) is efficiency minus a weight times the
share of requested MW not served, minus a weight times one minus Jain's
fairness index of the served shares of hosting capacity.
Code. icgym.rule_design.equilibrium_response, Objective,
batch_metrics, OperatorEnv, SequentialOperatorEnv.
AC power flow¶
The AC period problem¶
In short. ACOPFRegion replaces the DC model with the full AC equations,
which include losses, reactive power, and voltage limits. The region is then
not a polytope and may not be downward closed.
Method. In each period the variables are bus voltage angles and
magnitudes and generator active and reactive outputs, in per unit. The
constraints are active and reactive power balance at every bus (with branch
two-port admittances, taps, phase shifts, and shunts), apparent-power limits
P^2 + Q^2 <= rate^2 at both ends of every rated branch, voltage limits,
generator limits, and a zero reference angle. New loads draw reactive power
tan(phi) x_i with tan(phi) = sqrt(1 - pf^2) / pf for a lagging power
factor pf. The programs are built symbolically in CasADi and solved by Ipopt
(tolerance 1e-9, at most 3000 iterations); one solver is compiled per
problem shape and reused.
Code. icgym.ac_region.ACNetwork, _Period, ACOPFRegion._joint_solver.
Local optima and restarts¶
In short. Ipopt finds local optima of nonconvex programs, so a maximum it returns can fall short of the true one. Starting points matter, and the region can try several.
Method. Each solve tries, in order, the previous solution of each period
(a warm start) and a flat start (angles zero, voltages one, outputs at the
middle of their ranges). With multistart=k, k random starts are added
(small angles, voltages near one, outputs within limits) and the best result
is kept; otherwise the first successful solve is used. Every query has a
feasible point (no new load), so if all of these fail the failure is
numerical, and up to eight more random starts are tried. Periods enter lazily
as in the DC region: up to three unhosted periods are added at a time,
highest total demand first.
Code. ACOPFRegion._solve, _random_start, _optimize.
Feasibility checks¶
In short. Saying a point is hosted is easy to certify: Ipopt returns an operating point that meets every limit. Saying it is not hosted is not, since Ipopt may just have failed to find such a point.
Method. To test whether period t hosts x, the region maximizes
a <= 1 with loads a x hosted. A solve that reaches a >= 1 - 1e-7 proves
the point is hosted. "Not hosted" is returned only if both the warm and the
flat start were tried, at least one solved, and neither reached 1. Random
restarts are tried only if neither of those two solves succeeded.
contains(s) runs this test in every period at s * (1 - 1e-6), starting
with the binding periods and then in order of peak load, so that a point that
is not hosted usually fails within a few solves. operating_point(s, t) returns the voltages, angles,
outputs, and branch MVA flows that host s.
Code. ACOPFRegion._feasible_lazy, contains, operating_point.
Certified water-filling¶
In short. Water-filling on the AC region uses the same stages as on the DC region, but each step is checked with feasibility tests, which are more reliable than the maxima.
Method. At each stage:
- The level comes from the level program, as in the DC case. If Ipopt fails
on it even after random restarts, the level is found instead by bisection
on hosted points along the ray (to a relative
1e-4), and the stage is counted inbisected_stages. - The level is pushed: while the point a relative step
certify(default1e-3) further along the ray is hosted, the level moves there and the level program is re-solved from it (at most 50 pushes). - A rising applicant counts as blocked only if growing it alone by the
relative step
certifyis not hosted.
If no applicant is blocked although the common level cannot rise (possible
when one load relieves another), the lowest-indexed applicant with room is
frozen, and the stage is recorded in unblocked_stages.
Code. ACOPFRegion.water_fill, _bisect_level, _unblocked_stage.
Downward-closure check¶
In short. The theory's guarantees need a downward-closed region. On the
AC region that can fail: removing load can raise voltages above their limits.
downward_closure_check tests the assumption on sample points of the
boundary.
Method. Each sample is a boundary point: water-filling with random weights
(uniform on [0.2, 1]) and requests of twice the hosting capacities. For each
applicant and each factor in cuts (default 0 and 0.5), its load is multiplied
by that factor and the point is tested with contains. The result lists the
number of tests and the violations. Passing is evidence, not a proof; a
violation is a real counterexample, up to the reliability of the
feasibility test.
Code. icgym.ac_region.downward_closure_check.