API reference

Abstract supertype for active-power support terms.

Abstract supertype for TLC inner-current controllers.

Abstract supertype for TLC inner-voltage controllers.

Abstract supertype for TLC modulation blocks.

Abstract supertype for active-power outer-loop controllers.

Abstract supertype for reactive-power outer-loop controllers.

Abstract supertype for TLC-compatible synchronization blocks.

Abstract supertype for modular TLC state-space models.

Abstract supertype for reactive-power support terms.

Select magnitude and phase plots from completed Bode calculations.

mutable struct Conductor

Describe one conducting layer of a coaxial cable.

• rᵢ::Union{Float64, Int64}: Inner radius \[m\]. Default: 0

• rₒ::Union{Float64, Int64}: Outer radius \[m\]. Default: 0

• ρ::Union{Float64, Int64}: Electrical resistivity \[Ω·m\]. Default: 0

• μᵣ::Union{Float64, Int64}: Relative permeability \[dimensionless\]. Default: 1

• A::Union{Float64, Int64}: Optional nominal conducting area \[m²\]. Default: 0

mutable struct Conductors

Describe overhead-line phase-conductor bundle geometry and material data.

• nᵇ::Int64: Number of conductor bundles or phases. Default: 1

• nˢᵇ::Int64: Number of subconductors in each bundle. Default: 1

• yᵇᶜ::Union{Float64, Int64}: Height of the lowest bundle above ground \[m\]. Default: 0

• Δyᵇᶜ::Union{Float64, Int64}: Vertical offset between bundles \[m\]. Default: 0

• Δxᵇᶜ::Union{Float64, Int64}: Horizontal bundle offset \[m\]. Default: 0

• Δ̃xᵇᶜ::Union{Float64, Int64}: Secondary horizontal offset used by offset/concentric layouts \[m\]. Default: 0

• dˢᵃᵍ::Union{Float64, Int64}: Maximum conductor sag \[m\]. Default: 0

• dˢᵇ::Union{Float64, Int64}: Nearest-neighbor subconductor spacing \[m\]. Default: 0

• rᶜ::Union{Float64, Int64}: Conductor radius \[m\]. Default: 0

• Rᵈᶜ::Union{Float64, Int64}: DC resistance of one complete conductor \[Ω/km\]. Default: 0

• gᶜ::Union{Float64, Int64}: Per-unit-length shunt conductance \[S/m\]. Default: 1.0e-11

• μᵣᶜ::Union{Float64, Int64}: Relative conductor permeability \[dimensionless\]. Default: 1

• positions::Tuple{Vector{Union{Float64, Int64}}, Vector{Union{Float64, Int64}}}: Explicit horizontal and vertical conductor coordinates \[m\]. Default: ([], [])

• organization::Symbol: Geometric layout identifier. Default: Symbol()

Abstract supertype for converter controller parameter blocks.

TLC modulation block backed by a generic Pade delay.

struct DelayModulation{D<:PadeDelay} <: AbstractModulationTLC

Fields

• delay::PadeDelay

Construct a TLC delay modulation block.

DelayModulation(; timeDelay, padeOrderNum, padeOrderDen)

Details

The internal PadeDelay uses two inputs and the :m_delay state prefix to preserve the historical TLC state names.

struct EigenvalueAnalysis{B} <: PowerImpedance.AbstractPowerImpedanceFormulation{B}

Apply eigenvalue analysis between fmin and fmax in hertz.

• backend::Type: Resolved calculation backend.

• fmin::Float64: Lower assessment frequency [Hz].

• fmax::Float64: Upper assessment frequency [Hz].

• determinant::Bool: Whether to calculate the inverse-determinant index.

Select modal plots from completed eigenvalue calculations.

$(TYPEDSIGNATURES)

Electrical subsystem of an induction machine.

The model is formulated in the synchronous dq reference frame using an inverse-Γ representation. It describes the dynamics of stator currents and rotor flux linkages and computes the electromagnetic torque supplied to the mechanical subsystem.

Parameters

Base quantities

• ωn : electrical base angular frequency (rad/s)
• p_f : number of poles
• Vac_base : line-to-line RMS voltage base
• S_base : power base

Transformer impedance

• lt : transformer inductance
• rt : transformer resistance

Machine parameters

• l_m : magnetizing inductance
• l_sl : stator leakage inductance
• r_s : stator resistance
• l_rl : rotor leakage inductance
• r_r : rotor resistance

States

• i_d : d-axis stator current
• i_q : q-axis stator current
• Ψ_df : d-axis rotor flux linkage
• Ψ_qf : q-axis rotor flux linkage

Initial Conditions

The electrical states are initialized from the active and reactive power setpoint:

```julia id = 2/3 * pac iq = -2/3 * qac Ψdf = 1.0 Ψqf = 0.0

Electrical parameters and states of the TLC reactor model.

struct ElectricalTLC <: PowerImpedance.AbstractStateSpace

Fields

• Lᵣ::Float64

• Rᵣ::Float64

• ωbase::Float64

• Sbase::Float64

• vDCbase::Float64

• zACbase::Float64

• lACbase::Float64

• iDCbase::Float64

• vACbase::Float64

• iACbase::Float64

struct FrequencyResponseResult{F, R, W, N, M, G} <: AbstractProblemResult

Store one scalar matrix frequency response.

• formulation::Any: Resolved response formulation.

• kind::Symbol: Response identifier.

• response::Any: Numeric response with dimensions n x n x nf.

• frequencies::Any: Angular frequencies [rad/s].

• nodes::Any: Ordered response nodes.

• network_model::Any: Linearized network used by the calculation.

• diagnostics::Any: Calculation diagnostics.

Lagged frequency-support active-power contribution.

struct FrequencySupportLag <: AbstractFrequencySupport

Fields

• Kω::Float64: Default: 0.0

• ωc::Float64: Default: 0.0

struct GeneralizedNyquist{B} <: PowerImpedance.AbstractPowerImpedanceFormulation{B}

Apply generalized Nyquist analysis to a loop-gain response.

order_maxima is the neighborhood order used to identify oscillatory peaks.

mutable struct Groundwires

Describe overhead-line ground-wire geometry and material data.

• nᵍ::Int64: Number of ground wires. Default: 0

• Δxᵍ::Union{Float64, Int64}: Horizontal offset between ground wires \[m\]. Default: 0

• Δyᵍ::Union{Float64, Int64}: Vertical offset above the lowest phase conductor \[m\]. Default: 0

• rᵍ::Union{Float64, Int64}: Ground-wire radius \[m\]. Default: 0

• dᵍˢᵃᵍ::Union{Float64, Int64}: Maximum ground-wire sag \[m\]. Default: 0

• Rᵍᵈᶜ::Union{Float64, Int64}: DC resistance of one ground wire \[Ω/km\]. Default: 0

• μᵣᵍ::Union{Float64, Int64}: Relative ground-wire permeability \[dimensionless\]. Default: 1

• positions::Tuple{Vector{Union{Float64, Int64}}, Vector{Union{Float64, Int64}}}: Explicit horizontal and vertical ground-wire coordinates \[m\]. Default: ([], [])

struct HarmonicImpedancePlotDefinition <: PowerImpedance.PlotBuilder.AbstractPlotDefinition

Select the declarative harmonic-impedance magnitude recipe for a scalar FrequencyResponseResult.

PI inner-current controller for TLC modulation commands.

struct InnerCurrentPIControl{F<:PowerImpedance.AbstractMeasurementFilter} <: AbstractInnerCurrentControl

Fields

• pi_ctrl::PIControl

• filter::PowerImpedance.AbstractMeasurementFilter

• activate_ω_c_multiplication::Bool

mutable struct Insulator

Describe one insulating layer and its optional semiconducting screens.

• rᵢ::Union{Float64, Int64}: Inner radius \[m\]. Default: 0

• rₒ::Union{Float64, Int64}: Outer radius \[m\]. Default: 0

• ϵᵣ::Union{Float64, Int64}: Relative permittivity \[dimensionless\]. Default: 1

• μᵣ::Union{Float64, Int64}: Relative permeability \[dimensionless\]. Default: 1

• a::Union{Float64, Int64}: Inner semiconducting-screen thickness \[m\]. Default: 0

• b::Union{Float64, Int64}: Outer semiconducting-screen thickness \[m\]. Default: 0

struct LinearizationResult{F, M, G} <: AbstractProblemResult

Store a linearized network and the operating point used to construct it.

• formulation::Any: Resolved linearization formulation.

• network_model::Any: Linearized frequency-domain network model.

• operating_point::OperatingPoint: Steady-state point about which active elements were linearized.

• diagnostics::Any: Linearization diagnostics.

struct MMC{S<:AbstractSynchronization, Δ<:PowerImpedance.AbstractΔdqControl, Σ<:PowerImpedance.AbstractΣdqzControl, Mod<:PowerImpedance.AbstractModulationMMC} <: AbstractMMC

Combine the measurement, synchronization, differential-current control, internal-current control, modulation, and electrical submodels of a modular multilevel converter.

• meas::Measurement: Measurement and signal-filtering block.

• sync::AbstractSynchronization: Synchronization block.

• delta_control::PowerImpedance.AbstractΔdqControl: Differential-current AC-side control structure.

• sigma_control::PowerImpedance.AbstractΣdqzControl: Sum/circulating-current internal control structure.

• modulation::PowerImpedance.AbstractModulationMMC: Modulation and delay block.

• elec::ElectricalMMC: MMC electrical plant and physical bases.

Composite measurement block for the TLC signal set.

struct Measurement <: PowerImpedance.AbstractStateSpace

Fields

• vG_d::MeasurementSignal

• vG_q::MeasurementSignal

• v_dc::MeasurementSignal

• i_d::MeasurementSignal

• i_q::MeasurementSignal

• i_dc::MeasurementSignal

• θ::MeasurementSignal

• P_ac::MeasurementSignal

• Q_ac::MeasurementSignal

• P_dc::MeasurementSignal

Construct the converter measurement block from filter specifications.

Measurement(; v_ac, i_ac, v_dc, i_dc, θ, P_ac, Q_ac, P_dc)

Details

The v_ac filter is applied to vG_d and vG_q; the i_ac filter is applied to i_d and i_q; scalar filters are used for v_dc, i_dc, θ, P_ac, Q_ac, and P_dc.

Single measured signal with an optional measurement filter.

struct MeasurementSignal{F<:PowerImpedance.AbstractMeasurementFilter} <: PowerImpedance.AbstractStateSpace

Fields

• signal::Symbol

• filter::PowerImpedance.AbstractMeasurementFilter: Default: NoFilter()

Construct a filtered measurement signal.

MeasurementSignal(signal, filter)

Details

The filter specification is converted to state-space matrices with measurement_filter_ss before being stored.

$(TYPEDSIGNATURES)

Mechanical subsystem of an induction machine.

The model describes rotor-speed dynamics driven by the difference between electromagnetic torque and a speed-dependent load torque.

Parameters

• H : inertia constant
• T_0 : Nominal load torque [pu]
• A : nonlinear coefficient
• B: linear coefficient
• C: constant coefficient

\[\tau_m = T_0 (A \omega_r^m + B \omega_r + C)\]

Initial conditions

• ω_r = 1.0

struct Network elements::OrderedDict{Symbol, Element} nets :: Dict{Symbol, Net} connections :: Dict{Symbol, Net} Network() = new(OrderedDict{Symbol, Element}(), Dict{Symbol, Net}(), Dict{Symbol, Vector{Int}}()) end

struct NetworkDiagramDefinition <: PowerImpedance.PlotBuilder.AbstractPlotDefinition

Select the optional GraphMakie single-line network-diagram recipe for a materialized NetworkBuilder.NetworkState.

Loading GraphMakie provides the recipe implementation and renderer. A supplied PowerFlowResult enriches the network topology without triggering a solve or conversion.

No frequency-support contribution.

No inner-current control.

Pass-through inner-voltage controller.

Forwards active and reactive current references to the inner-current loop.

Pass-through modulation block without delay.

No active-power outer-loop control.

No reactive-power outer-loop control.

Synchronization block that fixes the control frame to the stationary frame.

No voltage-support contribution.

Select a generalized-Nyquist plot from completed stability calculations.

struct OperatingPoint

Store the steady-state quantities required to linearize active elements.

• setpoints::Dict{Symbol, Setpoint}: Calculated steady-state values indexed by element name.

Active-power PI controller with optional frequency support.

struct OuterActivePowerControl{S<:AbstractFrequencySupport} <: AbstractOuterActiveControl

Fields

• pi_ctrl::PIControl

• support::AbstractFrequencySupport

Construct an active-power PI controller.

OuterActivePowerControl(; pi_ctrl, support)

DC-voltage outer-loop controller that produces a d-axis current reference.

struct OuterActiveVdcControl <: AbstractOuterActiveControl

Fields

• pi_ctrl::PIControl: Default: PIControl()

Reactive-power PI controller with optional voltage support.

struct OuterReactiveQControl{S<:AbstractVoltageSupportTLC} <: AbstractOuterReactiveControl

Fields

• pi_ctrl::PIControl

• support::AbstractVoltageSupportTLC

Construct a reactive-power PI controller.

OuterReactiveQControl(; pi_ctrl, support)

AC-voltage outer-loop controller that produces a q-axis current reference.

struct OuterReactiveVacControl <: AbstractOuterReactiveControl

Fields

• pi_ctrl::PIControl: Default: PIControl()

mutable struct Overhead_line <: PowerImpedance.Transmission_line

Store the native overhead-line length, conductor data, ground-wire data, and earth-return properties used by frequency-domain evaluation.

• length::Union{Float64, Int64}: Physical line length \[m\]. Default: 0

• conductors::Conductors: Phase-conductor geometry and materials. Default: Conductors()

• groundwires::Groundwires: Ground-wire geometry and materials. Default: Groundwires()

• earth_parameters::NTuple{N, Union{Float64, Int64}} where N: Earth relative permeability, relative permittivity, and resistivity \[Ω·m\]. Default: (1, 1, 1)

Store proportional-integral controller gains.

struct PIControl <: Controller

Fields

• Kp::Float64: Default: 0

• Ki::Float64: Default: 0

Details

PIControl is intentionally a lightweight immutable parameter container. State variables for the integrator live in the state-space blocks that use the controller.

Phase-locked-loop synchronization block.

struct PLLSynchronization{Filter<:PowerImpedance.AbstractMeasurementFilter} <: AbstractSynchronization

Fields

• pi_ctrl::PIControl

• filter::PowerImpedance.AbstractMeasurementFilter

Construct a PLL synchronization block.

PLLSynchronization(; pi_ctrl, filter)

Details

The filter argument filters the measured q-axis voltage before the PI controller computes the frequency deviation.

Pade-approximated multi-input time delay.

struct PadeDelay <: PowerImpedance.AbstractStateSpace

Fields

• timeDelay::Float64

• padeOrderNum::Int64

• padeOrderDen::Int64

• n_inputs::Int64

• state_prefix::Symbol

• A::Matrix{Float64}

• B::Matrix{Float64}

• C::Matrix{Float64}

• D::Matrix{Float64}

Details

PadeDelay stores a state-space realization of a delay with n_inputs independent channels. A zero timeDelay or zero denominator order creates a zero-state pass-through block.

Construct a PadeDelay from Pade approximation settings.

PadeDelay(
;
    timeDelay,
    padeOrderNum,
    padeOrderDen,
    n_inputs,
    state_prefix
)

Details

state_prefix controls the generated state names. For example, a two-channel third-order delay with state_prefix = :m_delay yields states :m_delay_x1 through :m_delay_x6.

Select a passivity-index plot from completed passivity calculations.

struct PowerFlowResult{F, R, D, N, E, G} <: AbstractProblemResult

Store one PowerModelsACDC power-flow calculation and its operating point.

• formulation::Any: Resolved power-flow formulation.

• result::Any: PowerModelsACDC solution and termination information.

• data::Any: PowerModelsACDC input data used by the calculation.

• nodes2bus::Any: Mapping from PowerImpedance nodes to power-flow buses.

• elem2comp::Any: Mapping from PowerImpedance elements to power-flow components.

• operating_point::OperatingPoint: Steady-state quantities used for active-element linearization.

• diagnostics::Any: Convergence status and solver diagnostics.

struct PowerImpedanceProblem{N, K, E, F} <: AbstractProblemDefinition

Specify a network frequency-response calculation.

• network::Any: Materialized network state or linearized network model.

• nodes::Any: Ordered retained node names.

• eliminated_elements::Any: Elements excluded from the response calculation.

• frequency_range::Any: Minimum frequency, maximum frequency, and point count in hertz.

Setpoint(; Pac=missing, Qac=missing, θac=missing, Vac=missing,
         Pdc=missing, Vdc=missing)

Store an AC/DC steady-state operating point.

Arguments

• Pac: AC active power \[MW\].
• Qac: AC reactive power \[MVAr\].
• θac: AC voltage angle \[rad\].
• Vac: phase-voltage amplitude \[kV\].
• Pdc: DC active power \[MW\].
• Vdc: DC voltage \[kV\].

Every field defaults to missing; the power-flow pipeline fills quantities that are not fixed by the component's control mode.

Select a singular-value plot from completed small-gain calculations.

struct StabilityProblem{R} <: AbstractProblemDefinition

Specify a small-signal analysis of completed frequency-response results.

• response::Any: One frequency-response result or an explicit pair for small-gain analysis.

struct StabilityResult{F, O, G} <: AbstractProblemResult

Store one completed small-signal analysis without graphics objects.

• formulation::Any: Resolved stability formulation.

• analysis::Symbol: Analysis identifier.

• output::Any: Calculated analysis quantities.

• diagnostics::Any: Calculation diagnostics.

A synchronous machine model. Validated against PSCAD. The model is based on the modified Kundur's example, with a steam turbine and governor. The model is implemented in the dq reference frame, and the electrical equations are based on the Park's transformation. The mechanical equations are based on the swing equation, and the governor is based on a simple first-order model. The AVR is based on a simple first-order model with a lead-lag compensator.
**Disclaimer**: Validation is slightly below 1% error, mostly at lowest frequencies. 
Possible reasons:
- Highly sensitive to operation point. Terminal voltage for power flow should be calculated based on AVR & exciter if no integral control
- Smaller timestep PSCAD (current validation with 1us)

Composite modular TLC model.

struct TLC{E<:ElectricalTLC, Meas<:Measurement, Sync<:AbstractSynchronization, Active<:AbstractOuterActiveControl, Reactive<:AbstractOuterReactiveControl, IV<:AbstractInnerVoltage, IC<:AbstractInnerCurrentControl, Mod<:AbstractModulationTLC} <: AbstractTLC

Fields

• elec::ElectricalTLC

• meas::Measurement

• sync::AbstractSynchronization

• outerActive::AbstractOuterActiveControl

• outerReactive::AbstractOuterReactiveControl

• innerVoltage::AbstractInnerVoltage

• innerCurrent::AbstractInnerCurrentControl

• mod::AbstractModulationTLC

Details

The field order defines the state ordering used by statenames and the execution order used in state_space!.

struct UnstableFrequencyAnalysis{B} <: PowerImpedance.AbstractPowerImpedanceFormulation{B}

Detect oscillatory frequencies from complementary-sensitivity peaks.

order_maxima is the neighborhood order used to select candidate peaks.

Select complementary-sensitivity plots from completed frequency detection.

Lagged AC-voltage support contribution to reactive-power reference.

struct VoltageSupportLag <: AbstractVoltageSupportTLC

Fields

• K::Float64: Default: 0.0

• ωc::Float64: Default: 0.0

determine_impedance(
    network::Network;
    input_pins,
    output_pins,
    elim_elements,
    freq_range
)

Calculate the impedance seen at a Classic Network port over a logarithmic frequency grid. Elements in elim_elements are excluded when tracing the subnetwork between input_pins and output_pins.

Arguments

• network: connected Classic network.
• input_pins: ordered input nodes of the port.
• output_pins: ordered reference or output nodes of the port.
• elim_elements: elements excluded from the traced subnetwork.
• freq_range: tuple (fmin, fmax, count) that defines the logarithmic frequency grid in hertz. Default: (0.001, 10_000, 2_000).

Returns

• impedance: complex port-impedance matrix at each frequency, in ohms.
• angular_frequencies: angular-frequency vector in radians per second.
• topology: dictionary containing the traced node, element, and output-node lists.

Notes

The method normalizes the entries of input_pins and output_pins in place.

Errors

• Throws ArgumentError when either port list is empty.

Example

The following network contains a DC voltage source and a frequency-dependent cable:

using PowerImpedance
import PowerImpedance: @network

net = @network begin
    vs = dc_source(voltage = 500e3)
    c = cable(length = 100e3, positions = [(0,1)], earth_parameters = (1,1,1),
    C1 = Conductor(rₒ = 24.25e-3, ρ = 1.72e-8), C2 = Conductor(rᵢ = 41.75e-3, rₒ = 46.25e-3, ρ = 22e-8),
    C3 = Conductor(rᵢ = 49.75e-3, rₒ = 60.55e-3, ρ = 18e-8, μᵣ = 10),
    I1 = Insulator(rᵢ = 24.25e-3, rₒ = 41.75e-3, ϵᵣ = 2.3),
    I2 = Insulator(rᵢ = 46.25e-3, rₒ = 49.75e-3, ϵᵣ = 2.3),
    I3 = Insulator(rᵢ = 60.55e-3, rₒ = 65.75e-3, ϵᵣ = 2.3))
    vs[1.1] ⟷ c[1.1] ⟷ Node1
    vs[2.1] ⟷ c[2.1] ⟷  gnd
end

Exclude the voltage source to calculate the network impedance seen from its terminals:

impedance, angular_frequencies, topology = determine_impedance(
    net;
    elim_elements = [:vs],
    input_pins = [:Node1],
    output_pins = [:gnd],
    freq_range = (0.01, 10_000, 2_000),
)

Compatibility constructor for the previous TLC delay-modulation name.

PadeModulation(; kwargs...)

ac_source(; setpoint=Setpoint(Vac=220/sqrt(3)), pins=1,
          limits=Limits(), transformation=false, connection=true,
          source_kwargs...)

Construct an ideal AC voltage-source element and its power-flow data.

Arguments

• setpoint: AC voltage, angle, and power operating point. See Setpoint.
• pins: Number of phase-domain terminals.
• limits: Active- and reactive-power limits in the source power-flow base.
• transformation: Whether to expose supported transformed coordinates.
• connection: Whether NetworkBuilder includes the element in the system.
• source_kwargs: Legacy fields of the internal Source model.

Returns

• An Element whose model is a Source and whose ABCD representation is an ideal voltage source.

Errors

• Throws ArgumentError when source_kwargs contains an unknown field.

Examples

source = ac_source(
    setpoint = Setpoint(Vac = 220 / sqrt(3), Pac = 100.0, Qac = 0.0),
    pins = 3,
    transformation = true,
)

add!(n::Network, elem::PowerImpedance.Element) -> Symbol

Add elem to n under a generated designator and leave its pins unconnected. If an equal element already belongs to the network, return its existing designator.

Arguments

• n: classic network that receives the element.
• elem: element to add.

Returns

The generated or existing element designator.

add!(n::Network, designator::Symbol, elem::Element)

Adds the element elem to the network n with the reference designator designator, leaving its pins unconnected. If the network already contained an element named designator, it is removed first.

add!(n::Network, name::Symbol, pins::Union{Tuple{Symbol,Any}}...)

Adds the nets in pins to the nets in n.nets with the key/node name name

add!(n::Network, pin::Tuple{Symbol, Symbol})

Adds the net pin to the nets in n.nets with a generic name. Pin is a net, ie. pin::Tuple{designator, pin}.

angular_frequencies(result::FrequencyResponseResult) -> Any

Return the strictly increasing angular-frequency coordinates in rad/s.

cable(; length=0, positions=[], earth_parameters=(1, 1, 1),
      configuration=:coaxial, type=:underground, eliminate=true,
      transformation=false, connection=true, layers...)

Construct a frequency-dependent group of coaxial power cables.

Arguments

• length: Physical cable length \[m\].
• positions: Cable-center coordinates (x, y) \[m\]; one pair per cable.
• earth_parameters: Earth relative permeability \[dimensionless\], relative permittivity \[dimensionless\], and resistivity \[Ω·m\].
• configuration: Cable geometry identifier. Default: :coaxial.
• type: Installation identifier. Default: :underground.
• eliminate: Whether grounded internal conducting layers are Kron-reduced.
• transformation: Whether to expose a supported transformed representation.
• connection: Whether NetworkBuilder includes the element in the system.
• layers: Named Conductor values (C1, C2, ...) and Insulator values (I1, I2, ...). A metallic screen may be supplied as SC together with sheath C2.

Returns

• An Element with one input and output terminal per cable position.

Notes

Conductor radii and insulator radii are in metres. Conductor resistivity is in \[Ω·m\]; relative permeability and permittivity are dimensionless. The complete phase-domain self and mutual parameter matrices are evaluated at the requested frequency before optional internal-layer elimination.

Errors

• Throws ArgumentError for an unknown property or layer, or when a metallic screen is supplied without sheath C2.

Examples

cable_element = cable(
    length = 100e3,
    positions = [(-0.5, 1.0), (0.5, 1.0)],
    C1 = Conductor(rₒ = 0.02622, ρ = 2.354e-8, μᵣ = 1.035),
    I1 = Insulator(rᵢ = 0.02622, rₒ = 0.06006, ϵᵣ = 2.67),
    C2 = Conductor(rᵢ = 0.06006, rₒ = 0.06336, ρ = 2.14e-7),
    earth_parameters = (1.0, 1.0, 100.0),
)

check_stability(
    net::Network,
    mmc::PowerImpedance.Element;
    direction,
    omega_range
)

Calculate the converter and network impedances at a selected partition of a Classic network. The method forms the minor-loop gain as Z_network / Z_device and reports the phase margin at each detected unity-gain crossing.

Arguments

• net: connected Classic network.
• mmc: active converter or synchronous-machine element at the partition.
• direction: partition side. :dc selects the DC terminals. Other values select the AC terminals. Default: :dc.
• omega_range: legacy logarithmic frequency-grid tuple used by the impedance calculation. Default: (0, 4, 1_000).

Returns

• impedance_data: one [Z_device Z_network Z_network/Z_device] row for each frequency.
• angular_frequencies: angular-frequency vector in radians per second.

Errors

• Throws ArgumentError when mmc is not an active converter or synchronous machine.

function composite_element(subnet::Network, input_pins::Array{Any}, output_pins::Array{Any})

Create a net element from the (sub-)network net. The input_pins and output_pin define input and output nodes of the element.

Example

connect!(n::Network, pins::Union{Symbol,Tuple{Symbol,Any}}...)

Connects the given pins (or named nets) to each other in the network n. Named nets are given as Symbols, pins are given as Tuple{Symbols,Any}s, where the first entry is the reference designator of an element in c, and the second entry is the pin name. For convenience, the latter is automatically converted to a Symbol as needed.

Example

connect!(n::Network)

Connects all elements' pins with their node names.

dc_source(; pins=1, setpoint=Setpoint(Vdc=240),
          transformation=false, connection=true, source_kwargs...)

Construct an ideal DC voltage-source element and its power-flow data.

Arguments

• pins: Number of DC conductors represented on each legacy element side.
• setpoint: DC voltage and power operating point. See Setpoint.
• transformation: Whether to expose a supported transformed representation.
• connection: Whether NetworkBuilder includes the element in the system.
• source_kwargs: Legacy fields of the internal Source model.

Returns

• An Element whose model is a DC Source.

Errors

• Throws ArgumentError when source_kwargs contains an unknown field.

Examples

source = dc_source(setpoint = Setpoint(Vdc = 320.0, Pdc = 100.0))

diagram(network::NetworkBuilder.NetworkState; kwargs...)
diagram(network::NetworkBuilder.NetworkState, powerflow::PowerFlowResult; kwargs...)

Render a single-line network diagram through the optional GraphMakie extension.

Arguments

• network: Materialized network whose topology is rendered.
• powerflow: Optional completed result used to enrich the topology with PowerModels input and solution records.

Returns

• An extension-owned diagram handle exposing its Makie figure, projection, resolved positions, and selection state.

Notes

This function never calculates power flow. Load GraphMakie and one Makie backend before calling it.

disconnect!(n::Network, p::Tuple{Symbol,Symbol})

Disconnects the given pin p from anything else in the network n. The pin is given as a Tuple{Symbols,Any}, where the first entry is the reference designator of an element in n, and the second entry is the pin name. For convenience, the latter is automatically converted to a Symbol as needed. Note that if e.g. three pin p1, p2, and p3 are connected then disconnect!(n, p1) will disconnect p1 from p2 and p3, but leave p2 and p3 connected to each other.

eval_abcd(tl::Overhead_line, s :: Complex)

Form ABCD representation from known values for Y and Z and write values in the dictionary Γ = √ZY Yᶜ = Z⁻¹γ ABCD = [cosh(Γl) Yᶜ⁻¹sinh(Γl) Yᶜsinh(Γl) cosh(Γl)]

Evaluate the ABCD representation of a converter at complex frequency s.

eval_abcd(converter, s)

Details

The legacy converter interface delegates ABCD evaluation to eval_y.

impedance(; z=0, pins::Int=0, transformation=false)

Construct a constant or frequency-dependent series impedance multiport.

Arguments

• z: Impedance specification \[Ω\]. A number produces an equal diagonal; a collection with pins entries produces an unequal diagonal; a collection with pins^2 entries produces the complete matrix; and a callable z(s) is evaluated at complex frequency s.
• pins: Port order. When zero, a numeric scalar implies one pin and an array length must be a perfect square from which the order can be inferred.
• transformation: Whether to expose a supported transformed representation.

Returns

• An Element containing the normalized dense impedance representation.

Errors

• Throws ArgumentError when the impedance shape is incompatible with pins or when pins=0 cannot be inferred from the supplied array.

Examples

single = impedance(z = 5.0, pins = 1)
diagonal = impedance(z = [1.0, 2.0, 3.0], pins = 3)
coupled = impedance(z = [1.0 0.1; 0.1 2.0], pins = 2)
dynamic = impedance(z = s -> 0.1 + s * 2e-3, pins = 1)

inductionmachine(; elec=ElectricalIM(),
                    mech=MechanicalIM(),
                    setpoint=Setpoint(),
                    connection=true)

Create an induction machine element.

Arguments

• elec : electrical machine model.
• mech : mechanical machine model.
• setpoint : operating-point specification used for initialization.
• connection : whether the element is connected to the network.

Returns

An Element containing an InductionMachine model.

Example

im = inductionmachine(
    elec = ElectricalIM(),
    mech = MechanicalIM(T_0 = 0.9))

function makeabcd(net::Network, dict::Dict{Symbol, Array{Union{Symbol,Int}}}, startpins::Array{Symbol}, end_pins::Array{Symbol})

Creates ABCD represntation of the network between start pins and end pins
using data written in dictionary dict.

make_y_matrix(network::Network; elim_elements::Array{Symbol} = Symbol[], 
              input_pins::Array{Any}, freq_range=(0.01, 10000, 2000))

Computes the frequency-dependent admittance matrix (Y-matrix) for a given electrical network. It determines the nodal admittance representation based on the specified input pins and frequency range.

Arguments

• network::Network: The electrical network model for which the admittance matrix is computed.
• elim_elements::Array{Symbol} (default []): List of elements to be excluded from the computation.
• input_pins::Array{Any}: A list of input nodes (ports) that define the matrix rows/columns.
• freq_range::Tuple{Real, Real, Int} (default (0.01, 10000, 2000)): Defines the range of frequencies in Hz in logarithmic scale:
  • min_f: Minimum frequency.
  • max_f: Maximum frequency.
  • n_f: Number of frequency points.

Behavior

• Recursively explores the network from the input pins to determine the node and element connectivity.
• Constructs the Y-matrix by eliminating specified elements and non-essential nodes.
• Computes admittance matrices over a frequency range given by freq_range.
• Frequencies are logarithmically spaced and internally converted to rad/s (ω = 2πf).

Output

• Returns Ybus, an array of admittance matrices (one per frequency point).
• The output matrices exclude ground-connected output nodes.

Exceptions

• Throws ArgumentError if input_pins is empty.

Example

net = create_network(...)  # Assume a valid network object
Y_matrices = make_y_matrix(net, input_pins=["N1", "N2"], freq_range=(0.01, 10000, 2000))

make_z(net::Network, dict::Dict{Symbol, Array{Union{Symbol,Int}}}, 
       start_pins::Array{Symbol}, end_pins::Array{Symbol}, s::Complex)

Computes the impedance matrix (Z-matrix) of a given electrical network between specified start and end pins using component equations and Kirchhoff’s laws.

Arguments

• net::Network: The electrical network model for which impedance is calculated.
• dict::Dict{Symbol, Array{Union{Symbol,Int}}}: A dictionary containing:
  • :node_list: List of network nodes.
  • :element_list: List of elements in the network.
  • :output_list: List of output (grounded) nodes.
• start_pins::Array{Symbol}: The input pins where current is injected.
• end_pins::Array{Symbol}: The output pins where voltage is measured.
• s::Complex: Complex frequency variable (s = jω for steady-state AC analysis).

Behavior

• Constructs a system matrix incorporating Kirchhoff’s Current Law (KCL) and individual component equations using their ABCD parameters.
• Handles various elements, including converters and synchronous machines, by forming the appropriate impedance representation.
• Solves a linear system to obtain the impedance between the specified pins.

Output

• Returns Z, the impedance matrix relating input currents to output voltages.

Exceptions

• Ensures valid indexing when accessing nodes and elements in the network.

Example

net = create_network(...)  # Assume a valid network object
Z_matrix = make_z(net, dict, start_pins=["N1"], end_pins=["N2"], s=1im*2π*60)

mmc(; elec=ElectricalMMC(), meas=Measurement(), sync,
    delta_control, sigma_control,
    modulation=UncompensatedModulation(), setpoint=Setpoint(),
    limits=Limits(), connection=true)

Construct a modular multilevel converter from composable electrical, signal, control, and modulation blocks.

Arguments

• elec: MMC electrical plant and physical base quantities.
• meas: Converter measurement and filtering block.
• sync: Synchronization model, such as PLLSynchronization or NoSynchronization.
• delta_control: AC-side differential-current control structure.
• sigma_control: Internal sum/circulating-current control structure.
• modulation: MMC modulation and delay model.
• setpoint: AC/DC steady-state operating point.
• limits: Active- and reactive-power limits in the converter base.
• connection: Whether NetworkBuilder includes the converter in the system.

Returns

• An Element with one DC terminal group and one transformed AC terminal group.

Notes

The selected synchronization and outer-control blocks determine the AC and DC power-flow control modes. Frequency-domain evaluation solves the converter's nonlinear equilibrium at the resulting operating point before linearization.

Examples

converter = mmc(
    sync = PLLSynchronization(),
    delta_control = ΔdqControlGFL(
        outer_active = OuterActivePowerControl(),
        outer_reactive = OuterReactiveQControl(),
        occ = InnerCurrentPIControl(),
    ),
    sigma_control = ΣdqzControlTEC(),
    setpoint = Setpoint(Pac = 100.0, Qac = 0.0, Vac = 220.0, Vdc = 640.0),
)

overhead_line(; length=0, conductors=Conductors(),
              groundwires=Groundwires(), earth_parameters=(1, 1, 1),
              transformation=false, connection=true)

Construct a frequency-dependent overhead transmission-line element.

Arguments

• length: Physical line length \[m\].
• conductors: Phase-conductor bundle and tower geometry.
• groundwires: Optional ground-wire geometry and material data.
• earth_parameters: Earth relative permeability \[dimensionless\], relative permittivity \[dimensionless\], and resistivity \[Ω·m\].
• transformation: Whether to expose a supported transformed representation.
• connection: Whether NetworkBuilder includes the element in the system.

Returns

• An Element with one input and output terminal per conductor bundle.

Notes

Conductors supports explicit positions or the implemented :flat, :vertical, :delta, :offset, and :concentric organizations. Frequency evaluation retains the complete self and mutual series-impedance and shunt- admittance matrices.

Errors

• Throws ArgumentError for an unknown keyword or an unsupported conductor organization/order during parameter evaluation.

Examples

line = overhead_line(
    length = 90e3,
    conductors = Conductors(
        organization = :flat,
        nᵇ = 3,
        nˢᵇ = 1,
        Rᵈᶜ = 0.063,
        rᶜ = 0.015,
        yᵇᶜ = 30.0,
        Δxᵇᶜ = 10.0,
        dˢᵃᵍ = 10.0,
    ),
    earth_parameters = (1.0, 1.0, 100.0),
)

power_flow(
    net::Network
) -> Tuple{Dict{String, Any}, Any, Dict{Any, Any}, Dict{Any, Any}}

Build the PowerModelsACDC representation of a Classic network, solve its AC/DC power flow, and update active-element setpoints with the solved operating point.

Arguments

• net: classic network to solve.

Returns

• result: PowerModelsACDC solver result.
• data: PowerModelsACDC input dictionary.
• nodes2bus: mapping from Classic network nodes to PowerModels bus identifiers.
• elem2comp: mapping from Classic elements to PowerModels component identifiers.

Notes

This method mutates active elements in net by replacing their operating setpoints with solved values.

response_kind(result::FrequencyResponseResult) -> Symbol

Return the physical response represented by a frequency-response result.

response_nodes(result::FrequencyResponseResult) -> Any

Return the ordered node labels associated with the response matrix.

response_values(result::FrequencyResponseResult) -> Any

Return the response tensor. Its dimensions are node, node, and frequency.

tlc(; elec=ElectricalTLC(), meas=Measurement(),
    sync=NoSynchronization(), outerActive=NoOuterActiveControl(),
    outerReactive=NoOuterReactiveControl(),
    innerVoltage=NoInnerVoltageControl(),
    innerCurrent=NoInnerCurrentControl(), mod=NoModulation(),
    setpoint=Setpoint(), limits=Limits(), connection=true)

Construct a two-level voltage-source converter from composable plant, signal, control, and modulation blocks.

Arguments

• elec: TLC electrical plant and physical base quantities.
• meas: Converter measurement and filtering block.
• sync: Synchronization model.
• outerActive: Active-power or DC-voltage outer control.
• outerReactive: Reactive-power or AC-voltage outer control.
• innerVoltage: Inner voltage-control block.
• innerCurrent: Inner current-control block.
• mod: Modulation and delay block.
• setpoint: AC/DC steady-state operating point.
• limits: Active- and reactive-power limits in the converter base.
• connection: Whether NetworkBuilder includes the converter in the system.

Returns

• An Element with one DC terminal group and one transformed AC terminal group.

Notes

The selected synchronization and outer-control blocks determine the converter's AC and DC power-flow modes. Frequency-domain evaluation equilibrates and linearizes the complete numeric converter at the solved operating point.

Examples

converter = tlc(
    sync = PLLSynchronization(),
    outerActive = OuterActivePowerControl(),
    outerReactive = OuterReactiveQControl(),
    innerCurrent = InnerCurrentPIControl(),
    setpoint = Setpoint(Pac = 100.0, Qac = 0.0, Vac = 220.0, Vdc = 640.0),
)

transformer(def=:explicit; transformer_kwargs...)

Construct a one-phase or balanced three-phase transformer element.

Arguments

• def: Parameterization mode. :explicit uses the supplied equivalent-circuit values. :tests derives them from the open- and short-circuit test fields.
• pins: Number of phase-domain terminals. Default: 1.
• organization: Three-phase winding organization, :YY or :ΔY.
• ω: Rated angular frequency \[rad/s\].
• V₁ᵒ, V₁ˢ, V₂ᵒ, V₂ˢ: Open- and short-circuit voltages \[V\] used by def=:tests.
• I₁ᵒ, I₁ˢ: Open- and short-circuit primary currents \[A\].
• P₁ᵒ, P₁ˢ: Open- and short-circuit losses \[W\].
• n: Primary-to-secondary turns ratio \[dimensionless\].
• Lₚ, Lₛ, Lₘ: Primary, secondary, and magnetizing inductances \[H\].
• Rₚ, Rₛ, Rₘ: Primary, secondary, and magnetizing resistances \[Ω\].
• Cₜ, Cₛ: Turn-to-turn and stray capacitances \[F\].
• hasRω: Whether winding resistance is frequency dependent.
• k: Winding-resistance frequency exponent \[dimensionless\].
• transformation: Whether to expose transformed three-phase coordinates.

Returns

• An Element containing the detailed transformer model.

Errors

• Throws ArgumentError for an unknown transformer keyword. Invalid or zero test data can also make the :tests calculation undefined.

Examples

transformer_element = transformer(
    :explicit;
    pins = 3,
    organization = :YY,
    n = 1.1,
    Rₚ = 0.1,
    Lₚ = 1e-3,
    Rₛ = 0.1,
    Lₛ = 1e-3,
)

unwrap!(values[, period])

Unwrap an angular sequence in place by selecting the nearest branch of period at each sample.

PowerImpedance.Grammar

Define the package-local problem, formulation, result, and parameter-space language used by PowerImpedance calculations.

AbsoluteError(errors)

Mark nonnegative errors as absolute standard deviations in the same physical unit as the corresponding nominal values.

AbsoluteError(vals::T) where {T<:Tuple}

Construct an absolute-error marker from tuple-valued standard deviations.

Errors

• Throws ArgumentError for non-real, non-finite, or negative values.

AbsoluteGrid

Represent the Cartesian product of nominal values and absolute standard deviations in the same physical unit as the nominal value.

Monte Carlo entry points sample each case with distribution=:normal or with the variance-equivalent distribution=:uniform law.

AbsoluteGrid(vals::V, abs_err::P) where {V<:Tuple,P<:Tuple}

Construct an absolute-uncertainty axis from tuple-valued nominal values and standard deviations expressed in the same physical units.

Errors

• Throws ArgumentError for non-real or non-finite nominal values, or for non-real, non-finite, or negative uncertainty values.

Abstract supertype for numerical formulations.

Abstract supertype for deterministic parameter-study results containing T.

Abstract supertype for calculation problem definitions.

Abstract supertype for completed calculation results.

Abstract supertype for uncertainty-study results containing T.

struct Combinatorial{F, B, P} <: AbstractFormulation

Enumerate every deterministic configuration and apply inner.

• inner::Any: Scalar formulation applied to each materialized problem.

• backend::Type: Resolved higher-order execution backend.

• failure_policy::Symbol: Behavior when a configuration fails.

struct Configuration{Target, F, V<:Tuple, N<:Tuple, B<:Tuple}

Represent one resolved deterministic choice while retaining uncertainty descriptors for later materialization or sampling.

• target::Any: Callable that constructs Target from the resolved axis values.

• values::Tuple: Resolved values supplied to target.

• names::Tuple: Parameter names corresponding to values.

• bindings::Tuple: Selections retained for coupled axes.

DeterministicGrid

Represent a finite, explicitly enumerated parameter axis.

Use Grid to construct this type from one value or a collection of alternatives.

Select retained whole-trial values from a completed donor checkpoint.

struct Gridspace{Target, F, A<:Tuple, N<:Tuple, C} <: PowerImpedance.Grammar.AbstractDefinition{Target}

Represent a lazy space of complete Target configurations. combine is local to this space and is either :product or :zip.

• target::Any: Callable that constructs Target from one selection of the direct axes.

• axes::Tuple: Direct parameter or object-valued axes.

• names::Tuple: Parameter names corresponding to axes.

• combine::Any: Local composition rule represented by Val{:product} or Val{:zip}.

Select deterministic line parameters from a completed donor checkpoint.

struct LinearError{F, B, P} <: AbstractFormulation

Propagate first-order uncertainty through inner without random sampling.

• inner::Any: Scalar formulation evaluated with uncertainty-aware numeric values.

• backend::Type: Resolved higher-order execution backend.

• failure_policy::Symbol: Behavior when a configuration fails.

struct LinearErrorResult{T, F, V<:AbstractArray{T, 1}, S, D} <: AbstractUncertaintyResult{T}

Store primitive results calculated by direct first-order propagation.

• formulation::Any: LinearError formulation used for the study.

• values::AbstractVector: Uncertainty-aware primitive results aligned with space.

• space::Any: Resolved successful configuration manifests.

• details::Any: Named propagation metadata.

Construct an explicit Measurements moment surrogate from a donor checkpoint.

struct MonteCarlo{F, B, S, P} <: AbstractFormulation

Specify Monte Carlo evaluation of uncertain configurations.

• inner::Any: Scalar formulation applied to every numeric trial.

• backend::Type: Resolved higher-order execution backend.

• trials::Union{Nothing, Int64}: Requested trial count, or nothing for DKW sizing.

• distribution::Symbol: Primitive sampling distribution.

• seed::Any: Master random seed.

• confidence::Float64: Simultaneous confidence level.

• tolerance::Float64: DKW tolerance.

• return_samples::Bool: Whether raw numeric trial samples are retained.

• failure_policy::Symbol: Behavior when a configuration or trial fails.

struct MonteCarloResult{T, F, Sv, S, D} <: AbstractUncertaintyResult{T}

Store Monte Carlo statistics and their resolved trial configurations.

• formulation::Any: MonteCarlo formulation used for the study.

• stats::Any: Statistics aligned with configuration groups.

• space::Any: Resolved successful trial manifests.

• details::Any: Named sampling, replay, and failure metadata.

struct ParametricProblem{S, O} <: AbstractProblemDefinition

Specify evaluation of a PowerImpedance-owned parameter space.

• space::Any: Space whose configurations materialize owned problems.

• options::Any: Options merged into each scalar calculation.

struct ParametricResult{T, F, V<:AbstractArray{T, 1}, S, D} <: AbstractParametricResult{T}

Store deterministic primitive results and their resolved configurations.

• formulation::Any: Higher-order formulation used for the study.

• values::AbstractVector: Primitive results aligned with space.

• space::Any: Resolved successful configuration manifests.

• details::Any: Named execution metadata.

RelativeGrid

Represent the Cartesian product of nominal values and relative standard deviations expressed in percent.

Monte Carlo entry points sample each case with distribution=:normal or with the variance-equivalent distribution=:uniform law.

RelativeGrid(vals::V, rel_err::P) where {V<:Tuple,P<:Tuple}

Construct a relative-uncertainty axis from tuple-valued nominal values and percentage standard deviations.

Errors

• Throws ArgumentError for non-real or non-finite nominal values, or for non-real, non-finite, or negative uncertainty values.

struct UncertainValue{T, S<:PowerImpedance.Grammar.AbstractUncertainty, E}

Store a dependency-free uncertainty descriptor. sigma is an absolute standard uncertainty in the same physical unit as nominal.

• nominal::Any: Nominal parameter value.

• sigma::Any: Absolute standard uncertainty in the same physical unit as nominal.

• style::PowerImpedance.Grammar.AbstractUncertainty: Origin of the uncertainty declaration.

Grid(values)
Grid(values, relative_errors)
Grid(values, AbsoluteError(errors))
component(Grid, keyword arguments...)

Create an explicit deterministic or uncertain parameter axis. Collections passed directly to Grid are expanded. Component Gridspace constructors retain ordinary collections as one atomic value.

Arguments

• values: one nominal value or a collection of explicitly enumerated values.
• relative_errors: relative standard deviations in percent.
• errors: an AbsoluteError containing standard deviations in the physical unit of values.

Returns

• A DeterministicGrid, RelativeGrid, or AbsoluteGrid.

Passing the Grid function itself as the first positional argument to any component or configuration constructor selects its lazy NetworkBuilder method. The call impedance(Grid, z=Grid([1.0, 2.0]), pins=1) returns a Gridspace. Calling impedance(z=1.0, pins=1) uses the scalar constructor. Julia does not dispatch on keyword argument types, so the positional marker selects the lazy method.

Notes

The sampling law is selected by the Monte Carlo entry point. :normal uses Normal(nominal, standard_deviation). :uniform uses the interval nominal ± √3 standard_deviation, which has the same variance. Separate Gridspace axes are sampled independently unless a purpose-built object provides specialized joint-sampling dispatch.

Calculate problem with formulation.

Return the resolved parameterization of configuration as a named tuple.

Return a lazy iterator over the resolved configurations in space.

Materialize a resolved configuration through its target constructor.

Prepare a completed PowerImpedance checkpoint for a subsequent formulation.

Project a completed external checkpoint into an explicit accepted input.

Add a keyword constructor that returns a lazy Gridspace.

Add promoted numeric constructors and numeric convert support to a struct.

Select the validated PowerModelsACDC power-flow formulation.

Select frequency-domain admittance linearization.

struct AdmittanceLookup{T<:Number}

Store element admittance functions and their positions in the complete nodal admittance matrix.

• Y!::Array{FunctionWrappers.FunctionWrapper{Nothing, Tuple{AbstractArray{T, 3}, AbstractVector{<:Complex}}}, 1} where T<:Number: In-place element admittance functions.

• indices::Vector{Matrix{Tuple{Int64, Int64}}}: Nodal-matrix position of every local admittance entry.

struct LinearizationProblem{N<:PowerImpedance.NetworkBuilder.NetworkState, F} <: AbstractProblemDefinition

Specify admittance linearization of one materialized network.

• network::PowerImpedance.NetworkBuilder.NetworkState: Materialized network to linearize.

• powerflow::Any: Previously calculated power-flow result, or nothing.

struct NetworkLookup

Map element and node names to integer frequency-model indices.

• elements::Dict{Symbol, Int64}: Element name to admittance index.

• nodes::Dict{Symbol, Int64}: Node name to nodal-matrix index.

struct NetworkModel{T<:Number}

Store the linearized frequency-domain representation of one network.

• element_admittances::PowerImpedance.NetworkBuilder.AdmittanceLookup: Element admittance functions and their nodal positions.

• active_elements::Vector{Int64}: Indices of active elements.

• passive_elements::Vector{Int64}: Indices of passive elements.

• grounded_nodes::Vector{Int64}: Indices eliminated as grounded or ideal-source nodes.

• retained_nodes::Vector{Int64}: Default retained-node indices for active-network responses.

• indices::PowerImpedance.NetworkBuilder.NetworkLookup: Element and node name lookup tables.

NetworkModel(network::NetworkState, operating_point)

Construct the frequency-domain network model at a calculated operating point. Ideal sources are omitted from the element admittance lookup and their external nodes are included in the grounded-node selection.

mutable struct NetworkState

Store one materialized NetworkBuilder system with ordinary numeric elements, topology, and numerical options.

Construct systems with define rather than calling this type directly.

• elements::NamedTuple: Materialized PowerImpedance elements indexed by name.

• topology::PowerImpedance.NetworkBuilder.NetworkTopology: Node–element incidence relation.

• options::NamedTuple: Numerical and power-flow options.

struct NetworkTopology

Store the node incidence relation used by NetworkBuilder calculations.

Each stored row identifies a node, its power-flow bus, an element side and terminal, and the electrical domain. Construct a topology through define or NetworkTopology(elements, connections).

• connections::TypedTables.Table{@NamedTuple{node::Symbol, bus::Int64, element::Symbol, side::Int64, terminal::Int64, domain::Int64}, 1, @NamedTuple{node::Vector{Symbol}, bus::Vector{Int64}, element::Vector{Symbol}, side::Vector{Int64}, terminal::Vector{Int64}, domain::Vector{Int64}}}: Typed node–element incidence rows.

NetworkTopology(elements, connections)

Construct the topology of a materialized network from named connection rows.

Arguments

• elements: Named tuple of ordinary PowerImpedance elements.
• connections: Tuple or vector of named tuples with the fields node, element, side, and terminal.

Returns

• A NetworkTopology with typed rows and deterministic bus numbering.

Errors

• Throws ArgumentError for malformed rows, missing elements, invalid ports, duplicate terminal assignments, or nodes that mix AC and DC terminals.

struct PowerFlowProblem{N<:PowerImpedance.NetworkBuilder.NetworkState} <: AbstractProblemDefinition

Specify an AC/DC power-flow calculation for one materialized network.

• network::PowerImpedance.NetworkBuilder.NetworkState: Materialized network whose operating point is required.

define(
    elements::NamedTuple,
    connections::Union{Tuple, AbstractVector};
    options
) -> Union{PowerImpedance.NetworkBuilder.NetworkState, Gridspace{PowerImpedance.NetworkBuilder.NetworkState, F, A, Tuple{Symbol, Symbol}, Val{:product}} where {F, A<:Tuple}}

Construct a NetworkState or a lazy space of network states from scalar and parametric elements.

Arguments

• elements: Named tuple of scalar elements and element Gridspaces.
• connections: tuple or vector of named topology rows.
• options: builder and power-flow options.

Returns

• A NetworkState when every input is scalar.
• A Gridspace{NetworkState} when an element or direct option is parametric.

determine_impedance(model::NetworkModel; nets, elim_elements=Symbol[],
                    freq_range=(0.001, 10000, 2000))

Calculate the nodal impedance seen at nets from an already linearized NetworkModel. Elements named by elim_elements are omitted before ground elimination and Kron reduction. freq_range is (minimum, maximum, count) in hertz.

Return the complex impedance tensor and angular-frequency vector in radians per second. The tensor dimensions are (length(nets), length(nets), count).

solve(builder::NetworkState)

Build and solve one ordinary numeric NetworkBuilder system.

Arguments

• builder: materialized system definition.

Returns

• A named tuple containing powerflow and the constructed scalar network.

Notes

The Gridspace{NetworkState} overload applies this scalar pipeline to every deterministic case and numeric Monte Carlo trial.

update!(
    builder::PowerImpedance.NetworkBuilder.NetworkState;
    elements,
    topology,
    options
) -> PowerImpedance.NetworkBuilder.NetworkState

Replace fields of an existing NetworkState.

Arguments

• builder: mutable system definition to update.
• elements: replacement named tuple of scalar elements.
• topology: replacement node-element incidence relation.
• options: replacement builder options.

Returns

• The updated network.

Notes

Calculated operating points are returned by compute and are not cached here.

UnitHandler

Define physical-quantity tags, display units, metric scaling, and numeric presentation independently of a plotting backend.

Metric-prefix exponents used when scaling physical quantities.

Display symbols for the supported metric prefixes.

Display symbols for the supported unit names.

struct QuantityTag{Q}

Identify the physical meaning of plotted or reported numeric values.

struct Unit

Represent one physical unit and its metric prefix.

• name::Symbol: Unit name, such as :ohm, :hertz, or :db_ohm.

• prefix::Symbol: Metric prefix, such as :base, :milli, or :kilo.

Unit(name=:dimensionless, prefix=:base)

Construct a physical unit after validating its metric prefix.

struct Units

Represent a composite physical unit. Numerator and denominator factors are stored separately.

• base::Vector{PowerImpedance.UnitHandler.Unit}: Numerator units.

• per::Vector{PowerImpedance.UnitHandler.Unit}: Denominator units.

default_unit(
    _::PowerImpedance.UnitHandler.QuantityTag
) -> PowerImpedance.UnitHandler.Units

Return the native unit of a physical quantity.

display_unit(
    quantity::PowerImpedance.UnitHandler.QuantityTag
) -> PowerImpedance.UnitHandler.Units

Return the preferred display unit of a physical quantity.

format_value(value::Number; digits) -> Any

Format a deterministic value or a value with standard uncertainty. Values with nonzero uncertainty are written as value ± uncertainty.

get_exp(unit::PowerImpedance.UnitHandler.Units) -> Int64

Return the net base-10 prefix exponent of a composite unit.

get_label(unit::PowerImpedance.UnitHandler.Units) -> String

Return the display label for a composite unit.

get_label(unit::PowerImpedance.UnitHandler.Unit) -> String

Return the display label for one unit.

get_label(
    _::PowerImpedance.UnitHandler.QuantityTag{Q}
) -> String

Return a human-readable quantity label without units.

get_symbol(
    _::PowerImpedance.UnitHandler.QuantityTag{Q}
) -> String

Return the conventional symbol for a physical quantity.

nominal(value::Number) -> Number

Return the nominal numeric value. Optional uncertainty extensions specialize this method for their scalar types.

quantity(
    name::Symbol
) -> PowerImpedance.UnitHandler.QuantityTag

Construct the quantity tag named by name.

scale_factor(
    quantity::PowerImpedance.UnitHandler.QuantityTag,
    target::PowerImpedance.UnitHandler.Units
) -> Float64

Return the factor that converts a quantity from its native unit to target.

scale_factor(
    source::PowerImpedance.UnitHandler.Units,
    target::PowerImpedance.UnitHandler.Units
) -> Float64

Return the factor that converts values from source units to target units.

scale_factor(
    target::PowerImpedance.UnitHandler.Units
) -> Float64

Return the factor that converts unprefixed values into target units.

standard_uncertainty(value::Number) -> Any

Return the standard uncertainty of a number. Deterministic numbers return zero. Optional uncertainty extensions specialize this method.

units(
    prefix::Symbol,
    name::Symbol;
    per
) -> PowerImpedance.UnitHandler.Units

Construct a simple unit with an optional denominator. For example, units(:base, :ohm; per=(:kilo, :meter)) represents Ω/km.

PlotBuilder

Build backend-neutral plotting descriptions from typed completed results. Optional Makie extensions render the resulting RenderDefinition values.

AbstractPlotDefinition

Supertype for backend-neutral PlotBuilder recipe identifiers.

Abstract supertype for backend-neutral grid track sizes.

AxisDefinition(dim, quantity, units, label[, scale]; allowed_scales, exponent, attributes)

Describe one backend-neutral plot axis.

ColorbarDefinition(label, colormap, limits, ticks; slot=:colorbars)

Declare one backend-neutral colorbar and its destination slot.

Define a grid track sized from its rendered content.

Declare page-level reset and SVG controls and their destination slot.

Declare the SVG theme, base filename, and automatic-open behavior.

FixedTrack(value)

Define a nonnegative fixed-size grid track in pixels.

FixedTrack(value)

Construct a fixed grid track of value pixels.

Arguments

• value: finite, nonnegative track size in px.

Returns

• A validated FixedTrack.

Errors

• Throws ArgumentError when value is negative or non-finite.

GridArea(rows, columns)

Select positive, one-based row and column spans in a named grid.

GridArea(rows, columns)

Construct an area from inclusive one-based row and column spans.

Arguments

• rows: nonempty range of positive row indices.
• columns: nonempty range of positive column indices.

Returns

• A validated GridArea.

Errors

• Throws ArgumentError for empty or nonpositive spans.

GridDefinition(name; parent, area, rows, columns, rowgap, columngap, padding)

Declare one grid in a backend-neutral named layout tree.

LayoutDefinition(name, grids, slots)

Define and validate a backend-neutral named grid tree.

LayoutDefinition(name, grids, slots)

Construct and validate a named grid layout.

Arguments

• name: layout identity.
• grids: root and nested GridDefinition declarations.
• slots: named SlotDefinition destinations.

Returns

• A validated LayoutDefinition.

Errors

• Throws the validation errors documented by validate.

struct LegendDefinition

Declare legend visibility, interactivity, destination slot, and overflow mode.

• enabled::Bool: Whether to render a legend.

• interactive::Bool: Whether legend entries control series visibility.

• slot::Symbol: Destination legend slot.

• overflow::Symbol: Overflow mode, either :ellipsis or :show_all.

LegendDefinition(
;
    enabled,
    interactive,
    slot,
    overflow
) -> PowerImpedance.PlotBuilder.LegendDefinition

Construct a LegendDefinition.

Keywords

• enabled: render the legend. Default: true.
• interactive: let legend entries control series visibility. Default: true.
• slot: destination layout slot. Default: :legend.
• overflow: use :ellipsis to show the largest fitting entry prefix followed by (...), or :show_all to render every entry. Default: :ellipsis.

Returns

• A validated LegendDefinition.

Errors

• Throws ArgumentError when overflow is unsupported.

PageDefinition(title, size, key, layout, views; controls, legend, colorbars, status, export_definition)

Describe one complete render page using typed backend-neutral components.

PlacementDefinition([slot], [area])

Assign a view to a named slot with automatic or explicit grid placement.

PlotRecipe(object, input, renderer)

Store a domain object together with typed semantic and renderer options.

struct PrimitiveRender{S}

Store plots and extension-owned state returned by a custom PlotBuilder primitive renderer.

• plots::Vector{Any}: Makie plot objects owned by the rendered primitive.

• state::Any: Extension-owned state retained by the built UIPlot.

RelativeTrack([weight])

Construct a grid track receiving weight shares of available space.

Arguments

• weight: finite, positive dimensionless share. Default: 1.

Returns

• A validated RelativeTrack.

Errors

• Throws ArgumentError when weight is nonpositive or non-finite.

RelativeTrack([weight])

Define a grid track that receives a positive share of available space.

RenderDefinition(definition, figures)

Store validated pages produced for one plot definition type.

SeriesDefinition(kind, xdata, ydata, zdata, label; group, visible, attributes)

Describe one backend-neutral plotting primitive and its data.

SlotDefinition(name, parent, area; halign, valign)

Declare a named content destination inside a grid.

Declare status-line visibility, initial text, and destination slot.

UIPlot

Hold a backend-neutral render definition together with one built figure, its panels, controls, and backend context. A rendered recipe returns one UIPlot per declarative page. Call close(plot) when the handle is no longer needed to release its backend resources and observable callbacks.

ViewDefinition(xaxis, yaxis, zaxis, title, series, key; placement, aspect, limits, attributes)

Describe one plot panel and its placement.

axis_attributes(::Type{S}, dim, recipe)

Return visual renderer attributes for one axis.

axis_exponent(::Type{S}, dim, recipe, series)

Return the base-ten display exponent for linear ticks on one axis.

axis_label(::Type{S}, dim, quantity, unit, recipe)

Return the displayed label for one axis.

axis_quantity(::Type{S}, dim, recipe)

Return the semantic quantity tag for one axis.

axis_scale(::Type{S}, dim, recipe)

Return the initial scale for one axis.

axis_scales(::Type{S}, dim, recipe, series)

Return the scales available to one fully resolved axis.

axis_unit(::Type{S}, dim, quantity, recipe)

Return the display units for one axis quantity.

Build a RenderDefinition through the active optional plotting extension.

colorbar_definitions(::Type{S}, recipe)

Return typed colorbar declarations for a recipe page.

control_definition(::Type{S}, recipe)

Return the typed interactive-control declaration for a recipe page.

default_figsize(::Type{S}, recipe)

Return the default page width and height in pixels for a recipe.

default_title(::Type{S}, recipe)

Return the title for a semantic page or view facet.

dispatch_on(::Type{S})

Return the domain type accepted by plot definition S.

export_definition(::Type{S}, recipe, title)

Return the typed SVG export declaration for a recipe page.

Export the current state of a UIPlot through an explicitly loaded CairoMakie extension.

geom_axes(::Type{S}, mode, recipe, page_key, view_key)

Return the dimensions used by a recipe view.

group_facets(::Type{S}, mode, recipe, page_key)

Return semantic series facets for the selected recipe page.

grouping_mode(::Type{S}, mode, recipe)

Return the value-dispatched grouping mode for a resolved recipe.

input_defaults(::Type{S}, object)

Return defaults for every name declared by input_kwargs(S).

input_kwargs(::Type{S})

Return semantic keyword names accepted by plot definition S.

layout_definition(::Type{S}, recipe)

Return a layout preset symbol or complete LayoutDefinition for a recipe page.

layout_preset(::Val{name}, view_count)

Construct a built-in named layout preset for view_count views.

Errors

• ArgumentError when name is not :single, :grid, :preview, or :material_scale.

legend_definition(::Type{S}, recipe)

Return the typed legend declaration for a recipe page.

legend_label(::Type{S}, recipe, series_key)

Return the legend label for one semantic series facet.

make_axes(::Type{S}, mode, recipe, page_key, view_key)

Construct backend-neutral axes for one view.

make_pages(::Type{S}, mode, grouping, recipe)

Construct every backend-neutral page for a resolved recipe.

make_render(
    ::Type{S<:PowerImpedance.PlotBuilder.AbstractPlotDefinition},
    object;
    kwargs...
) -> PowerImpedance.PlotBuilder.RenderDefinition

Materialize a domain object through the PlotBuilder grammar. Plot definitions specialize accessors while retaining this rendering sequence.

make_series(::Type{S}, mode, grouping, recipe, page_key, view_key, axes)

Construct backend-neutral primitive definitions for one view.

make_views(::Type{S}, mode, grouping, recipe, page_key)

Construct backend-neutral views for one semantic page facet.

page_facets(::Type{S}, mode, recipe)

Return semantic page facets for recipes using :faceted_pages.

page_identity(::Type{S}, recipe, page_key)

Return the semantic NamedTuple identity for one page.

parse_kwargs(::Type{S}, object, kwargs)

Validate and split caller input into the semantic and renderer options declared by a recipe. Unsupported keywords are errors.

plot_kind(::Type{S}, recipe, series_key)

Return the primitive symbol used by one semantic series facet.

recipe_mode(::Type{S}, recipe)

Return the value-dispatched plotting mode for a resolved recipe.

Render an extension-owned PlotBuilder primitive on a backend axis.

Implementations return a PrimitiveRender containing the Makie plots and the extension-owned state retained by the resulting UIPlot.

renderer_defaults(::Type{S}, object)

Return defaults for every name declared by renderer_kwargs(S).

renderer_kwargs(::Type{S})

Return recipe-specific renderer keyword names accepted by plot definition S.

resolve_input(::Type{S}, recipe)

Validate and enrich parsed recipe input before materialization.

series_attributes(::Type{S}, recipe, series_key)

Return backend-neutral visual attributes for one series facet.

series_data(::Type{S}, dim, recipe, series_key)

Return data for axis dim and one semantic series facet.

series_group(::Type{S}, recipe, series_key)

Return the visibility-group symbol for one semantic series facet.

series_visible(::Type{S}, recipe, series_key)

Return the initial visibility of one semantic series facet.

status_definition(::Type{S}, recipe)

Return the typed status-line declaration for a recipe page.

validate(definition)

Validate a layout, page, or complete render definition and return it.

Errors

• ArgumentError, DimensionMismatch, or DomainError when semantic fields, data shapes, layout relationships, placements, or logarithmic data are invalid.

view_aspect(::Type{S}, recipe)

Return the aspect declaration for one view.

view_attributes(::Type{S}, recipe)

Return visual renderer attributes for one view.

view_key(::Type{S}, recipe)

Return the semantic identity for one view.

view_limits(::Type{S}, recipe)

Return explicit axis limits for one view, or nothing.

view_placement(::Type{S}, recipe)

Return the named-slot placement for one view.

PlotBuilder.BackendHandler

Coordinate optional Makie backends without loading them from the core package.

Return whether backend has been explicitly loaded.

Return the active Makie backend as :cairo, :gl, :wgl, :unknown, or :none.

Ensure that an explicitly loaded backend is active.

Create a backend-specific screen when supported.

Display a Makie figure through the loaded plotting extension.

set_backend!(backend; force=false)

Activate an explicitly loaded Makie backend.

force is retained for source compatibility and has no effect.

Run f with an explicitly loaded backend and restore the previous backend.