Optimal power flow#

solve_dc_opf(case, *, flow_limits=True, cost_segments=20, losses=False, loss_segments=8, net=None, slack_participation=None)#

Return a priced least-cost DC dispatch for the requested constraints.

Parameters:

  • case -- Case that supplies the network, demand, generator limits, and generation costs.

  • flow_limits -- Enforce positive branch ratings when true.

  • cost_segments -- Resolution for quadratic generation cost curves.

  • losses -- Include the supported transmission-loss estimate when true.

  • loss_segments -- Resolution for the loss estimate.

  • net -- Optional prepared DC network for the same case topology.

  • slack_participation -- Buses or generators that balance net injections.

Returns:

Generator dispatch and branch flows in MW, bus angles in radians, nodal prices in dollars per MWh, and the total cost in dollars per hour.

Raises:

DCOPFError -- The case or optimization request is invalid or cannot solve.

class DCOPFResult(objective, pg=<factory>, theta=<factory>, lmp=<factory>, lmp_energy=<factory>, lmp_congestion=<factory>, lmp_loss=<factory>, flow=<factory>)#

Store a priced DC dispatch by power-system identity.

The result contains the objective value, generator dispatch in MW, branch flows in MW, bus angles in radians, and nodal prices in dollars per MWh. Generator, branch, and bus values use case record identities.

doc()#

Return scalar result fields and table column bindings.

as_tables()#

Row-tables for the SQL query surface, physical units, literal field names: gen (dispatch MW), lmp (per-bus prices $/MWh), branch (flow MW).

classmethod column_quantities()#

Return the quantity each projected column binds, keyed by table then column. as_tables() names the columns and this says what they measure, so each reads its label, unit, and type from its quantity.

solve_dc_scopf(case, *, contingencies=Contingencies(sweeps=(Sweep(family='branch', scope=None),), named=()), monitored=None, contingency_rating='normal', eval_limit=None, preseed_loading=0.9, max_iterations=20, cuts_per_iteration=10, cost_segments=20, warm_start=None, ac_cuts=None, corrective=False, max_recourse_blocks=20, ramp_window_min=30.0, ramp_headroom_fraction=1.0, losses=False, loss_segments=8, max_loss_iterations=20, loss_tol_mw=1e-06, net=None, slack_participation=None, progress=None)#

Return a priced DC dispatch that meets the requested security criteria.

Parameters:

  • case -- Case that supplies the network, dispatch limits, ramp data, and generation costs.

  • contingencies -- The outages to evaluate: sweeps and named outages. The default sweeps every in-service branch.

  • monitored -- Branch identities to check. None selects all branches with a positive applicable rating.

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

  • eval_limit -- Evaluate at most this many ranked contingencies. None evaluates all selected contingencies. The result reports any omitted coverage.

  • preseed_loading -- Add initially screened limits at or above this loading fraction. Use None or 1.0 to disable this selection.

  • max_iterations -- Maximum number of security review passes.

  • cuts_per_iteration -- Maximum number of newly enforced security limits added per pass.

  • cost_segments -- Resolution for quadratic generation cost curves.

  • warm_start -- Optional (contingency_label, branch_identity) pairs from an earlier result. The result reports pairs that do not apply.

  • ac_cuts -- Optional customer-supplied AC security constraints.

  • corrective -- Allow post-contingency generator redispatch when true.

  • max_recourse_blocks -- Maximum number of contingencies that can receive separate corrective redispatch.

  • ramp_window_min -- Corrective redispatch window in minutes.

  • ramp_headroom_fraction -- Fraction of available headroom to use when a generator has no applicable ramp value.

  • losses -- Include the supported transmission-loss estimate when true.

  • loss_segments -- Resolution for the loss estimate.

  • max_loss_iterations -- Maximum number of loss refinement passes.

  • loss_tol_mw -- Convergence tolerance for the loss estimate in MW.

  • net -- Optional prepared DC network for the same case topology.

  • slack_participation -- Buses or generators that balance net injections.

  • progress -- Optional callable that receives one progress frame per master iteration. A true result stops the study.

Returns:

Dispatch, flows, nodal price components, checked contingencies, binding limits, corrective actions, and any incomplete coverage notice.

Raises:

DCOPFError -- The case or optimization request is invalid or cannot solve.

solve_scopf(case, *, monitored=None, contingency_rating='normal', max_outer=4, backend=None, solve_options=None, ac_warm_start=None, voltage=None, slack_participation=None, progress=None, **dc_kwargs)#

Return a priced dispatch with AC security verification.

Parameters:

  • case -- Case that supplies the network, controls, limits, and costs.

  • monitored -- Branch identities to check. None selects all branches with a positive applicable rating.

  • contingency_rating -- Use "emergency" ratings after outages or the default "normal" ratings throughout. The selected tier is exact, so an unset emergency rating stays unset.

  • max_outer -- Maximum number of AC security review passes.

  • backend -- AC solver backend. None uses normal backend selection.

  • solve_options -- Power-flow options for AC verification.

  • ac_warm_start -- Optional contingency and branch pairs from an earlier result. The result reports pairs that do not apply.

  • voltage -- Optional VoltageSecurity request. Its band supplies a common (low, high) per-unit range. None uses each bus's emergency limits when voltage security is requested without a common band.

  • slack_participation -- Resources that balance injections. The "areas" policy is not available for AC verification.

  • progress -- Optional callable that receives the study's progress frames: one per master iteration, and one per AC review counted over its batch. A true result stops the study.

  • dc_kwargs -- Additional options accepted by solve_dc_scopf. This function owns ac_cuts and the prepared DC network.

Returns:

Dispatch, price components, AC verification status, binding conditions, voltage actions when requested, and any remaining violation. termination states whether verification completed or why it stopped.

Raises:

  • DCOPFError -- The case or optimization request is invalid or cannot solve.

  • TypeError -- A caller supplies an option that this function owns.

class ScopfResult(objective, converged, termination, iterations, pg=<factory>, theta=<factory>, flow=<factory>, lmp=<factory>, lmp_energy=<factory>, lmp_congestion=<factory>, lmp_security=<factory>, lmp_loss=<factory>, binding=<factory>, remedial=<factory>, remaining=<factory>, failed=<factory>, stats=<factory>, contingencies=None, contingency_rating=None, warm_start=<factory>, ac_warm_start=<factory>, voltage=<factory>, evaluated=<factory>)#

Store a priced operating point and its security results.

The result identifies convergence, dispatch, branch flows, nodal prices, checked contingencies, binding security limits, and customer-visible warnings. Generator and branch values use case record identities.

doc()#

Return the result document: the scalar and telemetry header, with the column bindings for the row-tables (gen / lmp / branch / binding / remedial). The priced secured operating point lives on the queryable slot and is queried in SQL; the document stores no copy of it.

as_tables()#

Row-tables for the SQL query surface, physical units: gen (dispatch MW), lmp (per-bus energy/congestion/security/loss $/MWh), branch (base flow MW), binding (the binding contingencies with shadow prices), remedial (corrective per-contingency redispatch).

classmethod column_quantities()#

Return the quantity each projected column binds, keyed by table then column.

The dispatch tables are the base-case ones. This result adds the security component of the price, and the two contingency tables: what bound, and what the corrective redispatch moves.

to_markdown(path=None)#

Render the dispatch, prices, and security outcomes as Markdown.

class gpf.AcCut#

Store an AC security constraint for a later SCOPF solve.

solve_sced(case, demand=None, *, demand_mw=None, durations=None, pg0=None, flow_limits=True, cost_segments=20, losses=False, loss_segments=8, ramp_headroom_fraction=1.0, reserve=None, reserve_window_min=10.0, net=None, slack_participation=None)#

Return a priced dispatch schedule for the requested time periods.

Supply exactly one demand form. demand contains one base-demand multiplier per period. demand_mw contains a T by n_bus array in the prepared network bus order.

Parameters:

  • case -- Case that supplies the network, generators, limits, ramp data, and generation costs.

  • demand -- Base-demand multiplier for each period.

  • demand_mw -- Explicit bus demand in MW for each period.

  • durations -- Positive period lengths in hours. The default is one hour per period.

  • pg0 -- Initial generator output in MW, keyed by (bus, generator_id). Every key must name an in-service generator.

  • flow_limits -- Enforce positive branch ratings when true.

  • cost_segments -- Resolution for quadratic generation cost curves.

  • losses -- Include the supported transmission-loss estimate when true.

  • loss_segments -- Resolution for the loss estimate.

  • ramp_headroom_fraction -- Fraction of available headroom to use when a generator has no applicable ramp value.

  • reserve -- System reserve requirement in MW for each period.

  • reserve_window_min -- Reserve response window in minutes.

  • net -- Optional prepared DC network for the same case topology.

  • slack_participation -- Buses or generators that balance net injections.

Returns:

Per-period generator dispatch, branch flows, nodal prices, reserve values, binding ramp transitions, and the total horizon cost.

Raises:

DCOPFError -- The request has incompatible dimensions or the schedule cannot solve.

class ScedResult(objective, periods, durations, pg=<factory>, theta=<factory>, flow=<factory>, lmp=<factory>, lmp_energy=<factory>, lmp_congestion=<factory>, lmp_loss=<factory>, reserve=<factory>, reserve_price=<factory>, ramp_binding=<factory>, stats=<factory>)#

Store a priced multi-period dispatch schedule.

Per-period values include dispatch, branch flows, energy prices, reserve, and reserve prices. Generator and branch values use case record identities.

doc()#

Return the result document: the scalar header, with the column bindings for the row-tables. Per-period dispatch, prices, and flows live on the queryable slot, carry a period column, and are queried in SQL; the document stores no copy of them.

as_tables()#

Row-tables for the SQL query surface, one period column per multi-period quantity, physical units: gen (dispatch + reserve MW), lmp (per-bus prices $/MWh), branch (flow MW), period (hours, reserve price $/MW), ramp (binding inter-temporal transitions).

classmethod column_quantities()#

Return the quantity each projected column binds, keyed by table then column.

The dispatch tables are the base-case ones with a period column in front, because a horizon answers the same question once per period. The two prices this result adds are separate quantities: a reserve prices capacity per MW held, and a ramp constraint's shadow price prices energy per MWh.

class gpf.DcNetwork#

Store a prepared DC network for reuse across compatible studies.

class DcSensitivity(net)#

Calculate standard DC transfer and outage factors.

Bus and branch arguments are zero-based indexes in the associated DcNetwork. Use net.bus_ids and net.branch_keys to translate between these indexes and case identities. PTDF arrays use network branch order by network bus order. LODF arrays use network branch order on both axes.

ptdf_columns(buses)#

Return one PTDF column for each requested network bus index.

Results follow the input order. Each array has one from-end flow change per network branch for a unit MW injection at that bus, balanced by the network participation policy.

ptdf_weighted(weights)#

Return the PTDF column of one weighted injection in a single solve.

weights maps network bus indexes to injection weights. The result equals the weighted sum of ptdf_columns over those buses, up to floating-point rounding, and costs one right-hand side instead of one per bus.

ptdf_column(bus)#

Return the PTDF column for one network bus index.

The array contains the from-end flow change on each network branch for a unit MW injection balanced by the network participation policy.

ptdf_branches(branches)#

Return one PTDF row for each requested network branch index.

Results follow the input order. Each array contains that branch's from-end flow response to a unit MW injection at each network bus.

ptdf_branch(branch)#

Return the PTDF row for one network branch index.

theta_from_injections(injections)#

Return bus angles for one injection vector or a column block.

A vector has shape (n_bus,). A block has shape (n_bus, n_conditions). The network participation policy balances net injections. Each island reference angle is zero.

theta_from_injection(p)#

Return bus angles for one (n_bus,) injection vector.

lodf_column(outage)#

Return one LODF column with diagonal value -1.

outage is a network branch index. The result follows network branch order. The function returns None when the outage separates the network and has no finite LODF.

outage_weights(outages)#

Return flow-redistribution weights for a branch-outage set.

outages contains network branch indexes. The returned array has shape (n_branch, n_outages). Post-outage flow equals the base flow plus each weight column times its outaged branch flow. The function returns None when the outage set separates the network.

otdf_rows(monitored, outages, weights=None)#

Return post-outage transfer-factor rows for monitored branches.

monitored and outages contain network branch indexes. Each result row follows network bus order. weights can supply the result of outage_weights. The function returns None when the outage set separates the network.

otdf_row(monitored, outages, weights=None)#

Return one monitored branch's post-outage transfer-factor row.

property bridges#

Return the bridge forest of the network.

bridge_rows(ks, inj)#

Return the len(ks) x n_branch weight rows of bridge outages ks from their balancing injections inj.

dead_pocket_flows(pocket, split)#

Return (inner, f_worst) for a pocket that cannot balance.

inner lists the pocket's own branches. f_worst is, per inner branch, the signed post-outage flow of largest magnitude over every state the pocket can settle in: a set of tripped units, the remaining units within their floors and ceilings, and load shed to balance. A trip set is feasible when the remaining floors fit under the load. Flows are linear in the state through the pocket's own transfer factors, so each extreme sits at a vertex found by a greedy fill.

classify_split(k, split)#

Report whether dispatch can balance the island created by an outage.

split_verdict(k, split)#

Return the split verdict of one bridge outage.

split_verdicts(ks, split)#

Return the split verdict of every bridge outage in ks.

bridge_outages(ks, split)#

Return the verdicts of bridge outages ks and their balancing injections, ready for the LODF stream.

The injection of outage k is what the surviving side absorbs per MW of lost bridge flow, with the scale -s: a recoverable pocket's generators by headroom share, or the surviving endpoint of a pocket that cannot balance, less the slack withdrawal under distributed slack. The stream forms w from it as scale * bf @ theta with w[k] = -1, so a balanced pocket, whose injection is empty, gives zero weights.

lodf_stream(rows_branch, sums=None)#

Return a backend LODF stream over the given rows of this network.

rows_branch lists network branch indexes. sums is an optional sparse matrix whose rows are weighted sums of branch rows, appended after the branch rows.

post_outage_transfers(outages, X, rows, split)#

Yield (ks, P, verdicts) blocks of post-outage values of the linear flows X on rows, in outage order.

X is n_branch x C. P[o, r, c] is column c on branch rows[r] after outage ks[o]; the outaged branch itself carries zero. verdicts maps each bridge outage of the block to its IslandSplit. A dead pocket's own branches carry nothing: no transfer reaches them.

post_outage_flows(outages, f, rows, split)#

Yield (ks, P, verdicts) blocks of post-outage physical flows of f, the split context's flow, on rows, in outage order.

P[o, r, 0] is the flow on branch rows[r] after outage ks[o]; the outaged branch itself carries zero. verdicts maps each bridge outage of the block to its IslandSplit. A dead pocket's own branches carry their settled flow.

build_dc_network(case, *, slack_participation=None, nominal_taps=False, require_slack=True, spec=None)#

Build a reusable DC network from a case.

spec is the case's lowering when the caller already holds it, so the AC and DC views of one case share one set of identities.

Parameters:

  • case -- Source case.

  • slack_participation -- Buses or generators that balance injections.

  • nominal_taps -- Ignore transformer tap ratios in branch susceptance when true.

  • require_slack -- Require a reference bus when true.

Returns:

Network matrices, indexes, ratings, and sensitivity inputs.

Raises:

DCOPFError -- If the case has no buses or required reference bus.

class DCOPFError#

Report a DC model or solve failure.