Mixed-system power flow#

class PowerFlowRegion(id, source)#: Bind one region name to a transmission or distribution source model.

class PowerFlowSystemSpec(regions, couplings=(), name='system', solve_options=None)#: Define standalone or coupled regions and their explicit ports.

class BalancedIdealClosure(kind='balanced_ideal')#: Set zero- and negative-sequence boundary voltage to zero.

class SequenceNortonClosure(zero_admittance, zero_current, negative_admittance, negative_current, kind='sequence_norton')#: Supply zero- and negative-sequence Norton equivalents.

class PhaseSequencePort(id, scalar_region, scalar_bus, phase_region, phase_bus, phase_nodes, neutral_node, closure)#

Connect one named scalar region to one named phase region.

The port uses scalar-to-phase voltage orientation and positive current into the phase region. Compilation derives both electrical bases. Neutral grounding remains part of phase topology.

id#

Stable coupling identity.

Type:: gpf.PortId

scalar_region#

Positive-sequence region identity.

Type:: gpf.RegionId

scalar_bus#

Entered scalar bus number in that region.

Type:: int

phase_region#

Phase region identity.

Type:: gpf.RegionId

phase_bus#

OpenDSS bus name in the phase region.

Type:: str

phase_nodes#

Ordered A, B, and C OpenDSS node numbers.

Type:: tuple[int, int, int]

neutral_node#

Optional OpenDSS neutral-node number.

Type:: int | None

closure#

Required missing-sequence closure.

Type:: gpf.BalancedIdealClosure | gpf.SequenceNortonClosure

lift_voltage(positive_pu, phase_voltage_ln_base)#: Lift one positive-sequence voltage to A, B, and C volts.

project_current(phase_amperes, scalar_power_base, phase_voltage_ll_base)#: Project A, B, and C currents to positive-sequence per unit.

boundary_power(phase_voltage, phase_current)#: Return total three-phase boundary power in volt-amperes.

PortId(x, /)#: Identify one coupling port across source revisions.

RegionId(x, /)#: Identify one named power-flow region.

class PowerFlowManifestError#: Report one invalid mixed-system manifest.

gpf.SYSTEM_MANIFEST_SCHEMA: str#

load_power_flow_manifest(path)#

Load one versioned mixed-system TOML manifest.

Parameters:

path -- Path to the TOML manifest. Region paths are relative to it.

Returns:

A source graph for compile_power_flow_system().

Raises:

PowerFlowManifestError -- If the manifest violates its schema.
OSError -- If the manifest cannot be read.

class CouplingPortResult(id, positive_voltage_pu, positive_current_pu, scalar_power_pu, phase_power_va, power_residual_va)#

Store the final voltage, current, power, and balance for one port.

to_dict()#: Return one JSON-compatible port result.

class CouplingSolveStats(component_count, maximum_boundary_dimension, scalar_solves, phase_solves, boundary_factorizations, sensitivity_solves, control_reviews, allocation_bytes)#: Store work counters for one coupled solve.

class CoupledSolvedSystem(regions, ports, converged, iterations, maximum_port_residual, solve_time_s, stats, findings=(), name='system')#

Store named region solutions, port results, and convergence status.

to_dict()#: Return one JSON-compatible mixed-system result.

class CouplingSolveOptions(max_iterations=20, tolerance=1e-07, damping=1.0)#: Configure the coupled boundary Newton iteration.

class SystemSolveOptions(scalar=<factory>, phase=<factory>, coupling=<factory>)#: Store per-region formulation options and coupling options.

class CompiledPowerFlowSystem(regions, couplings=(), name='system')#

Store one prepared power-flow system for repeated solves.

property is_coupled#: Return whether the system contains coupling equations.

class CompiledPositiveSequenceRegion(id, source, spec, operating_points=(), basis='POS')#: Store one prepared positive-sequence region.

class CompiledPhaseRegion(id, spec, source=None, operating_points=(), basis='PHASE')#: Store one prepared phase-domain region.

class CompiledPhaseSequencePort(source, scalar_region, phase_region, scalar_bus, phase_nodes, neutral_node, scalar_power_base, phase_voltage_base)#

Store one validated phase-sequence port and its electrical bases.

property id#: Return the stable coupling identity.

property closure#: Return the explicit sequence closure.

compile_power_flow_system(source, *, options=None, member_costs=None)#

Prepare one standalone or mixed power-flow system.

Parameters:

source -- A transmission case, distribution circuit, phase-network specification, or named multi-region system.
options -- Transmission build options.
member_costs -- Optional member costs for transmission case expansion.

Returns:

A system that can create a PowerFlowSession or a time-series study.

Raises:

TypeError -- The source or one region has an unsupported type.
ValueError -- A coupling references an invalid bus, node, or region.

class PowerFlowSession(system, *, backend=None, verbose=False)#

Manage repeated solves for one prepared power-flow system.

finalize()#: Prepare every region and port for solving.

solve(*, options=None)#: Solve from source initial values and return full results.

reset_sequence()#: Make the next ordered advance start from source initial values.

advance(*, options=None, extract=True)#: Solve one ordered operating point from the prior accepted state.

run_schedule(schedule, *, options=None, retain='all', stop_on_failure=True)#

Run one compiled operating-point schedule through this session.

Parameters:

schedule -- Prepared operating-point updates in time order.
options -- Common system solve options for every step.
retain -- Full result retention mode.
stop_on_failure -- Stop after the first failed operating point.

Returns:

Ordered status and optional full solutions.

close()#: Release resources held by this session.

class SystemSolveOutcome(status, solution)#: Store solve status and an optional full solution.

class SystemSolveStatus(converged, iterations, max_port_residual, exit_reason, elapsed_s)#: Store convergence status without full network results.