Solver#

solve_power_flow(case, *, backend=None, options=None, member_costs=None, verbose=False, **solve_opts)#

Validate and solve a power-flow case without changing the case.

The function builds the solver network, runs the selected backend, applies enabled equipment controls, and returns all solution arrays. The var_limit_start solve option controls when the solver enforces limits for voltage-regulating devices.

Parameters:

case -- Case to solve.
backend -- Backend name, "cuda" or "cpu". None selects an available backend.
options -- Network-build options. None uses defaults for the case source format.
member_costs -- Reactive-sharing cost overrides keyed by regulator type code and device index. A lower cost assigns a larger share.
verbose -- Print setup timing and control-pass progress to standard error.
solve_opts -- Fields from PfSolveOptions. Unknown keys raise TypeError. The additional area_interchange option uses 0 to disable area control, 1 to adjust tie lines, or 2 to adjust tie lines and loads.

Returns:

The solution, convergence status, and equipment results.

sensitivity(case, *, slack_participation=None, **solve_kwargs)#

Solve a case and yield a sensitivity snapshot.

Parameters:

case -- Case to solve and linearize.
slack_participation -- Optional {bus_number: nonnegative_weight} mapping for balanced transfer injections. Weights must have a positive sum and are normalized within each connected island. None uses the solved network's reference resource.
solve_kwargs -- Keyword arguments accepted by solve_power_flow, such as backend, build options, and PfSolveOptions fields.

Yields:

A sensitivity snapshot that remains valid inside the context manager.

Raises:

SensitivityError -- The case does not converge or slack participation is invalid.

Examples

>>> with gpf.sensitivity(case) as snap:
...     ptdf = snap.ptdf(monitored=[(101, 102, "1")])

class SensitivityError#: Report a sensitivity construction or factor failure.

class SensitivitySnapshot(session, slack_participation=None)#

Store user-requested sensitivities for one solved operating point.

The context manager provides AC transfer, outage, voltage, generator, shifter, and supported control responses. Methods accept case bus and equipment identities. Returned matrices identify their row and column order. slack_participation selects the balancing resources for transfer and outage results.

close()#: Release the sensitivity factors and their backend handle.

ptdf(monitored=None, targets=None)#

Return power transfer distribution factors.

Parameters:

monitored -- Branch identities (from_bus, to_bus, circuit_id). None selects every in-service branch.
targets -- Case bus numbers for unit active-power injections. None selects every solved bus.

Returns:

A matrix of from-end active-flow change per unit active-power injection. Rows follow monitored and columns follow targets. Each injection is balanced by the snapshot's slack participation.

Raises:

KeyError -- A requested branch or bus is not in the solved network.

lodf(monitored=None, outage=None)#

Return line outage distribution factors.

Parameters:

monitored -- Branch identities to observe. None selects every in-service branch.
outage -- Branch identities to remove one at a time. None selects every in-service branch.

Returns:

A dimensionless matrix. Rows follow monitored and columns follow outage. A value is the monitored from-end flow change divided by the pre-outage flow on the removed branch. A branch's own diagonal value is -1. An islanding outage column is zero.

Raises:

KeyError -- A requested branch is not in the solved network.

mlodf(monitored, outage)#

Return simultaneous multi-outage LODF.

Parameters:

monitored -- Branch identities to observe. None selects every in-service branch.
outage -- Two or more branch identities to remove together. A one-branch input returns ordinary LODF values.

Returns:

A dimensionless matrix with monitored branches as rows and outage branches as columns. Post-outage flow is f_m + sum_j MLODF[m, j] * f_kj.

Raises:

KeyError -- A requested branch is not in the solved network.
SensitivityError -- The outage set creates an island and has no finite redistribution factors.

otdf(monitored, outage, targets=None)#

Return post-outage transfer factors for each requested outage.

Parameters:

monitored -- Branch identities to observe. None selects every in-service branch.
outage -- Branch identities to remove one at a time.
targets -- Case bus numbers for balanced active-power injections. None selects every solved bus.

Returns:

A mapping keyed by "from-to-circuit" outage labels. Each dimensionless matrix contains post-outage from-end active-flow change per unit injection. Rows follow monitored and columns follow targets.

Raises:

KeyError -- A requested branch or bus is not in the solved network.

psdf(monitored, shifters)#

Return branch-flow sensitivity to shifter angle in pu per radian.

Parameters:

monitored -- Branch identities to observe. None selects every in-service branch.
shifters -- Phase-shifting transformer branch identities.

Returns:

A matrix in per-unit from-end active flow per radian. Rows follow monitored and columns follow shifters.

Raises:

KeyError -- A requested branch is not in the solved network.

Notes

The response uses one balancing resource and does not include reactive-mismatch coupling.

control_response(*, taps=(), shunts=(), injections=(), shifters=(), setpoints=())#

Return the supported response to selected control changes.

Parameters:

taps -- Tap-changing transformer branch identities. Each column represents a unit tap-ratio change.
shunts -- Switched-shunt bus numbers. Each column represents a 1 Mvar injection.
injections -- (bus, reactive_mvar_per_active_mw) rows. Each column represents a 1 MW active injection with the declared reactive-power companion.
shifters -- Phase-shifting transformer branch identities. Each column represents a one-radian angle change.
setpoints -- Voltage-regulation target bus numbers. Each column represents a 1 per-unit voltage-setpoint change.

Returns:

A response object with three projections. dvm(buses=None) returns voltage-magnitude response. flow(monitored) returns from-end active-flow response. member_q(members=None) returns reactive-power response for voltage-regulating members. Each method returns a SensitivityMatrix with the same control columns. Columns contain taps, shunts, injections, shifters, and setpoints in that order. The object remains valid only while this snapshot is open.

Raises:

KeyError -- A requested branch, bus, or regulation target is not in the solved network.

vsf(buses=None, *, taps=(), shunts=(), injections=(), shifters=())#

Return voltage-magnitude sensitivity to selected controls.

Parameters:

buses -- Bus numbers to observe. None selects every solved bus.
taps -- Tap-changing transformer branch identities.
shunts -- Switched-shunt bus numbers.
injections -- (bus, reactive_mvar_per_active_mw) rows.
shifters -- Phase-shifting transformer branch identities.

Returns:

A matrix with observed buses as rows. Columns follow taps, shunts, injections, and shifters. Values are per-unit voltage change per unit tap ratio, Mvar, MW, or radian, respectively.

Raises:

KeyError -- A requested branch or bus is not in the solved network.

flow_response(monitored, *, taps=(), shunts=())#

Return active-flow sensitivity to tap and shunt controls.

Parameters:

monitored -- Branch identities to observe.
taps -- Tap-changing transformer branch identities.
shunts -- Switched-shunt bus numbers.

Returns:

A matrix with monitored branches as rows. Tap columns contain per-unit from-end active-flow change per unit tap ratio. Shunt columns contain per-unit from-end active-flow change per Mvar.

Raises:

KeyError -- A requested branch or bus is not in the solved network.

shift_angles(shifters)#

Return solved phase-shifter angles.

Parameters:: shifters -- Phase-shifting transformer branch identities.
Returns:: One angle in radians per input branch, in input order. Values use the interval (-pi, pi].
Raises:: KeyError -- A requested branch is not in the solved network.

class SensitivityMatrix(row_labels, col_labels, values)#

Store a labeled dense sensitivity matrix.

row_labels#

Physical identities in the order of values rows.

Type:: list[str]

col_labels#

Perturbation identities in the order of values columns.

Type:: list

values#

Two-dimensional floating-point array with shape (len(row_labels), len(col_labels)).

Type:: numpy.ndarray

as_dict()#: Return values as {row_label: {col_label: value}}.

solve_file(path, **overrides)#

Load and solve a case selected by its file-name suffix.

Parameters:

path -- Path to a supported case file.
overrides -- Options accepted by solve_power_flow(). These values override the input format defaults.

Returns:

The solved case.

class SolvePreset(var_limit_start='immediate', build=<factory>)#

Store the solver defaults for one input format.

var_limit_start#

Default time to start reactive-limit enforcement.

Type:: Literal['off', 'immediate', 'automatic']

build#

Default network-build option values.

Type:: collections.abc.Mapping[str, object]

gpf.RAW_PRESET: SolvePreset#

gpf.MATPOWER_PRESET: SolvePreset#

resolve_build_options(case, options=None, *, var_limit_start=None)#

Return the build options a lowering of case runs under.

options replaces the source format's build values. var_limit_start is the reactive-limit policy the build will be solved under; format-derived options take the format's policy when the caller names none. The Q-band demotion is applied once, under that policy.

parse_var_limit_mode(text)#

Normalize a reactive-limit enforcement mode.

Parameters:: text -- Case-insensitive mode name.
Returns:: "off", "immediate", or "automatic".
Raises:: ValueError -- If the value does not name a supported mode.

class SolvedCase(sbase, basfrq, bus_ids, vm, va, p_inj, q_inj, bus_types_final, gen_bus_ids, gen_machids, gen_p, gen_q, branch_from_bus_ids, branch_to_bus_ids, branch_ckts, p_from, q_from, p_to, q_to, p_loss, q_loss, vsc_dc_names, vsc_dc_bus1_ids, vsc_dc_bus2_ids, vsc_dc_p_conv1, vsc_dc_q_conv1, vsc_dc_p_conv2, vsc_dc_q_conv2, vsc_dc_i_dc, vsc_dc_p_loss, vsc_dc_v_dc1, vsc_dc_v_dc2, converged, iterations, control_reviews, max_mismatch, backend, solve_time_s=0.0, parse_time_s=0.0, warnings=(), step_history=(), exit_reason=PfExitReason.CONVERGED, gen_limit_binding=<factory>, statcom_limit_binding=<factory>, upfc_shunt_limit_binding=<factory>, vsc_limit_binding=<factory>, lcc_dc_names=<factory>, lcc_dc_rect_bus_ids=<factory>, lcc_dc_inv_bus_ids=<factory>, lcc_dc_p_rect=<factory>, lcc_dc_q_rect=<factory>, lcc_dc_p_inv=<factory>, lcc_dc_q_inv=<factory>, lcc_dc_i_d_pu=<factory>, lcc_dc_cos_alpha=<factory>, lcc_dc_cos_gamma=<factory>, lcc_dc_tap_r=<factory>, lcc_dc_tap_i=<factory>, lcc_dc_mode=<factory>, lcc_dc_limit_flags=<factory>, indmach_bus_ids=<factory>, indmach_machids=<factory>, indmach_p_draw=<factory>, indmach_q_draw=<factory>, indmach_slip=<factory>, indmach_stalled=<factory>, branch_rates=<factory>, rating_names=<factory>)#

Store an immutable power-flow solution.

Bus, generator, and branch identity arrays define the order of their result arrays. Power and voltage values use per-unit on sbase unless a field states another unit. Voltage angles use radians. Check converged before using equipment results from a failed solve. The result includes bus, generator, branch, supported device, convergence, and customer warning fields.

property status#: Return the convergence status as display text.

property n_limit_binding#: Return the number of regulators bound at a reactive limit.

property any_limit_binding#: Return whether any regulator reached its limit.

summary()#: Return convergence, size, loss, and binding-limit information.

get_bus_voltage(bus_id)#

Return a bus voltage as (magnitude_pu, angle_rad).

Parameters:: bus_id -- Bus number.
Raises:: KeyError -- If the solution does not contain the bus.

get_generator_q(bus_id, machid='1')#

Return a generator's reactive output in per unit.

Parameters:

bus_id -- Generator bus number.
machid -- Machine identifier.

Raises:

KeyError -- If the solution does not contain the generator.

to_dict()#: Return all stored and derived results as JSON-compatible values.

PfStepRecord#: alias of StepRecord

PfArgmaxResults#: alias of ArgmaxResults

PfArgmaxBin#: alias of ArgmaxBin

class UnsupportedPowerFlowCaseError(message, *, issues=())#

Report case features that prevent a power-flow solve.

The issues attribute contains the structured findings that produced the error message.