GitHub

Function Reference

Sparlectra.Sparlectra — Module
Sparlectra 0.4.18

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.Branch — Type
Branch

A mutable structure representing a branch in a power system.

Fields

  • comp::AbstractComponent: The component of the branch.
  • fromBus::Integer: The index of the bus where the branch starts.
  • toBus::Integer: The index of the bus where the branch ends.
  • r_pu::Float64: The per unit resistance of the branch.
  • x_pu::Float64: The per unit reactance of the branch.
  • b_pu::Float64: The per unit total line charging susceptance of the branch.
  • g_pu::Float64: The per unit total line charging conductance of the branch.
  • ratio::Float64: The transformer off nominal turns ratio.
  • angle::Float64: The transformer off nominal phase shift angle.
  • status::Integer: The status of the branch. 1 = in service, 0 = out of service.
  • sn_MVA::Union{Nothing,Float64}: The nominal power of the branch = rateA.
  • fBranchFlow::Union{Nothing,BranchFlow}: The flow from fromNodeID to toNodeID.
  • tBranchFlow::Union{Nothing,BranchFlow}: The flow from toNodeID to fromNodeID.
  • pLosses::Union{Nothing,Float64}: The active power losses.
  • qLosses::Union{Nothing,Float64}: The reactive power losses.

Constructors

  • Branch(; from::Int, to::Int, baseMVA::Float64, branch::AbstractBranch, id::Int, status::Integer = 1, ratio::Union{Nothing,Float64} = nothing, side::Union{Nothing,Int} = nothing, vn_kV::Union{Nothing,Float64} = nothing, fromOid::Union{Nothing,Int} = nothing, toOid::Union{Nothing,Int} = nothing): Creates a new Branch instance.

Methods

  • Base.show(io::IO, b::Branch): Prints the Branch instance.
source
Sparlectra.BranchFlow — Type
BranchFlow

A structure representing the flow in a branch of a power system.

Fields

  • vm_pu::Union{Nothing,Float64}: The voltage magnitude in per unit.
  • va_deg::Union{Nothing,Float64}: The voltage angle in degrees.
  • pFlow::Union{Nothing,Float64}: The active power flow.
  • qFlow::Union{Nothing,Float64}: The reactive power flow.

Constructors

  • BranchFlow(vm_pu::Union{Nothing,Float64} = nothing, va_deg::Union{Nothing,Float64} = nothing, pFlow::Union{Nothing,Float64} = nothing, qFlow::Union{Nothing,Float64} = nothing): Creates a new BranchFlow instance.

Methods

  • Base.show(io::IO, b::BranchFlow): Prints the BranchFlow instance.

Example

BranchFlow(vm_pu = 1.0, va_deg = 0.0, pFlow = 100.0, qFlow = 50.0)
source
Sparlectra.BranchModel — Type
BranchModel

A structure representing a branch model in a power system.

Fields

  • r_pu::Float64: The per unit resistance of the branch.
  • x_pu::Float64: The per unit reactance of the branch.
  • b_pu::Float64: The per unit total line charging susceptance of the branch.
  • g_pu::Float64: The per unit total line charging conductance of the branch.
  • ratio::Float64: The transformer off nominal turns ratio.
  • angle::Float64: The transformer off nominal phase shift angle.
  • sn_MVA::Union{Nothing,Float64}: The nominal power of the branch = rateA.

Constructors

  • BranchModel(; r_pu::Float64, x_pu::Float64, b_pu::Float64, g_pu::Float64, ratio::Float64, angle::Float64, sn_MVA::Union{Nothing,Float64} = nothing): Creates a new BranchModel instance.

Example

BranchModel(r_pu = 0.01, x_pu = 0.1, b_pu = 0.02, g_pu = 0.02, ratio = 1.0, angle = 0.0, sn_MVA = 100.0)
source
Sparlectra.Component — Type
Component

A structure representing a component in a power system.

Fields

  • cID::String: The ID of the component.
  • cName::String: The name of the component.
  • cTyp::ComponentTyp: The type of the component.
  • cVN::Float64: The nominal voltage of the component in kV.

Constructors

  • Component(id::String, name::String, typ::ComponentTyp, vn::Float64): Creates a new Component instance with a specified nominal voltage.
  • Component(id::String, name::String, typ::ComponentTyp): Creates a new Component instance with a nominal voltage of 1 kV.
  • Component(id, name, cmp::String, Unenn::Float64): Creates a new Component instance with a specified nominal voltage and component type as a string.

Methods

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

Example

Component("1", "Generator", "GENERATOR", 110.0)
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.getRXBG — Method
getRXBG(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

getRXBG(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.ACLineSegment — Type
ACLineSegment

A mutable structure representing an AC line segment in a power system.

Fields

  • comp::AbstractComponent: The component of the AC line segment.
  • length::Float64: The length of the AC line segment.
  • 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.
  • c_nf_per_km::Union{Nothing,Float64}: The capacitance per kilometer of the AC line segment. It can be Nothing or a Float64 value.
  • tanδ::Union{Nothing,Float64}: The tangent of the loss angle of the AC line segment. It can be Nothing or a Float64 value.
  • ratedS::Union{Nothing,Float64}: The rated power of the AC line segment. It can be Nothing or a Float64 value.
  • paramsBasedOnLength::Bool: A boolean indicating whether the parameters are based on the length of the AC line segment, if false, the parameters (r,x,g,b) have to multiply by length.
  • _isPIModel::Bool: A boolean indicating whether the AC line segment is a PI model, all parameters are p.u. .

Constructors

  • ACLineSegment(; vn_kv::Float64, from::Int, to::Int, length::Float64, r::Float64, x::Float64, b::Union{Nothing,Float64} = nothing, c_nf_per_km::Union{Nothing,Float64} = nothing, tanδ::Union{Nothing,Float64} = nothing, ratedS::Union{Nothing,Float64} = nothing, paramsBasedOnLength=true): Creates a new ACLineSegment instance.

Methods

  • Base.show(io::IO, acseg::ACLineSegment): Prints the ACLineSegment 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.PowerTransformer — Type
PowerTransformer

A mutable structure representing a power transformer in a power system.

Fields

  • comp::AbstractComponent: The component of the power transformer.
  • trafoTyp::TrafoTyp: The type of the transformer.
  • isControlled::Bool: Whether the tap changer is enabled.
  • nS::Integer: The number of active sides, >=2.
  • nController::Integer: The number of sides controlled.
  • isBiWinder::Bool: Whether the transformer is a bi-winder.
  • HVSideNumber::Integer: The number of the high voltage side [1,2,3]. For a 3-winding transformer, HV =1, MV=2, LV=3.
  • tapSideNumber::Integer: The number of the tap side [1,2,3]. It is 0 if there is no tap.
  • side1::PowerTransformerWinding: The first winding of the transformer.
  • side2::PowerTransformerWinding: The second winding of the transformer.
  • side3::Union{Nothing,PowerTransformerWinding}: The third winding of the transformer. It can be Nothing or a PowerTransformerWinding instance.
  • _equiParms::Integer: The winding side with short-circuit parameters. 1 for side1, 2 for side2, 3 for all sides (3-winding transformer).

Constructors

  • PowerTransformer(comp::AbstractComponent, tapEnable::Bool, s1::PowerTransformerWinding, s2::PowerTransformerWinding, s3::Union{Nothing,PowerTransformerWinding} = nothing, trafoTyp::TrafoTyp = Sparlectra.Ratio): Creates a new PowerTransformer instance.

Methods

  • Base.show(io::IO, x::PowerTransformer): Prints the PowerTransformer instance.
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.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.toPU_RXGB — 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.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