PowerWorld

The PowerWorld is the high-level entry point for interacting with PowerWorld via ESA++. It wraps SimAuto with a Pythonic interface for case management, data access, and analysis helpers.

class PowerWorld(fname=None)[source]

Initialize the PowerWorld interface.

Parameters:: fname (str, optional) – Path to the PowerWorld case file (.pwb).

areas()[source]

Retrieve all area objects with all available fields.

Returns:: DataFrame – All defined fields for Area objects.

buscoords(astuple=True)[source]

Retrieve bus latitude and longitude from substation data.

Delegates to network.buscoords().

Parameters:: astuple (bool, default True) – If True, return (Longitude, Latitude) as a tuple of Series. If False, return a merged DataFrame.
Returns:: tuple of pd.Series or DataFrame – Bus geographic coordinates.

busmap()[source]

Create mapping from bus numbers to matrix indices.

Delegates to network.busmap().

Returns:: pd.Series – Series indexed by BusNum with positional index values.

close()[source]: Closes the current case.

edit_mode()[source]: Enter PowerWorld into EDIT mode.

flatstart()[source]: Resets the case to a flat start (1.0 pu voltage, 0.0 angle).

flows()[source]

Retrieve branch power flows and loading.

Returns:: DataFrame – Columns: LineMW, LineMVR, LineMVA, LinePercent, plus branch key fields.

gens()[source]

Retrieve generator outputs and status.

Returns:: DataFrame – Columns: GenMW, GenMVR, GenStatus, plus key fields.

jacobian(dense=False, form=JacobianForm.RECTANGULAR, ids=False)[source]

Get the power flow Jacobian matrix.

Parameters:

dense (bool, default False) – If True, return dense array. Else sparse CSR.
form (str, default 'R') – Coordinate form: ‘R’ (rectangular), ‘P’ (polar), ‘DC’ (B’).
ids (bool, default False) – If True, return (matrix, row_ids) with row/column labels.

Returns:

ndarray or scipy.sparse.csr_matrix – The power flow Jacobian matrix (when ids=False).
tuple – (matrix, row_ids) when ids=True.

lines()[source]

Retrieve all transmission lines (excluding transformers).

Returns:: DataFrame – All branch fields for branches with BranchDeviceType == "Line".

loads()[source]

Retrieve load demands and status.

Returns:: DataFrame – Columns: LoadMW, LoadMVR, LoadStatus, plus key fields.

lodf(branch, method=LinearMethod.DC)[source]

Calculate Line Outage Distribution Factors.

Parameters:

branch (tuple) – Branch key as (from_bus, to_bus, circuit).
method (str, default "DC") – Linear method: “DC” or “DCPS”.

Returns:

DataFrame – Branch LODF values (LineLODF column) plus key fields.

log(message)[source]

Add a message to the PowerWorld message log.

Parameters:: message (str) – The message text to append.

mismatch(asComplex=False)[source]

Return bus power mismatches.

Parameters:: asComplex (bool, default False) – If True, return P + jQ as complex Series.
Returns:: tuple of pd.Series or pd.Series – (P, Q) mismatches or complex S = P + jQ.

netinj(asComplex=False)[source]

Sum of all generator, load, bus shunt, and switched shunt P and Q.

Parameters:: asComplex (bool, default False) – If True, return P + jQ as complex array.
Returns:: tuple of ndarray or ndarray – (P, Q) or complex S = P + jQ.

overloads(threshold=100.0)[source]

Return branches exceeding a loading threshold.

Parameters:: threshold (float, default 100.0) – Percent loading threshold.
Returns:: DataFrame – Subset of flows() where LinePercent > threshold.

pflow(getvolts=True, method=SolverMethod.POLARNEWT)[source]

Solve Power Flow.

Parameters:

getvolts (bool, optional) – Return voltages after solving. Defaults to True.
method (str, optional) – Solution method. Defaults to “POLARNEWT”.

Returns:

pd.Series, tuple of pd.Series, or None – Complex voltage Series if getvolts=True (default), or None if getvolts=False.

print_log(clear=False, new_only=False)[source]

Prints the PowerWorld Message Log to the console.

Parameters:

clear (bool, optional) – If True, clears the log after printing. Defaults to False.
new_only (bool, optional) – If True, only prints new entries. Defaults to False.

Returns:

str – The log contents.

ptdf(seller, buyer, method=LinearMethod.DC)[source]

Calculate Power Transfer Distribution Factors.

Parameters:

seller (int) – Seller bus number.
buyer (int) – Buyer bus number.
method (str, default "DC") – Linear method: “DC”, “DCPS”, or “AC”.

Returns:

DataFrame – Branch PTDF values (LinePTDF column) plus key fields.

run_mode()[source]: Enter PowerWorld into RUN mode.

save(filename=None)[source]

Save the case to disk.

Parameters:: filename (str, optional) – Output file path. If None, overwrites the currently open case.

set_voltages(V)[source]

Set bus voltages from a complex vector.

Parameters:: V (ndarray) – Complex voltage vector (per-unit).

shunts()[source]

Retrieve switched shunt outputs and status.

Returns:: DataFrame – Columns: ShuntMW, ShuntMVR, ShuntStatus, plus key fields.

snapshot()[source]

Context manager that saves and restores case state.

Usage:

with pw.snapshot():
    pw[Gen, "GenMW"] = modified_gen
    pw.pflow()
    v = pw.voltage()
# state restored here

summary()[source]

Quick overview of the current case state.

Returns:: dict – Keys: n_bus, n_branch, n_gen, n_load, total_gen_mw, total_load_mw, v_min, v_max, sbase.

transformers()[source]

Retrieve all transformers (excluding lines).

Returns:: DataFrame – All branch fields for branches with BranchDeviceType == "Transformer".

ts_solve(ctgs, fields)[source]

Run transient stability simulation for the specified contingencies.

Handles auto-correction, initialization, solving each contingency, result retrieval, processing, and concatenation.

Parameters:

ctgs (Union[str, List[str]]) – A single contingency name or a list of names.
fields (List[str]) – Retrieval field strings (e.g., from TSWatch.prepare).

Returns:

Tuple[DataFrame, DataFrame] – (Metadata, Time-Series Data).

violations(v_min=0.9, v_max=1.1)[source]

Return bus voltage violations.

Parameters:

v_min (float, default 0.9) – Low voltage threshold (pu).
v_max (float, default 1.1) – High voltage threshold (pu).

Returns:

DataFrame – Columns ‘Low’ and ‘High’ with violating bus voltages.

voltage(complex=True, pu=True)[source]

Retrieve bus voltages.

Parameters:

complex (bool, default True) – If True, return complex voltage. Else (magnitude, angle_rad).
pu (bool, default True) – If True, per-unit. Else kV.

Returns:

pd.Series or tuple of pd.Series – If complex=True, a complex-valued Series V = |V| * exp(j*theta). If complex=False, a tuple (magnitude, angle_rad).

ybus(dense=False)[source]

Return the Y-Bus matrix.

Parameters:: dense (bool, default False) – If True, return dense array. Else sparse CSR.
Returns:: ndarray or scipy.sparse.csr_matrix – The system admittance matrix (n_bus x n_bus).

zones()[source]

Retrieve all zone objects with all available fields.

Returns:: DataFrame – All defined fields for Zone objects.

allow_mult_islands: Allow multiple island solutions.

check_phase_shifters: Check phase shifter adjustments.

check_shunts: Check switched shunt adjustments.

check_taps: Check transformer tap adjustments.

convergence_tol: Power flow convergence tolerance (float).

dc_mode: Enable DC power flow approximation mode.

disable_angle_rotation: Disable automatic angle rotation to slack bus.

disable_gen_mvr_check: Disable generator MVR limit checking.

disable_opt_mult: Disable optimal multiplier acceleration.

do_one_iteration: Solve only one Newton iteration per call.

enforce_gen_mw_limits: Enforce generator MW output limits.

eval_solution_island: Evaluate solution quality per island.

flat_start: Start from flat voltage profile (1.0 pu, 0 deg).

inner_backoff_gen_vars: Back off generator VAR limits in inner loop.

inner_check_gen_vars: Check generator VAR limits in inner loop.

inner_ss_check: Check switched shunt/contingency controls in inner loop.

max_iterations: Maximum Newton-Raphson iterations (int).

max_vcl_iterations: Maximum voltage-constrained loop iterations (int).

min_volt_i_load: Minimum voltage for constant-current loads (float, pu).

min_volt_s_load: Minimum voltage for constant-impedance loads (float, pu).

property n_branch: Number of branches in the case.

property n_bus: Number of buses in the case.

property n_gen: Number of generators in the case.

prevent_oscillations: Prevent control oscillations.

property sbase: System MVA base.

Embedded Analysis Modules

PowerWorld hosts three embedded analysis modules that share the parent’s SimAuto connection:

`pw.network`	Network topology analysis (incidence, Laplacian, paths). See `Network`.
`pw.gic`	GIC calculations and sensitivity. See `GIC`.
`pw.buscat`	Bus type classification for Jacobian structure. See `BusCat`.

pw = PowerWorld("case.pwb")
pw.pflow()

bc = pw.buscat.refresh()
pv_buses = bc.pv_idx()
v_set = bc.v_setpoints()

Descriptors

Lightweight descriptor classes that map Python attributes to PowerWorld option fields. Used by PowerWorld for solver options and by GIC for GIC analysis options.

class SolverOption(key, is_bool=True)[source]: Descriptor mapping a Python attribute to a Sim_Solution_Options field.

class GICOption(key, is_bool=True)[source]: Descriptor mapping a Python attribute to a GIC_Options_Value entry.