Network Model Reference

Sparlectra 0.8.7

Sparlectra is a Julia package for the calculation of electrical networks. It is designed to be used in the context of power system analysis and optimization.

• GitHub Repository: https://github.com/welthulk/Sparlectra.jl
• Website: https://welthulk.github.io/Sparlectra.jl

DiagnosticsConfig

Typed diagnostic-output configuration shared by examples and future modules.

MatpowerImportConfig

Typed MATPOWER import/example configuration for case selection and import conventions.

ObservabilityConfig

State-estimation observability diagnostic configuration.

OutputConfig

Typed output and logfile-format configuration. Console and logfile result streams are intentionally independent so example runners can disable classic logfile tables without suppressing compact console progress.

PerformanceConfig

Typed performance and diagnostic-volume configuration.

PowerFlowConfig

Typed power-flow configuration. It owns solver tolerances, sparse execution settings, automatic damping, start-mode controls, and Q-limit behavior.

QLimitConfig

Typed reactive-power limit switching configuration used by power-flow runners.

RuntimeConfig

Typed runtime/threading configuration for example and benchmark entry points.

SparlectraConfig

Central typed configuration assembled once at application or example boundaries. Module-specific sections own their parsing and validation through constructors such as PowerFlowConfig(raw) and MatpowerImportConfig(raw).

StartCurrentIterationConfig

Guarded fixed-point current-injection pre-solve configuration. The stage is disabled by default and, when enabled, only prepares the initial voltage profile before the normal rectangular Newton-Raphson solve.

StartModeConfig

Typed power-flow start-option configuration. These fields collect the flat-start and rectangular start-projection controls that otherwise tend to be forwarded as long keyword lists through example and benchmark call chains.

StateEstimationConfig

Typed state-estimation configuration for future SE runners and diagnostics.

configured_matpower_cases(config) -> Vector{String}

Return configured MATPOWER cases in deterministic execution order. A non-empty matpower.cases list takes precedence over the compatible single-case matpower.case setting.

print_effective_config([io], config::SparlectraConfig)

Print an Effective Sparlectra Configuration block with typed module sections.

refresh_sparlectra_config_file(path; write=false, backup=true, normalize_deprecated=true, default_path=DEFAULT_SPARLECTRA_CONFIG_PATH)

Compare a user YAML configuration with the current Sparlectra template, add missing keys from the template, and optionally normalize documented deprecated aliases. Dry-run mode returns the refreshed YAML without writing. Writes are explicit and create a timestamped backup unless backup=false is requested.

Node

A mutable structure representing a node in a power system.

Fields

• comp::AbstractComponent: The component of the node.
• busIdx::Integer: The index of the bus.
• _nodeType::NodeType: The type of the node.
• _ratedS::Union{Nothing,Float64}: The rated power of the node.
• _lZone::Union{Nothing,Integer}: The loss zone of the node.
• _area::Union{Nothing,Integer}: The area of the node.
• _vm_pu::Union{Nothing,Float64}: The voltage magnitude of the node in per unit.
• _va_deg::Union{Nothing,Float64}: The voltage angle of the node in degrees.
• _pƩLoad::Union{Nothing,Float64}: The total active power load at the node.
• _qƩLoad::Union{Nothing,Float64}: The total reactive power load at the node.
• _pShunt::Union{Nothing,Float64}: The total active power shunt at the node.
• _qShunt::Union{Nothing,Float64}: The total reactive power shunt at the node.
• _pƩGen::Union{Nothing,Float64}: The total active power generation at the node.
• _qƩGen::Union{Nothing,Float64}: The total reactive power generation at the node.
• _vmin_pu::Union{Nothing,Float64}: The minimum voltage magnitude at the node in per unit.
• _vmax_pu::Union{Nothing,Float64}: The maximum voltage magnitude at the node in per unit.

Constructors

• Node(; busIdx::Integer, vn_kV::Float64, nodeType::NodeType, ratedS::Union{Nothing,Float64} = nothing, zone::Union{Nothing,Integer} = nothing, area::Union{Nothing,Integer} = nothing, vm_pu::Union{Nothing,Float64} = nothing, va_deg::Union{Nothing,Float64} = nothing, pƩLoad::Union{Nothing,Float64} = nothing, qƩLoad::Union{Nothing,Float64} = nothing, pShunt::Union{Nothing,Float64} = nothing, qShunt::Union{Nothing,Float64} = nothing, pƩGen::Union{Nothing,Float64} = nothing, qƩGen::Union{Nothing,Float64} = nothing, vmin_pu::Union{Nothing,Float64} = nothing, vmax_pu::Union{Nothing,Float64} = nothing, isAux::Bool = false, oBusIdx::Union{Nothing,Int} = nothing, ): Creates a new Node instance.

Methods

• Base.show(io::IO, node::Node): Prints the Node instance.

getLineRXBG(o::ACLineSegment)::Tuple{Float64,Float64,Union{Nothing,Float64},Union{Nothing,Float64}}

Returns the resistance, reactance, susceptance, and conductance of an AC line segment. If the parameters are based on length, they are multiplied by the length of the line segment.

Arguments

• o::ACLineSegment: The AC line segment.

Returns

• r::Float64: The resistance of the AC line segment.
• x::Float64: The reactance of the AC line segment.
• b::Union{Nothing,Float64}: The susceptance of the AC line segment. It can be Nothing or a Float64 value.
• g::Union{Nothing,Float64}: The conductance of the AC line segment. It can be Nothing or a Float64 value.

Example

getLineRXBG(acLineSegment)

get_line_parameters(line::ACLineSegment)::Dict{Symbol,Any}

Returns a dictionary of the parameters of an AC line segment. If a parameter is nothing, it is replaced with 0.0.

Arguments

• line::ACLineSegment: The AC line segment.

Returns

• parameters::Dict{Symbol,Any}: A dictionary where the keys are the parameter names and the values are the parameter values.

Example

get_line_parameters(acLineSegment)

BusLink

Topological, impedance-less connection between two buses. Bus links are not part of the electrical branch model (YBUS). They are intended for post-power-flow KCL allocation, e.g. busbar couplers / sectionalizers.

PowerTransformerControl

Transformer outer-loop transformer controller channel.

PowerTransformerTaps

A mutable structure representing the tap settings of a power transformer.

Fields

• step::Int: The actual step/position.
• lowStep::Int: The lowest step/position.
• highStep::Int: The highest step/position.
• neutralStep::Int: The neutral step/position.
• voltageIncrement_kV::Float64: The voltage increment per step in kV.
• neutralU::Float64: The voltage at the neutral step, usually equal to the rated voltage of the transformer end, but can deviate.
• neutralU_ratio::Float64: The ratio of the neutral voltage to the rated voltage.
• tapStepPercent::Float64: The percentage change in voltage per step.
• tapSign::Integer: The direction of the tap changer, 1 for increasing voltage with increasing step, -1 for decreasing.

Constructors

• PowerTransformerTaps(; Vn_kV::Float64, step::Int, lowStep::Int, highStep::Int, neutralStep::Int, voltageIncrement_kV::Float64, neutralU::Union{Nothing,Float64} = nothing, neutralU_ratio::Union{Nothing,Float64} = nothing): Creates a new PowerTransformerTaps instance.

Methods

• Base.show(io::IO, x::PowerTransformerTaps): Prints the PowerTransformerTaps instance.

PowerTransformerWinding

A mutable structure representing a winding of a power transformer.

Fields

• Vn::Float64: The rated voltage of the winding in kV.
• r::Float64: The resistance of the winding in Ohm.
• x::Float64: The reactance of the winding in Ohm.
• b::Union{Nothing,Float64}: The susceptance of the winding in S.
• g::Union{Nothing,Float64}: The conductance of the winding in S.
• ratio::Union{Nothing,Float64}: The turns ratio of the winding.
• shift_degree::Union{Nothing,Float64}: The phase shift of the winding in degrees.
• ratedU::Union{Nothing,Float64}: The rated voltage of the winding.
• ratedS::Union{Nothing,Float64}: The rated power of the winding.
• taps::Union{Nothing,PowerTransformerTaps}: The tap settings of the winding.
• controls::Vector{PowerTransformerControl}: Controllers assigned to this winding side.
• isPu_RXGB::Union{Nothing,Bool}: Whether the resistance, reactance, susceptance, and conductance are given in per unit.
• modelData::Union{Nothing,TransformerModelParameters}: The model parameters of the transformer.
• _isEmpty::Bool: Whether the has no model data.

Constructors

• PowerTransformerWinding(Vn::Float64, r::Float64, x::Float64, b::Union{Nothing,Float64} = nothing, g::Union{Nothing,Float64} = nothing, ratio::Union{Nothing,Float64} = nothing, shift_degree::Union{Nothing,Float64} = nothing, ratedU::Union{Nothing,Float64} = nothing, ratedS::Union{Nothing,Float64} = nothing, taps::Union{Nothing,PowerTransformerTaps} = nothing, isPu_RXGB::Union{Nothing,Bool} = nothing, modelData::Union{Nothing,TransformerModelParameters} = nothing): Creates a new PowerTransformerWinding instance.
• PowerTransformerWinding(; Vn_kV::Float64, modelData::Union{Nothing,TransformerModelParameters} = nothing, ratio::Union{Nothing,Float64} = nothing, shift_degree::Union{Nothing,Float64} = nothing, ratedU::Union{Nothing,Float64} = nothing, ratedS::Union{Nothing,Float64} = nothing, taps::Union{Nothing,PowerTransformerTaps} = nothing): Creates a new PowerTransformerWinding instance.

Methods

• Base.show(io::IO, x::PowerTransformerWinding): Prints the PowerTransformerWinding instance.

create3WTWindings!(; u_kV::Array{Float64,1}, sn_MVA::Array{Float64,1}, addEx_Side::Array{TransformerModelParameters,1}, sh_deg::Array{Float64,1}, tap_side::Int, tap::PowerTransformerTaps)::Tuple{PowerTransformerWinding,PowerTransformerWinding,PowerTransformerWinding}

Creates windings for a three-winding transformer using the MVA method.

Arguments

• u_kV::Array{Float64,1}: The rated voltages of the windings in kV.
• sn_MVA::Array{Float64,1}: The rated powers of the windings in MVA.
• addEx_Side::Array{TransformerModelParameters,1}: The additional parameters for each side of the transformer.
• sh_deg::Array{Float64,1}: The phase shift of each winding in degrees.
• tap_side::Int: The number of the tap side [1,2,3]. It is 0 if there is no tap.
• tap::PowerTransformerTaps: The tap settings of the winding.

Returns

Returns a tuple of PowerTransformerWinding instances for the three windings of the transformer.

Example

create3WTWindings!(u_kV = [110.0, 20.0, 10.0], sn_MVA = [100.0, 80.0, 20.0], addEx_Side = [tmp1, tmp2, tmp3], sh_deg = [0.0, 0.0, 0.0], tap_side = 1, tap = tapSettings)

adjacentBranches: Find adjacent branches for each node in the network.

Parameters:

• Y::AbstractMatrix{ComplexF64}: Admittance matrix of the network.
• log::Bool = false: Optional parameter indicating whether to print the adjacent branches (default is false).

Returns:

• adjList::Vector{Vector{Int}}: Vector of vectors containing the indices of adjacent branches for each node.

branchFlow_pu(branch::Branch, from::Int, to::Int, tapSide::Int, V::Vector{ComplexF64})

Calculate branch flow in per unit for a given branch and voltage vector.

Arguments

• branch::Branch: The branch for which to calculate flow
• from::Int: From bus index
• to::Int: To bus index
• tapSide::Int: Tap side (1 or 2)
• V::Vector{ComplexF64}: Voltage vector in per unit

Returns

• ComplexF64: Branch flow in per unit

calcNeutralU(neutralU_ratio::Float64, vn_hv::Float64, tap_min::Integer, tap_max::Integer, tap_step_percent::Float64)::Float64

Calculates the neutral voltage of a transformer based on the given parameters.

Arguments

• neutralU_ratio::Float64: The ratio of the neutral voltage to the rated high voltage.
• vn_hv::Float64: The rated high voltage of the transformer.
• tap_min::Integer: The minimum tap position.
• tap_max::Integer: The maximum tap position.
• tap_step_percent::Float64: The percentage change in voltage per tap step.

Returns

• Float64: The calculated neutral voltage.

Example

```julia neutral_voltage = calcNeutralU(1.0, 110.0, -10, 10, 1.25)

calcVKDependence(xTaps::Vector{Int}, yVKs::Vector{Float64}, tapPos::Float64)::Float64

Calculates the voltage dependence on the tap position using cubic spline interpolation.

Arguments

• xTaps::Vector{Int}: A vector of tap positions.
• yVKs::Vector{Float64}: A vector of corresponding voltage values.
• tapPos::Float64: The current tap position for which the voltage is to be calculated.

Returns

• Float64: The interpolated voltage value at the given tap position.

Example

```julia xTaps = [1, 2, 3, 4, 5] yVKs = [1.0, 1.1, 1.2, 1.3, 1.4] tapPos = 2.5 voltage = calcVKDependence(xTaps, yVKs, tapPos)

createYBUS(branchVec::Vector{Branch}, shuntVec::Vector{Shunt}, isoNodes::Vector{Int}, sparse::Bool = true, printYBUS::Bool = false)

Creates the bus admittance matrix (YBUS) of the network.

Arguments

• branchVec::Vector{Branch}: The vector of branches in the network.
• shuntVec::Vector{Shunt}: The vector of shunts in the network.
• isoNodes::Vector{Int}: The vector of isolated nodes in the network.
• sparse::Bool: A flag to indicate if the YBUS matrix should be sparse. Default is true.
• printYBUS::Bool: A flag to indicate if the YBUS matrix should be printed. Default is false.

Returns

• Y::Matrix{ComplexF64}: The bus admittance matrix (YBUS).

cubicSplineCoefs(x::Vector{Float64}, y::Vector{Float64})::Tuple{Vector{Float64}, Vector{Float64}, Vector{Float64}, Vector{Float64}}

Calculates the coefficients of the cubic spline interpolation for the given data points.

Arguments

• x::Vector{Float64}: A vector of x-coordinates of the data points.
• y::Vector{Float64}: A vector of y-coordinates of the data points.

Returns

• a::Vector{Float64}: The coefficients for the cubic term.
• b::Vector{Float64}: The coefficients for the quadratic term.
• c::Vector{Float64}: The coefficients for the linear term.
• d::Vector{Float64}: The coefficients for the constant term.

Example

```julia x = [1.0, 2.0, 3.0, 4.0] y = [1.0, 4.0, 9.0, 16.0] a, b, c, d = cubicSplineCoefs(x, y)

fromPU_RXBG(r_pu::Float64, x_pu::Float64, g_pu::Union{Nothing,Float64} = nothing, b_pu::Union{Nothing,Float64} = nothing, v_kv::Float64, baseMVA::Float64)::Tuple{Float64,Float64,Float64,Float64}

Converts the resistance, reactance, conductance, and susceptance from per unit to physical units.

Arguments

• r_pu::Float64: The per unit resistance.
• x_pu::Float64: The per unit reactance.
• g_pu::Union{Nothing, Float64}: The per unit conductance. It can be Nothing or a Float64 value.
• b_pu::Union{Nothing, Float64}: The per unit susceptance. It can be Nothing or a Float64 value.
• v_kv::Float64: The voltage in kV.
• baseMVA::Float64: The base power in MVA.

Returns

• r::Float64: The resistance in Ohm.
• x::Float64: The reactance in Ohm.
• g::Float64: The conductance in S.
• b::Float64: The susceptance in S.

Example

fromPU_RXBG(r_pu = 0.01, x_pu = 0.1, g_pu = 0.02, b_pu = 0.02, v_kv = 110.0, baseMVA = 100.0)

toPU_RXGB(; r::Float64, x::Float64, g::Union{Nothing, Float64}=nothing, b::Union{Nothing, Float64}=nothing, v_kv::Float64, baseMVA::Float64)::Tuple{Float64, Float64, Float64, Float64}

Converts the resistance, reactance, conductance, and susceptance from physical units to per unit.

Arguments

• r::Float64: The resistance in Ohm.
• x::Float64: The reactance in Ohm.
• g::Union{Nothing, Float64}: The conductance in S. It can be Nothing or a Float64 value.
• b::Union{Nothing, Float64}: The susceptance in S. It can be Nothing or a Float64 value.
• v_kv::Float64: The voltage in kV.
• baseMVA::Float64: The base power in MVA.

Returns

• r_pu::Float64: The per unit resistance.
• x_pu::Float64: The per unit reactance.
• g_pu::Float64: The per unit conductance.
• b_pu::Float64: The per unit susceptance.

Example

toPU_RXGB(r = 0.01, x = 0.1, g = 0.02, b = 0.02, v_kv = 110.0, baseMVA = 100.0)

calcLinkFlowsKCL!(net::Net; tol::Float64 = 1e-6)

Compute bus-link active/reactive flows from nodal KCL after a power-flow run, without introducing links into the YBUS matrix. Link direction uses the fromBus -> toBus sign convention.

For each bus i: sum(Plink,out - Plink,in) = Pinj(i) - Pbranch,out(i) (and analog for Q).

Algorithm overview:

1. Build net nodal injections P_inj/Q_inj from static generation minus load.
2. Add solved shunt injections (node._pShunt/_qShunt) to nodal injections.
3. Subtract outgoing terminal branch powers to get the link right-hand side b.
4. Build oriented incidence matrix A for active links.
5. Solve per connected link component (BFS) using pinv(A_component) * b_component.
6. If sum(b_component) is not near zero, distribute the residual uniformly before solving so the component system becomes consistent.
7. Write resulting link P/Q flows and derive terminal currents from |S| and V_LL.

Notes:

• tol is only used for the component residual-balancing step.
• For meshed/singular components (e.g., rings), pinv yields the minimum-norm least-squares solution consistent with KCL.

calcNetLosses!(net::Net, V::Vector{ComplexF64})

Calculates branch flows and network losses using an externally provided complex voltage vector V (typically from the final NR residual).

calcNetLosses!(net::Net)

Calculates branch flows and network losses for the given network.

This default method builds the complex voltage vector internally and forwards to calcNetLosses!(net, V). If the NR solver already has V available, it can call the two-argument variant directly to avoid recomputing V.

active_set_q_limits!(
    net, it, nb;
    get_qreq_pu,
    is_pv,
    make_pq!,
    make_pv!,
    qmin_pu,
    qmax_pu,
    pv_orig_mask,
    allow_reenable::Bool,
    q_hyst_pu::Float64,
    cooldown_iters::Int,
    verbose::Int=0,
    io::IO=stdout,
) -> (changed::Bool, reenabled::Bool)

Core PV/Q-limit active-set logic shared by solvers.

Callbacks:

• getqreqpu(bus) -> Float64
• is_pv(bus) -> Bool
• makepq!(bus, qclamp_pu::Float64, side::Symbol) # side = :min/:max
• make_pv!(bus)
• onviolation!(bus, qreqpu::Float64, side::Symbol, qclamppu::Float64) -> Bool (optional; return true if violation was handled without PV->PQ fallback)

getQLimits_pu(net::Net) -> (qmin_pu, qmax_pu)

Return per-bus Q limits in p.u. (build once if empty).

Returns the last iteration number where bus hit a Q-limit, or nothing.

printFinalLimitValidation(net::Net; q_headroom::Float64=0.20, io::IO=stdout)

Prints post-PF validation tables for violated Q limits and voltage limits. Returns (q_violations, v_violations).

printPVQLimitsTable(net::Net; io::IO=stdout, max_rows::Int=30)

Print a compact table of PV-bus reactive limits before the PF iteration starts. Values are shown in MVAr.

printQLimitLog(net::Net; sort_by=:iter, io::IO=stdout)

Pretty-prints the structured Q-limit log (net.qLimitLog) as a small table.

Keyword arguments

• sort_by: :iter (default) or :bus — controls sorting.
• io: optional output stream (default = stdout).

Each line shows: where Side is :min or :max.

pv_hit_q_limit(net, pv_names)

Returns true if any of the PV buses from pv_names appears in net.qLimitEvents. pv_names is a list of bus names (strings).

validate_q_limit_signs!(qmin_pu, qmax_pu; io::IO=stdout, autocorrect::Bool=false, warn::Bool=true)

Validate Q-limit sign conventions per bus:

• expect qmin ≤ 0
• expect qmax ≥ 0
• expect qmin ≤ qmax

If autocorrect=true, suspicious sign-only limits are flipped and inverted ranges are swapped.

ACPFlowReport

Structured container for AC power flow results.

The vectors (nodes, branches, links, transformer_controls, q_limit_events) are table-like and can be converted directly to DataFrames if DataFrames.jl is available, e.g. DataFrame(report.nodes).

Fields

• metadata: Global run/case metadata (solver, tolerance, elapsed time, losses, ...).
• nodes: Per-bus electrical state and power balance values.
• branches: Per-branch directional flows and losses.
• links: Link-flow values from KCL post-processing.
• transformer_controls: Tap-controller state rows with typed missing for non-applicable engineering values.
• q_limit_events: PV→PQ limit-hit markers.

_build_transformer_control_rows(net::Net)

Internal helper that mirrors transformer control state into table-like rows for ACPFlowReport.

Notes:

• Rows are intentionally typed for DataFrame conversion.
• Non-applicable controller fields remain missing (not placeholder strings).

buildACPFlowReport(net::Net; ...)

Builds a structured report object from solved network data. This provides a machine-readable alternative to printACPFlowResults.

clearIsolatedBuses!(; net::Net)

Removes all isolated buses from the network.

Arguments

• net::Net: The network from which to remove isolated buses.

Returns

• Int: The number of isolated buses removed.

Example

clearIsolatedBuses!(net = network)

removeACLine!(; net::Net, fromBus::String, toBus::String)

Removes an AC line between two buses from the network.

Arguments

• net::Net: The network from which to remove the AC line.
• fromBus::String: The name of the bus where the line starts.
• toBus::String: The name of the bus where the line ends.

Returns

• Bool: True if the AC line was successfully removed, false otherwise.

Example

removeACLine!(net = network, fromBus = "Bus1", toBus = "Bus2")

removeBranch!(; net::Net, branchNr::Int)

Removes a branch from the network.

Arguments

• net::Net: The network from which to remove the branch.
• branchNr::Int: The number of the branch to remove.

Returns

• Bool: True if the branch was successfully removed, false otherwise.

Example

removeBranch!(net = network, branchNr = 1)

removeBus!(; net::Net, busName::String)

Checks if a bus could be removed from the network. Note: This function cannot actually remove the bus since Net is immutable, but it performs all validation checks.

Arguments

• net::Net: The network to check.
• busName::String: The name of the bus to check.

Returns

• Bool: True if the bus could be removed, false otherwise.

Example

removeBus!(net = network, busName = "Bus1")

removeTrafo!(; net::Net, fromBus::String, toBus::String)

Removes a transformer between two buses from the network.

Arguments

• net::Net: The network from which to remove the transformer.
• fromBus::String: The name of the bus where the transformer starts.
• toBus::String: The name of the bus where the transformer ends.

Returns

• Bool: True if the transformer was successfully removed, false otherwise.

Example

removeTrafo!(net = network, fromBus = "Bus1", toBus = "Bus2")