Function Reference

Sparlectra 0.4.35

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

Naming Conventions: The project follows the Julia Naming Conventions for the most part, but it's important to note that the naming convention for functions might deviate. In this module, functions are written in CamelCase with a lowercase initial letter.

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)

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.
• 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)

getNBI(nodeNumberVec, branchTupleVec)

Generates the Node-Branch Incidence (NBI) matrix for a given set of nodes and branches.

Arguments

• nodeNumberVec::Vector{Int}: A vector containing the node numbers.
• branchTupleVec::Vector{Tuple{Int, Int}}: A vector of tuples where each tuple represents a branch with the from and to bus numbers.

Returns

• NBI_matrix::Matrix{Int}: The Node-Branch Incidence matrix.

Example

see function testNBIMDO()

mdoRCM(n::Int, branchTupleVec::Vector{Tuple{Int, Int}})::Vector{Int}

Performs the Modified Reverse Cuthill-McKee (RCM) algorithm to reorder the nodes of a graph to reduce its bandwidth.

Arguments

• n::Int: The number of nodes in the graph.
• branchTupleVec::Vector{Tuple{Int, Int}}: A vector of tuples where each tuple represents a branch with the from and to bus numbers.

Returns

• order::Vector{Int}: A vector representing the new order of the nodes after applying the RCM algorithm.

Example

see function testNBIMDO()

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.

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)

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)

build_complex_jacobian(Ybus, V)

Builds the 2n × 2n Wirtinger-type Jacobian blocks for the complex-state Newton–Raphson formulation.

Given: I = Ybus * V S = V .* conj.(I)

We construct the blocks: J11 = ∂S/∂V J12 = ∂S/∂V* J21 = ∂conj(S)/∂V J22 = ∂conj(S)/∂V*

Returns: J11, J12, J21, J22 (all full matrices, not Diagonal)

build_rectangular_jacobian_pq_pv(
    Ybus,
    V,
    bus_types,
    Vset,
    slack_idx;
    use_sparse::Bool = false,
)

Dispatches to either the dense or sparse rectangular Jacobian builder matching mismatch_rectangular.

• If use_sparse == true and Ybus is a SparseMatrixCSC{ComplexF64}, the sparse builder is used.
• Otherwise, the dense builder is used.

build_rectangular_jacobian_pq_pv_dense(
    Ybus, V, bus_types, Vset, slack_idx
) -> J::Matrix{Float64}

Build the analytic rectangular Jacobian for the mismatch vector F(V) defined in mismatch_rectangular.

• State vector: x = [Vr(non-slack); Vi(non-slack)]
• Rows: for each non-slack bus i
  • PQ: [ΔPi; ΔQi]
  • PV: [ΔPi; ΔVi] with ΔVi = |Vi| - Vset[i]

bus_types and Vset must be consistent with mismatch_rectangular.

build_rectangular_jacobian_pq_pv_sparse(
    Ybus,
    V,
    bus_types,
    Vset,
    slack_idx,
) -> SparseMatrixCSC{Float64}

Builds the analytic rectangular Jacobian corresponding to mismatch_rectangular using the sparsity pattern of Ybus.

State vector: x = [Vr(non-slack); Vi(non-slack)] ∈ ℝ^(2(n-1))

Residual F(V): - PQ buses: ΔPi, ΔQi - PV buses: ΔPi, ΔVi - Slack bus: no equations

Jacobian entries are derived from Si(V) = Vi * conj( (Ybus * V)_i )

Wirtinger-based identities: ∂S/∂V = diag(conj(I)) + diag(V) * conj(Ybus) ∂S/∂V* = diag(V) * conj(Ybus)

Chain rule to rectangular: ∂S/∂Vr = ∂S/∂V + ∂S/∂V* ∂S/∂Vi = j(∂S/∂V - ∂S/∂V*)

With ΔPi = Re(ΔSi), ΔQi = Im(ΔSi), ΔVi = |Vi| - Vset[i].

Returns: J :: SparseMatrixCSC{Float64} with size (2(n-1)) × (2(n-1)).

complex_newton_step_rectangular(
    Ybus,
    V,
    S;
    slack_idx,
    damp,
    bus_types,
    Vset,
    use_sparse=false,
)

Performs one Newton–Raphson step in rectangular coordinates using the analytic Jacobian that matches mismatch_rectangular.

• State: x = [Vr(non-slack); Vi(non-slack)]
• Residual: F(x) = mismatch_rectangular(...)

mismatch_rectangular(Ybus, V, S, bus_types, Vset, slack_idx) -> F::Vector{Float64}

Compute the real-valued mismatch vector F(V) for the rectangular complex-state formulation with PQ and PV buses.

For each non-slack bus i:

• if bustypes[i] == :PQ: ΔPi = Re(Scalc[i]) - Re(Sspec[i]) ΔQi = Im(Scalc[i]) - Im(S_spec[i])

• if bustypes[i] == :PV: ΔPi = Re(Scalc[i]) - Re(Sspec[i]) ΔV_i = |V[i]| - Vset[i]

F is stacked as [ΔP2, ΔQ/ΔV2, ..., ΔPn, ΔQ/ΔVn] over all non-slack buses.

runpf!(net, maxIte, tolerance=1e-6, verbose=0; method=:polar_full)

Unified AC power flow interface.

Arguments:

• net::Net: network
• maxIte::Int: maximum iterations
• tolerance::Float64: mismatch tolerance
• verbose::Int: verbosity level
• method::Symbol: :polar_full (default) or :rectangular

Returns: (iterations::Int, status::Int)

where status == 0 indicates convergence.

runpf_rectangular!(net, maxIte, tolerance=1e-6, verbose=0)

Runs a rectangular complex-state Newton–Raphson power flow on net::Net.

Returns: (iterations::Int, status::Int) where status == 0 indicates convergence.

update_net_voltages_from_complex!(net, V)

Update the bus voltage magnitudes and angles in the network from the final complex voltages V (in per-unit).

complex_newton_step_rectangular_fd(
    Ybus,
    V,
    S;
    slack_idx::Int = 1,
    damp::Float64  = 1.0,
    h::Float64     = 1e-6,
    bus_types::Vector{Symbol},
    Vset::Vector{Float64},
) -> Vector{ComplexF64}

Performs one Newton–Raphson step in rectangular coordinates using a finite-difference Jacobian on the mismatch

F(V) = mismatch_rectangular(Ybus, V, S, bus_types, Vset, slack_idx)

which corresponds to a stacked vector of

• ΔP, ΔQ for PQ buses
• ΔP, ΔV for PV buses

over all non-slack buses.

Arguments:

• Ybus: bus admittance matrix (n×n, Complex)
• V: current complex bus voltage vector (length n)
• S: specified complex power injections P + jQ (length n)
• slack_idx: index of the slack bus (no equations / no variables)
• damp: scalar damping factor for the Newton step (0 < damp ≤ 1)
• h: perturbation step for finite differences
• bus_types: vector of bus types (:PQ, :PV, :Slack)
• Vset: voltage magnitude setpoints for PV buses

Returns:

• Updated complex voltage vector V_new (length n)

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")

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,
) -> (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)

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.

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)

Gibt true zurück, wenn einer der PV-Busse aus pv_names in net.qLimitEvents vorkommt.

pv_names ist eine Liste von Busnamen (Strings).

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.