Regions from a network¶
Exporting a batch region¶
icgym.network builds the batch region of a set of buses from a DC
power-flow scenario. The scenario is a folder of CSV files: buses, branches,
generators, and hourly demand. A period can host new loads x if some
redispatch of the existing generators serves them within branch and
generator limits.
The exporter works in three steps: 1. It recovers each period's region exactly, by support-function projection. Branch limits are added lazily, so 2,000-bus networks stay fast. 2. It intersects the periods. 3. It keeps the positive parts of the facets. That is the largest downward-closed subset, which treats counterflow between new loads as non-firm.
The exact signed facets are stored alongside, so counterflow can be inspected.
icgym-export --data path/to/scenario --buses 9,13,14 --workers 8 --out region.json
from icgym import load_region_record
record = load_region_record("region.json") # region, signed facets, metadata (input hashes, periods)
Scenario files:
| File | Columns used |
|---|---|
bus.csv |
bus_id, type (3 = reference bus) |
branch_limits.csv |
branch_id, from_bus_id, to_bus_id, reactance_pu, thermal_limit_mva, status |
generator_limits.csv |
generator_id, bus_id, p_min_mw, p_max_mw, status |
demand_bus.csv |
period and one column per bus (MW) |
dcline.csv |
status, from_bus_id, to_bus_id, Pt (active DC lines are not supported yet) |
Large batches: DCOPFRegion¶
Explicit regions are practical up to about three applicants on a large network. Beyond that, the per-period regions have thousands of facets.
For larger batches, DCOPFRegion keeps the region implicit:
- It answers every query with LPs over the served loads and each period's
redispatch: water-filling, hosting capacities, the planner's optimum, and
the proportional and utilitarian rules.
- It adds binding periods and branch limits lazily.
- It plugs into the same rules, games, and environments, at seconds per
allocation.
from icgym import BatchGame, DCOPFRegion, UniformRule
from icgym.network import DCNetwork
net = DCNetwork.from_csv_dir("path/to/activsg2000_scenario")
region = DCOPFRegion(net, ["7106", "5430", "5276", "7259", "5250"])
game = BatchGame(region, UniformRule(beta=0.5))
DCOPFRegion is the exact network region, so it counts the relief that one
new load gives another (counterflow). The exported Region is its largest
downward-closed subset, which the theory assumes. The two agree wherever
counterflow does not bind.
LocationGame.from_network(net, menu, n) builds a location game on any DC
network, using exact regions.
AC power flow: ACOPFRegion¶
The DC model ignores losses, reactive power, and voltage limits. ACOPFRegion
answers the same queries under the full AC power-flow equations:
- A period hosts the new loads only if some redispatch of the existing
generators, in active and reactive power, keeps every branch within its
MVA rating, every bus voltage within its limits, and every generator
within its active and reactive limits.
- New loads draw reactive power at a fixed lagging power_factor.
- Periods enter lazily, as in DCOPFRegion.
It needs the ac extra, which installs CasADi with the Ipopt solver:
pip install "interconnection-gym[ac] @ git+https://github.com/MhaoMou/interconnection-gym"
from icgym import ACOPFRegion, BatchGame, PerMWCommitment, UniformRule, downward_closure_check
from icgym.datasets import ieee14_ac_network
net = ieee14_ac_network() # the IEEE 14-bus case with the package's limits and days
region = ACOPFRegion(net, ["9", "13"], power_factor=0.95)
region.hosting_capacities() # MW of new active load at each bus alone
game = BatchGame(region, UniformRule(), PerMWCommitment(0.4), value=1.0)
downward_closure_check(region, samples=10) # test the theory's assumption on boundary samples
ACNetwork.from_matpower reads any MATPOWER case, with optional MVA limits
and per-period load multipliers.
What carries over from the theory
The theory's proofs assume a downward-closed polytope. The AC region is
not a polytope, and it need not be downward closed (removing load can
raise voltages above their limits). Water-filling, the rules, and the
games still run on it, but the guarantees become checks:
downward_closure_check tests the assumption, and BatchGame.exploitability
tests whether the max-min fair point is an equilibrium.
Local optima
Ipopt finds local optima of nonconvex programs. Every query starts from
a feasible point (no new load) and maximizes a linear function of the
loads, and the region is usually star-shaped along the directions the
rules use, but a level can in principle fall short of the global one.
Pass multistart=k to re-solve from k random starting points.