Diagnostics

analyze_case(case)

Analyze a GpfCase before normalization.

Does NOT mutate the case. Safe to call multiple times. Returns structured analysis for debugging convergence issues. Voltage-control semantics match what the solver applies.

Parameters:

case -- Parsed case (from parse_raw() or GpfCase.from_raw())

Returns:

CaseAnalysis with feature counts, resolved conflicts, and potential issues.

class CaseAnalysis(counts=<factory>, isolated_buses=<factory>, orphan_slack_buses=<factory>, control_model=None, extreme_taps=<factory>, low_impedance_branches=<factory>, has_unsupported_facts_modes=False)

Bases: object

Pre-build analysis of a GpfCase.

Inspects raw case data without normalization or spec building, using the same voltage control semantics as the solver.

counts

Inventory of feature counts.

Type:

gpf.FeatureCounts

isolated_buses

Buses with the isolated type code (IDE=4). This is the declared bus type, not a connectivity scan; a bus left without an in-service branch is not listed here.

Type:

list[int]

orphan_slack_buses

Buses declared as the swing bus (IDE=3) with no in-service generator, so they cannot set the system reference.

Type:

list[int]

control_model

Voltage-control claims and conflicts, or None until built.

Type:

gpf.VoltageControlReport | None

extreme_taps

(from, to, ckt, tap) for windings with a tap far from nominal (|tap - 1| > 0.2).

Type:

list[tuple[int, int, str, float]]

low_impedance_branches

(from, to, ckt, z) for branches whose series impedance is near zero (z < 1e-6).

Type:

list[tuple[int, int, str, float]]

has_unsupported_facts_modes

A FACTS device uses a control mode other than 0 or 1.

Type:

bool

property controllers_by_target

Map each regulated bus to every controller acting on it, local and remote. A locally regulating device is keyed under its own bus; a remote regulator is keyed under the bus named by its ireg field. More than one controller on a bus indicates a shared target (see conflicts).

issues_summary()

List of potential issues.

render_report(max_items=10)

Multi-line diagnostic report.

summary()

One-line summary.

class FeatureCounts(n_buses=0, n_isolated_buses=0, n_generators=0, n_generators_remote=0, n_generators_wind=0, n_loads=0, n_loads_zip=0, n_branches=0, n_transformers_2w=0, n_transformers_3w=0, n_tap_controls=0, n_phase_shift_controls=0, n_switched_shunts=0, n_switched_shunts_fixed=0, n_statcoms=0, n_upfcs=0, n_vsc_dc_lines=0, n_two_terminal_dc=0, n_two_terminal_dc_ccc=0)

Bases: object

Counts of features in the case.

n_isolated_buses

Buses with the isolated type code (IDE=4). This is the declared bus type, not a connectivity scan; a bus left without an in-service branch is not counted here.

Type:

int

n_generators_remote

Generators that regulate a remote bus (the regulated bus differs from the generator's own bus).

Type:

int

n_generators_wind

Generators in a wind control mode.

Type:

int

n_loads_zip

Loads with constant-current or constant-impedance parts.

Type:

int

n_tap_controls

Transformer windings that control voltage by tap.

Type:

int

n_phase_shift_controls

Transformer windings that control flow by phase shift.

Type:

int

n_switched_shunts

Switched shunts with an active control mode.

Type:

int

n_switched_shunts_fixed

Switched shunts locked at their initial value.

Type:

int

n_statcoms

FACTS devices in shunt (STATCOM) configuration.

Type:

int

n_upfcs

FACTS devices in series-shunt (UPFC) configuration.

Type:

int

n_two_terminal_dc

In-service two-terminal HVDC links.

Type:

int

n_two_terminal_dc_ccc

In-service two-terminal HVDC links with capacitor commutation, which is not supported.

Type:

int