Available transfer capability#

solve_atc(case, source, sink, *, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, trm=0.0, cbm=0.0, cutoff=0.005, max_limiters=25, gen_limited=False, base_flows='ac', slack_participation=None, interfaces=None, island_cap_exempt=(), backend=None)#

Calculate available transfer capability for one direction.

Endpoints accept a bus number, a named settlement point, a bus sequence with equal shares, or a {bus: weight} mapping. Weights are normalized to one. points resolves named settlement points.

Parameters:

case -- Case that supplies the network, dispatch, ratings, and costs.
source -- Injection endpoint.
sink -- Withdrawal endpoint.
contingencies -- The outages to evaluate: sweeps and named outages. The default sweeps every in-service branch in the transfer's island.
contingency_rating -- Use "emergency" ratings after outages or the default "normal" ratings throughout. The solver does not substitute a normal rating when an emergency rating is unset.
monitored -- Branch identities to check. None selects all branches with a positive applicable rating.
points -- Settlement points keyed by customer name.
trm -- Transmission reliability margin in MW.
cbm -- Capacity benefit margin in MW.
cutoff -- Ignore an absolute transfer distribution factor at or below this value when it cannot define a transfer limit.
max_limiters -- Maximum number of ranked limiting conditions to return.
gen_limited -- Also limit the transfer by source generation headroom.
base_flows -- Where the zero-transfer branch flows come from. "ac" solves the AC base case and starts from its flows; a base case that does not solve returns a blocked Unsolved result. "dc" keeps the lossless DC flows. solve_atc_matrix() also accepts explicit flows.
backend -- Solver backend for the "ac" anchor.
slack_participation -- Resources that balance generator outages.
interfaces -- Additional monitored interface declarations.
island_cap_exempt -- Buses whose own disconnection is the customer's outage. An island holding one of them puts no generation-headroom cap on the transfer; its surviving flows still screen.

Returns:

TTC and ATC in MW, where ATC = TTC - trm - cbm, together with the ranked limits ahead, the ranked pre-existing violations, and any contingency that could not be evaluated.

Raises:

DCOPFError -- An endpoint, contingency, or network selection is invalid.

solve_atc_ac(case, source, sink, *, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, trm=0.0, cbm=0.0, cutoff=0.005, max_limiters=25, gen_limited=False, interfaces=None, island_cap_exempt=(), backend=None, solve_options=None, voltage_band=None, screen='full', search_limit_mw=None, base_flows='ac', net=None, progress=None, label='AC verification')#

Calculate available transfer capability with AC verification.

Parameters:

case -- Case that supplies the network, base dispatch, controls, and branch ratings.
source -- Injection endpoint. Use a bus number, a settlement-point name, a sequence of equally weighted buses, or a {bus: weight} mapping. Every source bus must have in-service generation.
sink -- Withdrawal endpoint in the same forms as source. A sink bus must have in-service load or generation that can absorb the transfer.
contingencies -- The outages to evaluate: sweeps and named outages. The default sweeps every in-service branch in the transfer's island.
contingency_rating -- "emergency" uses emergency ratings after an outage. The default "normal" uses normal ratings for all conditions. A missing emergency rating remains unset.
monitored -- Branch identities to check. None checks every branch with a positive applicable rating.
points -- SettlementPoint objects keyed by the names used for source or sink. Point weights must sum to one.
trm -- Transmission reliability margin in MW. The result subtracts this value from TTC.
cbm -- Capacity benefit margin in MW. The result subtracts this value from TTC after TRM.
cutoff -- Ignore an absolute transfer distribution factor at or below this value when it cannot define a transfer limit.
max_limiters -- Maximum number of ranked limiting conditions to return.
gen_limited -- Limit the transfer by available source-generation headroom in addition to network limits.
interfaces -- Optional monitored interface declarations. Each interface supplies a name, normal and optional emergency bounds in MW, and weighted branch members in written flow direction.
island_cap_exempt -- Buses whose own disconnection is the customer's outage. An island holding one of them puts no generation-headroom cap on the transfer; its surviving flows still screen.
backend -- AC solver backend. None uses normal backend selection.
solve_options -- Mapping of PfSolveOptions field names to values for each AC power-flow solve.
voltage_band -- Optional common (low, high) per-unit voltage band. None uses the applicable limits from each bus record.
screen -- "full" verifies every evaluated contingency at the final transfer. "candidates" verifies only the highest-ranked candidates from the initial screen.
search_limit_mw -- Maximum transfer in MW that the study can test. This value is a study ceiling, not a reported limiter. Use it when no physical limit is expected within a known range.
base_flows -- Where the zero-transfer flows of the DC proposal come from, as in solve_atc_matrix(). The default "ac" solves the base case here; a base case that does not solve returns a blocked Unsolved result.
net -- The DC network explicit flows were anchored on. None builds one.
progress -- Optional callable that receives one progress frame per AC screen, counted over that screen's batch. A true result stops the search with the solver cancellation exception.
label -- Phase prefix of those frames.

Returns:

An AtcResult. ttc_mw is the verified transfer limit. atc_mw equals ttc_mw - trm - cbm. limiter identifies the binding thermal, interface, voltage, generation-headroom, island, or stability condition. limiters contains the retained ranking of the limits ahead. pre_existing contains the violations measured at zero transfer, with the DC estimate for scenarios the search did not measure; any entry blocks the direction. failed identifies contingencies that could not be evaluated and islands that cannot balance their own load.

Raises:

DCOPFError -- The request is invalid, an endpoint cannot move the required equipment, or the AC study cannot provide a result.

Examples

Verify N-1 transfer capability from generator bus 101 to load bus 205:

>>> result = gpf.solve_atc_ac(
...     case,
...     101,
...     205,
...     trm=25.0,
...     voltage_band=(0.95, 1.05),
... )
>>> available_mw = result.atc_mw

solve_atc_matrix(case, directions, *, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, points=None, trm=0.0, cbm=0.0, cutoff=0.005, max_limiters=25, gen_limited=False, base_flows='ac', slack_participation=None, interfaces=None, island_cap_exempt=(), backend=None, net=None, progress=None)#

Calculate available transfer capability for multiple directions.

Parameters:

case -- Case that supplies the network, dispatch, ratings, and costs.
directions -- Sequence of (source, sink) pairs or a mapping from customer labels to these pairs. Each endpoint can be a bus number, a settlement-point name, a sequence of equally weighted buses, or a {bus: weight} mapping.
contingencies -- The outages to evaluate: sweeps and named outages. The default sweeps every in-service branch in the transfer's island.
contingency_rating -- "emergency" uses emergency ratings after an outage. The default "normal" uses normal ratings for all conditions. A missing emergency rating remains unset.
monitored -- Branch identities to check. None checks every branch with a positive applicable rating.
points -- SettlementPoint objects keyed by the names used in directions. Each point maps buses to weights that sum to one.
trm -- Transmission reliability margin in MW. The result subtracts this value from TTC.
cbm -- Capacity benefit margin in MW. The result subtracts this value from TTC after TRM.
cutoff -- Ignore an absolute transfer distribution factor at or below this value when it cannot define a transfer limit.
max_limiters -- Maximum number of ranked limiting conditions to retain for each direction.
gen_limited -- Limit each direction by its source-generation headroom.
base_flows -- Where the zero-transfer branch flows come from. "ac" solves the AC base case and starts from its flows; a base case that does not solve returns a blocked Unsolved result for every direction. "dc" keeps the lossless DC flows. An array gives every flow in MW in prepared-network order. A mapping gives flows by branch key.
backend -- Solver backend for the "ac" anchor.
slack_participation -- Optional balancing participation accepted by build_dc_network. Balanced endpoint weights make ordinary point-to-point transfer factors independent of this selection.
interfaces -- Optional monitored interface declarations. Each interface supplies a name, normal and optional emergency bounds in MW, and weighted branch members in written flow direction.
island_cap_exempt -- Buses whose own disconnection is the customer's outage. An island holding one of them puts no generation-headroom cap on the transfer; its surviving flows still screen.
net -- The case's prepared DC network, when the caller already built it. None builds one.
progress -- Optional callable that receives one ScenarioProgress per screened block, counted over the scenarios dc_scenario_count reports. A true result stops the run with the solver cancellation exception.

Returns:

A list in input order when directions is a sequence, or a mapping with the supplied labels when directions is a mapping. Each AtcResult contains ttc_mw, atc_mw, the binding limiter, the ranked limits ahead in limiters, the ranked pre-existing violations in pre_existing, and unevaluated contingencies in failed. A pre-existing violation blocks the direction.

Raises:

DCOPFError -- A direction, contingency, or network selection is invalid.

class AtcResult(atc_mw, ttc_mw, limiter, source=None, sink=None, direction='', limiters=<factory>, failed=<factory>, stats=<factory>, contingencies=None, contingency_rating=None, pre_existing=<factory>)#

Store available transfer capability for one direction.

The result contains TTC and ATC in MW, the transfer endpoints, the binding customer-visible constraint, other reported constraints, and any failed contingency. limiters ranks the limits ahead of the transfer. pre_existing ranks the constraints already at or beyond their limit at zero transfer that the direction loads further. Any entry there blocks the direction, and attributed_mw then reports the transfer to the first limit ahead.

property attributed_mw#: Return the available transfer with pre-existing violations excused: the first limit ahead less the same margins atc_mw carries.

property available_mw#: Return nonnegative transfer available in the requested direction.

property blocked#: Return whether a constraint blocks the direction at zero transfer.

property ac_stats#: Return the AC search statistics, or an empty dict for a DC result.

property search_limited#: Return whether the AC search reached its ceiling without a limit.

property split_capped#: Return the islanding outage whose DC cap set the AC result.

property margin_limited#: Return whether margins consume otherwise positive capability.

doc()#: Return scalar fields and limiter table bindings.

as_tables()#: Return the ranked limiter tables in physical units.

classmethod column_quantities()#: Return quantity bindings for the limiter columns of both tables.

to_markdown(path=None)#: Render the transfer study as Markdown and optionally write it.

class AtcLimiter(limit, outage, limit_mw, flow0, rate_mw, tdf, ac_flow_at_limit=None)#

Describe one constraint that limits a transfer result.

The result identifies the monitored limit, any related outage, the applicable rating, the calculated flow, and the available transfer in MW. ac_flow_at_limit stores the solved AC flow at the reported transfer.

property contingency#: The binding contingency's display label (outage.name).

property limit_type#: Return the mechanism name derived from the limiter variant.

property monitored#: Return the monitored element identity.

property label#: Return the display label owned by the limiter variant.

driven_mw(transfer_mw)#: Return the flow driven by a transfer.

property margin_mw#: Return the rating margin before any transfer, or None for a constraint without a flow rating.

property flow_at_limit_mw#

Return the monitored flow at the limiting transfer.

An AC search reports the solved flow. A linear result reports the zero-transfer flow plus the driven flow. A constraint without a flow rating returns None.

property zero_transfer_excess_mw#: Return the limit excess at zero transfer for a blocked direction.

rating_needed(transfer_mw)#

Return the flow rating required to pass a transfer.

Return None for non-flow limits, zero TDF, or an adequate rating.

class Thermal(branch)#

A monitored branch reaches its MW rating.

property monitored#: Return the monitored branch identity.

property label#: Return a readable branch label.

class Interface(name)#

A flowgate reaches its rating on its members' signed flow sum.

property monitored#: Return the monitored interface identity.

property label#: Return the interface name.

class VoltageBand(bus)#: A bus voltage leaves its band as the transfer grows (AC tier).

class GenHeadroom(bus)#: The source's own generation runs out before the network does.

class IslandHeadroom(bus)#: A sink stranded inside a recoverable split's pocket runs out of local generation headroom as the transfer grows.

class Stability#: The AC solve stops converging as the transfer grows: the nose point.

class Unsolved#: The zero-transfer base case itself does not solve.

solve_poi_headroom(case, pois=None, *, sink='system', contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, interfaces=None, points=None, trm=0.0, cbm=0.0, max_limiters=25, ac=False, verify_top=None, backend=None, voltage_band=None, strength=False, progress=None)#

Return ranked point-of-interconnection headroom over a case set.

Parameters:

case -- One case, a Study, or an iterable of (name, case) pairs.
pois -- Candidate bus numbers or line-tap declarations. A line tap is a TapLine or a mapping with from, to, ckt, pct, and optional bus fields. A Study can supply declared candidates when this value is omitted.
sink -- Withdrawal endpoint. Use a bus number, settlement-point name, or "system" for displacement by the generation in the POI's island.
contingencies -- Outages to evaluate beside the study's own declaration. The default adds one sweep over every in-service branch; an empty declaration screens the study's alone.
contingency_rating -- Exact post-contingency rating tier. The default is "normal". An unset selected rating stays unset.
monitored -- Branch identities to check. None selects rated branches.
interfaces -- Additional monitored interface declarations.
points -- Settlement points keyed by customer name.
trm -- Transmission reliability margin in MW.
cbm -- Capacity benefit margin in MW.
max_limiters -- Maximum ranked limiting conditions to retain.
ac -- Add AC verification when true.
verify_top -- Number of top-ranked candidates to verify with AC. None uses the standard selection.
backend -- AC solver backend.
voltage_band -- Optional common (low, high) per-unit voltage band.
strength -- Add base-network SCMVA and SCR when true.
progress -- Optional callable that receives a ScenarioProgress count per screening pass and returns true to stop the study.

Returns:

Every candidate in every operating case, ranked by usable headroom in MW, with the binding case and limiting condition.

Raises:

DCOPFError -- The study has no case or candidate, or a selection is invalid.

solve_project_headroom(study, *, sink='system', contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, interfaces=None, points=None, trm=0.0, cbm=0.0, max_limiters=25, ac=False, backend=None, voltage_band=None, strength=False, progress=None)#

Return headroom for each declared project and operating case.

Generation projects inject at their declared POI. Load projects withdraw at their declared POI. The reported deliverable output does not exceed the project's requested output.

Parameters:

study -- Study that declares projects or loads, operating cases, and their dispatch assumptions.
sink -- Counterpart for each project transfer. Use a bus number, a named settlement point, or "system" for displacement across the generation in the project's island.
contingencies -- Outages to evaluate beside the study's own declaration. The default adds one sweep over every in-service branch; an empty declaration screens the study's alone.
contingency_rating -- "emergency" uses emergency ratings after an outage. The default "normal" uses normal ratings for all conditions. An unset selected rating stays unset.
monitored -- Branch identities to check. None checks rated branches.
interfaces -- Optional monitored interface declarations with MW bounds and weighted branch members.
points -- SettlementPoint objects keyed by names used in sink.
trm -- Transmission reliability margin in MW.
cbm -- Capacity benefit margin in MW.
max_limiters -- Maximum ranked limiting conditions to retain per result.
ac -- Verify every project transfer with AC power flow when true.
backend -- AC solver backend. None uses normal backend selection.
voltage_band -- Optional common (low, high) per-unit voltage band. None uses the limits from each bus record.
strength -- Add base-network fault level in MVA and short-circuit ratio at each project POI.
progress -- Optional callable that receives a ScenarioProgress count per screening pass. A true result stops the study by raising the solver cancellation exception.

Returns:

A CaseSetReport. cases contains one PoiHeadroomCase per operating case. Each row reports DC headroom, optional AC headroom, usable headroom_mw, project identity, and limiting condition. binding contains each project's lowest-headroom case.

Raises:

DCOPFError -- The study has no declared project or load, or an endpoint, contingency, or monitored element is invalid.

class PoiHeadroom(kind, dc_mw, headroom_mw, ac_mw=None, scmva=None, scr=None, tap='', *, bus, label, case, dc, ac=None, limit_type='unconstrained', limiter=None)#

Store one POI's DC, optional AC, and ranked headroom.

Full ATC results retain raw network capability and limiter evidence. Tier MW values include the project request cap. headroom_mw fixes the tier used for ranking across cases. Optional SCMVA and SCR describe base-network strength. limit_type identifies the network, request, or unconstrained cause.

property poi#: Return the tapped line or bus number for display.

class PoiHeadroomCase(name, rows, skipped=<factory>)#

One case of a POI screen: its candidates, ranked by headroom descending (best injection points first).

Each row stores its underlying AtcResult objects in row.dc and row.ac. Use AtcResult.to_markdown() for a detailed report about one point of interconnection. A CaseSetReport contains these per-case results.

static row_json(r, header)#: One row of the SQL headroom table: DC and AC-verified headroom MW, the ranked one of the two, the binding element/contingency/type, the blocked flag, and any system-strength columns.

static upgrade_id(r)#: This screen's identity columns on a row of the upgrades table: which candidate, in which case, delivering how much.

static cols(header)#: Return report columns for the POI headroom table.

static binding_cols(header)#: The binding-case table of a case set, in this screen's columns. The label column carries the project name: project mode can put several projects on one POI bus, so the bus alone does not identify a row.

run_screen(study, *, sink='system', contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, max_limiters=25, ac=False, backend=None, voltage_band=None, strength=False, progress=None)#

Return individual project deliverability with and without the queue.

This screen compares each project alone with the same project after the study's other queued projects are present. Network-service projects use solve_group_deliverability instead.

Parameters:

study -- Study that declares projects, queue members, operating cases, and dispatch assumptions.
sink -- Withdrawal counterpart for generation projects and source counterpart for load projects. Use "system" for displacement across the generation in the project's island or a bus number for a fixed bus.
contingencies -- Explicit outages. An entry can be one (from_bus, to_bus, circuit_id) branch identity, a group of branch identities, or an Outage. An Outage can name branch or generator identities.
contingency_rating -- "emergency" uses emergency ratings after an outage. The default "normal" uses normal ratings for all conditions. An unset selected rating stays unset.
monitored -- Branch identities to check. None checks rated branches.
max_limiters -- Maximum ranked limiting conditions to retain per result.
ac -- Verify and rank the with-queue result with AC power flow when true. The AC search stops at the resource capacity plus margins. A search that reaches that ceiling without a limit reports the tested transfer and no network headroom. The report still retains the two DC results.
backend -- AC solver backend. None uses normal backend selection.
voltage_band -- Optional common (low, high) per-unit voltage band. None uses the limits from each bus record.
strength -- Add base-network fault level in MVA and SCR = scmva / request_mw at each POI. Project and queue machines do not contribute to these values.
progress -- Optional callable that receives the screen's progress frames, each named by its phase and the case when the study has several. A true result stops the study by raising the solver cancellation exception.

Returns:

A CaseSetReport. Each ScreenRow retains the DC answer alone, the DC answer with the queue, and the AC answer when it ran. The binding table reports each project's lowest-deliverable case from the ranked answer. The screen table reports one row per calculation.

Raises:

ValueError -- The study has no case, no eligible project, or an invalid selection.

class ScreenCase(name, rows, skipped=<factory>)#

One case of a queue screen: the projects it screened, in declaration order. It is the inner structure of the CaseSetReport that a screen returns.

classmethod binding_columns()#: Return the column bindings of the binding table.

classmethod upgrade_columns()#: Return the column bindings of the upgrades table.

classmethod binding_json(r, header)#: Return one row of the SQL binding table: the ranked answer.

classmethod row_json(r, header)#: Return the ranked calculation's screen row.

classmethod table_rows(r, header)#: Return one SQL screen row per calculation.

classmethod upgrade_rows(r, header)#

Return one upgrades row per limiter of the ranked answer.

The rating is estimated at the full request, so a project the network already carries in full needs no upgrade.

rendered_rows(header)#: Return the screen rows for the Markdown table.

classmethod rendered_binding(rows, header)#: Return the binding rows for the Markdown table.

static cols(header)#: Return the Markdown columns of the per-calculation table.

static binding_cols(header)#: Return the Markdown columns of the binding table.

class ScreenRow(label, poi_bus, kind, request_mw, resource_mw, alone, queued, case, ac=None, scmva=None, scr=None)#

Store one project's screen calculations in one case.

alone and queued are the DC answers without and with the declared queue. ac is the AC verification of the queued network when it ran. selected is the answer the report ranks: the AC one when it ran, else the queued DC one.

property selected#: Return the ranked answer.

property calculations#: Return every calculation as (network state, answer) pairs.

property result#: Return the ranked answer's network result.

property deliverable_mw#: Return the ranked deliverable output.

property ranked_mw#: Return the value used to rank cases.

property limiter#: Return the network limiter when the network sets the deliverable.

property limit_type#: Return the mechanism that sets the ranked deliverable.

solve_group_deliverability(study, *, sink='system', contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), contingency_rating='normal', monitored=None, interfaces=None, points=None, trm=0.0, cbm=0.0, max_limiters=25, ac=False, backend=None, voltage_band=None, progress=None)#

Return simultaneous network-service delivery by member and case.

Each case supplies the member dispatch weights. The group transfer is split by those weights. Each member's verdict is "full" when its share meets its request and "partial" otherwise. Other project services use solve_project_headroom or run_screen.

Parameters:

study -- Study with operating cases and projects that declare the network-resource service.
sink -- Group withdrawal endpoint. Use a bus number, a named settlement point, or "system" for displacement across the generation in the group's island.
contingencies -- Outages to evaluate beside the study's own declaration. The default adds one sweep over every in-service branch; an empty declaration screens the study's alone.
contingency_rating -- "emergency" uses emergency ratings after an outage. The default "normal" uses normal ratings for all conditions. An unset selected rating stays unset.
monitored -- Branch identities to check. None checks rated branches.
interfaces -- Optional monitored interface declarations with MW bounds and weighted branch members.
points -- SettlementPoint objects keyed by names used in sink.
trm -- Transmission reliability margin in MW.
cbm -- Capacity benefit margin in MW.
max_limiters -- Maximum ranked limiting conditions to retain per result.
ac -- Verify the group transfer with AC power flow and use that value for ranking when true.
backend -- AC solver backend. None uses normal backend selection.
voltage_band -- Optional common (low, high) per-unit voltage band. None uses the limits from each bus record.
progress -- Optional callable that receives a ScenarioProgress count per screening pass. A true result stops the study by raising the solver cancellation exception.

Returns:

A CaseSetReport. Each GroupCase row contains the member weight, requested MW, total group deliverability, member deliverability in MW, verdict, and limiting condition. binding contains each member's lowest-deliverability case.

Raises:

DCOPFError -- The study has no eligible group member, or an endpoint, contingency, or monitored element is invalid.