GitHub

Function Reference

Sparlectra.Sparlectra — Module
Sparlectra 0.4.21

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.

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.

source
Sparlectra.Node — Type
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.
source
Sparlectra.Shunt — Type
Shunt

A mutable structure representing a shunt in a power system.

Fields

  • comp::AbstractComponent: The component of the shunt.
  • busIdx::Int: The index of the bus.
  • p_shunt::Float64: The active power of the shunt.
  • q_shunt::Float64: The reactive power of the shunt.
  • G_shunt::Float64: The conductance of the shunt.
  • B_shunt::Float64: The susceptance of the shunt.
  • y_pu_shunt::ComplexF64: The shunt admittance in per unit.
  • status::Int: The status of the shunt. 1 = in service, 0 = out of service.

Constructors

  • Shunt(; fromBus::Int, id::Int, base_MVA::Float64, vn_kV_shunt::Float64, p_shunt::Union{Nothing,Float64} = nothing, q_shunt::Union{Nothing,Float64} = nothing, g_shunt::Union{Nothing,Float64} = nothing, b_shunt::Union{Nothing,Float64} = nothing, ratio::Float64 = 1.0, status::Int = 1): Creates a new Shunt instance.

Methods

  • Base.show(io::IO, shunt::Shunt): Prints the Shunt instance.
source
Sparlectra.getLineRXBG — Method
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)
source
Sparlectra.get_line_parameters — Method
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)
source
Sparlectra.PowerTransformerTaps — Type
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.
source
Sparlectra.PowerTransformerWinding — Type
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.
source
Sparlectra.create3WTWindings! — Method
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)
source
Sparlectra.getNBI — Method
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()

source
Sparlectra.mdoRCM — Method
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()

source
Sparlectra.adjacentBranches — Function

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.
source
Sparlectra.calcNeutralU — Method
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)

source
Sparlectra.calcVKDependence — Method
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)

source
Sparlectra.createYBUS — Method
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).
source
Sparlectra.cubicSplineCoefs — Method
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)

source
Sparlectra.toPU_RXBG — Method
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)
source
Sparlectra.to_RXGB — Method
to_RXGB(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

to_RXGB(r_pu = 0.01, x_pu = 0.1, g_pu = 0.02, b_pu = 0.02, v_kv = 110.0, baseMVA = 100.0)
source
Sparlectra.calcNetLosses! — Method
calcNetLosses!(net::Net)

Calculates the network losses for the given network.

Arguments

  • net::Net: The network.

Example

```julia calcNetLosses!(net = network)

source
Sparlectra.runpf! — Function

Runs the power flow calculation using the Newton-Raphson method.

Arguments

  • net::Net: Network data structure.
  • maxIte::Int: Maximum number of iterations.
  • tolerance::Float64 = 1e-6: Tolerance for convergence (default: 1e-6).
  • verbose::Int = 0: Verbosity level (default: 0).

Returns

A tuple containing the number of iterations and the result of the calculation:

  • 0: Convergence reached.
  • 1: No convergence.
  • 2: Unsolvable system of equations.
  • 3: Error.
source
Sparlectra.clearIsolatedBuses! — Method
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)
source
Sparlectra.removeACLine! — Method
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")
source
Sparlectra.removeBranch! — Method
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)
source
Sparlectra.removeBus! — Method
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")
source
Sparlectra.removeTrafo! — Method
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")
source