Transmission power flow

GPF solves balanced transmission networks with a positive-sequence power-flow formulation. RAW, RAWX, and MATPOWER sources produce a SolvedCase with bus, generator, branch, converter, control, and convergence results.

The Getting started chapter shows the shortest editable case workflow. This chapter defines the transmission solve contract and explains how to interpret its result. The modeling reference remains the source for device equations and input-field behavior.

Solve a transmission case

solve_file() selects the input parser from the file suffix and runs a one-shot solve. The following example is executed by the documentation test suite:

import gpf

solved = gpf.solve_file("../rawx/ieee14.rawx")

assert solved.converged
print(solved.summary())

Use load_case() before solve_power_flow() when the study must inspect or edit the source records. The CLI accepts the same files directly. The CLI reference defines output selection and solve overrides.

Understand the positive-sequence model

One transmission bus has one positive-sequence voltage magnitude and angle. The formulation represents a balanced fundamental-frequency operating point. Use a distribution power flow when phase unbalance, single-phase equipment, explicit neutrals, or conductor voltages must be retained.

Bus type determines which transmission quantities are specified and solved:

• A load bus specifies its net injection and solves voltage magnitude and angle.

• A regulating bus specifies active power and voltage magnitude and solves reactive power and angle.

• A swing bus holds voltage magnitude and angle and absorbs its island power balance.

Every energized island must contain a swing bus. GPF rejects a swingless island instead of assigning an arbitrary angle reference. The network-element models define bus, load, shunt, branch, and island behavior.

Understand starts and solve options

solve_power_flow() does not change the source GpfCase. Each one-shot call starts from the voltage, dispatch, tap, shunt, and device state supplied by that case. An ordered time-series power flow uses an explicit continuation sequence instead.

RAW and RAWX solution records can provide convergence defaults. Explicit Python or CLI options override the applicable file values. MATPOWER inputs retain their format-specific reactive-limit default. The modeling conventions define units, signs, convergence tolerance, and file-default precedence. The API reference defines every PfSolveOptions field.

Interpret convergence and controls

The Newton solve enforces complex-power balance at every active bus. max_mismatch reports the largest final bus mismatch in per unit, and iterations reports the Newton work. exit_reason identifies convergence or the condition that stopped the solve.

Equipment controls are reviewed with the electrical solution. Voltage regulators can reach reactive limits, transformer taps and phase shifters can move, switched shunts can change step, and supported converters can change operating mode. control_reviews reports the number of reviews, while the reported electrical state includes the accepted control actions. Binding-limit arrays identify voltage regulators that reached their limits.

The modeling pages define each control contract:

• Generators define voltage regulation and reactive limits.

• Transformers define tap and phase-shift controls.

• Switched shunts define discrete and continuous regulation.

• HVDC and FACTS models define converter modes and limits.

• Area interchange defines scheduled tie-flow control.

Read a transmission result

SolvedCase aligns every numerical array with explicit identity arrays. For example, bus_ids defines the order of vm, va, p_inj, and q_inj. Generator identity uses gen_bus_ids and gen_machids. Branch identity uses the from bus, to bus, and circuit arrays.

Power arrays use per unit on sbase, and voltage magnitudes use per unit on the bus base voltage. Voltage angles use radians. Rendered reports convert power to MW and Mvar and angles to degrees. A caller must check converged before it uses equipment results from a failed solve.

The Recipes show how to read bus and generator quantities, inspect the convergence trace, find binding reactive limits, and compare two solutions.

Render reports

render() selects Rich terminal output, plain text, HTML, or JSON from the destination. Automatic terminal detail shows all tables for small systems and reduces large-system output. The --full option requests all bus, generator, and branch tables, while --summary requests solve metadata only.

The report includes device-specific sections when the case contains those devices. LCC operating modes, angles, taps, and limit conditions remain available alongside the normal bus, generator, and branch tables.

Check and diagnose a transmission case

Automatic validation and the case doctor answer different questions. validate_case() runs before every transmission solve and reports unsupported, approximated, or fixed device behavior. The case doctor is an explicit check that combines source-file findings, model-support findings, network-preparation changes, and optional convergence diagnostics. It determines whether a case is fit for a study, not only whether it converges.

Every finding identifies its source:

Parse

The reader accepted the file but could not retain all its content. These values will not survive a save.

Case

validate_case() found a model or control capability condition in the source records.

Lowering

Network preparation changed or rejected part of the source representation. Examples include node consolidation and a controller that uses a supported fallback mode.

The following commands select how far the doctor proceeds:

gpf doctor case.raw
gpf doctor case.raw --level deep
gpf doctor case.raw --level full

The static level checks case data and model support. The deep level also checks the prepared network but does not solve it. The full level adds a power-flow solve and ranks likely causes of a convergence failure.

The report opens with its verdict, evidence, and recommended actions. Findings have stable IssueCode values, so tests and integrations can match a code without parsing its message. The --markdown and --json options provide portable report formats.

The doctor can apply safe repairs to a new file:

gpf doctor case.raw --fix -o repaired.raw

The command never writes over the input file. A repair that changes topology also requires --allow topology. The doctor checks the repaired case again and reports what remains.

A pipeline can select the findings that fail its gate:

gpf doctor case.raw --fail-on NO_VIABLE_SLACK,ISOLATED_BUS -q

Status 0 means that the requested gate passed. Status 1 means that it failed, and status 2 means that the doctor could not complete. The submission profile checks a case before handoff. The Case doctor reference lists every finding code, repair, and CLI option.