Skip to content

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)

periods property

periods: int

Number of periods.

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.

support

support(direction, zero=None) -> tuple[float, np.ndarray]

max d'x over the period's region (x >= 0) and a maximizer.

zero lists coordinates held at zero.

feasible

feasible(x) -> bool

Whether loads x can be hosted, with every branch limit (no lazy rows).

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.

n property

n: int

Number of applicants.

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

data_dir

data_dir() -> Path

Root of the local cache (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).

demand property

demand: ndarray

Active base load, periods x buses (MW).

periods property

periods: int

Number of periods.

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