Concepts

gpf uses the terms in this chapter to describe cases, controls, studies, and results. These definitions help you interpret a solution and follow the tutorials.

Power-flow sources

A power-flow source is a complete steady-state model of one network or a graph of connected networks. RAW, RAWX, and MATPOWER files produce a transmission GpfCase. OpenDSS files produce a phase-domain DssCircuit. A mixed-system manifest produces a PowerFlowSystemSpec with named regions and ports.

Each reader validates source syntax and identity before the solve. The representation-specific chapters define the electrical checks that follow.

Identity

Devices are addressed by power-system identity rather than by array position:

Representation	Stable identity
Transmission	Bus number with device identifier, or terminal buses with circuit identifier
OpenDSS	Object class and name; bus name and node number for electrical nodes
Mixed system	Region and port identities with source identities inside each region

Array indices belong to one load of one file and are not durable names.

This convention lets a schedule, coupling, contingency list, monitored set, or edit survive the insertion or removal of unrelated equipment. The study layer therefore uses source identities instead of positions.

The solved point

The power flow computes one steady-state operating point. The result contains the solved voltage state, device outputs, control states, and convergence status. The network representation determines the state and its units.

Input	Representation	Result
RAW, RAWX, or MATPOWER	Positive sequence	SolvedCase
OpenDSS	Phase domain	PhaseSolvedCase
Mixed-system manifest	Coupled named regions	CoupledSolvedSystem

The transmission, distribution, and mixed-system chapters define each solve contract and result.

Controls at the solution

A power network can contain devices whose settings depend on the solution. The operating point depends on each control state, and each control decision depends on the operating point.

gpf returns one operating point that satisfies the applicable control relations and network equations. The result reports controls that reach a limit, controls that use an approximation, and controls that cannot be represented. Device pages define each supported relation and its limit behavior.

What the solver does with a device

A case may name equipment the solver models exactly, equipment it models with a stated simplification, and equipment it cannot model at all. Which of these applies is reported rather than assumed, and every device family and control mode carries one of five outcomes.

Two of them mean the device shapes the solution. A device solved natively is carried with its supported model and control. A device solved with an approximation is carried with a simplification that is named in advance rather than discovered from the answer.

Two mean it does not. A device locked at its input keeps the state the file gave it and its control is not stepped: the tap does not move, the shunt does not switch. A rejected case is refused before the solve, rather than solved to a point that the file does not describe.

The fifth outcome covers a record with no power-flow effect, which is carried through parsing and writing and never enters the solution.

Each departure from as-modeled behavior carries a stable code, attached to the solution rather than printed and lost. A result is therefore self-describing: it states the approximations it rests on, and a test or an integration asserts on the code rather than on the message beside it.

Studies

A study is a reproducible statement of an analysis. It names a base case, a scope, a set of monitored elements, a set of contingencies, and the criteria against which the results are judged. Because every part of the definition uses power-system identity, the definition is itself a file, and rerunning it against a revised base case is a supported operation rather than a reconstruction.

Contingencies are evaluated from a common base operating point, and the set is solved as a batch rather than one case after another. A single power flow is the degenerate case: one scenario, no outage.

Screening a set of contingencies and reporting each point in detail are distinct operations. A screen answers whether any monitored element exceeds its limit; the detailed point is retained for the cases where that answer matters.

Results

Every result retains the source identities that define its numerical ordering. Reports present bus or node voltages, device outputs, flows, losses, violations, and solve status as named tables with explicit units.

Transmission results from related cases can be compared by device identity. The impact report therefore states each change per device instead of presenting two unrelated result tables.

Limits, violations, and margins

A limit is a bound that the operating point is required to respect: a thermal rating on a branch, a voltage band at a bus, a reactive capability on a machine. A violation is a monitored quantity that exceeds its limit at a solved point, reported together with the amount of the excess and the element that carries it.

A margin is the distance to the first violation along a direction of change. The direction distinguishes the studies: increasing transfer between a source and a sink gives a transfer margin, increasing load gives a loading margin, and increasing reactive demand at a bus gives a reactive margin. In each case two quantities are reported, the amount of change the system accepts and the element that binds first, of which the second is usually the more actionable.

Sensitivities

A sensitivity is the derivative of one quantity with respect to another at a given operating point: the change in a branch flow per unit change in injection, or per unit change in the status of another branch. Because a sensitivity is linear, it is cheap to evaluate, and a large candidate set can be ranked before any member of it is solved exactly.

The operating point at which the derivative is taken determines what the sensitivity is worth. Factors taken at a solved AC point account for the voltage profile and the reactive behavior present in that point, whereas factors taken at a DC approximation do not. In gpf the factors are taken at the solved point, so a linear screen and the exact solve that follows it describe the same system.