Fault analysis (short circuit)#

solve_faults(case, faults=None, *, kinds=('3ph',), method='classical', prefault='flat', scale=1.0, tier='subtransient', variant='cmax', tmin=None, tk=1.0, zf=0j, zg=0j, contributions=None, zcorec=True, solved_sources='characteristic', backend=None)#

Calculate fault current for selected buses and fault types.

Parameters:

  • case -- Case with positive-, negative-, and zero-sequence data attached.

  • faults -- Faults to solve. None selects every bus. A sequence of bus numbers applies every value in kinds at those buses. A sequence of (bus, kind), (bus, kind, zf), or (bus, kind, zf, zg) rows defines each fault explicitly.

  • kinds -- Fault types for None or bus-number input. Values are "3ph" for three-phase, "slg" for single line-to-ground, "ll" for line-to-line, and "llg" for double line-to-ground.

  • method -- "classical" returns symmetrical-component results. "iec" adds IEC 60909 initial, peak, breaking, and thermal duty values.

  • prefault -- Classical pre-fault profile. "flat" uses machine EMFs behind their impedances. "uniform" sets every bus to the scaled voltage at zero angle. "solved" uses the solved power-flow operating point.

  • scale -- Voltage multiplier for "flat" and "uniform" pre-fault profiles. A nonpositive value selects 1.0 per unit.

  • tier -- Machine reactance tier. Use "subtransient" for first-cycle current, "transient" for transient current, or "synchronous" for sustained current.

  • variant -- IEC network variant. "cmax" calculates maximum current for equipment duty. "cmin" calculates minimum current for protection sensitivity.

  • tmin -- IEC minimum breaking time in seconds. None uses 0.1 seconds.

  • tk -- IEC thermal-equivalent fault duration in seconds.

  • zf -- Default complex fault impedance in per unit.

  • zg -- Default complex ground impedance in per unit. Explicit fault rows can override zf and zg.

  • contributions -- Faulted bus numbers that retain per-element current and post-fault voltage detail. "all" retains detail for every fault. None returns only the fault summary table. Contribution detail is available only for method="classical".

  • zcorec -- Apply transformer impedance-correction tables to classical zero-sequence leakage when true. IEC applies its prescribed correction model instead.

  • solved_sources -- Converter-source treatment for prefault="solved". "characteristic" uses converter current characteristics. "dispatch" uses solved complex output and requires the solved pre-fault profile.

  • backend -- Backend name or None for automatic selection.

Returns:

A FaultReport. Its fault table contains one row per requested fault with sequence and phase currents in per unit and kA, Thevenin impedances in per unit and ohms, and IEC duty columns when requested. Its optional contribution and voltage tables join to fault through the integer fault column.

Raises:

  • ValueError -- An option combination, fault type, or fault definition is invalid.

  • UnsupportedPowerFlowCaseError -- Required sequence data is missing or a solved pre-fault power flow does not converge.

Examples

Calculate three-phase and line-to-ground faults at two buses:

>>> report = gpf.solve_faults(
...     case, [101, 205], kinds=("3ph", "slg")
... )
>>> rows = report.as_tables()["fault"]
fault_delta(case_a, case_b, *, buses=None, kinds=('3ph', 'slg'), method='classical', prefault='flat', tier='subtransient', variant='cmax', threshold_pct=0.0, backend=None, label_a='base', label_b='current')#

Compare fault currents between two cases.

Parameters:

  • case_a -- Base case.

  • case_b -- Changed case.

  • buses -- Bus numbers to compare. None selects all common buses.

  • kinds -- Fault types to compare. Values are "3ph", "slg", "ll", and "llg".

  • method -- "classical" for symmetrical-component results or "iec" for IEC 60909 results.

  • prefault -- Classical pre-fault profile. Use "flat", "uniform", or "solved".

  • tier -- Machine reactance tier. Use "subtransient", "transient", or "synchronous".

  • variant -- IEC network variant, "cmax" or "cmin".

  • threshold_pct -- Percentage change that marks a row as exceeding.

  • backend -- Backend name or None for automatic selection.

  • label_a -- Display name for the base case.

  • label_b -- Display name for the changed case.

Returns:

A FaultDelta. Its delta table joins the cases by bus and fault type and reports baseline, current, absolute-change, percentage-change, status, and threshold fields. model_changes reports related case record changes.

Raises:

  • ValueError -- A fault option or bus selection is invalid.

  • UnsupportedPowerFlowCaseError -- Required sequence data is missing or a requested solved pre-fault power flow does not converge.

class FaultReport(method, prefault, tier, variant, sbase, fault, contribution, voltage, options, warnings, stats)#

Store a bus-fault sweep as a queryable result.

fault holds one row per fault (sequence + phase currents, per-sequence Thevenins, X/R, and IEC duty columns when applicable). contribution and voltage are populated only for the faults whose bus was requested for detail; they join to fault on the fault index column. The wire form contains the scalar header and these tables.

doc()#

Return the result document: the scalar header, with the column bindings for the row-tables, which live on the queryable slot and are queried in SQL.

as_tables()#

Row-tables for the SQL query surface: fault (per-fault currents, Thevenins, X/R, IEC duties), contribution (per-element currents into each detailed fault), voltage (per-bus post-fault voltages of the detailed faults). Empty tables are omitted.

classmethod column_quantities()#

Return the quantity each projected column binds, keyed by table then column. A current in per unit and the same current in kA are different quantities, and so are a Thevenin in per unit and in ohms.

to_markdown(path=None)#

Render the sweep summary (one line per fault) plus a home-bus block per detailed fault. The pu / physical / polar output flags stay carried on options for a consumer; this exhibit shows per-unit plus kA.

to_csv(path=None)#

The fault table as CSV (the sweep summary engineers import).

class FaultDelta(source_a, source_b, method, threshold_pct, delta, summary, model_changes, model_summary)#

Store fault-current changes between two cases.

delta contains baseline, current, absolute-change, and percentage-change values for each fault. model_changes describes the related case changes.

doc()#

Return the self-contained fault-delta document.

as_tables()#

The delta table: one row per (bus, kind) with baseline/current fault current and their difference and percent change.

classmethod column_quantities()#

Return the quantity each delta column binds, keyed by table then column. The two fault currents and their difference are currents; the percent change is its own quantity, because it measures a change and not a loading.

to_markdown(path=None)#

Return the fault-current difference as Markdown.