Networks and data¶
icgym.network ¶
Batch regions from a DC power-flow study.
A period t can host the new loads x at a set of buses if some
redispatch of the existing generators serves the base load plus x within
branch and generator limits (lossless DCOPF in PTDF form). The batch region is
the intersection over periods of these per-period regions.
:func:export_region computes the region exactly, period by period: it grows
an inner approximation by the maximizers of support LPs until every facet of
its convex hull is confirmed by an LP (a projection by support functions). The
facets of all periods together describe the region; their positive parts
describe its largest downward-closed subset (counterflow between new loads
treated as non-firm), which is the :class:~icgym.region.Region returned.
Input: a scenario directory with bus.csv, branch_limits.csv,
generator_limits.csv, demand_bus.csv and dcline.csv in the format
of the ERCOT connection game packages.
DCNetwork
dataclass
¶
DCNetwork(buses: list[str], ptdf: ndarray, limit: ndarray, gen_bus: ndarray, gen_min: ndarray, gen_max: ndarray, demand: ndarray, branch_names: list[str], source_hash: str = '', source: str = '', root: str = '', gen_cost: ndarray | None = None)
from_csv_dir
classmethod
¶
from_csv_dir(directory: str | Path, horizon: int | None = None) -> DCNetwork
Read a DC power-flow scenario folder (bus, branch, generator, demand, and DC-line CSV files).
period_problem ¶
period_problem(t: int, buses) -> PeriodProblem
The redispatch problem of period t with new loads at buses.
PeriodProblem
dataclass
¶
PeriodProblem(flow_site: ndarray, flow_gen: ndarray, base: ndarray, limit: ndarray, total_demand: float, gen_bounds: list, n: int, active: set = set())
One period's DCOPF: |flow_gen p - flow_site x - base| <= limit,
sum p - sum x = total demand, generator bounds, x >= 0.
Branch limits enter lazily: an LP is solved with the branches found binding so far, and violated branches are added until none remain, which gives the exact optimum with small LPs on large networks.
ExportedRegion
dataclass
¶
ExportedRegion(region: Region, signed_A: ndarray, signed_b: ndarray, metadata: dict)
has_counterflow
property
¶
has_counterflow: bool
Whether any exact facet has a negative coefficient (relief between new loads).
period_facets ¶
period_facets(problem: PeriodProblem, tol: float = 1e-07, max_iter: int = 200, gap: float | None = None)
Facets (G, h) with G x <= h of one period's region.
With gap=None the facets are exact (to tol). With a relative
gap, enumeration stops once the support of the true region exceeds
every facet of the current hull by at most gap times the period's
largest hosting capacity; the result is the hull of feasible points, so it
lies inside the true region. Coordinates with zero hosting capacity are
fixed at zero by a row x_i <= 0. Returns the facets other than x >= 0.
export_region ¶
export_region(net: DCNetwork, buses, periods=None, workers: int = 1, tol: float = 1e-07, names=None, gap: float | None = None) -> ExportedRegion
Batch region of new loads at buses over periods (default all).
gap trades exactness for speed in many dimensions (see :func:period_facets).
assemble_region ¶
assemble_region(net: DCNetwork, buses, periods, parts, tol: float = 1e-07, names=None) -> ExportedRegion
Combine per-period facets parts (from :func:period_facets) into a region.
icgym.dcopf_region ¶
An implicit batch region: the DCOPF itself, queried by linear programs.
:class:DCOPFRegion answers the questions the rules ask (water-filling levels,
hosting capacities, the planner's optimum, the proportional rule's common
fraction, the utilitarian allocation) by solving LPs over the served loads and
every period's generator redispatch, instead of listing facets. It is exact for
any number of applicants, at the cost of seconds per allocation rather than
microseconds; use :func:icgym.network.export_region for small batches that
need speed.
Two things keep the LPs small on large networks, without changing their optimum: periods enter lazily (the LP starts with the periods found binding so far, and any period the solution violates is added), and so do branch limits within each period.
The region is the exact DCOPF region H: relief that one new load gives
another (counterflow) is counted. The theory assumes its largest
downward-closed subset; where counterflow binds, the two can differ (compare
with an exported region).
DCOPFRegion ¶
DCOPFRegion(net: DCNetwork, buses, applicant_names=None, initial_periods: int = 3)
Batch region of new loads at buses, defined implicitly by the DCOPF.
hosting_capacities ¶
hosting_capacities() -> np.ndarray
Single-bus hosting capacity of each applicant, others served zero.
max_total ¶
max_total() -> tuple[float, np.ndarray]
Planner's optimum: the largest total served load and a maximizer.
contains ¶
contains(s, tol: float = 1e-06) -> bool
Whether served loads s are feasible in every period, within tol.
max_common_fraction ¶
max_common_fraction(r) -> float
Largest alpha <= 1 with alpha r feasible (proportional rule).
utilitarian ¶
utilitarian(r) -> np.ndarray
Largest total with s <= r; ties broken by the largest smallest fraction.
water_fill ¶
water_fill(requests, weights=None, active=None, return_stages: bool = False)
Water-filling U(r) by LPs: raise the level, then find who is blocked.
icgym.scenarios ¶
Scenarios: regions to play on.
Synthetic regions for research and testing, small worked examples, and JSON input/output so that regions computed from a network study (for example the DCOPF hosting-capacity region of a set of buses) can be loaded.
random_region ¶
random_region(n: int, m: int, seed: int | None = None, density: float = 0.7, skew: float = 1.0) -> Region
Random downward-closed region with n applicants and m limits.
density is the chance that an applicant loads a limit; skew > 1
spreads the loadings further apart.
flat_fee_example ¶
flat_fee_example() -> Region
Two applicants and one limit s_1 + 1.5 s_2 <= 3 (paper, Fig. 5).
poa_worst_case ¶
poa_worst_case(n: int, R: float, k: int | None = None, eps: float = 0.001) -> Region
Regions that approach the price-of-anarchy bound (1+nR)^2/(4nR).
k applicants with hosting capacity R barely load a shared limit
that the other n - k, with capacity 1, load fully.
save_region ¶
save_region(region: Region, path: str | Path, signed=None, **metadata) -> None
Write a region as JSON; signed=(A, b) stores the exact facets too.
load_region ¶
load_region(path: str | Path) -> Region
Read a region written by :func:save_region or icgym-export.
load_region_record ¶
load_region_record(path: str | Path) -> dict
The full record: region, exact signed facets (if stored), and metadata.
bundled ¶
bundled(system: str = 'activsg2000') -> list[str]
Names of the regions shipped with the package for system ('activsg2000').
Names are group/buses_... for regions in a group folder (pairs,
poa, location) and buses_... otherwise.
bundled_region ¶
bundled_region(system: str, buses) -> Region
Bundled region of system for the bus multiset buses, columns in the given order.
Applicants at the same bus are interchangeable, so any bundled file with the same multiset of buses serves.
ieee14 ¶
ieee14(buses) -> Region
IEEE 14-bus batch region for a bus set such as (9, 13, 14).
Not shipped: the case file is downloaded from its public source on first
use and the region is exported and cached locally (see :mod:icgym.datasets).
activsg2000 ¶
activsg2000(buses) -> Region
Bundled ACTIVSg2000 batch region (2,000 buses, five representative days).
Exact exports for 150 bus pairs, 35 batches of two or three buses, and 8
location multisets; see bundled('activsg2000'). Larger batches need
:class:icgym.DCOPFRegion on the network itself.
reference ¶
reference(system: str, name: str) -> dict
Bundled reference results, e.g. reference('activsg2000', 'poa_implicit')
(25 batches of three and five buses evaluated with DCOPFRegion) or
'location_w' (max-min fair points of all 216 placements of the location game).
icgym.datasets ¶
Optional datasets that are built on the user's machine, not shipped.
The IEEE 14-bus scenario combines the public IEEE 14-bus case (topology,
reactances, base loads, generator sizes) with our own additions (thermal
limits, which the case lacks, generator costs, and hourly load multipliers of
five representative days), which ship with the package under the MIT license.
On first use, :func:fetch_ieee14 downloads the case file from MATPOWER's
repository (a conversion of the University of Washington Power Systems Test
Case Archive file), checks its SHA-256 hash, and writes the scenario to a
local cache; :func:ieee14 then exports and caches the batch region of any
set of buses (a few seconds each).
The case file is not redistributed by this package. Its archive describes its
material as provided for research and education, not for commercial gain;
check the terms of the sources before commercial use. A case file obtained
elsewhere can be supplied with case_file= or the ICGYM_IEEE14_CASE
environment variable. The cache lives in ICGYM_DATA_DIR (default
~/.cache/icgym).
fetch_ieee14 ¶
fetch_ieee14(case_file: str | Path | None = None, quiet: bool = False) -> Path
Build the IEEE 14-bus representative-day scenario locally; returns its directory.
The directory holds the CSV files that :meth:icgym.network.DCNetwork.from_csv_dir
and icgym-export --data read.
ieee14_network ¶
ieee14_network(case_file: str | Path | None = None)
The IEEE 14-bus scenario as a :class:icgym.network.DCNetwork (built on first use).
ieee14_ac_network ¶
ieee14_ac_network(case_file: str | Path | None = None)
The IEEE 14-bus scenario as an :class:icgym.ac_region.ACNetwork, for AC studies.
The same case file and overlay as :func:ieee14_network: the overlay's
thermal limits become MVA limits, its multipliers scale active and reactive
base loads alike, and voltage limits, reactive limits, line resistances, and
shunts come from the case file.
ieee14 ¶
ieee14(buses, case_file: str | Path | None = None, workers: int = 1) -> Region
IEEE 14-bus batch region for a bus set such as (9, 13, 14), columns in the given order.
Exported on first use from the locally built scenario (five representative days, 120 hourly periods) and cached; applicants at the same bus are interchangeable, so one export serves every order.
icgym.ac_region ¶
An implicit batch region under AC power flow: the ACOPF, queried by Ipopt.
:class:ACOPFRegion answers the same questions as
:class:~icgym.dcopf_region.DCOPFRegion (water-filling levels, hosting
capacities, the planner's optimum, the proportional rule's common fraction, the
utilitarian allocation), but a period hosts the new loads only if some
redispatch of the existing generators, in active and reactive power, meets the
full AC power-flow equations with
- apparent-power limits on both ends of every branch,
- bus voltage magnitudes within their limits, and
- generator active and reactive limits.
New loads draw reactive power at a fixed power factor (lagging). Losses, voltage
limits, and reactive power make the region nonconvex, and it need not be
downward closed (the theory's Assumption 1); :func:downward_closure_check
tests that assumption on samples of the region's boundary.
The nonlinear programs are solved by Ipopt through CasADi (the ac extra:
pip install "interconnection-gym[ac]"). Ipopt finds local optima. Every
query here is a feasible problem (no new load is always feasible) maximizing a
linear function of the new loads, and the region is usually star-shaped along
the directions the rules use, but a returned level can in principle fall short
of the global one. multistart re-solves from extra starting points.
Periods enter lazily, as in the DC region: the joint program starts with the peak periods, and any period the solution cannot host is added.
ACNetwork
dataclass
¶
ACNetwork(buses: list[str], bus_type: ndarray, gs: ndarray, bs: ndarray, vmin: ndarray, vmax: ndarray, f: ndarray, t: ndarray, r: ndarray, x: ndarray, b: ndarray, tap: ndarray, shift: ndarray, rate: ndarray, gen_bus: ndarray, pmin: ndarray, pmax: ndarray, qmin: ndarray, qmax: ndarray, pd: ndarray, qd: ndarray, base_mva: float = 100.0, source: str = '', branch_names: list = list())
An AC network over periods: MATPOWER-style data in per unit of base_mva.
pd/qd are the base loads (periods x buses, MW and MVAr). Branch
rate is the apparent-power limit in MVA (inf for none).
from_matpower
classmethod
¶
from_matpower(case_file, rate=None, period_multipliers=None, pmin=None, source: str = '')
Read a MATPOWER .m case.
rate maps "f-t" to an MVA limit (overriding rateA; a zero
rateA means no limit). period_multipliers scales the base active
and reactive loads, one period per multiplier (default: one period).
pmin maps a generator's bus to its minimum output (MW).
admittances ¶
admittances()
Branch two-port admittances (Yff, Yft, Ytf, Ytt) as complex arrays (p.u.).
branch_flows ¶
branch_flows(vm, va)
Complex power entering each branch at its from and to ends (p.u.), as arrays.
mismatch ¶
mismatch(vm, va, pg, qg, pd, qd)
Bus power mismatch (p.u.) of an operating point: injections minus generation plus load.
ACOPFRegion ¶
ACOPFRegion(net: ACNetwork, buses, power_factor=0.95, applicant_names=None, initial_periods: int = 3, multistart: int = 0, seed: int = 0, certify: float = 0.001)
Bases: DCOPFRegion
Batch region of new loads at buses, defined implicitly by the multi-period ACOPF.
power_factor (one number or one per applicant, lagging) sets the
reactive power each new load draws. Queries return MW of new active load.
water_fill ¶
water_fill(requests, weights=None, active=None, return_stages: bool = False)
Water-filling U(r) by NLPs, each step checked by feasibility tests.
A hosted point is a certificate (Ipopt returns an operating point that
meets every limit), while a maximum can be a local one. So the level is
pushed while a point certify (relative) further along the ray is
hosted, and an applicant counts as blocked only if growing it alone by
certify is not hosted.
contains ¶
contains(s, tol: float = 1e-06) -> bool
Whether served loads s are hosted in every period, within tol.
operating_point ¶
operating_point(s, period: int) -> dict
An AC operating point hosting loads s in period: voltages, angles, generation, flows.
downward_closure_check ¶
downward_closure_check(region, samples: int = 20, seed: int = 0, cuts=(0.0, 0.5), tol: float = 1e-05) -> dict
Test the theory's downward-closure assumption on the region's boundary.
Each sample is a boundary point: water-filling with random weights. For
each applicant and each factor in cuts, its load is reduced to that
factor and the point is tested. Returns the number of tests and the
violations (points inside the region whose reduction is outside).