Network Model Reference

Sparlectra 0.9.19

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

ApslfConfig

Typed configuration for the AnalyticLoadFlow.jl-backed analytic power-series solver (ApslfSolver), used when power_flow.solver == :apslf.

ApslfStartConfig

Typed configuration for using the analytic power-series solver as a start-value generator ahead of the rectangular Newton-Raphson solve. Deliberately has no use_pade/nr_polish fields: polishing is left to the downstream NR solve, so the generator always runs with nr_polish=false internally.

CGMESImportConfig

Options of the cgmes_import configuration block — the ENTSO-E CGMES import (see importCGMES). path accepts a folder, a ZIP, or several of both (base case plus boundary set) separated by ;.

Fields

• path::String: delivery location(s); ;-separated for multi-part deliveries.
• base_mva::Float64: system base, which CGMES does not define.
• require_boundary::Bool: fail when topology references stay unresolved.
• tap_control::Bool: start from the SSH tap positions and attach the CGMES-defined outer-loop tap controllers instead of importing the solved SvTapStep positions as fixed taps.
• machine_control::Bool: attach outer-loop remote voltage controllers (MachineVoltageControl) for machines whose voltage RegulatingControl points at a different bus, instead of holding those machines PV at their own bus.
• ignore_connected::Bool: diagnostic override that treats every terminal as connected, for snapshots whose SSH flags contradict their own SV state.
• vset_min_pu, vset_max_pu::Float64: plausibility band for a voltage RegulatingControl.targetValue, in p.u. of the regulated bus's nominal voltage. A target outside the band is treated as a placeholder: it is ignored and the unit is held PV at the bus voltage derived from the nominal data, with a warning: message. Widen the band to accept a delivery's own values, or set vset_min_pu = 0 and a large vset_max_pu to disable the check entirely.
• multi_slack::Bool: give every electrical island its own SV-declared angle reference (at most one per island). Required for multi-island deliveries — without it every island beyond the primary one has no reference and the island-wise power flow refuses to run. Disable only to force the legacy single-reference behavior.
• start_values::Symbol: Newton-Raphson start state for CGMES runs. :flat (default) uses a synthetic flat start — the solver earns the solution itself; :sv starts from the delivery's imported SvVoltage state and force-disables the competing start-value machines for the run. On CGMES runs this key wins over power_flow.flatstart / power_flow.start_mode.flatstart; MATPOWER and DTF runs ignore it. The SV comparison artifact (sv_compare.csv) is written either way.

ContingencyConfig

Configuration of the N-1 contingency batch (issue #331).

Fields

• rescue_ladder::Vector{Symbol}: the per-case start-value ladder, an ordered, duplicate-free subset of (:warm, :apslf, :dc, :flat). Default [:warm] reproduces the pre-#331 single warm solve. Each stage is one bounded solve with a distinct start recipe, tried in order until one converges. The allowed stages and their recipes are documented on runContingencies!; the set is validated (subset, no duplicates) by _validate_contingency_ladder.

DcPowerFlowConfig

Typed configuration for the standalone DC power flow (rundcpf!), used when power_flow.solver == :dc.

angle_reference_deg is the uniform angle offset added to every bus after the slack-referenced linear solve (the slack bus itself is fixed at this reference) — see solve_dc_powerflow for why this post-hoc shift is exact. ignore_out_of_service documents that status == 0 branches are always excluded from the B′ assembly (there is currently no supported way to include them; the field exists for forward compatibility with the YAML schema, not as a live toggle).

DistributedSlackConfig

Distributed active-power slack (issue #192): the REF bus keeps the angle reference while the island's active-power imbalance is absorbed by a set of participating generators via one scalar lambda_P per island.

Fields

• enabled::Bool: off by default — disabled reproduces the classical single-slack behavior bit-for-bit.
• p_mode::Symbol: how raw participation weights are derived — :pg_weighted (scheduled Pg), :pmax_weighted (maxP), :headroom_weighted (max(maxP − Pg, 0)), :imported (ProSumer.participationFactor, filled from MATPOWER APF / CGMES GeneratingUnit.normalPF), :explicit (the weights table).
• respect_p_limits::Bool: diagnostic only — WARN when a participant's corrected P leaves [minP, maxP]; no re-dispatch.
• fallback::Symbol: :error throws when an island has no valid participant; :ref_only falls back to the classical slack for that island with a warning.
• weights::Dict{String,Float64}: :explicit mode only — bus name (or bus index as string) → weight.

ExternalGridConfig

Compute the marked slack bus as a non-ideal external-grid source (issue #299): the reference voltage moves to a hidden internal bus behind the feeder impedance z = Un²/Sk'', so the connection-bus voltage reacts to loading instead of being held ideally stiff.

Fields

• enabled::Bool: off by default — the classical ideal slack.
• source::Symbol: where Sk''/R/X come from — :auto prefers the values a CGMES delivery declares on the slack bus's ExternalNetworkInjection and falls back to the config numbers below (MATPOWER/DTF carry no such data); :config always uses the config numbers.
• sk_MVA::Float64: initial symmetrical short-circuit power of the feeder.
• rx::Float64: its R/X ratio.

IslandPowerFlowConfig

Configuration for AC-island-aware power-flow diagnostics.

MatpowerExportConfig

Typed MATPOWER export configuration.

write_solution selects whether writeMatpowerCasefile writes the solved AC power-flow state back into the exported case:

• true (default): mpc.bus VM/VA reflect the solved node state and mpc.branch gains the standard MATPOWER result columns 14–17 (PF, QF, PT, QT), sourced from the existing branch-flow report path. A mpc.sparlectra.solution_written = 1 marker documents this. If the network has not been solved, the exporter warns and falls back to the 13-column model-only export instead of writing empty result columns.
• false: the export is a pure model file. mpc.branch keeps its historical 13 columns, and VM = 1.0/VA = 0.0 for all non-slack/non-PV buses (slack and PV setpoints are preserved).

MatpowerImportConfig

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

MeritLineSearchConfig

Typed configuration for the optional Armijo merit-function line search used as an alternative acceptance criterion inside the rectangular Newton-Raphson autodamp backtracking loop. Disabled by default; when disabled the solver behaves exactly as before this feature was added. See Merit-Function Line Search for the theoretical background.

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.

ParallelRuntimeConfig

Typed configuration of the in-process parallel execution of independent work items (island solves, short-circuit sweeps, contingency batches). enabled = false forces every parallel site onto the serial path (the serial functions themselves, not copies). max_tasks = "auto" resolves to Threads.nthreads(); an integer string caps the task count (applied via chunking, so it caps Threads.@threads sites too). Work lists shorter than min_work_items run serially to avoid task overhead on tiny cases.

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.

ShortCircuitConfig

Options of the short_circuit configuration block — the IEC 60909 balanced short-circuit evaluation (runShortCircuit!).

Fields

• c_factor::Float64: scalar override for the IEC 60909-0 voltage factor c. 0.0 (default) selects the hardcoded Table-1 values by nominal voltage level and case (c_max/c_min); a positive value replaces the table for every bus — intended for expert/verification runs where a worked example prescribes the factor. A configurable per-voltage-level table is not configurable.

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.

TransformerConfig

Typed transformer-modeling configuration shared by all network importers.

tap_changer_model selects how transformer tap changers act on the equivalent circuit:

• :ideal — tap steps only change the complex winding ratio; the series impedance keeps its neutral-position value (no impedance feedback; previous Sparlectra behavior).
• :impedance_correction — tap steps additionally re-refer the transformer series impedance through the tapped winding (R and X scaled with |1 + f·e^(jφ)|², implemented centrally in src/equicircuit.jl).

The option applies to all transformers of an imported case and is read by both the MATPOWER and the native DTF importer.

TrustRegionConfig

Typed configuration for the optional scaled-Newton trust-region step control in the rectangular Newton-Raphson solver: an alternative to autodamp that caps the Newton step norm at an adaptive radius and accepts/rejects steps by merit decrease. Disabled by default; mutually exclusive with autodamp. See Trust-Region Step Control for the theoretical background.

step_mode = :scaled (default) rescales the full Newton direction to the radius when it exceeds it, leaving pre-existing behavior byte-for-byte unchanged. step_mode = :dogleg blends the Newton direction with a steepest-descent (Cauchy) step along the dogleg path when the radius shrinks below the Newton step norm, trading some convergence speed for graceful degradation when the Newton direction becomes a poor descent direction. See Trust-Region Step Control, "Dogleg step mode".

WebUIConfig

Web UI presentation preferences that are not part of the solver/API contract.

_resolve_parallel_runtime(enabled, max_tasks, min_work_items) -> (on, cap, min_items)

Resolve per-call parallel overrides against the ACTIVE runtime.parallel configuration (nothing = take the configured value). Meant to be called ONCE by the orchestrating (serial) code of a parallel site before any task spawns; workers never touch the config globals.

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.

parallel_max_tasks(cfg::ParallelRuntimeConfig) -> Int

Resolve the configured runtime.parallel.max_tasks to a concrete task count: "auto" yields Threads.nthreads(), an integer string yields that number (validation guarantees it is positive).

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.

HvdcLink

Immutable record of one HVDC link between two converter prosumers. The record identifies the terminals and their provenance; live electrical values are always read from the prosumers or the attached controller, never stored here. controller_name is nothing for Stage-0 fixed injections and carries the HvdcPairControl name once a pair controller is attached (updates replace the vector element, the record itself stays immutable).

Fields: name, from_bus/to_bus (bus indices), from_prosumer/ to_prosumer (indices into net.prosumpsVec), status (1 = in service), source (:matpower, :cgmes, :api), kind (:b2b back-to-back or :p2p point-to-point, CGMES: a participating DCLineSegment makes it :p2p), controller_name.

AbstractTapChangerModel

Supertype for tap-changer model structs attached to a PowerTransformerWinding (PowerTransformerTaps for the ratio-tap-changer case; further variants, e.g. a CGMES-style phase-tap-changer model, are staged separately). See docs/src/branchmodel.md for the overall layering.

PhaseTapChangerModel

A mutable structure representing a CGMES-style phase-tap-changer (PST) model, data only — the CGMES formulas are implemented in equicircuit.jl (calcPhaseTapFraction, calcPhaseTapAngleRatio, calcPhaseTapReactance, calcPhaseTapTable). See docs/src/branchmodel.md.

Fields

• kind::Symbol: :symmetrical, :asymmetrical, or :tabular.
• step::Int: The actual step/position.
• lowStep::Int: The lowest step/position (auto-derived from table for :tabular if omitted).
• highStep::Int: The highest step/position (auto-derived from table for :tabular if omitted).
• neutralStep::Int: The neutral step/position; for :tabular it must be a step present in table.
• voltage_step_increment::Union{Nothing,Float64}: u, per step, in per unit of rated voltage (cim:PhaseTapChangerNonLinear.voltageStepIncrement); must be nothing for :tabular.
• step_phase_shift_increment::Union{Nothing,Float64}: Degrees per step for linear models (cim:PhaseTapChangerLinear.stepPhaseShiftIncrement).
• winding_connection_angle_deg::Union{Nothing,Float64}: ψ, required for :asymmetrical (cim:PhaseTapChangerAsymmetrical.windingConnectionAngle). A quadrature booster is :asymmetrical with ψ = 90°. Must be nothing for :tabular.
• x_min::Union{Nothing,Float64}: X(0) in per unit; must be nothing for :tabular.
• x_max::Union{Nothing,Float64}: X(αmax) in per unit; must be nothing for :tabular.
• convention::Symbol: sign/reciprocal convention forwarded to calcSkewAngleTap for :asymmetrical models, and used to reconstruct the regulating vector for :tabular models; default :reciprocal_from_side.
• table::Union{Nothing,Vector{TapTablePoint}}: required, non-empty, strictly ascending/unique-by-step for :tabular; must be nothing otherwise. The table is the single source of truth whenever present — no formula reconstruction and no interpolation between steps.

Constructors

• PhaseTapChangerModel(; kind::Symbol, step::Int, lowStep::Union{Nothing,Int} = nothing, highStep::Union{Nothing,Int} = nothing, neutralStep::Int, voltage_step_increment::Union{Nothing,Float64} = nothing, step_phase_shift_increment::Union{Nothing,Float64} = nothing, winding_connection_angle_deg::Union{Nothing,Float64} = nothing, x_min::Union{Nothing,Float64} = nothing, x_max::Union{Nothing,Float64} = nothing, convention::Symbol = :reciprocal_from_side, table::Union{Nothing,Vector{TapTablePoint}} = nothing): Creates a new PhaseTapChangerModel instance. lowStep/highStep are required for :symmetrical/:asymmetrical; for :tabular they are derived from table when omitted, and validated against it otherwise.

Methods

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

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.
• convention::Symbol: The ratio-tap correction convention. Only :neutral_relative is currently supported: the calcRatioTapCorrection factor is applied as a divisor on the winding ratio (ratio / corr), matching calcTransformerRatio.

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, convention::Symbol = :neutral_relative): 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.
• phase_taps::Union{Nothing,PhaseTapChangerModel}: The phase-tap-changer (PST) model of the winding, parallel to taps; nothing if this winding has no PST.

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, controls::Union{Nothing,Vector{PowerTransformerControl}} = nothing, phase_taps::Union{Nothing,PhaseTapChangerModel} = 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, controls::Union{Nothing,Vector{PowerTransformerControl}} = nothing, phase_taps::Union{Nothing,PhaseTapChangerModel} = nothing): Creates a new PowerTransformerWinding instance.

Methods

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

TapTablePoint

An immutable row of a tabular phase-tap-changer characteristic (cim:PhaseTapChangerTablePoint / cim:TapChangerTablePoint): step maps to ratio/angle_deg (and optionally x_pu), overriding formula-based reconstruction whenever present on a PhaseTapChangerModel.

Fields

• step::Int: cim:TapChangerTablePoint.step.
• ratio::Float64: effective off-nominal ratio at this step, cim:TapChangerTablePoint.ratio.
• angle_deg::Float64: effective phase shift in degrees at this step, cim:TapChangerTablePoint.angle.
• x_pu::Union{Nothing,Float64}: series reactance in per unit at this step, cim:TapChangerTablePoint.x; nothing if not provided.

Constructors

• TapTablePoint(; step::Int, ratio::Float64, angle_deg::Float64, x_pu::Union{Nothing,Float64} = nothing): Creates a new TapTablePoint 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, phase_tap_side::Int = 0, phase_taps::Union{Nothing,PhaseTapChangerModel} = nothing)::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.
• phase_tap_side::Int = 0: Winding index [1,2,3] carrying a PhaseTapChangerModel (Schrägregler); 0 means none. Uses the same 1-based winding-index convention as tap_side. May equal tap_side — a ratio tap and a phase tap on the same winding is a valid configuration and is not rejected.
• phase_taps::Union{Nothing,PhaseTapChangerModel} = nothing: The phase-tap-changer model attached at phase_tap_side. Must be nothing iff phase_tap_side == 0; a PhaseTapChangerModel is required whenever phase_tap_side != 0.

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)

With a phase-tap-changer model attached to winding 2:

psc = PhaseTapChangerModel(kind = :asymmetrical, step = 0, lowStep = -8, highStep = 8, neutralStep = 0, winding_connection_angle_deg = 60.0)
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, phase_tap_side = 2, phase_taps = psc)

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

calc2WTEndsReferredRXGB(; r1, x1, g1, b1, r2, x2, g2, b2, U1, U2) -> (r, x, g, b)

Refer the impedance/admittance contributions of both PowerTransformerEnds of a CGMES two-winding transformer to the end-2 voltage base and sum them. Each end's r,x [Ω] and g,b [S] are given on that end's own ratedU base (U1, U2 [kV]); real exports often put everything on one end, but this referral must not rely on it. Impedances scale with (U2/U1)², admittances with the inverse. The end-2 (to-side) base matches the branch-model convention of calcAdmittance (series/shunt admittance on the to side, complex ratio at the from side).

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)

calcPhaseTapAngleRatio(m::PhaseTapChangerModel; step::Int = m.step) -> NamedTuple

Effective ratio/shift/regulating-vector of a CGMES phase-tap-changer model (ENTSO-E PST Modelling, CGMES v2.4, 2014-05-28) at the given tap step.

• kind == :symmetrical (ch. 4.2): α = 2·atand(f/2), magnitude is always 1.0 (effective_ratio == 1.0 regardless of convention). With the default :reciprocal_from_side convention the returned effective_shift_deg is -α (mirroring calcSkewAngleTap's sign convention); :direct_regulating_vector returns +α.
• kind == :asymmetrical (ch. 6.2, quadrature booster = ψ = 90°): delegates to calcSkewAngleTap(tap_fraction = f, skew_angle_deg = winding_connection_angle_deg, convention = m.convention) unchanged.
• kind == :tabular: table OVERRIDES the formula path — delegates to calcPhaseTapTable for (effective_ratio, effective_shift_deg) and reconstructs regulating_vector as the exact inverse of calcSkewAngleTap's regulating-vector-to-(ratio,shift) mapping for m.convention (:reciprocal_from_side: regulating_vector = (1/ratio) * cis(-deg2rad(shift_deg)); :direct_regulating_vector: regulating_vector = ratio * cis(deg2rad(shift_deg))).

Returns

• NamedTuple (effective_ratio, effective_shift_deg, regulating_vector).

calcPhaseTapFraction(m::PhaseTapChangerModel; step::Int = m.step) -> Float64

(step - neutralStep) * voltage_step_increment, the CGMES n-n₀ tap fraction f shared by the :symmetrical and :asymmetrical formulas in calcPhaseTapAngleRatio.

Failure behavior

Errors if m.voltage_step_increment is nothing. Always throws ArgumentError for kind == :tabular — a tabular model has no linear tap fraction, only discrete (ratio, angle_deg) rows (see calcPhaseTapTable).

calcPhaseTapReactance(m::PhaseTapChangerModel, alpha_deg::Real) -> Union{Nothing,Float64}

CGMES series-reactance dependence on the phase-tap angle (ch. 3 summary table), evaluated at the given alpha_deg (typically the effective_shift_deg of calcPhaseTapAngleRatio at some step):

• :symmetrical: X(α) = x_min + (x_max - x_min) * (sind(α/2) / sind(αmax/2))^2
• :asymmetrical: X(α) = x_min + (x_max - x_min) * (tand(α) / tand(αmax))^2
• :tabular: returns the x_pu of the m.table row at m.step (may be nothing); alpha_deg is ignored — the table is the single source of truth and carries no continuous angle dependence.

where (for the formula kinds) αmax is calcPhaseTapAngleRatio(m; step = m.highStep).effective_shift_deg. Squaring cancels any sign flip from m.convention, so the result does not depend on which convention was used to obtain alpha_deg as long as it is consistent with m.

Returns

• Float64, or nothing if m.x_min/m.x_max (formula kinds) or the table row's x_pu (:tabular) is nothing.

calcPhaseTapTable(m::PhaseTapChangerModel; step::Int = m.step) -> NamedTuple

Exact lookup of the m.table row for step (no interpolation between table steps — taps are discrete; continuous interpolation is deferred to a later, outer-loop-facing stage). Implemented as a linear findfirst scan over the already-validated, strictly ascending table — no Dict caching in this stage.

Returns

• NamedTuple (effective_ratio, effective_shift_deg, x_pu), taken verbatim from the matching TapTablePoint (ratio, angle_deg, x_pu).

Failure behavior

Throws ArgumentError if m.table === nothing or if no row matches step.

calcRatioTapCorrection(taps::PowerTransformerTaps; step::Int = taps.step) -> Float64

Multiplicative ratio-tap correction 1 + (step - neutralStep) * tapStepPercent/100 for the :neutral_relative convention (the only convention PowerTransformerTaps currently supports). Applied as a divisor on the winding ratio by calcTransformerRatio; this is the single source of truth for that formula, see docs/src/branchmodel.md.

Arguments

• taps::PowerTransformerTaps: the tap-changer model.
• step::Int: tap position to evaluate at; defaults to taps.step.

Returns

• Float64: the correction factor (1.0 at the neutral step).

calcRatioTapRange(taps::PowerTransformerTaps) -> NamedTuple

Ratio-terms tap range (tap_min, tap_max, tap_step), evaluated with calcRatioTapCorrection at lowStep and highStep: tap_min = min(corr(lowStep), corr(highStep)), tap_max = max(...), tap_step = abs(tapStepPercent / 100).

Returns

• NamedTuple (tap_min, tap_max, tap_step).

calcSkewAngleTap(; tap_fraction::Real, skew_angle_deg::Real, convention::Symbol = :reciprocal_from_side)

Convert a longitudinal regulating-voltage fraction and skew angle into the effective complex tap quantities used by transformer equivalent circuits.

The regulating vector is 1 + tap_fraction * cis(skew_angle_deg). With the default :reciprocal_from_side convention, the returned magnitude/angle represent the from-side off-nominal tap convention used by Sparlectra: the effective ratio multiplier is 1 / abs(regulating_vector) and the effective phase shift is -angle(regulating_vector).

calcTapCorrectedRX(; r_pu::Real, x_pu::Real, tap_changer_model::Symbol, tap_fraction::Union{Nothing,Real} = nothing, skew_angle_deg::Real = 0.0, ratio::Union{Nothing,Real} = nothing)

Apply the tap-changer impedance correction of calcTapImpedanceCorrectionFactor to a transformer series impedance. This is the central implementation used by both the MATPOWER and the native DTF importer; importers must not duplicate the correction math.

Returns

• NamedTuple (r_pu, x_pu, factor) with the corrected per-unit series resistance/reactance and the applied correction factor.

calcTapImpedanceCorrectionFactor(; tap_changer_model::Symbol, tap_fraction::Union{Nothing,Real} = nothing, skew_angle_deg::Real = 0.0, ratio::Union{Nothing,Real} = nothing)::Float64

Return the multiplicative correction factor applied to the transformer series impedance (R and X) for the selected tap-changer model.

Sparlectra distinguishes two tap-changer models:

• :ideal — the tap changer only changes the complex winding ratio; the short-circuit impedance keeps its neutral-position value (factor 1.0).
• :impedance_correction — the tap changer acts on a physical winding, so the short-circuit impedance is re-referred through the tapped winding. R and X are scaled with $|1 + f e^{j\varphi}|^2$, where f is the additional-voltage fraction (tap_fraction) and $\varphi$ the skew angle in degrees (skew_angle_deg).

Callers provide either the regulating-vector parameters (tap_fraction and skew_angle_deg; used by the native DTF importer) or the effective Sparlectra off-nominal tap ratio (used by the MATPOWER importer). With Sparlectra's reciprocal from-side tap convention (ratio = 1 / |1 + f e^{jφ}|, see calcSkewAngleTap) both forms are equivalent; the ratio form yields 1 / ratio^2. A ratio of 0.0 (MATPOWER "no tap") or 1.0 is treated as neutral. When neither tap_fraction nor ratio is given, the factor is 1.0.

Arguments

• tap_changer_model::Symbol: :ideal or :impedance_correction.
• tap_fraction::Union{Nothing,Real}: longitudinal regulating-voltage fraction f.
• skew_angle_deg::Real: skew angle of the additional voltage in degrees.
• ratio::Union{Nothing,Real}: effective Sparlectra off-nominal tap ratio.

Returns

• Float64: multiplicative factor for the series resistance and reactance.

Failure behavior

Throws an ArgumentError for an unsupported tap_changer_model value.

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.
• hvdc_links: One row per HVDC link (net.hvdcLinks): terminal flows, loss, mode, rating, controller status (see _hvdc_link_flow_rows).

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

_distributed_slack_bus_shares(net) -> (active::Bool, shares::Dict{Int,NTuple{2,Float64}})

Per-bus distributed-slack participation for the bus table of the classical result print: bus index to (alpha, dp_mw), aggregated over the generators of a bus (the persisted participation table is per generator). active is false when the last solve ran without the distributed slack or no solver status exists; the table then omits the participation columns.

_fitColumn(text, width) -> String

Trim text to width characters, marking the cut with …. Fixed-width @sprintf fields pad but never truncate, so long names — CGMES bus and branch identifiers routinely exceed 25 characters — would otherwise push every following column out of alignment.

_hvdc_link_flow_rows(net) -> Vector{NamedTuple}

One row per HvdcLink for the HVDC Link Flows table, ACPFlowReport, and the CSV export. Sign convention: p_from_MW is the power leaving the from bus into the link (positive for export), p_to_MW the power delivered into the to bus. With an attached controller the values come from its setpoints and live terminal state (mode is the controller mode); without one they come from the terminal prosumers (mode = :fixed, loss = -(P_from_injection + P_to_injection) in the MATPOWER convention where the from injection is negative).

_print_distributed_slack_summary_line(io, net)

One line inside the classical result header when the last solve ran with the distributed slack active: mode, the solved lambda_P, and the participant count. The per-bus participation itself lives in the bus table (columns dSl alpha and Pg eff MW, see _distributed_slack_bus_shares). Prints nothing when the feature was off or the net has no rectangular solver status.

_print_wrong_branch_summary_line(io, net)

Prints a single console/log line summarizing the wrong-branch detection outcome when it is suspect or invalid (status is neither :ok nor :not_checked). Clean runs and disabled detection print nothing, keeping logs stable for the common case.

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