pwrs.corex.mpoption#

class pwrs.corex.mpoption.PfNrConfig(max_it: int = 10, lin_solver: str = '')[source]#

Bases: DataclassDictMixin

Parameters:

  • max_it (int)

  • lin_solver (str)

class pwrs.corex.mpoption.PfFdConfig(max_it: int = 30)[source]#

Bases: DataclassDictMixin

Parameters:

max_it (int)

class pwrs.corex.mpoption.PfGsConfig(max_it: int = 1000)[source]#

Bases: DataclassDictMixin

Parameters:

max_it (int)

class pwrs.corex.mpoption.PfRadialConfig(max_it: int = 20, vcorr: Literal[0, 1] = 0)[source]#

Bases: DataclassDictMixin

Parameters:

  • max_it (int)

  • vcorr (Literal[0, 1])

class pwrs.corex.mpoption.PfConfig(alg='NR', current_balance=0, v_cartesian=0, tol=1e-08, nr=<factory>, fd=<factory>, gs=<factory>, radial=<factory>, enforce_q_lims=0)[source]#

Bases: DataclassDictMixin

Power flow options.

Parameters:
alg#

AC power flow algorithm. Default is "NR". - "NR": Newton’s method (formulation depends on current_balance and v_cartesian) - "NR-SP": Newton’s method (power mismatch, polar) - "NR-SC": Newton’s method (power mismatch, cartesian) - "NR-SH": Newton’s method (power mismatch, hybrid) - "NR-IP": Newton’s method (current mismatch, polar) - "NR-IC": Newton’s method (current mismatch, cartesian) - "NR-IH": Newton’s method (current mismatch, hybrid) - "FDXB": Fast-Decoupled (XB version) - "FDBX": Fast-Decoupled (BX version) - "GS": Gauss-Seidel - "PQSUM": Power Summation method (radial networks only) - "ISUM": Current Summation method (radial networks only) - "YSUM": Admittance Summation method (radial networks only)

Type:

PfAlg

current_balance#

Type of nodal balance equation. Default is 0. - 0: use complex power balance equations - 1: use complex current balance equations

Type:

PfCurrentBalance

v_cartesian#

Voltage representation. Default is 0. - 0: bus voltage variables represented in polar coordinates - 1: bus voltage variables represented in cartesian coordinates - 2: hybrid, polar updates computed via modified cartesian Jacobian

Type:

PfVCartesian

tol#

Termination tolerance on per-unit P & Q mismatch. Default is 1e-8.

Type:

float

nr#

Newton method options. - max_it (int): maximum number of iterations for Newton’s method (default 10) - lin_solver (str): linear solver passed to MPLINSOLVE for Newton update step (default "") - "": default to "" for small systems, "LU3" for larger ones - "": built-in backslash operator - "LU": explicit default LU decomposition and back substitution - "LU3": 3-output LU, Gilbert-Peierls with AMD reordering - "LU4": 4-output LU, UMFPACK solver (same as "LU") - "LU5": 5-output LU, UMFPACK solver with row scaling

Type:

PfNrConfig

fd#

Fast-decoupled method options. - max_it (int): maximum number of iterations (default 30)

Type:

PfFdConfig

gs#

Gauss-Seidel method options. - max_it (int): maximum number of iterations (default 1000)

Type:

PfGsConfig

radial#

Radial power flow method options. - max_it (int): maximum number of iterations (default 20) - vcorr (Literal[0, 1]): perform voltage correction procedure (default 0) - 0: do not perform voltage correction - 1: perform voltage correction

Type:

PfRadialConfig

enforce_q_lims#

Enforce generator reactive power limits at expense of |V|. Default is 0. - 0: do not enforce limits - 1: enforce limits with simultaneous bus type conversion - 2: enforce limits with one-at-a-time bus type conversion

Type:

PfEnforceQLims

class pwrs.corex.mpoption.CpfPlotConfig(level: CpfPlotLevel = 0, bus: list[int] = <factory>)[source]#

Bases: DataclassDictMixin

Parameters:

  • level (CpfPlotLevel)

  • bus (list[int])

class pwrs.corex.mpoption.CpfConfig(parameterization=3, stop_at='NOSE', enforce_p_lims=0, enforce_q_lims=0, enforce_v_lims=0, enforce_flow_lims=0, step=0.05, adapt_step=0, step_min=0.0001, step_max=0.2, adapt_step_damping=0.7, adapt_step_tol=0.001, target_lam_tol=1e-05, nose_tol=1e-05, p_lims_tol=0.01, q_lims_tol=0.01, v_lims_tol=0.0001, flow_lims_tol=0.01, plot=<factory>, user_callback=None)[source]#

Bases: DataclassDictMixin

Continuation power flow options.

Attributes: parameterization (CpfParameterization): Choice of parameterization. Default is 3.

  • 1: natural

  • 2: arc length

  • 3: pseudo arc length

stop_at (CpfStopAt): Determines stopping criterion. Default is "NOSE".

  • "NOSE": stop when nose point is reached

  • "FULL": trace full nose curve

  • float: stop upon reaching specified target lambda value

enforce_p_lims (CpfBinaryFlag): Enforce generator active power limits. Default is 0.

  • 0: do not enforce limits

  • 1: enforce limits, simultaneous bus type conversion

enforce_q_lims (CpfBinaryFlag): Enforce generator reactive power limits at expense of |V|. Default is 0.

  • 0: do not enforce limits

  • 1: enforce limits, simultaneous bus type conversion

enforce_v_lims (CpfBinaryFlag): Enforce bus voltage magnitude limits. Default is 0.

  • 0: do not enforce limits

  • 1: enforce limits, termination on detection

enforce_flow_lims (CpfBinaryFlag): Enforce branch flow MVA limits. Default is 0.

  • 0: do not enforce limits

  • 1: enforce limits, termination on detection

step (float): Continuation power flow step size. Default is 0.05. adapt_step (CpfBinaryFlag): Toggle adaptive step size feature. Default is 0.

  • 0: adaptive step size disabled

  • 1: adaptive step size enabled

step_min (float): Minimum allowed step size. Default is 1e-4. step_max (float): Maximum allowed step size. Default is 0.2. adapt_step_damping (float): Damping factor for adaptive step sizing. Default is 0.7. adapt_step_tol (float): Tolerance for adaptive step sizing. Default is 1e-3. target_lam_tol (float): Tolerance for target lambda detection. Default is 1e-5. nose_tol (float): Tolerance for nose point detection in p.u. Default is 1e-5. p_lims_tol (float): Tolerance for generator active power limit enforcement in MW. Default is 0.01. q_lims_tol (float): Tolerance for generator reactive power limit enforcement in MVAR. Default is 0.01. v_lims_tol (float): Tolerance for bus voltage magnitude enforcement in p.u. Default is 1e-4. flow_lims_tol (float): Tolerance for line MVA flow enforcement in MVA. Default is 0.01. plot (CpfPlotConfig): Nose curve plotting options.

  • level (CpfPlotLevel): control plotting of nose curve (default 0)

  • 0: do not plot nose curve

  • 1: plot when completed

  • 2: plot incrementally at each iteration

  • 3: same as 2, with pause at each iteration

  • bus (list[int]): index of bus whose voltage is to be plotted (default empty)

user_callback (object | None): User callback specification. Default is None.

May be a function name string, a struct-like object with function name and optional priority and/or args, or a list of such entries.

Parameters:

  • parameterization (CpfParameterization)

  • stop_at (CpfStopAt)

  • enforce_p_lims (CpfBinaryFlag)

  • enforce_q_lims (CpfBinaryFlag)

  • enforce_v_lims (CpfBinaryFlag)

  • enforce_flow_lims (CpfBinaryFlag)

  • step (float)

  • adapt_step (CpfBinaryFlag)

  • step_min (float)

  • step_max (float)

  • adapt_step_damping (float)

  • adapt_step_tol (float)

  • target_lam_tol (float)

  • nose_tol (float)

  • p_lims_tol (float)

  • q_lims_tol (float)

  • v_lims_tol (float)

  • flow_lims_tol (float)

  • plot (CpfPlotConfig)

  • user_callback (object | None)

class pwrs.corex.mpoption.OpfAcConfig(solver: OpfAcSolver = 'DEFAULT')[source]#

Bases: DataclassDictMixin

Parameters:

solver (OpfAcSolver)

class pwrs.corex.mpoption.OpfDcConfig(solver: OpfDcSolver = 'DEFAULT')[source]#

Bases: DataclassDictMixin

Parameters:

solver (OpfDcSolver)

class pwrs.corex.mpoption.OpfSoftlimsConfig(default: OpfSoftlimsDefault = 1)[source]#

Bases: DataclassDictMixin

Parameters:

default (OpfSoftlimsDefault)

class pwrs.corex.mpoption.OpfPowerModelsConfig(formulation: PowerModelsFormulation = 'ACP', solver: PowerModelsSolver = 'DEFAULT', extensions: tuple[object, ...]=(), highs_options: dict[str, object]=<factory>, glpk_options: dict[str, object]=<factory>, clarabel_options: dict[str, object]=<factory>, scs_options: dict[str, object]=<factory>, mosek_options: dict[str, object]=<factory>)[source]#

Bases: DataclassDictMixin

Parameters:

  • formulation (PowerModelsFormulation)

  • solver (PowerModelsSolver)

  • extensions (tuple[object, ...])

  • highs_options (dict[str, object])

  • glpk_options (dict[str, object])

  • clarabel_options (dict[str, object])

  • scs_options (dict[str, object])

  • mosek_options (dict[str, object])

class pwrs.corex.mpoption.OpfConfig(backend='MATPOWER', power_models=<factory>, ac=<factory>, dc=<factory>, current_balance=0, v_cartesian=0, violation=5e-06, use_vg=0, flow_lim='S', ignore_angle_lim=0, softlims=<factory>, init_from_mpc=-1, start=0, return_raw_der=0)[source]#

Bases: DataclassDictMixin

Optimal power flow options.

Attributes: backend (OpfBackend): OPF implementation. Default is "MATPOWER".

  • "MATPOWER": use the MATPOWER-compatible OPF path

  • "POWER_MODELS": use the PowerModels-compatible formulation path

power_models (OpfPowerModelsConfig): PowerModels backend configuration.

  • formulation: network formulation, "ACP", "ACR", "ACT", "SOCWR", "DCP", "DCMP", "NFA", "DCPLL", "LPACC", "BFA", "SOCBF", "IVR", "QCRM", "QCLS", "SOCWRCONIC", "SOCBFCONIC", "SDPWRM", or "SPARSESDPWRM"

  • solver: "DEFAULT" selects by model capability, preferring HiGHS for LP/QP models, GLPK for LP fallback, and Ipopt for nonlinear models. Explicit "HIGHS", "GLPK", and "IPOPT" selections do not fall back. Default is "DEFAULT".

  • extensions: callable model extensions applied after formulation construction and before solver selection. Default is empty.

  • highs_options and glpk_options: native solver option mappings.

ac (OpfAcConfig): AC OPF solver options.

  • solver (OpfAcSolver): AC optimal power flow solver. Default is "DEFAULT".

  • "DEFAULT": choose pwrs default AC solver, currently "MIPS"

  • "MIPS": Pwrs Interior Point Solver

  • "FMINCON": MATLAB Optimization Toolbox fmincon

  • "IPOPT": IPOPT interface

  • "KNITRO": Artelys Knitro interface

  • "MINOPF": MINOS-based MINOPF package

  • "PDIPM": TSPOPF primal/dual interior point solver

  • "SDPOPF": semidefinite-relaxation OPF solver

  • "TRALM": trust-region augmented Lagrangian method

dc (OpfDcConfig): DC OPF solver options.

  • solver (OpfDcSolver): DC optimal power flow solver. Default is "DEFAULT".

  • "DEFAULT": choose based on availability, preferring commercial/open-source LP/QP solvers before "MIPS"

  • "MIPS": Pwrs Interior Point Solver

  • "BPMPD": BPMPD interface

  • "CLP": COIN-OR LP solver

  • "CPLEX": IBM CPLEX

  • "GLPK": GNU Linear Programming Kit

  • "GUROBI": Gurobi optimizer

  • "IPOPT": IPOPT interface

  • "MOSEK": MOSEK interface

  • "OSQP": OSQP interface

  • "OT": MATLAB Optimization Toolbox quadprog/linprog

current_balance (OpfCurrentBalance): Type of nodal balance equations. Default is 0.

  • 0: use complex power balance equations

  • 1: use complex current balance equations

v_cartesian (OpfVCartesian): Voltage representation. Default is 0.

  • 0: bus voltage variables represented in polar coordinates

  • 1: bus voltage variables represented in cartesian coordinates

violation (float): Constraint violation tolerance. Default is 5e-6. use_vg (float): How generator voltage setpoints affect bus voltage bounds. Default is 0.

  • 0: use bus Vmin and Vmax only, ignore generator Vg

  • 1: replace bus Vmin and Vmax with corresponding generator Vg

  • values between 0 and 1: use a weighted blend of the two behaviors

flow_lim (OpfFlowLim): Quantity constrained by branch flow limits. Default is "S".

  • "S": apparent power flow, in MVA

  • "P": active power flow, in MW

  • "2": squared active power flow, corresponding to MW limits

  • "I": current magnitude, in MVA at 1 p.u. voltage

ignore_angle_lim (OpfIgnoreAngleLim): Whether to ignore branch angle difference limits. Default is 0.

  • 0: include angle limits when specified

  • 1: ignore angle limits even if present

softlims (OpfSoftlimsConfig): Soft limit behavior.

  • default (OpfSoftlimsDefault): handling for soft limits without explicit settings. Default is 1.

  • 0: do not include unspecified soft limits

  • 1: include unspecified soft limits using default values

init_from_mpc (OpfInitFromMpc): Deprecated; use start instead. Default is -1.

Controls whether the current MATPOWER case state initializes the OPF. - -1: let MATPOWER decide based on solver/algorithm - 0: do not use current case state - 1: use current case state

start (OpfStart): OPF initialization strategy. Default is 0.

  • 0: default; MATPOWER chooses based on solver

  • 1: ignore current case state and use solver-specific interior initialization

  • 2: use current MATPOWER case state

  • 3: solve a power flow first and use that solution

return_raw_der (OpfReturnRawDer): For AC OPF, include raw constraint and derivative data in results.raw. Default is 0.

  • 0: do not return raw derivative info

  • 1: return g, dg, df and d2f in results.raw

Parameters:

  • backend (OpfBackend)

  • power_models (OpfPowerModelsConfig)

  • ac (OpfAcConfig)

  • dc (OpfDcConfig)

  • current_balance (OpfCurrentBalance)

  • v_cartesian (OpfVCartesian)

  • violation (float)

  • use_vg (float)

  • flow_lim (OpfFlowLim)

  • ignore_angle_lim (OpfIgnoreAngleLim)

  • softlims (OpfSoftlimsConfig)

  • init_from_mpc (OpfInitFromMpc)

  • start (OpfStart)

  • return_raw_der (OpfReturnRawDer)

class pwrs.corex.mpoption.OutLimConfig(all: OutLimAll = -1, v: OutLimDetail = 1, line: OutLimDetail = 1, pg: OutLimDetail = 1, qg: OutLimDetail = 1)[source]#

Bases: DataclassDictMixin

Parameters:

  • all (OutLimAll)

  • v (OutLimDetail)

  • line (OutLimDetail)

  • pg (OutLimDetail)

  • qg (OutLimDetail)

class pwrs.corex.mpoption.OutConfig(all=-1, sys_sum=1, area_sum=0, bus=1, branch=1, gen=0, lim=<factory>, force=0, suppress_detail=-1)[source]#

Bases: DataclassDictMixin

Output options.

Attributes: all: Controls pretty-printing of results. Default is -1.

Options:

  • -1: Individual flags control what prints.

  • 0: Do not print anything. Overrides individual flags, except for output written to files specified explicitly.

  • 1: Print everything. Overrides individual flags.

sys_sum: Print system summary. Default is 1.
Options:

  • 0: Do not print.

  • 1: Print.

area_sum: Print area summaries. Default is 0.
Options:

  • 0: Do not print.

  • 1: Print.

bus: Print bus detail. Default is 1.
Options:

  • 0: Do not print.

  • 1: Print.

branch: Print branch detail. Default is 1.
Options:

  • 0: Do not print.

  • 1: Print.

gen: Print generator detail. Default is 0.
Options:

  • 0: Do not print.

  • 1: Print.

lim: Constraint/limit output configuration. Default is an OutLimConfig.
Includes options for:
  • all: Overall control for constraint info output.

    • -1: Individual limit flags control what prints.

    • 0: Do not print constraint info.

    • 1: Print binding constraint info only.

    • 2: Print all constraint info.

  • v: Voltage limit info.

    • 0: Do not print.

    • 1: Print binding constraints only.

    • 2: Print all constraints.

  • line: Line flow limit info, using the same options as v.

  • pg: Generator active power limit info, using the same options as v.

  • qg: Generator reactive power limit info, using the same options as v.

force: Print results even if the success flag is 0. Default is 0.
Options:

  • 0: Do not force printing.

  • 1: Force printing.

suppress_detail: Suppress all output except the system summary. Default is -1.
Options:

  • -1: Suppress details automatically for large systems (more than 500 buses).

  • 0: Do not suppress any output enabled by other flags.

  • 1: Suppress all output except the system summary. Overrides individual flags, but not all = 1.

Parameters:

  • all (OutAll)

  • sys_sum (Literal[0, 1])

  • area_sum (Literal[0, 1])

  • bus (Literal[0, 1])

  • branch (Literal[0, 1])

  • gen (Literal[0, 1])

  • lim (OutLimConfig)

  • force (Literal[0, 1])

  • suppress_detail (OutBinaryOrAuto)

class pwrs.corex.mpoption.MipsScConfig(red_it: int = 20)[source]#

Bases: DataclassDictMixin

Parameters:

red_it (int)

class pwrs.corex.mpoption.MipsConfig(step_control=0, feastol=0, gradtol=1e-06, comptol=1e-06, costtol=1e-06, max_it=150, sc=<factory>, verbose=None, linsolver=None, cost_mult=None, xi=None, sigma=None, z0=None, alpha_min=None, rho_min=None, rho_max=None, mu_threshold=None, max_stepsize=None)[source]#

Bases: DataclassDictMixin

MIPS solver options.

Parameters:

  • step_control (Literal[0, 1])

  • feastol (float)

  • gradtol (float)

  • comptol (float)

  • costtol (float)

  • max_it (int)

  • sc (MipsScConfig)

  • verbose (int | None)

  • linsolver (MipsLinsolver | None)

  • cost_mult (float | None)

  • xi (float | None)

  • sigma (float | None)

  • z0 (float | None)

  • alpha_min (float | None)

  • rho_min (float | None)

  • rho_max (float | None)

  • mu_threshold (float | None)

  • max_stepsize (float | None)

step_control#

Enable step-size control. Default is 0. - 0: disabled - 1: enabled

Type:

Literal[0, 1]

linsolver#

Linear system solver. Default is "". - "" or "\": default SciPy solve - "LU3" variants or "SUPERLU": SciPy SuperLU - "LU", "LU4"/"LU5" variants or "UMFPACK": SuiteSparse UMFPACK - "PARDISO": Intel MKL PARDISO via PyPardiso - "KLU": SuiteSparse KLU via nbklu Missing optional solvers emit a warning and fall back to SciPy SuperLU.

Type:

MipsLinsolver

feastol#

Feasibility (equality) tolerance. Default is 0. If 0, it is set from opf.violation.

Type:

float

gradtol#

Gradient tolerance. Default is 1e-6.

Type:

float

comptol#

Complementarity (inequality) tolerance. Default is 1e-6.

Type:

float

costtol#

Optimality tolerance. Default is 1e-6.

Type:

float

max_it#

Maximum number of iterations. Default is 150.

Type:

int

sc#

Step-control options. - red_it (int): maximum number of reductions per iteration when step control is enabled (default 20)

Type:

MipsScConfig

xi#

Constant used in alpha updates. Default is None

Type:

float | None

sigma#

Centering parameter. Default is None

Type:

float | None

z0#

Initial slack variable value. Default is None

Type:

float | None

alpha_min#

Numerical-failure threshold for alpha parameters. Default is None

Type:

float | None

rho_min#

Lower bound on rho_t. Default is None

Type:

float | None

rho_max#

Upper bound on rho_t. Default is None

Type:

float | None

mu_threshold#

KT multipliers below this value for non-binding constraints are forced to zero. Default is None

Type:

float | None

max_stepsize#

Numerical-failure threshold for the 2-norm of the reduced Newton step. Default is None

Type:

float | None

class pwrs.corex.mpoption.IpoptConfig(opts: dict[str, object]=<factory>, opt_fname: str = '', opt: int = 0)[source]#

Bases: DataclassDictMixin

Parameters:

  • opts (dict[str, object])

  • opt_fname (str)

  • opt (int)

class pwrs.corex.mpoption.FminconConfig(alg: FminconAlg = 4, tol_x: float = 0.0001, tol_f: float = 0.0001, max_it: int = 0, opts: dict[str, object]=<factory>)[source]#

Bases: DataclassDictMixin

Parameters:

  • alg (FminconAlg)

  • tol_x (float)

  • tol_f (float)

  • max_it (int)

  • opts (dict[str, object])

class pwrs.corex.mpoption.KnitroConfig(tol_x: float = 0.0001, tol_f: float = 0.0001, maxit: int = 0, opts: dict[str, object]=<factory>, opt_fname: str = '', opt: int = 0)[source]#

Bases: DataclassDictMixin

Parameters:

  • tol_x (float)

  • tol_f (float)

  • maxit (int)

  • opts (dict[str, object])

  • opt_fname (str)

  • opt (int)

class pwrs.corex.mpoption.SysWideZipLoadsConfig(pw: tuple[float, float, float] | None = None, qw: tuple[float, float, float] | None = None)[source]#

Bases: DataclassDictMixin

Parameters:

  • pw (tuple[float, float, float] | None)

  • qw (tuple[float, float, float] | None)

class pwrs.corex.mpoption.ExpConfig(sys_wide_zip_loads: pwrs.corex.mpoption.SysWideZipLoadsConfig = <factory>)[source]#

Bases: DataclassDictMixin

Parameters:

sys_wide_zip_loads (SysWideZipLoadsConfig)

class pwrs.corex.mpoption.MatpowerConfig(v=21, model='AC', pf=<factory>, cpf=<factory>, opf=<factory>, verbose=1, out=<factory>, mips=<factory>, exp=<factory>, fmincon=<factory>, ipopt=<factory>, knitro=<factory>)[source]#

Bases: DataclassDictMixin

MATPOWER options struct.

Parameters:
v#

version number of MATPOWER options struct

Type:

int

verbose#
Type:

VerboseLevel

model#

AC vs. DC power flow model. Default is AC. - AC: use nonlinear AC model & corresponding algorithms/options - DC: use linear DC model & corresponding algorithms/options

Type:

ModelType

pf#

power flow options

Type:

PfConfig

cpf#

continuation power flow options

Type:

CpfConfig

opf#

optimal power flow options

Type:

OpfConfig

out#

output options controlling what results are returned

Type:

OutConfig

mips#

MIPS-specific options

Type:

MipsConfig

exp#

experimental features and options

Type:

ExpConfig

fmincon#

options for MATLAB Optimization Toolbox fmincon

Type:

FminconConfig

ipopt#

options for IPOPT solver, used when ‘opf.ac.solver’ or ‘opf.dc.solver’ is set to ‘IPOPT’

Type:

IpoptConfig

knitro#

options for the Artelys Knitro solver

Type:

KnitroConfig

pwrs.corex.mpoption.mpoption(*args)[source]#

Create or modify a MATPOWER options dict.

This function preserves the MATPOWER mpoption interface, supporting default construction, overrides by name/value pairs, merging from an existing options dict, and conversion to or from the legacy numeric options vector form.

However, for type safety, we recommend using the native Python interface by constructing and modifying a MatpowerConfig dataclass directly. The legacy interface is still supported for compatibility, but it is more error-prone and less efficient than using the dataclass API.

Parameters:

*args (Any) – MATPOWER option inputs. To create a default options dict, call with no arguments: mpoption(). To modify an existing options dict, use name/value pairs: mpoption(existing_opt, 'name', value, ...). The first argument may also be an existing options dict to merge with, or an old-style numeric options vector to convert from.

Returns:

The resulting MATPOWER options struct.

Return type:

MatpowerConfig