Transmission contingency analysis#

An N-1 study solves the base case and one scenario for each selected single-element outage. A branch N-1 study checks thermal limits by default. The command-line builder also checks each bus against its emergency voltage limits.

Default branch N-1 policy#

Study(case).sweep() applies this policy:

  • The outage set contains every in-service AC branch, transformer, and system switching device in the selected outage scope.

  • The thermal monitor contains every finalized in-service AC branch. An outage scope does not reduce the monitor scope. Flow can move outside the outage area after an outage.

  • The base condition and every contingency use exact rating slot 1.

  • The thermal threshold is 100 percent.

  • The case flags select MVA or current-basis loading.

  • A missing PSS/E rating makes the result incomplete.

gpf study n-1 CASE adds emergency voltage limits to the same thermal policy. Use --voltage-band LOW HIGH to replace those voltage limits with one common band.

The study file records the policy. A file with [[sweep]] family = "branch" gains the same thermal default when it is read. The only way to disable criteria is the explicit result_policy = "convergence_only" setting, or the matching --convergence-only command-line option.

Exact rating selection#

The base and contingency rating slots are independent. The solver reads only the selected slot. It never selects a different slot because the selected value is zero.

This TOML selects rating slot 1 for the base case and slot 3 for contingencies:

[study]
name = "summer N-1"
format = 5
base_case = "summer.raw"

[monitor]
voltage = { emergency_band = true }
thermal = { base_rating_set = 1, contingency_rating_set = 3, loading_basis = "case", missing_rating = "error" }

[[sweep]]
family = "branch"

The equivalent Python definition is:

from gpf.scenario import Study

result = (
    Study("summer.raw", name="summer N-1")
    .monitor(
        emergency_band=True,
        base_rating_set=1,
        contingency_rating_set=3,
        loading_basis="case",
        missing_rating="error",
    )
    .sweep()
    .run()
)

rating_set=N remains an explicit convenience in the Python API. It selects slot N for both conditions and uses MVA loading. It does not define a fallback chain.

Zero ratings#

Zero has source-format semantics:

  • In RAW, RAWX, and a programmatically constructed GpfCase, zero means that the selected PSS/E rating is missing. The default missing_rating = "incomplete" records the gap in coverage. missing_rating = "error" refuses the run before solving.

  • In MATPOWER, zero means that the branch has no thermal limit. The result counts the branch as unlimited. It does not count it as missing or test it for an overload.

The report always states the number of monitored, rated, missing, and unlimited branches. A zero in another rating slot has no effect on the selected slot.

MVA and current loading#

loading_basis = "case" reads XFRRAT for transformers and NXFRRAT for other AC branches. A positive flag selects current-basis loading. A zero flag selects MVA loading. Use "mva" or "current" to override the case flags.

MVA loading compares terminal apparent power directly with the selected rating. Current-basis loading converts the rating to a terminal MVA limit:

terminal limit MVA = selected rating * terminal voltage pu
loading percent = terminal MVA / terminal limit MVA * 100

The solver checks both ends and reports the governing terminal, its voltage, and its effective MVA limit.

Verdict and coverage#

Each result has one verdict:

  • pass means every declared scenario was evaluated, coverage is complete, and no selected criterion was violated.

  • fail means at least one thermal, voltage, or interface criterion was violated. A failure takes precedence over incomplete coverage.

  • incomplete means no known violation was found, but a selected rating is missing or a scenario was refused, did not converge, recovered by shedding, or could not evaluate a swing-machine trip. An unmonitored case interface also makes the result incomplete.

result.coverage identifies the result policy, checked criteria, scenario counts, rating coverage, and skipped interfaces. The Markdown and JSON reports carry the same values. The gpf study n-1 and gpf study run commands return status 0 only for pass. They return status 1 for fail and incomplete.

Other N-1 tools#

ATC, SCOPF, FTR, and interconnection screens use exact rating tiers too. Their default contingency_rating = "normal" uses RATE_A for every condition. Select "emergency" to use RATE_C after an outage. An unset RATE_C stays unset. The solver does not substitute RATE_A.