Mixed-system manifest reference#

The gpf.system/1 TOML schema defines an engineer-authored graph of named power-flow regions and explicit phase-sequence ports. The manifest loads into a PowerFlowSystemSpec and can be solved through the CLI or Python API.

Unknown fields and unknown schema versions are rejected. Region source paths must be relative to the manifest directory, which keeps a complete model directory portable.

Complete example#

The following manifest is loaded and solved by the documentation tests:

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

Root fields#

Field	Type	Required	Meaning
`schema`	string	Yes	Exact value `gpf.system/1`.
`name`	nonempty string	Yes	System identity used in results and reports.
`regions`	table	Yes	One or more named source regions.
`ports`	array of tables	For multi-region systems	Explicit phase-sequence couplings.
`solve`	table	No	Coupling and per-region solve options.

Every region in a multi-region system must participate in at least one port. Region identities and port identities must be unique.

Region fields#

Each [regions.IDENTITY] table accepts exactly two fields:

Field	Type	Meaning
`formulation`	string	`positive_sequence` or `phase`.
`source`	relative path	Source file loaded for this region.

A positive-sequence region accepts a format supported by load_case(). A phase region accepts an OpenDSS .dss source. GPF does not infer the formulation from the source suffix.

Port fields#

Each [[ports]] table defines one coupling:

Field	Type	Required	Meaning
`id`	nonempty string	Yes	Stable port identity.
`kind`	string	Yes	Exact value `phase_sequence`.
`scalar_region`	region identity	Yes	Positive-sequence endpoint.
`scalar_bus`	positive integer	Yes	Entered bus number in the scalar source.
`phase_region`	region identity	Yes	Phase-domain endpoint.
`phase_bus`	nonempty string	Yes	OpenDSS bus name.
`phase_nodes`	three positive integers	Yes	Ordered A, B, and C node numbers.
`neutral_node`	nonnegative integer	No	Active neutral node on `phase_bus`.
`closure`	string or table	Yes	Missing-sequence boundary closure.

phase_nodes must contain three distinct positive node numbers. An entered neutral must be distinct from the phase nodes and must resolve to an active electrical node. Ground node zero is not active and therefore should be omitted; phase topology retains normal grounding behavior.

Closure forms#

The compact balanced closure uses a string:

closure = "balanced_ideal"

This closure sets zero-sequence and negative-sequence boundary voltage to zero.

The Norton closure uses a nested table on the current port:

[ports.closure]
kind = "sequence_norton"
zero_admittance = [2.0, -1.0]
zero_current = [0.0, 0.0]
negative_admittance = [3.0, 1.0]
negative_current = [0.0, 0.0]

Every complex value is a finite [real, imaginary] array. All four Norton values are required.

Coupling options#

[solve.coupling] accepts these optional fields:

Field	Default	Constraint	Meaning
`max_iterations`	`20`	Positive integer	Coupled boundary iteration limit.
`tolerance`	`1e-7`	Positive finite number	Maximum normalized port residual.
`damping`	`1.0`	Greater than 0 and at most 1	Maximum boundary step.

Per-region options#

[solve.scalar.IDENTITY] accepts fields from PfSolveOptions. The identity must name a positive-sequence region.

[solve.phase.IDENTITY] accepts these fields:

Field	Default	Constraint	Meaning
`max_iterations`	`100`	Positive integer	Electrical iteration limit per pass.
`tolerance`	`1e-8`	Positive finite number	Maximum normalized Newton step.
`damping`	`1.0`	Greater than 0 and at most 1	Maximum line-search step.
`max_control_iterations`	`10`	Integer from 1 through 1024	Static-control pass limit.
`controls`	`true`	Boolean	Enable supported static controls.

An option table must match its region formulation. Omitted option tables use the normal formulation defaults.

Loading and solving#

import gpf

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

The manifest can also be passed directly to solve_file() or the CLI. A parse or validation error raises PowerFlowManifestError and identifies the invalid field location.