Mixed transmission-distribution power flow#

A mixed transmission-distribution power flow combines named positive-sequence and phase-domain regions through explicit phase-sequence ports. The same system API also represents a standalone transmission or distribution system.

Understand the sequence boundary#

Let a = exp(j 2 pi / 3). Every port uses the following Fortescue convention:

\[\begin{split}\begin{aligned} V_a &= V_0 + V_1 + V_2, \\ V_b &= V_0 + a^2 V_1 + a V_2, \\ V_c &= V_0 + a V_1 + a^2 V_2, \\ I_1 &= (I_a + a I_b + a^2 I_c)/3. \end{aligned}\end{split}\]

The transmission side owns positive-sequence voltage and total three-phase power. The phase side owns conductor voltage and current. The following identity defines the port normalization:

\[S_{abc}=\sum_{p\in\{a,b,c\}}V_p I_p^* =3\sum_{s\in\{0,1,2\}}V_s I_s^*.\]

Positive-sequence voltage does not determine V0 or V2. Therefore, every port requires one of these closures:

balanced_ideal

The boundary sets V0 = V2 = 0. The phase boundary source supplies the corresponding sequence currents.

sequence_norton

The port supplies explicit zero-sequence and negative-sequence Norton admittances and currents.

No closure is inferred from a source suffix or network appearance.

Define regions and ports#

PowerFlowSystemSpec contains named PowerFlowRegion objects and their PhaseSequencePort couplings. A positive-sequence region accepts a transmission case, while a phase region accepts a DssCircuit or PhaseNetworkSpec.

Every port declares the following source identities:

  1. A positive-sequence region and its entered transmission bus number.

  2. A phase region and its OpenDSS bus name.

  3. Ordered OpenDSS node numbers for phases A, B, and C.

  4. An optional active neutral node on the same phase bus.

  5. An explicit zero-sequence and negative-sequence closure.

GPF resolves these identities and derives the transmission power base and phase voltage base. A user does not enter either base a second time.

Use a system manifest#

TOML provides the recommended engineer-authored representation. Region paths are relative to the manifest, which permits a complete model directory to be moved without rewriting its region paths.

The following manifest is loaded and solved by the documentation test suite:

schema = "gpf.system/1"
name = "transmission with one feeder"

[regions.tx]
formulation = "positive_sequence"
source = "../rawx/ieee14.rawx"

[regions.feeder]
formulation = "phase"
source = "feeder/Master.dss"

[[ports]]
id = "tx-feeder"
kind = "phase_sequence"
scalar_region = "tx"
scalar_bus = 4
phase_region = "feeder"
phase_bus = "sourcebus"
phase_nodes = [1, 2, 3]
closure = "balanced_ideal"

[solve.coupling]
max_iterations = 20
tolerance = 1e-7
damping = 1.0

[solve.scalar.tx]
max_iter = 50
tol = 1e-8

[solve.phase.feeder]
max_iterations = 100
tolerance = 1e-8
max_control_iterations = 10
controls = true

The manifest is solved through either CLI form:

gpf system.toml
gpf solve system.toml --full
gpf system.toml --json

The exact schema is defined in the mixed-system manifest reference.

Use the Python API#

load_power_flow_manifest() returns the same PowerFlowSystemSpec that can be constructed programmatically. The following example uses the one-shot solve path and then reads both formulations and the coupling result:

import gpf

system = gpf.load_power_flow_manifest("system.toml")
solved = gpf.solve_power_flow(system)

assert solved.converged
transmission = solved.regions[gpf.RegionId("tx")]
feeder = solved.regions[gpf.RegionId("feeder")]
port = solved.ports[0]
print(transmission.converged, feeder.converged, port.power_residual_va)

A persistent workflow prepares the graph once and supports repeated solves:

compiled = gpf.compile_power_flow_system(system)
with gpf.PowerFlowSession(compiled) as session:
    session.finalize()
    outcome = session.solve()
    solved = outcome.solution

solve_power_flow() returns the formulation result directly for a one-shot solve. PowerFlowSession.solve() returns SystemSolveOutcome, which separates compact status from optional full result extraction.

Understand coupled solution and controls#

The solver updates all connected regions until the regional equations and port power balance converge. A phase control action first settles the affected phase region. GPF then verifies the complete connected system before it accepts the control state.

One compiled system can contain multiple transmission regions, multiple phase regions, and multiple connected components. Each component contains only its incident ports. A standalone region uses the same public workflow without a port.

Read a mixed result#

CoupledSolvedSystem.regions maps each RegionId to its formulation result. Positive-sequence regions return SolvedCase, and phase regions return PhaseSolvedCase.

Each CouplingPortResult reports:

  • Positive-sequence voltage and current in per unit.

  • Transmission-side complex power in per unit.

  • Phase-side complex power in volt-amperes.

  • Complex power residual in volt-amperes.

maximum_port_residual reports the largest normalized coupling residual. stats provides solve-work counters for performance review. These counters do not replace electrical convergence criteria.