Build options

class PfBuildOptions(merge_zero_z_threshold=0.002, merge_zero_z_xfmr_threshold=0.0, gen_remote_regulation=True, gen_wind_handling=True, gen_regulator_admission=True, gen_regulator_min_q_range_mvar=1.0, gen_remote_regulator_min_coupling_pu=1.0, seed_q_init=True, load_zip=True, tap_control=True, phase_shift_control=True, switched_shunts=True, statcom=True, upfc=True, vsc_dc_lines=True, lcc_dc_lines=True)

Bases: object

Build-time options for power flow network construction.

Each flag controls whether a feature is compiled into the network spec. When False, the corresponding spec is omitted or simplified.

Note: 3-winding transformer expansion is NOT a build option. It is a topology-changing transform that must happen before normalization for the case to be solvable. Use the expand_3w_transformers parameter of solve_power_flow() instead.

merge_zero_z_threshold

Pre-normalization |Z| threshold (pu on system base) for merging zero-impedance branches and 2W transformers. Branches with |Z| below threshold and matching baskv are merged via union-find (the Z1 substation-split convention). Cross-baskv branches have their reactance inflated to the threshold floor instead. Set to 0.0 (or negative) to disable. Default 2e-3 captures large-production bus-split conventions at typical substation-Z magnitudes. 3-winding transformers are not touched.

Type:

float

gen_remote_regulation

When False, all generators use local voltage control (ireg forced to ibus). Remote voltage control claims are dropped.

Type:

bool

gen_wind_handling

When False, wind machines (wmod=1,2,3) are treated as normal generators with their raw qt/qb limits (no wpf interpretation).

Type:

bool

gen_regulator_admission

When True (default), PV generators with no practical Q authority (Q band below gen_regulator_min_q_range_mvar) or too-weak source-target reactive coupling for a remote target (path |B| below gen_remote_regulator_min_coupling_pu) are demoted to fixed-Q injections before solving, avoiding ill-conditioned regulator equations. Set False to admit every PV gen (legacy).

Type:

bool

gen_regulator_min_q_range_mvar

Minimum finite Q band (Mvar) for a PV generator to be admitted as a voltage regulator. Default 1.0.

Type:

float

gen_remote_regulator_min_coupling_pu

Minimum source-target series |B| (pu) for a remote regulator claim to be admitted. Default 1.0.

Type:

float

load_zip

When False, ZIP load components (ip, iq, yp, yq) are zeroed; only constant power (pl, ql) is retained.

Type:

bool

tap_control

When False, transformer tap controls (cod1=1 voltage, cod1=2 Mvar flow) are not built. Taps lock at the current windv1 value with no outer-loop tap adjustment.

Type:

bool

phase_shift_control

When False, phase shift controls (cod1=3) are not built. Phase angles lock at the current ang1 value with no outer-loop adjustment.

Type:

bool

switched_shunts

When False, switched shunts with modsw>0 are treated as fixed at BINIT with no outer-loop shunt adjustment.

Type:

bool

statcom

When False, STATCOM devices (FACTS with jbus=0, mode=1) are not built. Their Q injection is removed from the network.

Type:

bool

upfc

When False, UPFC devices (FACTS with jbus>0, mode=1) are not built. Their P/Q flow control is removed from the network.

Type:

bool

vsc_dc_lines

When False, VSC DC lines are not built. Their P injection and DC-side coupling are removed from the network.

Type:

bool

describe_disabled()

List of disabled feature names.

classmethod full()

All features enabled (default production mode).

classmethod minimal_nr()

Minimal Newton-Raphson: no outer-loop controls, no FACTS/HVDC.

Useful for debugging convergence issues. Solves the same topology but without discrete control adjustments or DC coupling.

classmethod no_facts_dc()

No FACTS devices or VSC-HVDC.

Pure AC network with all generator/transformer controls.

classmethod no_remote()

No remote voltage regulation from generators.

All generators control their local bus voltage. FACTS/HVDC retained.

class PfSolveOptions(max_iter=50, tol=1e-06, q_tol=1e-08, var_limit_start_outer_iter=0, ac_tap_adjust=None, lcc_dc_tap_adjust=None, phase_shift_adjust=None, swshunt_adjust=None, max_outer_iter=0, low_voltage_load_pu=0.0)

Bases: object

Numerical and control knobs for one pf_solve run.

max_iter

Maximum Newton-Raphson iterations.

Type:

int

tol

Convergence tolerance in pu.

Type:

float

q_tol

Tolerance for reactive-power limit saturation checks (generator and VSC mode-1).

Type:

float

var_limit_start_outer_iter

Outer-iteration index (0-based) at which reactive-limit enforcement begins. -1 = never; 0 = from the first outer pass (default); k = delay until outer pass k.

Type:

int

ac_tap_adjust

Inner-loop AC tap-changer gate. False disables; True/None leave it enabled. Explicit tri-state ints pass through.

Type:

bool | int | None

lcc_dc_tap_adjust

LCC HVDC TAPR/TAPI gate (same tri-state convention).

Type:

bool | int | None

phase_shift_adjust

Phase-shifter MW-flow gate (same convention).

Type:

bool | int | None

swshunt_adjust

Switched-shunt motion gate (same convention).

Type:

bool | int | None

max_outer_iter

Cap on outer control passes. 0 = unlimited (default); 1 = inner Newton only.

Type:

int

low_voltage_load_pu

Voltage (pu) below which constant-power load tapers toward zero. 0.0 (default) disables the taper.

Type:

float