API reference

LineCableModels.DataModel

The DataModel module provides data structures, constructors and utilities for modeling power cables within the LineCableModels.jl package. This module includes definitions for various cable components, and visualization tools for cable designs.

Overview

• Provides objects for detailed cable modeling with the CableDesign and supporting types: CircStrands, Strip, Tubular, Semicon, and Insulator.
• Includes objects for cable system modeling with the LineCableSystem type, and multiple formation patterns like trifoil and flat arrangements.
• Contains functions for calculating the base electric properties of all elements within a CableDesign, namely: resistance, inductance (via GMR), shunt capacitance, and shunt conductance (via loss factor).
• Offers visualization tools for previewing cable cross-sections and system layouts.
• Provides a library system for storing and retrieving cable designs.

Dependencies

• Base
• Colors
• DataFrames
• Dates
• LineCableModels.Commons
• LineCableModels.DataModel.BaseParams
• LinearAlgebra
• Makie
• Measurements
• Plots
• Printf
• Statistics

Exports

• CableComponent
• CableDesign
• CablePosition
• CablesLibrary
• CircStrands
• ConductorGroup
• Diameter
• Insulator
• InsulatorGroup
• LineCableSystem
• MaxFill
• NominalData
• RectStrands
• Sector
• SectorInsulator
• SectorParams
• Semicon
• Strip
• Thickness
• Tubular
• WireArray
• equivalent
• flat_formation
• get_outer_radius
• preview
• trifoil_formation

mutable struct CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a CableComponent, i.e. a group of AbstractCablePart objects, with the equivalent geometric and material properties:

• id::String: Cable component identification (e.g. core/sheath/armor).

• conductor_group::ConductorGroup: The conductor group containing all conductive parts.

• conductor_props::Material: Effective properties of the equivalent coaxial conductor.

• insulator_group::InsulatorGroup: The insulator group containing all insulating parts.

• insulator_props::Material: Effective properties of the equivalent coaxial insulator.

CableComponent(
    id::String,
    conductor_group::ConductorGroup,
    insulator_group::InsulatorGroup
) -> CableComponent

Weakly-typed constructor that infers the scalar type T from the two groups, coerces them if necessary, and calls the strict kernel.

Arguments

• id: Cable component identification.
• conductor_group: The conductor group (any ConductorGroup{S}).
• insulator_group: The insulator group (any InsulatorGroup{R}).

Returns

• A CableComponent{T} where T is the resolved scalar type.

Initializes a CableComponent object based on its constituent conductor and insulator groups. The constructor performs the following sequence of steps:

1. Validate that the conductor and insulator groups have matching radii at their interface.
2. Obtain the lumped-parameter values (R, L, C, G) from the conductor and insulator groups, which are computed within their respective constructors.
3. Calculate the correction factors and equivalent electromagnetic properties of the conductor and insulator groups:

Arguments

• id: Cable component identification (e.g. core/sheath/armor).
• conductor_group: The conductor group containing all conductive parts.
• insulator_group: The insulator group containing all insulating parts.

Returns

A CableComponent instance with calculated equivalent properties:

• id::String: Cable component identification.
• conductor_group::ConductorGroup{T}: The conductor group containing all conductive parts.
• conductor_props::Material{T}: Effective properties of the equivalent coaxial conductor.

* `rho`: Resistivity \[Ω·m\].
* `eps_r`: Relative permittivity \[dimensionless\].
* `mu_r`: Relative permeability \[dimensionless\].
* `T0`: Reference temperature \[°C\].
* `alpha`: Temperature coefficient of resistivity \[1/°C\].

• insulator_group::InsulatorGroup{T}: The insulator group containing all insulating parts.
• insulator_props::Material{T}: Effective properties of the equivalent coaxial insulator.

* `rho`: Resistivity \[Ω·m\].
* `eps_r`: Relative permittivity \[dimensionless\].
* `mu_r`: Relative permeability \[dimensionless\].
* `T0`: Reference temperature \[°C\].
* `alpha`: Temperature coefficient of resistivity \[1/°C\].

Examples

conductor_group = ConductorGroup(...)
insulator_group = InsulatorGroup(...)
cable = CableComponent("component_id", conductor_group, insulator_group)  # Create cable component with base parameters @ 50 Hz

See also

• calc_equivalent_rho
• calc_equivalent_mu
• calc_equivalent_eps
• calc_sigma_lossfact
• calc_solenoid_correction

mutable struct CableDesign{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents the design of a cable, including its unique identifier, nominal data, and components.

• cable_id::String: Unique identifier for the cable design.

• nominal_data::Union{Nothing, NominalData{T}} where T<:Union{Float64, Measurements.Measurement{Float64}}: Informative reference data.

• components::Array{CableComponent{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Vector of cable components.

CableDesign(
    cable_id::String,
    component::CableComponent;
    nominal_data
) -> CableDesign

Weakly-typed constructor that infers the scalar type from the component (and nominal data if present), coerces values to that type, and calls the typed kernel.

CableDesign(
    cable_id::String,
    conductor_group::ConductorGroup,
    insulator_group::InsulatorGroup;
    component_id,
    nominal_data
) -> CableDesign

Constructs a CableDesign instance from conductor and insulator groups. Convenience wrapper that builds the component with reduced boilerplate.

CableDesign(
    cable_id::String,
    component::CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}};
    nominal_data
) -> CableDesign

Strict numeric kernel: constructs a CableDesign{T} from one component (typed) and optional nominal data (typed or nothing). Assumes all inputs are already at scalar type T.

Arguments

• cable_id: Unique identifier for the cable design.
• component: Initial CableComponent for the design.
• nominal_data: Reference data for the cable design. Default: NominalData().

Returns

• A CableDesign object with the specified properties.

Examples

conductor_group = ConductorGroup(central_conductor)
insulator_group = InsulatorGroup(main_insulator)
component = CableComponent(conductor_group, insulator_group)
design = CableDesign("example", component)

See also

• CableComponent
• ConductorGroup
• InsulatorGroup

CablePosition(
    cable::Union{Nothing, CableDesign},
    horz::Number,
    vert::Number
) -> CablePosition
CablePosition(
    cable::Union{Nothing, CableDesign},
    horz::Number,
    vert::Number,
    conn::Union{Nothing, Dict{String, Int64}}
) -> CablePosition

Weakly-typed constructor that infers T from the cable and coordinates, builds/validates the phase mapping, coerces inputs to T, and calls the typed kernel.

struct CablePosition{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a physically defined cable with position and phase mapping within a system.

• design_data::CableDesign: The CableDesign object assigned to this cable position.

• horz::Union{Float64, Measurements.Measurement{Float64}}: Horizontal coordinate [m].

• vert::Union{Float64, Measurements.Measurement{Float64}}: Vertical coordinate [m].

• conn::Vector{Int64}: Phase mapping vector (aligned with design_data.components).

Constructs a CablePosition instance with specified cable design, coordinates, and phase mapping.

Arguments

• cable: A CableDesign object defining the cable structure.
• horz: Horizontal coordinate [m].
• vert: Vertical coordinate [m].
• conn: A dictionary mapping component names to phase indices, or nothing for default mapping.

Returns

• A CablePosition object with the assigned cable design, coordinates, and phase mapping.

Examples

cable_design = CableDesign("example", nominal_data, components_dict)
xa, ya = 0.0, -1.0  # Coordinates in meters

# With explicit phase mapping
cablepos1 = CablePosition(cable_design, xa, ya, Dict("core" => 1))

# With default phase mapping (first component to phase 1, others to 0)
default_cablepos = CablePosition(cable_design, xa, ya)

See also

• CableDesign

mutable struct CablesLibrary

Represents a library of cable designs stored as a dictionary.

• data::Dict{String, CableDesign}: Dictionary mapping cable IDs to the respective CableDesign objects.

CablesLibrary() -> CablesLibrary

Constructs an empty CablesLibrary instance.

Arguments

• None.

Returns

• A CablesLibrary object with an empty dictionary of cable designs.

Examples

# Create a new, empty library
library = CablesLibrary()

See also

• CableDesign
• add!
• delete!
• LineCableModels.ImportExport.save
• DataFrame

struct CircStrands{T<:Union{Float64, Measurements.Measurement{Float64}}, U<:Int64} <: LineCableModels.DataModel.AbstractStrandsLayer{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents an array of wires equally spaced around a circumference of arbitrary radius, with attributes:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radius of the wire array [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radius of the wire array [m].

• radius_wire::Union{Float64, Measurements.Measurement{Float64}}: Radius of each individual wire [m].

• num_wires::Int64: Number of wires in the array [dimensionless].

• lay_ratio::Union{Float64, Measurements.Measurement{Float64}}: Ratio defining the lay length of the wires (twisting factor) [dimensionless].

• mean_diameter::Union{Float64, Measurements.Measurement{Float64}}: Mean diameter of the wire array [m].

• pitch_length::Union{Float64, Measurements.Measurement{Float64}}: Pitch length of the wire array [m].

• lay_direction::Int64: Twisting direction of the strands (1 = unilay, -1 = contralay) [dimensionless].

• material_props::Material: Material object representing the physical properties of the wire material.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Temperature at which the properties are evaluated [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of all wires in the array [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance per wire in the array [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius of the wire array [m].

CircStrands(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    radius_wire::Union{Float64, Measurements.Measurement{Float64}},
    num_wires::Int64,
    lay_ratio::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}},
    lay_direction::Int64
) -> LineCableModels.DataModel.CircStrands{T, Int64} where T<:Union{Float64, Measurements.Measurement{Float64}}

Constructs a CircStrands instance based on specified geometric and material parameters.

Arguments

• r_in: Internal radius of the wire array [m].
• radius_wire: Radius of each individual wire [m].
• num_wires: Number of wires in the array [dimensionless].
• lay_ratio: Ratio defining the lay length of the wires (twisting factor) [dimensionless].
• material_props: A Material object representing the material properties.
• temperature: Temperature at which the properties are evaluated [°C].
• lay_direction: Twisting direction of the strands (1 = unilay, -1 = contralay) [dimensionless].

Returns

• A CircStrands object with calculated geometric and electrical properties.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
circstrands = CircStrands(0.01, Diameter(0.002), 7, 10, material_props, temperature=25)
println(circstrands.mean_diameter)  # Outputs mean diameter in m
println(circstrands.resistance)     # Outputs resistance in Ω/m

See also

• Material
• ConductorGroup
• calc_tubular_resistance
• calc_circstrands_gmr
• calc_helical_params

ConductorGroup(
    component::CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}}
) -> ConductorGroup

Build a ConductorGroup equivalent for a CableComponent, preserving num_turns and num_wires from the original group.

Constructs a single-layer ConductorGroup{T} from the computed equivalent Tubular(component), but carries over bookkeeping fields needed by downstream corrections (e.g., solenoid correction using num_turns).

Constructs a ConductorGroup instance initializing with the central conductor part.

Arguments

• central_conductor: An AbstractConductorPart object located at the center of the conductor group.

Returns

• A ConductorGroup object initialized with geometric and electrical properties derived from the central conductor.

struct Diameter{T<:Real} <: LineCableModels.DataModel.AbstractRadius

Represents the diameter of a cable component.

• value::Real: Numerical value of the diameter [m].

struct Insulator{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractInsulatorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents an insulating layer with defined geometric, material, and electrical properties given by the attributes:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radius of the insulating layer [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radius of the insulating layer [m].

• material_props::Material: Material properties of the insulator.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Operating temperature of the insulator [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the insulating layer [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance of the insulating layer [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius of the insulator [m].

• shunt_capacitance::Union{Float64, Measurements.Measurement{Float64}}: Shunt capacitance per unit length of the insulating layer [F/m].

• shunt_conductance::Union{Float64, Measurements.Measurement{Float64}}: Shunt conductance per unit length of the insulating layer [S·m].

Insulator(
    component::CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}}
) -> Insulator

Constructs the equivalent coaxial insulation as an Insulator directly from a CableComponent, calling the strict positional constructor.

Arguments

• component: The CableComponent providing geometry and material.

Returns

• Insulator{T} with radii from component.insulator_group and material from component.insulator_props at the group temperature (fallback to T0).

Insulator(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}}
) -> Insulator

Constructs an Insulator object with specified geometric and material parameters.

Arguments

• r_in: Internal radius of the insulating layer [m].
• r_ex: External radius or thickness of the layer [m].
• material_props: Material properties of the insulating material.
• temperature: Operating temperature of the insulator [°C].

Returns

• An Insulator object with calculated electrical properties.

Examples

material_props = Material(1e10, 3.0, 1.0, 20.0, 0.0)
insulator_layer = Insulator(0.01, 0.015, material_props, temperature=25)

mutable struct InsulatorGroup{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractInsulatorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a composite coaxial insulator group assembled from multiple insulating layers.

This structure serves as a container for different AbstractInsulatorPart elements (such as insulators and semiconductors) arranged in concentric layers. The InsulatorGroup aggregates these individual parts and provides equivalent electrical properties that represent the composite behavior of the entire assembly, stored in the attributes:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Inner radius of the insulator group [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: Outer radius of the insulator group [m].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the entire insulator group [m²].

• shunt_capacitance::Union{Float64, Measurements.Measurement{Float64}}: Shunt capacitance per unit length of the insulator group [F/m].

• shunt_conductance::Union{Float64, Measurements.Measurement{Float64}}: Shunt conductance per unit length of the insulator group [S·m].

• layers::Array{LineCableModels.DataModel.AbstractInsulatorPart{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Vector of insulator layer components.

InsulatorGroup(
    component::CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}}
) -> InsulatorGroup

Build an InsulatorGroup equivalent for a CableComponent while maintaining geometric coupling to the equivalent conductor group.

Stacks a single insulating layer of equivalent material and thickness over the new conductor group created from the same component.

Constructs an InsulatorGroup instance initializing with the initial insulator part.

Arguments

• initial_insulator: An AbstractInsulatorPart object located at the innermost position of the insulator group.

Returns

• An InsulatorGroup object initialized with geometric and electrical properties derived from the initial insulator.

Examples

material_props = Material(1e10, 3.0, 1.0, 20.0, 0.0)
initial_insulator = Insulator(0.01, 0.015, material_props)
insulator_group = InsulatorGroup(initial_insulator)
println(insulator_group.layers)           # Output: [initial_insulator]
println(insulator_group.shunt_capacitance) # Output: Capacitance in [F/m]

LineCableSystem(
    system_id::String,
    line_length::Number,
    cable::CableDesign,
    horz::Number,
    vert::Number
) -> LineCableSystem
LineCableSystem(
    system_id::String,
    line_length::Number,
    cable::CableDesign,
    horz::Number,
    vert::Number,
    conn::Union{Nothing, Dict{String, Int64}}
) -> LineCableSystem

Weakly-typed convenience constructor. Builds a CablePosition from a CableDesign and coordinates, then constructs the system.

mutable struct LineCableSystem{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a cable system configuration, defining the physical structure, cables, and their positions.

• system_id::String: Unique identifier for the system.

• line_length::Union{Float64, Measurements.Measurement{Float64}}: Length of the cable system [m].

• num_cables::Int64: Number of cables in the system.

• num_phases::Int64: Number of actual phases in the system.

• cables::Array{CablePosition{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Cross-section cable positions.

LineCableSystem(
    system_id::String,
    line_length::Number,
    cable::CablePosition
) -> LineCableSystem

Weakly-typed constructor. Infers scalar type T from line_length and the cable (or its design), coerces as needed, and calls the strict kernel.

Strict numeric kernel. Builds a typed LineCableSystem{T} from a vector of CablePosition{T}.

Constructs a LineCableSystem with an initial cable position and system parameters.

Arguments

• system_id: Identifier for the cable system.
• line_length: Length of the cable system [m].
• cable: Initial CablePosition object defining a cable position and phase mapping.

Returns

• A LineCableSystem object initialized with a single cable position.

Examples

cable_design = CableDesign("example", nominal_data, components_dict)
cablepos1 = CablePosition(cable_design, 0.0, 0.0, Dict("core" => 1))

cable_system = LineCableSystem("test_case_1", 1000.0, cablepos1)
println(cable_system.num_phases)  # Prints number of unique phase assignments

See also

• CablePosition
• CableDesign

struct NominalData{T<:Union{Float64, Measurements.Measurement{Float64}}}

Stores nominal electrical and geometric parameters for a cable design.

• designation_code::Union{Nothing, String}: Cable designation as per DIN VDE 0271/0276.

• U0::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Rated phase-to-earth voltage [kV].

• U::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Rated phase-to-phase voltage [kV].

• conductor_cross_section::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the conductor [mm²].

• screen_cross_section::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the screen [mm²].

• armor_cross_section::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the armor [mm²].

• resistance::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Base (DC) resistance of the cable core [Ω/km].

• capacitance::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Capacitance of the main insulation [μF/km].

• inductance::Union{Nothing, T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Inductance of the cable (trifoil formation) [mH/km].

NominalData(
;
    designation_code,
    U0,
    U,
    conductor_cross_section,
    screen_cross_section,
    armor_cross_section,
    resistance,
    capacitance,
    inductance
) -> NominalData{Float64}

Weakly-typed constructor that infers the target scalar type T from the provided numeric kwargs (ignoring nothing and the string designation), coerces numerics to T, and calls the strict kernel.

If no numeric kwargs are provided, it defaults to Float64.

struct RectStrands{T<:Union{Float64, Measurements.Measurement{Float64}}, S<:LineCableModels.DataModel.RectStrandsShape} <: LineCableModels.DataModel.AbstractStrandsLayer{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a concentric layer of rectangular strands with defined geometric, material, and electrical properties:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radial boundary [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radial boundary [m].

• material_props::Material: Material properties of the conductive strands.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Operating temperature of the layer [°C].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Equivalent electrical resistance of the layer [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius (GMR) of the layer [m].

• shape::LineCableModels.DataModel.RectStrandsShape: Shape payload defining the internal geometric layout.

RectStrands(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    thickness::Union{Float64, Measurements.Measurement{Float64}},
    width::Union{Float64, Measurements.Measurement{Float64}},
    num_wires::Int64,
    lay_ratio::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}},
    lay_direction::Int64
) -> LineCableModels.DataModel.RectStrands

Constructs a RectStrands instance.

Arguments

• r_in: Internal radius of the layer [m].
• thickness: Radial thickness of the strands [m].
• width: Width of the individual rectangular strip [m].
• num_wires: Number of strands in the layer [dimensionless].
• lay_ratio: Ratio defining the lay length of the strands [dimensionless].
• material_props: A Material object containing physical properties.
• temperature: Operating temperature [°C].
• lay_direction: Twisting direction (1 = unilay, -1 = contralay) [dimensionless].

Returns

• A RectStrands object with calculated geometric and electrical properties.

Examples

material = Material(1.724e-8, 1.0, 1.0, 20.0, 0.00393)
layer = RectStrands(0.01, 0.002, 0.005, 10, 12.0, material, 25.0, 1)

struct Sector{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractConductorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a single sector-shaped conductor with defined geometric and material properties.

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Inner radius (not applicable, typically 0 for the central point) [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: Outer radius (equivalent back radius) [m].

• params::SectorParams: Geometric parameters defining the sector's shape.

• rotation_angle_deg::Union{Float64, Measurements.Measurement{Float64}}: Rotation angle of this specific sector around the cable's center [degrees].

• material_props::Material: Material properties of the conductor.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Operating temperature of the conductor [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the sector [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance of the sector [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius (GMR) of the sector (approximated) [m].

• vertices::Array{GeometryBasics.Point2{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Calculated vertices defining the polygon shape.

• centroid::GeometryBasics.Point2{T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Geometric centroid of the sector shape.

struct SectorInsulator{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractInsulatorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents an insulating layer surrounding a sector-shaped conductor.

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Inner radius (not applicable, defined by inner sector) [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: Outer radius (equivalent back radius of outer boundary) [m].

• inner_sector::Sector: The inner sector conductor that this insulator surrounds.

• thickness::Union{Float64, Measurements.Measurement{Float64}}: The thickness of the insulating layer [m].

• material_props::Material: Material properties of the insulator.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Operating temperature of the insulator [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the insulating layer [m²].

• shunt_capacitance::Union{Float64, Measurements.Measurement{Float64}}: Shunt capacitance (approximated) [F/m].

• shunt_conductance::Union{Float64, Measurements.Measurement{Float64}}: Shunt conductance (approximated) [S·m].

• outer_vertices::Array{GeometryBasics.Point2{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Calculated vertices of the outer boundary polygon.

struct SectorParams{T<:Union{Float64, Measurements.Measurement{Float64}}}

Holds the geometric parameters that define the shape of a sector conductor.

• n_sectors::Int64: Number of sectors in the full cable (e.g., 3 or 4).

• r_back::Union{Float64, Measurements.Measurement{Float64}}: Back radius of the sector (outermost curve) [m].

• d_sector::Union{Float64, Measurements.Measurement{Float64}}: Depth of the sector from the back to the base [m].

• r_corner::Union{Float64, Measurements.Measurement{Float64}}: Corner radius for rounding sharp edges [m].

• theta_cond_deg::Union{Float64, Measurements.Measurement{Float64}}: Angular width of the conductor's flat base/sides [degrees].

• d_insulation::Union{Float64, Measurements.Measurement{Float64}}: Insulation thickness [m].

struct Semicon{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractInsulatorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a semiconducting layer with defined geometric, material, and electrical properties given by the attributes:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radius of the semiconducting layer [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radius of the semiconducting layer [m].

• material_props::Material: Material properties of the semiconductor.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Operating temperature of the semiconductor [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the semiconducting layer [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance of the semiconducting layer [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius of the semiconducting layer [m].

• shunt_capacitance::Union{Float64, Measurements.Measurement{Float64}}: Shunt capacitance per unit length of the semiconducting layer [F/m].

• shunt_conductance::Union{Float64, Measurements.Measurement{Float64}}: Shunt conductance per unit length of the semiconducting layer [S·m].

Semicon(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}}
) -> Semicon

Constructs a Semicon instance with calculated electrical and geometric properties.

Arguments

• r_in: Internal radius of the semiconducting layer [m].
• r_ex: External radius or thickness of the layer [m].
• material_props: Material properties of the semiconducting material.
• temperature: Operating temperature of the layer [°C] (default: T₀).

Returns

• A Semicon object with initialized properties.

Examples

material_props = Material(1e6, 2.3, 1.0, 20.0, 0.00393)
semicon_layer = Semicon(0.01, Thickness(0.002), material_props, temperature=25)
println(semicon_layer.cross_section)      # Expected output: ~6.28e-5 [m²]
println(semicon_layer.resistance)         # Expected output: Resistance in [Ω/m]
println(semicon_layer.gmr)                # Expected output: GMR in [m]
println(semicon_layer.shunt_capacitance)  # Expected output: Capacitance in [F/m]
println(semicon_layer.shunt_conductance)  # Expected output: Conductance in [S·m]

struct Strip{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractConductorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a flat conductive strip with defined geometric and material properties given by the attributes:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radius of the strip [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radius of the strip [m].

• thickness::Union{Float64, Measurements.Measurement{Float64}}: Thickness of the strip [m].

• width::Union{Float64, Measurements.Measurement{Float64}}: Width of the strip [m].

• lay_ratio::Union{Float64, Measurements.Measurement{Float64}}: Ratio defining the lay length of the strip (twisting factor) [dimensionless].

• mean_diameter::Union{Float64, Measurements.Measurement{Float64}}: Mean diameter of the strip's helical path [m].

• pitch_length::Union{Float64, Measurements.Measurement{Float64}}: Pitch length of the strip's helical path [m].

• lay_direction::Int64: Twisting direction of the strip (1 = unilay, -1 = contralay) [dimensionless].

• material_props::Material: Material properties of the strip.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Temperature at which the properties are evaluated [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the strip [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance of the strip [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius of the strip [m].

Strip(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    width::Union{Float64, Measurements.Measurement{Float64}},
    lay_ratio::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}},
    lay_direction::Int64
) -> Strip

Constructs a Strip object with specified geometric and material parameters.

Arguments

• r_in: Internal radius of the strip [m].
• r_ex: External radius or thickness of the strip [m].
• width: Width of the strip [m].
• lay_ratio: Ratio defining the lay length of the strip [dimensionless].
• material_props: Material properties of the strip.
• temperature: Temperature at which the properties are evaluated [°C]. Defaults to T₀.
• lay_direction: Twisting direction of the strip (1 = unilay, -1 = contralay) [dimensionless]. Defaults to 1.

Returns

• A Strip object with calculated geometric and electrical properties.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
strip = Strip(0.01, Thickness(0.002), 0.05, 10, material_props, temperature=25)
println(strip.cross_section) # Output: 0.0001 [m²]
println(strip.resistance)    # Output: Resistance value [Ω/m]

See also

• Material
• ConductorGroup
• calc_strip_resistance
• calc_tubular_gmr
• calc_helical_params

struct Thickness{T<:Real} <: LineCableModels.DataModel.AbstractRadius

Represents the thickness of a cable component.

• value::Real: Numerical value of the thickness [m].

struct Tubular{T<:Union{Float64, Measurements.Measurement{Float64}}} <: LineCableModels.DataModel.AbstractConductorPart{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a tubular or solid (r_in=0) conductor with geometric and material properties defined as:

• r_in::Union{Float64, Measurements.Measurement{Float64}}: Internal radius of the tubular conductor [m].

• r_ex::Union{Float64, Measurements.Measurement{Float64}}: External radius of the tubular conductor [m].

• material_props::Material: A Material object representing the physical properties of the conductor material.

• temperature::Union{Float64, Measurements.Measurement{Float64}}: Temperature at which the properties are evaluated [°C].

• cross_section::Union{Float64, Measurements.Measurement{Float64}}: Cross-sectional area of the tubular conductor [m²].

• resistance::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistance (DC) of the tubular conductor [Ω/m].

• gmr::Union{Float64, Measurements.Measurement{Float64}}: Geometric mean radius of the tubular conductor [m].

Tubular(
    component::CableComponent{T<:Union{Float64, Measurements.Measurement{Float64}}}
) -> Tubular

Constructs the equivalent coaxial conductor as a Tubular directly from a CableComponent, reusing the rigorously tested positional constructor.

Arguments

• component: The CableComponent providing geometry and material.

Returns

• Tubular{T} with radii from component.conductor_group and material from component.conductor_props at the group temperature (fallback to T0).

Tubular(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    material_props::Material{T<:Union{Float64, Measurements.Measurement{Float64}}},
    temperature::Union{Float64, Measurements.Measurement{Float64}}
) -> Tubular

Initializes a Tubular object with specified geometric and material parameters.

Arguments

• r_in: Internal radius of the tubular conductor [m].
• r_ex: External radius of the tubular conductor [m].
• material_props: A Material object representing the physical properties of the conductor material.
• temperature: Temperature at which the properties are evaluated [°C]. Defaults to T₀.

Returns

• An instance of Tubular initialized with calculated geometric and electrical properties.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
tubular = Tubular(0.01, 0.02, material_props, temperature=25)
println(tubular.cross_section) # Output: 0.000942 [m²]
println(tubular.resistance)    # Output: Resistance value [Ω/m]

See also

• Material
• calc_tubular_resistance
• calc_tubular_gmr

equivalent(
    original_design::CableDesign;
    new_id
) -> CableDesign

Builds a simplified CableDesign by replacing each component with a homogeneous equivalent and leverages shorthand constructors:

• ConductorGroup(component::CableComponent{T}) = ConductorGroup(Tubular(component))
• InsulatorGroup(component::CableComponent{T}) = InsulatorGroup(Insulator(component))

The geometry is preserved from the original component, while materials are derived from the component's effective conductor and insulator properties.

flat_formation(
    xc::Union{Float64, Measurements.Measurement{Float64}},
    yc::Union{Float64, Measurements.Measurement{Float64}},
    s::Union{Float64, Measurements.Measurement{Float64}};
    vertical
) -> NTuple{6, Union{Float64, Measurements.Measurement{Float64}}}

Calculates the coordinates of three conductors arranged in a flat (horizontal or vertical) formation.

Arguments

• xc: X-coordinate of the reference point [m].
• yc: Y-coordinate of the reference point [m].
• s: Spacing between adjacent conductors [m].
• vertical: Boolean flag indicating whether the formation is vertical.

Returns

• A tuple containing:
  • xa, ya: Coordinates of the first conductor [m].
  • xb, yb: Coordinates of the second conductor [m].
  • xc, yc: Coordinates of the third conductor [m].

Examples

# Horizontal formation
xa, ya, xb, yb, xc, yc = flat_formation(0.0, 0.0, 0.1)
println((xa, ya))  # First conductor coordinates
println((xb, yb))  # Second conductor coordinates
println((xc, yc))  # Third conductor coordinates

# Vertical formation
xa, ya, xb, yb, xc, yc = flat_formation(0.0, 0.0, 0.1, vertical=true)

trifoil_formation(
    x0::Union{Float64, Measurements.Measurement{Float64}},
    y0::Union{Float64, Measurements.Measurement{Float64}},
    r_ext::Union{Float64, Measurements.Measurement{Float64}}
) -> NTuple{6, Union{Float64, Measurements.Measurement{Float64}}}

Calculates the coordinates of three cables arranged in a trifoil pattern.

Arguments

• x0: X-coordinate of the center point [m].
• y0: Y-coordinate of the center point [m].
• r_ext: External radius of the circular layout [m].

Returns

• A tuple containing:
  • xa, ya: Coordinates of the top cable [m].
  • xb, yb: Coordinates of the bottom-left cable [m].
  • xc, yc: Coordinates of the bottom-right cable [m].

Examples

xa, ya, xb, yb, xc, yc = trifoil_formation(0.0, 0.0, 0.035)
println((xa, ya))  # Coordinates of top cable
println((xb, yb))  # Coordinates of bottom-left cable
println((xc, yc))  # Coordinates of bottom-right cable

LineCableModels.DataModel.BaseParams

The BaseParams submodule provides fundamental functions for determining the base electrical parameters (R, L, C, G) of cable components within the LineCableModels.DataModel module. This includes implementations of standard engineering formulas for resistance, inductance, and geometric parameters of various conductor configurations.

Overview

• Implements basic electrical engineering formulas for calculating DC resistance and inductance of different conductor geometries (tubular, strip, wire arrays).
• Implements basic formulas for capacitance and dielectric losses in insulators and semiconductors.
• Provides functions for temperature correction of material properties.
• Calculates geometric mean radii for different conductor configurations.
• Includes functions for determining the effective length for helical wire arrangements.
• Calculates equivalent electrical parameters and correction factors for different geometries and configurations.

Dependencies

• Base
• LineCableModels.Commons
• Measurements

Exports

• calc_circstrands_coords
• calc_circstrands_gmr
• calc_equivalent_alpha
• calc_equivalent_eps
• calc_equivalent_gmr
• calc_equivalent_lossfact
• calc_equivalent_mu
• calc_equivalent_rho
• calc_gmd
• calc_helical_params
• calc_inductance_trifoil
• calc_parallel_equivalent
• calc_shunt_capacitance
• calc_shunt_conductance
• calc_sigma_lossfact
• calc_solenoid_correction
• calc_strip_resistance
• calc_temperature_correction
• calc_tubular_gmr
• calc_tubular_inductance
• calc_tubular_resistance

calc_circstrands_coords(
    num_wires::Int64,
    radius_wire::Union{Float64, Measurements.Measurement{Float64}},
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    C::Tuple{T<:Union{Float64, Measurements.Measurement{Float64}}, T<:Union{Float64, Measurements.Measurement{Float64}}}
) -> Vector{<:Tuple{Union{Float64, Measurements.Measurement{Float64}}, Union{Float64, Measurements.Measurement{Float64}}}}

Calculates the center coordinates of wires arranged in a circular pattern.

Arguments

• num_wires: Number of wires in the circular arrangement [dimensionless].
• radius_wire: Radius of each individual wire [m].
• r_in: Inner radius of the wire array (to wire centers) [m].
• C: Optional tuple representing the center coordinates of the circular arrangement [m]. Default is (0.0, 0.0).

Returns

• Vector of tuples, where each tuple contains the (x, y) coordinates [m] of the center of a wire.

Examples

# Create a 7-wire array with 2mm wire radius and 1cm inner radius
wire_coords = calc_circstrands_coords(7, 0.002, 0.01)
println(wire_coords[1]) # Output: First wire coordinates

# Create a wire array with custom center position
wire_coords = calc_circstrands_coords(7, 0.002, 0.01, C=(0.5, 0.3))

See also

• LineCableModels.DataModel.CircStrands

calc_circstrands_gmr(
    lay_rad::Union{Float64, Measurements.Measurement{Float64}},
    N::Int64,
    rad_wire::Union{Float64, Measurements.Measurement{Float64}},
    mu_r::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the geometric mean radius (GMR) of a circular wire array, using formula (62), page 335, of the book by Edward Rosa [15]:

\[GMR = \sqrt[n] {r n a^{n-1}}\]

where $a$ is the layout radius, $n$ is the number of wires, and $r$ is the radius of each wire.

Arguments

• lay_rad: Layout radius of the wire array [m].
• N: Number of wires in the array [dimensionless].
• rad_wire: Radius of an individual wire [m].
• mu_r: Relative permeability of the wire material [dimensionless].

Returns

• Geometric mean radius (GMR) of the wire array [m].

Examples

lay_rad = 0.05
N = 7
rad_wire = 0.002
mu_r = 1.0
gmr = calc_circstrands_gmr(lay_rad, N, rad_wire, mu_r)
println(gmr) # Expected output: 0.01187... [m]

calc_equivalent_alpha(
    alpha1::Union{Float64, Measurements.Measurement{Float64}},
    R1::Union{Float64, Measurements.Measurement{Float64}},
    alpha2::Union{Float64, Measurements.Measurement{Float64}},
    R2::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the equivalent temperature coefficient of resistance (alpha) when two conductors are connected in parallel, by cross-weighted-resistance averaging:

\[\alpha_{eq} = \frac{\alpha_1 R_2 + \alpha_2 R1}{R_1 + R_2}\]

where $\alpha_1$, $\alpha_2$ are the temperature coefficients of the conductors, and $R_1$, $R_2$ are the respective resistances.

Arguments

• alpha1: Temperature coefficient of resistance of the first conductor [1/°C].
• R1: Resistance of the first conductor [Ω].
• alpha2: Temperature coefficient of resistance of the second conductor [1/°C].
• R2: Resistance of the second conductor [Ω].

Returns

• The equivalent temperature coefficient [1/°C] for the parallel combination.

Examples

alpha_conductor = 0.00393  # Copper
alpha_new_part = 0.00403   # Aluminum
R_conductor = 0.5
R_new_part = 1.0
alpha_eq = calc_equivalent_alpha(alpha_conductor, R_conductor, alpha_new_part, R_new_part)
println(alpha_eq)  # Output: 0.00396 (approximately)

calc_equivalent_eps(
    C_eq::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    r_in::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the equivalent permittivity for a coaxial cable insulation, using the formula [4]:

\[\varepsilon_{eq} = \frac{C_{eq} \log(\frac{r_{ext}}{r_{in}})}{2\pi \varepsilon_0}\]

where $\varepsilon_0$ is the permittivity of free space.

Arguments

• C_eq: Equivalent capacitance of the insulation [F/m].
• r_ex: External radius of the insulation [m].
• r_in: Internal radius of the insulation [m].

Returns

• Equivalent relative permittivity of the insulation [dimensionless].

Examples

eps_eq = calc_equivalent_eps(1e-10, 0.01, 0.005)  # Expected output: ~2.26 [dimensionless]

See also

• ε₀

calc_equivalent_gmr(
    existing::LineCableModels.DataModel.AbstractCablePart,
    new_layer::LineCableModels.DataModel.AbstractCablePart
) -> Any

Calculates the equivalent geometric mean radius (GMR) of a conductor after adding a new layer, by recursive application of the multizone stranded conductor defined as [3]:

\[GMR_{eq} = {GMR_{i-1}}^{\beta^2} \cdot {GMR_{i}}^{(1-\beta)^2} \cdot {GMD}^{2\beta(1-\beta)}\]

\[\beta = \frac{S_{i-1}}{S_{i-1} + S_{i}}\]

where:

• $S_{i-1}$ is the cumulative cross-sectional area of the existing cable part, $S_{i}$ is the total cross-sectional area after inclusion of the conducting layer ${i}$.
• $GMR_{i-1}$ is the cumulative GMR of the existing cable part, $GMR_{i}$ is the GMR of the conducting layer ${i}$.
• $GMD$ is the geometric mean distance between the existing cable part and the new layer, calculated using calc_gmd.

Arguments

• existing: The existing cable part (AbstractCablePart).
• new_layer: The new layer being added (AbstractCablePart).

Returns

• Updated equivalent GMR of the combined conductor [m].

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
conductor = Conductor(Strip(0.01, 0.002, 0.05, 10, material_props))
new_layer = CircStrands(0.02, 0.002, 7, 15, material_props)
equivalent_gmr = calc_equivalent_gmr(conductor, new_layer)  # Expected output: Updated GMR value [m]

See also

• calc_gmd

calc_equivalent_lossfact(
    G_eq::Union{Float64, Measurements.Measurement{Float64}},
    C_eq::Union{Float64, Measurements.Measurement{Float64}},
    ω::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the equivalent loss factor (tangent) of a dielectric material:

\[\tan \delta = \frac{G_{eq}}{\omega \cdot C_{eq}}\]

where $\tan \delta$ is the loss factor (tangent).

Arguments

• G_eq: Equivalent conductance of the material [S·m].
• C_eq: Equivalent capacitance of the material [F/m].
• ω: Angular frequency [rad/s].

Returns

• Equivalent loss factor of the dielectric material [dimensionless].

Examples

loss_factor = calc_equivalent_lossfact(1e-8, 1e-10, 2π*50)  # Expected output: ~0.0318 [dimensionless]

calc_equivalent_mu(
    gmr::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    r_in::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the relative permeability (mu_r) based on the geometric mean radius (GMR) and conductor dimensions, by executing the inverse of calc_tubular_gmr, and solving for mu_r:

\[\log GMR = \log r_2 - \mu_r \left[ \frac{r_1^4}{\left(r_2^2 - r_1^2\right)^2} \log\left(\frac{r_2}{r_1}\right) - \frac{3r_1^2 - r_2^2}{4\left(r_2^2 - r_1^2\right)} \right]\]

\[\mu_r = -\frac{\left(\log GMR - \log r_2\right)}{\frac{r_1^4}{\left(r_2^2 - r_1^2\right)^2} \log\left(\frac{r_2}{r_1}\right) - \frac{3r_1^2 - r_2^2}{4\left(r_2^2 - r_1^2\right)}}\]

where $r_1$ is the inner radius and $r_2$ is the outer radius.

Arguments

• gmr: Geometric mean radius of the conductor [m].
• r_ex: External radius of the conductor [m].
• r_in: Internal radius of the conductor [m].

Returns

• Relative permeability (mu_r) of the conductor material [dimensionless].

Errors

• Throws ArgumentError if r_ex is less than r_in.

Notes

Assumes a tubular geometry for the conductor, reducing to the solid case if r_in is zero.

Examples

gmr = 0.015
r_ex = 0.02
r_in = 0.01
mu_r = calc_equivalent_mu(gmr, r_ex, r_in)
println(mu_r) # Expected output: ~1.7 [dimensionless]

See also

• calc_tubular_gmr

calc_equivalent_rho(
    R::Union{Float64, Measurements.Measurement{Float64}},
    radius_ext_con::Union{Float64, Measurements.Measurement{Float64}},
    radius_in_con::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the equivalent resistivity of a solid tubular conductor, using the formula [4]:

\[\rho_{eq} = R_{eq} S_{eff} = R_{eq} \pi (r_{ext}^2 - r_{in}^2)\]

where $S_{eff}$ is the effective cross-sectional area of the tubular conductor.

Arguments

• R: Resistance of the conductor [Ω].
• radius_ext_con: External radius of the tubular conductor [m].
• radius_in_con: Internal radius of the tubular conductor [m].

Returns

• Equivalent resistivity of the tubular conductor [Ω·m].

Examples

rho_eq = calc_equivalent_rho(0.01, 0.02, 0.01)  # Expected output: ~9.42e-4 [Ω·m]

calc_gmd(
    co1::LineCableModels.DataModel.AbstractCablePart,
    co2::LineCableModels.DataModel.AbstractCablePart
) -> Any

Calculates the geometric mean distance (GMD) between two cable parts, by using the definition described in Grover [16]:

\[\log GMD = \left(\frac{\sum_{i=1}^{n_1}\sum_{j=1}^{n_2} (s_1 \cdot s_2) \cdot \log(d_{ij})}{\sum_{i=1}^{n_1}\sum_{j=1}^{n_2} (s_1 \cdot s_2)}\right)\]

where:

• $d_{ij}$ is the Euclidean distance between elements $i$ and $j$.
• $s_1$ and $s_2$ are the cross-sectional areas of the respective elements.
• $n_1$ and $n_2$ are the number of sub-elements in each cable part.

Arguments

• co1: First cable part (AbstractCablePart).
• co2: Second cable part (AbstractCablePart).

Returns

• Geometric mean distance between the cable parts [m].

Notes

For concentric structures, the GMD converges to the external radii of the outermost element.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
circstrands1 = CircStrands(0.01, 0.002, 7, 10, material_props)
circstrands2 = CircStrands(0.02, 0.002, 7, 15, material_props)
gmd = calc_gmd(circstrands1, circstrands2)  # Expected output: GMD value [m]

strip = Strip(0.01, 0.002, 0.05, 10, material_props)
tubular = Tubular(0.01, 0.02, material_props)
gmd = calc_gmd(strip, tubular)  # Expected output: GMD value [m]

See also

• calc_circstrands_coords
• calc_equivalent_gmr

calc_helical_params(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    lay_ratio::Union{Float64, Measurements.Measurement{Float64}}
) -> Tuple{Union{Float64, Measurements.Measurement{Float64}}, Union{Float64, Measurements.Measurement{Float64}}, Union{Float64, Int64, Measurements.Measurement{Float64}}}

Calculates the mean diameter, pitch length, and overlength based on cable geometry parameters. The lay ratio is defined as the ratio of the pitch length $L_p$ to the external diameter $D_e$:

\[\lambda = \frac{L_p}{D_e}\]

where $D_e$ and $L_p$ are the dimensions represented in the figure.

Arguments

• r_in: Inner radius of the cable layer [m].
• r_ex: Outer radius of the cable layer [m].
• lay_ratio: Ratio of the pitch (lay) length to the external diameter of the corresponding layer of wires [dimensionless].

Returns

• mean_diameter: Mean diameter of the cable layer [m].
• pitch_length: The length over which the strands complete one full twist [m].
• overlength: Effective length increase resulting from the helical path [1/m].

Notes

Reference values for lay_ratio are given under standard EN 50182 [12]:

Examples

r_in = 0.01
r_ex = 0.015
lay_ratio = 12

mean_diam, pitch, overlength = calc_helical_params(r_in, r_ex, lay_ratio)
# mean_diam ≈ 0.025 [m]
# pitch ≈ 0.3 [m]
# overlength > 1.0 [1/m]

calc_inductance_trifoil(
    r_in_co::Union{Float64, Measurements.Measurement{Float64}},
    r_ext_co::Union{Float64, Measurements.Measurement{Float64}},
    rho_co::Union{Float64, Measurements.Measurement{Float64}},
    mu_r_co::Union{Float64, Measurements.Measurement{Float64}},
    r_in_scr::Union{Float64, Measurements.Measurement{Float64}},
    r_ext_scr::Union{Float64, Measurements.Measurement{Float64}},
    rho_scr::Union{Float64, Measurements.Measurement{Float64}},
    mu_r_scr::Union{Float64, Measurements.Measurement{Float64}},
    S::Union{Float64, Measurements.Measurement{Float64}},
    rho_e::Union{Float64, Measurements.Measurement{Float64}},
    f::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the positive-sequence inductance of a trifoil-configured cable system composed of core/screen assuming solid bonding, using the formula given under section 4.2.4.3 of CIGRE TB-531:

\[Z_d = \left[Z_a - Z_x\right] - \frac{\left( Z_m - Z_x \right)^2}{Z_s - Z_x}\]

\[L = \mathfrak{Im}\left(\frac{Z_d}{\omega}\right)\]

where $Z_a$, $Z_s$ are the self impedances of the core conductor and the screen, and $Z_m$, and $Z_x$ are the mutual impedances between core/screen and between cables, respectively, as per sections 4.2.3.4, 4.2.3.5, 4.2.3.6 and 4.2.3.8 of the same document [8].

Arguments

• r_in_co: Internal radius of the phase conductor [m].
• r_ext_co: External radius of the phase conductor [m].
• rho_co: Electrical resistivity of the phase conductor material [Ω·m].
• mu_r_co: Relative permeability of the phase conductor material [dimensionless].
• r_in_scr: Internal radius of the metallic screen [m].
• r_ext_scr: External radius of the metallic screen [m].
• rho_scr: Electrical resistivity of the metallic screen material [Ω·m].
• mu_r_scr: Relative permeability of the screen conductor material [dimensionless].
• S: Spacing between conductors in trifoil configuration [m].
• rho_e: Soil resistivity [Ω·m]. Default: 100 Ω·m.
• f: Frequency [Hz]. Default: f₀.

Returns

• Positive-sequence inductance per unit length of the cable system [H/m].

Examples

L = calc_inductance_trifoil(0.01, 0.015, 1.72e-8, 1.0, 0.02, 0.025, 2.83e-8, 1.0, S=0.1, rho_e=50, f=50)
println(L) # Output: Inductance value in H/m

See also

• calc_tubular_gmr

calc_parallel_equivalent(
    Z1::Union{Float64, Complex{Measurements.Measurement{Float64}}, Measurements.Measurement{Float64}, ComplexF64},
    Z2::Union{Float64, Complex{Measurements.Measurement{Float64}}, Measurements.Measurement{Float64}, ComplexF64}
) -> Any

Calculates the parallel equivalent of two impedances (or series equivalent of two admittances):

\[Z_{eq} = \frac{Z_1 Z_2}{Z_1 + Z_2}\]

This expression, when applied recursively to LineCableModels.DataModel.CircStrands objects, implements the formula for the hexagonal wiring pattern described in CIGRE TB-345 [1] [17]:

\[\frac{1}{R_{\text{dc}}} = \frac{\pi d^2}{4 \rho} \left( 1 + \sum_{1}^{n} \frac{6n}{k_n} \right)\]

\[k_n = \left[ 1 + \left( \pi \frac{D_n}{\lambda_n} \right)^2 \right]^{1/2}\]

where $R_{\text{dc}}$ is the DC resistance, $d$ is the diameter of each wire, $ho$ is the resistivity, $n$ is the number of layers following the hexagonal pattern, $D_n$ is the diameter of the $n$-th layer, and $\lambda_n$ is the pitch length of the $n$-th layer, obtained using calc_helical_params.

Arguments

• Z1: The total impedance of the existing system [Ω].
• Z2: The impedance of the new layer being added [Ω].

Returns

• The parallel equivalent impedance [Ω].

Examples

Z1 = 5.0
Z2 = 10.0
Req = calc_parallel_equivalent(Z1, Z2)
println(Req) # Outputs: 3.3333333333333335

See also

• calc_helical_params

calc_shunt_capacitance(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    epsr::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the shunt capacitance per unit length of a coaxial structure, using the standard formula for the capacitance of a coaxial structure [8] [4] [14]:

\[C = \frac{2 \pi \varepsilon_0 \varepsilon_r}{\log \left(\frac{r_{ext}}{r_{in}}\right)}\]

where $\varepsilon_0$ is the vacuum permittivity, $\varepsilon_r$ is the relative permittivity of the dielectric material, and $r_{in}$ and $r_{ext}$ are the inner and outer radii of the coaxial structure, respectively.

Arguments

• r_in: Internal radius of the coaxial structure [m].
• r_ex: External radius of the coaxial structure [m].
• epsr: Relative permittivity of the dielectric material [dimensionless].

Returns

• Shunt capacitance per unit length [F/m].

Examples

r_in = 0.01
r_ex = 0.02
epsr = 2.3
capacitance = calc_shunt_capacitance(r_in, r_ex, epsr)
println(capacitance) # Expected output: ~1.24e-10 [F/m]

calc_shunt_conductance(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    rho::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the shunt conductance per unit length of a coaxial structure, using the improved model reported in [4] [13] [18]:

\[G = \frac{2\pi\sigma}{\log(\frac{r_{ext}}{r_{in}})}\]

where $\sigma = \frac{1}{\rho}$ is the conductivity of the dielectric/semiconducting material, $r_{in}$ is the internal radius, and $r_{ext}$ is the external radius of the coaxial structure.

Arguments

• r_in: Internal radius of the coaxial structure [m].
• r_ex: External radius of the coaxial structure [m].
• rho: Resistivity of the dielectric/semiconducting material [Ω·m].

Returns

• Shunt conductance per unit length [S·m].

Examples

r_in = 0.01
r_ex = 0.02
rho = 1e9
g = calc_shunt_conductance(r_in, r_ex, rho)
println(g) # Expected output: 2.7169e-9 [S·m]

calc_sigma_lossfact(
    G_eq::Union{Float64, Measurements.Measurement{Float64}},
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the effective conductivity of a dielectric material from the known conductance (related to the loss factor $\tan \delta$) via [4] [13] [18]:

\[\sigma_{eq} = \frac{G_{eq}}{2\pi} \log(\frac{r_{ext}}{r_{in}})\]

where $\sigma_{eq} = \frac{1}{\rho_{eq}}$ is the conductivity of the dielectric/semiconducting material, $G_{eq}$ is the shunt conductance per unit length, $r_{in}$ is the internal radius, and $r_{ext}$ is the external radius of the coaxial structure.

Arguments

• G_eq: Equivalent conductance of the material [S·m].
• r_in: Internal radius of the coaxial structure [m].
• r_ex: External radius of the coaxial structure [m].

Returns

• Effective material conductivity per unit length [S·m].

Examples

Geq = 2.7169e-9
sigma_eq = calc_sigma_lossfact(G_eq, r_in, r_ex)

calc_solenoid_correction(
    num_turns::Union{Float64, Measurements.Measurement{Float64}},
    radius_ext_con::Union{Float64, Measurements.Measurement{Float64}},
    radius_ext_ins::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the solenoid correction factor for magnetic permeability in insulated cables with helical conductors (CircStrands), using the formula from Gudmundsdottir et al. [5]:

\[\mu_{r, sol} = 1 + \frac{2 \pi^2 N^2 (r_{ins, ext}^2 - r_{con, ext}^2)}{\log(r_{ins, ext}/r_{con, ext})}\]

where:

• $N$ is the number of turns per unit length.
• $r_{con, ext}$ is the conductor external radius.
• $r_{ins, ext}$ is the insulator external radius.

Arguments

• num_turns: Number of turns per unit length [1/m].
• radius_ext_con: External radius of the conductor [m].
• radius_ext_ins: External radius of the insulator [m].

Returns

• Correction factor for the insulator magnetic permeability [dimensionless].

Examples

# Cable with 10 turns per meter, conductor radius 5 mm, insulator radius 10 mm
correction = calc_solenoid_correction(10, 0.005, 0.01)  # Expected output: > 1.0 [dimensionless]

# Non-helical cable (straight conductor)
correction = calc_solenoid_correction(NaN, 0.005, 0.01)  # Expected output: 1.0 [dimensionless]

calc_strip_resistance(
    thickness::Union{Float64, Measurements.Measurement{Float64}},
    width::Union{Float64, Measurements.Measurement{Float64}},
    rho::Union{Float64, Measurements.Measurement{Float64}},
    alpha::Union{Float64, Measurements.Measurement{Float64}},
    T0::Union{Float64, Measurements.Measurement{Float64}},
    Top::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the DC resistance of a strip conductor based on its geometric and material properties, using the basic resistance formula in terms of the resistivity and cross-sectional area:

\[R = \rho \frac{\ell}{W T}\]

where $\ell$ is the length of the strip, $W$ is the width, and $T$ is the thickness. The length is assumed to be infinite in the direction of current flow, so the resistance is calculated per unit length.

Arguments

• thickness: Thickness of the strip [m].
• width: Width of the strip [m].
• rho: Electrical resistivity of the conductor material [Ω·m].
• alpha: Temperature coefficient of resistivity [1/°C].
• T0: Reference temperature for the material properties [°C].
• Top: Operating temperature of the conductor [°C].

Returns

• DC resistance of the strip conductor [Ω].

Examples

thickness = 0.002
width = 0.05
rho = 1.7241e-8
alpha = 0.00393
T0 = 20
T = 25
resistance = calc_strip_resistance(thickness, width, rho, alpha, T0, T)
# Output: ~0.0001758 Ω

See also

• calc_temperature_correction

calc_temperature_correction(
    alpha::Union{Float64, Measurements.Measurement{Float64}},
    Top::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}
calc_temperature_correction(
    alpha::Union{Float64, Measurements.Measurement{Float64}},
    Top::Union{Float64, Measurements.Measurement{Float64}},
    T0::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the temperature correction factor for material properties based on the standard linear temperature model [17]:

\[k(T) = 1 + \alpha (T - T_0)\]

where $\alpha$ is the temperature coefficient of the material resistivity, $T$ is the operating temperature, and $T_0$ is the reference temperature.

Arguments

• alpha: Temperature coefficient of the material property [1/°C].
• T: Current temperature [°C].
• T0: Reference temperature at which the base material property was measured [°C]. Defaults to T₀.

Returns

• Temperature correction factor to be applied to the material property [dimensionless].

Examples

	# Copper resistivity correction (alpha = 0.00393 [1/°C])
	k = calc_temperature_correction(0.00393, 75.0, 20.0)  # Expected output: 1.2161

calc_tubular_gmr(
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    mu_r::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the geometric mean radius (GMR) of a tubular conductor, using [2]:

\[\log GMR = \log r_2 - \mu_r \left[ \frac{r_1^4}{\left(r_2^2 - r_1^2\right)^2} \log\left(\frac{r_2}{r_1}\right) - \frac{3r_1^2 - r_2^2}{4\left(r_2^2 - r_1^2\right)} \right]\]

where $\mu_r$ is the material magnetic permeability (relative to free space), $r_1$ and $r_2$ are the inner and outer radii of the tubular conductor, respectively. If $r_2$ is approximately equal to $r_1$ , the tube collapses into a thin shell, and the GMR is equal to $r_2$. If the tube becomes infinitely thick (e.g., $r_2 \gg r_1$), the GMR diverges to infinity.

Arguments

• r_ex: External radius of the tubular conductor [m].
• r_in: Internal radius of the tubular conductor [m].
• mu_r: Relative permeability of the conductor material [dimensionless].

Returns

• Geometric mean radius (GMR) of the tubular conductor [m].

Errors

• Throws ArgumentError if r_ex is less than r_in.

Examples

r_ex = 0.02
r_in = 0.01
mu_r = 1.0
gmr = calc_tubular_gmr(r_ex, r_in, mu_r)
println(gmr) # Expected output: ~0.0135 [m]

calc_tubular_inductance(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    mu_r::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the inductance of a tubular conductor per unit length, disregarding skin-effects (DC approximation) [4] [17] [14]:

\[L = \frac{\mu_r \mu_0}{2 \pi} \log \left( \frac{r_{ext}}{r_{in}} \right)\]

where $\mu_r$ is the relative permeability of the conductor material, $\mu_0$ is the vacuum permeability, and $r_{in}$ and $r_{ext}$ are the inner and outer radii of the conductor, respectively.

Arguments

• r_in: Internal radius of the tubular conductor [m].
• r_ex: External radius of the tubular conductor [m].
• mu_r: Relative permeability of the conductor material [dimensionless].

Returns

• Internal inductance of the tubular conductor per unit length [H/m].

Examples

r_in = 0.01
r_ex = 0.02
mu_r = 1.0
L = calc_tubular_inductance(r_in, r_ex, mu_r)
# Output: ~2.31e-7 H/m

See also

• calc_tubular_resistance

calc_tubular_resistance(
    r_in::Union{Float64, Measurements.Measurement{Float64}},
    r_ex::Union{Float64, Measurements.Measurement{Float64}},
    rho::Union{Float64, Measurements.Measurement{Float64}},
    alpha::Union{Float64, Measurements.Measurement{Float64}},
    T0::Union{Float64, Measurements.Measurement{Float64}},
    Top::Union{Float64, Measurements.Measurement{Float64}}
) -> Union{Float64, Measurements.Measurement{Float64}}

Calculates the DC resistance of a tubular conductor based on its geometric and material properties, using the resistivity and cross-sectional area of a hollow cylinder with radii $r_{in}$ and $r_{ext}$:

\[R = \rho \frac{\ell}{\pi (r_{ext}^2 - r_{in}^2)}\]

where $\ell$ is the length of the conductor, $r_{in}$ and $r_{ext}$ are the inner and outer radii, respectively. The length is assumed to be infinite in the direction of current flow, so the resistance is calculated per unit length.

Arguments

• r_in: Internal radius of the tubular conductor [m].
• r_ex: External radius of the tubular conductor [m].
• rho: Electrical resistivity of the conductor material [Ω·m].
• alpha: Temperature coefficient of resistivity [1/°C].
• T0: Reference temperature for the material properties [°C].
• Top: Operating temperature of the conductor [°C].

Returns

• DC resistance of the tubular conductor [Ω].

Examples

r_in = 0.01
r_ex = 0.02
rho = 1.7241e-8
alpha = 0.00393
T0 = 20
T = 25
resistance = calc_tubular_resistance(r_in, r_ex, rho, alpha, T0, T)
# Output: ~9.10e-8 Ω

See also

• calc_temperature_correction

LineCableModels.EarthProps

The EarthProps module provides functionality for modeling and computing earth properties within the LineCableModels.jl package. This module includes definitions for homogeneous and layered earth models, and formulations for frequency-dependent earth properties, to be used in impedance/admittance calculations.

Overview

• Defines the EarthModel object for representing horizontally or vertically multi-layered earth models with frequency-dependent properties (ρ, ε, μ).
• Provides the EarthLayer type for representing individual soil layers with electromagnetic properties.
• Implements a multi-dispatch framework to allow different formulations of frequency-dependent earth models with AbstractFDEMFormulation.
• Contains utility functions for building complex multi-layered earth models and generating data summaries.

Dependencies

• Base
• LineCableModels.Commons
• Measurements

Exports

• CPEarth
• EarthLayer
• EarthModel

struct CPEarth <: LineCableModels.EarthProps.AbstractFDEMFormulation

Represents an earth model with constant properties (CP), i.e. frequency-invariant electromagnetic properties.

Functor implementation for CPEarth.

Computes frequency-dependent earth properties using the CPEarth formulation, which assumes frequency-invariant values for resistivity, permittivity, and permeability.

Arguments

• frequencies: Vector of frequency values [Hz].
• base_rho_g: Base (DC) electrical resistivity of the soil [Ω·m].
• base_epsr_g: Base (DC) relative permittivity of the soil [dimensionless].
• base_mur_g: Base (DC) relative permeability of the soil [dimensionless].
• formulation: Instance of a subtype of AbstractFDEMFormulation defining the computation method.

Returns

• rho: Vector of resistivity values [Ω·m] at the given frequencies.
• epsilon: Vector of permittivity values [F/m] at the given frequencies.
• mu: Vector of permeability values [H/m] at the given frequencies.

Examples

frequencies = [1e3, 1e4, 1e5]

# Using the CP model
rho, epsilon, mu = CPEarth(frequencies, 100, 10, 1, CPEarth())
println(rho)     # Output: [100, 100, 100]
println(epsilon) # Output: [8.854e-11, 8.854e-11, 8.854e-11]
println(mu)      # Output: [1.2566e-6, 1.2566e-6, 1.2566e-6]

See also

• EarthLayer

struct EarthLayer{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents one single earth layer in an EarthModel object, with base and frequency-dependent properties, and attributes:

• base_rho_g::Union{Float64, Measurements.Measurement{Float64}}: Base (DC) electrical resistivity [Ω·m].

• base_epsr_g::Union{Float64, Measurements.Measurement{Float64}}: Base (DC) relative permittivity [dimensionless].

• base_mur_g::Union{Float64, Measurements.Measurement{Float64}}: Base (DC) relative permeability [dimensionless].

• t::Union{Float64, Measurements.Measurement{Float64}}: Thickness of the layer [m].

• rho_g::Vector{T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Computed resistivity values [Ω·m] at given frequencies.

• eps_g::Vector{T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Computed permittivity values [F/m] at given frequencies.

• mu_g::Vector{T} where T<:Union{Float64, Measurements.Measurement{Float64}}: Computed permeability values [H/m] at given frequencies.

Constructs an EarthLayer instance with specified base and frequency-dependent properties.

EarthLayer(
    frequencies::Array{T<:Union{Float64, Measurements.Measurement{Float64}}, 1},
    base_rho_g::Union{Float64, Measurements.Measurement{Float64}},
    base_epsr_g::Union{Float64, Measurements.Measurement{Float64}},
    base_mur_g::Union{Float64, Measurements.Measurement{Float64}},
    t::Union{Float64, Measurements.Measurement{Float64}},
    freq_dependence::LineCableModels.EarthProps.AbstractFDEMFormulation
) -> LineCableModels.EarthProps.EarthLayer

Constructs an EarthLayer instance with specified base properties and computes its frequency-dependent values.

Arguments

• frequencies: Vector of frequency values [Hz].
• base_rho_g: Base (DC) electrical resistivity of the layer [Ω·m].
• base_epsr_g: Base (DC) relative permittivity of the layer [dimensionless].
• base_mur_g: Base (DC) relative permeability of the layer [dimensionless].
• t: Thickness of the layer [m].
• freq_dependence: Instance of a subtype of AbstractFDEMFormulation defining the computation method for frequency-dependent properties.

Returns

• An EarthLayer instance with computed frequency-dependent properties.

Examples

frequencies = [1e3, 1e4, 1e5]
layer = EarthLayer(frequencies, 100, 10, 1, 5, CPEarth())
println(layer.rho_g) # Output: [100, 100, 100]
println(layer.eps_g) # Output: [8.854e-11, 8.854e-11, 8.854e-11]
println(layer.mu_g)  # Output: [1.2566e-6, 1.2566e-6, 1.2566e-6]

See also

• CPEarth

struct EarthModel{T<:Union{Float64, Measurements.Measurement{Float64}}}

Represents a multi-layered earth model with frequency-dependent properties, and attributes:

• freq_dependence::LineCableModels.EarthProps.AbstractFDEMFormulation: Selected frequency-dependent formulation for earth properties.

• vertical_layers::Bool: Boolean flag indicating whether the model is treated as vertically layered.

• layers::Array{LineCableModels.EarthProps.EarthLayer{T}, 1} where T<:Union{Float64, Measurements.Measurement{Float64}}: Vector of EarthLayer objects, starting with an air layer and the specified first earth layer.

Constructs an EarthModel instance with specified attributes.

EarthModel(
    frequencies::Array{T<:Union{Float64, Measurements.Measurement{Float64}}, 1},
    rho_g::Union{Float64, Measurements.Measurement{Float64}},
    epsr_g::Union{Float64, Measurements.Measurement{Float64}},
    mur_g::Union{Float64, Measurements.Measurement{Float64}};
    t,
    freq_dependence,
    vertical_layers,
    air_layer
) -> EarthModel

Constructs an EarthModel instance with a specified first earth layer. A semi-infinite air layer is always added before the first earth layer.

Arguments

• frequencies: Vector of frequency values [Hz].
• rho_g: Base (DC) electrical resistivity of the first earth layer [Ω·m].
• epsr_g: Base (DC) relative permittivity of the first earth layer [dimensionless].
• mur_g: Base (DC) relative permeability of the first earth layer [dimensionless].
• t: Thickness of the first earth layer [m]. For homogeneous earth models (or the bottommost layer), set t = Inf.
• freq_dependence: Instance of a subtype of AbstractFDEMFormulation defining the computation method for frequency-dependent properties (default: CPEarth).
• vertical_layers: Boolean flag indicating whether the model should be treated as vertically-layered (default: false).
• air_layer: optional EarthLayer object representing the semi-infinite air layer (default: EarthLayer(frequencies, Inf, 1.0, 1.0, Inf, freq_dependence)).

Returns

• An EarthModel instance with the specified attributes and computed frequency-dependent properties.

Examples

frequencies = [1e3, 1e4, 1e5]
earth_model = EarthModel(frequencies, 100, 10, 1, t=Inf)
println(length(earth_model.layers)) # Output: 2 (air + top layer)
println(earth_model.rho_eff) # Output: missing

See also

• EarthLayer
• add!

LineCableModels.ImportExport

The ImportExport module provides methods for serializing and deserializing data structures in LineCableModels.jl, and data exchange with external programs.

Overview

This module provides functionality for:

• Saving and loading cable designs and material libraries to/from JSON and other formats.
• Exporting cable system models to PSCAD and ATP formats.
• Serializing custom types with special handling for measurements and complex numbers.

The module implements a generic serialization framework with automatic type reconstruction and proper handling of Julia-specific types like Measurement objects and Inf/NaN values.

Dependencies

• Base
• DataFrames
• Dates
• EzXML
• JSON3
• LineCableModels.Commons
• LinearAlgebra
• Measurements
• Printf
• Serialization
• Tables
• XLSX

Exports

• export_data
• load!
• read_data
• save

export_data(
    ::Val{:atp},
    cable_system::LineCableSystem,
    earth_props::EarthModel;
    base_freq,
    file_name
) -> Union{Nothing, String}

Export a LineCableSystem to an ATPDraw‑compatible XML file (LCC component with input data).

This routine serializes the cable system geometry (positions and outer radii) and the already‑computed, frequency‑specific equivalent parameters of each cable component to the ATPDraw XML schema. The result is written to disk and the absolute file path is returned on success.

Arguments

• ::Val{:atp}: Backend selector for the ATP/ATPDraw exporter.
• cable_system::LineCableSystem: The system to export. Each entry in cable_system.cables provides one phase position and its associated CableDesign. The number of phases exported equals length(cable_system.cables).
• earth_props::EarthModel: Ground model used to populate ATP soil parameters. The exporter

uses the last layer’s base resistivity as Grnd resis.

• base_freq::Number = f₀ [Hz]: System frequency written to ATP (SysFreq) and stored in component metadata. *This exporter does not recompute R/L/C/G; it writes the values as

present in the groups/components at the time of export.*

• file_name::String = "*_export.xml": Output file name or path. If a relative path is given, it is resolved against the exporter’s source directory. The absolute path of the saved file is returned.

Behavior

1. Create the ATPDraw <project> root and header and insert a single LCC component with NumPhases = length(cable_system.cables).

2. For each CablePosition in cable_system.cables:

   • Write a <cable> element with:

 * `NumCond` = number of [`CableComponent`](@ref)s in the design,
 * `Rout` = outermost radius of the design (m),
 * `PosX`, `PosY` = cable coordinates (m).

1. For each CableComponent inside a cable:

   • Write one <conductor> element with fields (all per unit length):

 * `Rin`, `Rout` — from the component’s conductor group,
 * `rho` — conductor equivalence via [`calc_equivalent_rho`](@ref),
 * `muC` — conductor relative permeability via [`calc_equivalent_mu`](@ref),
 * `muI` — insulator relative permeability (taken from the first insulating layer’s material),
 * `epsI` — insulation relative permittivity via [`calc_equivalent_eps`](@ref),
 * `Cext`, `Gext` — shunt capacitance and conductance from the component’s insulator group.

1. Soil resistivity is written as Grnd resis using earth_props.layers[end].base_rho_g.
2. The XML is pretty‑printed and written to file_name. On I/O error, the function logs an error and returns nothing.

Units

Units are printed in the XML file according to the ATPDraw specifications:

• Radii (Rin, Rout, Rout of cable): [m]
• Coordinates (PosX, PosY): [m]
• Length (Length tag): [m]
• Frequency (SysFreq/Freq): [Hz]
• Resistivity (rho, Grnd resis): [Ω·m]
• Relative permittivity (epsI) / permeability (muC, muI): [dimensionless]
• Shunt capacitance (Cext): [F/m]
• Shunt conductance (Gext): [S/m]

Notes

• The exporter assumes each component’s equivalent parameters (R/G/C and derived ρ/ε/μ) were already computed by the design/group constructors at the operating conditions of interest.
• Mixed numeric types are supported; values are stringified for XML output. When using uncertainty types (e.g., Measurements.Measurement), the uncertainty is removed.
• Overlap checks between cables are enforced when building the system, not during export.

Examples

# Build or load a system `sys` and an earth model `earth`
file = export_data(Val(:atp), sys, earth; base_freq = 50.0,
					   file_name = "system_id_export.xml")
println("Exported to: ", file)

See also

• LineCableSystem, CablePosition, CableComponent
• EarthModel
• calc_equivalent_rho, calc_equivalent_mu, calc_equivalent_eps

export_data(
    ::Val{:atp},
    line_params::LineParameters;
    file_name,
    cable_system
) -> Union{Nothing, String}

Export calculated LineParameters (series impedance Z and shunt admittance Y) to an compliant ZY XML file.

This routine writes the complex Z and Y matrices versus frequency into a compact XML structure understood by external tools. Rows are emitted as comma‑separated complex entries (R+Xi / G+Bi) with one <Z>/<Y> block per frequency sample.

Arguments

• ::Val{:atp}: Backend selector for the ATP/ATPDraw ZY exporter.
• line_params::LineParameters: Object holding the frequency‑dependent matrices Z[:,:,k], Y[:,:,k], and f[k] in line_params.f.
• file_name::String = "ZY_export.xml": Output file name or path. If relative, it is resolved against the exporter’s source directory. The absolute path of the saved file is returned.
• cable_system::Union{LineCableSystem,Nothing} = nothing: Optional system used only to derive a default name. When provided and file_name is not overridden, the exporter uses "$(cable_system.system_id)_ZY_export.xml".

Behavior

1. The root tag <ZY> includes NumPhases, Length (fixed to 1.0), and format attributes ZFmt="R+Xi", YFmt="G+Bi".

2. For each frequency fᵏ = line_params.f[k]:

   • Emit a <Z Freq=...> block with num_phases lines, each line the k‑th slice of row i formatted as real(Z[i,j,k]) + imag(Z[i,j,k])i.
   • Emit a <Y Freq=...> block in the same fashion (default G+Bi).

3. Close the </ZY> element and write to disk. On I/O error the function logs and returns nothing.

Units

Units are printed in the XML file according to the ATPDraw specifications:

• freq (XML Freq attribute): [Hz]
• Z entries: [Ω/km] (per unit length)
• Y entries: [S/km] (per unit length) when YFmt = "G+Bi"
• XML Length attribute: [m]

Notes

• The exporter assumes size(line_params.Z, 1) == size(line_params.Z, 2) == size(line_params.Y, 1) == size(line_params.Y, 2) and length(line_params.f) == size(Z,3) == size(Y,3).
• Numeric types are stringified; mixed numeric backends (e.g., with uncertainties) are acceptable as long as they can be printed via @sprintf.
• This exporter does not modify or recompute matrices; it serializes exactly what is in line_params.

Examples

# Z, Y, f have already been computed into `lp::LineParameters`
file = export_data(:atp, lp; file_name = "ZY_export.xml")
println("Exported ZY to: ", file)

# Naming based on a cable system
file2 = export_data(:atp, lp; cable_system = sys)
println("Exported ZY to: ", file2)  # => "$(sys.system_id)_ZY_export.xml"

See also

• LineParameters
• LineCableSystem
• export_data(::Val{:atp}, cable_system, ...) — exporter that writes full LCC input data

export_data(
    ::Val{:pscad},
    cable_system::LineCableSystem,
    earth_props::EarthModel;
    base_freq,
    file_name
) -> Union{Nothing, String}

Exports a LineCableSystem to a PSCAD-compatible file format.

Arguments

• cable_system: A LineCableSystem object representing the cable system to be exported.
• earth_props: An EarthModel object containing the earth properties.
• base_freq: The base frequency [Hz] used for the PSCAD export.
• file_name: The path to the output file (default: "*_export.pscx")

Returns

• The absolute path of the saved file, or nothing on failure.

Examples

cable_system = LineCableSystem(...)
earth_model = EarthModel(...)
export_data(cable_system, earth_model, base_freq=50)

See also

• LineCableSystem

load!(library::CablesLibrary; file_name) -> CablesLibrary

Loads cable designs from a file into an existing CablesLibrary object. Modifies the library in-place. The format is determined by the file extension:

• .json: Loads using the custom JSON deserialization and reconstruction.
• .jls: Loads using Julia's native binary deserialization.

Arguments

• library: The CablesLibrary instance to populate (modified in-place).
• file_name: Path to the file to load (default: "cables_library.json").

Returns

• The modified CablesLibrary instance.

load!(
    library::MaterialsLibrary;
    file_name
) -> MaterialsLibrary

Loads materials from a JSON file into an existing MaterialsLibrary object. Modifies the library in-place.

Arguments

• library: The MaterialsLibrary instance to populate (modified in-place).
• file_name: Path to the JSON file to load (default: "materials_library.json").

Returns

• The modified MaterialsLibrary instance.

See also

• MaterialsLibrary

save(
    library::CablesLibrary;
    file_name
) -> Union{Nothing, String}

Saves a CablesLibrary to a file. The format is determined by the file extension:

• .json: Saves using the custom JSON serialization.
• .jls: Saves using Julia native binary serialization.

Arguments

• library: The CablesLibrary instance to save.
• file_name: The path to the output file (default: "cables_library.json").

Returns

• The absolute path of the saved file, or nothing on failure.

save(
    library::MaterialsLibrary;
    file_name
) -> Union{Nothing, String}

Saves a MaterialsLibrary to a JSON file.

Arguments

• library: The MaterialsLibrary instance to save.
• file_name: The path to the output JSON file (default: "materials_library.json").

Returns

• The absolute path of the saved file, or nothing on failure.

LineCableModels.Materials

The Materials module provides functionality for managing and utilizing material properties within the LineCableModels.jl package. This module includes definitions for material properties, a library for storing and retrieving materials, and functions for manipulating material data.

Overview

• Defines the Material struct representing fundamental physical properties of materials.
• Provides the MaterialsLibrary mutable struct for storing a collection of materials.
• Includes functions for adding, removing, and retrieving materials from the library.
• Supports loading and saving material data from/to JSON files.
• Contains utility functions for displaying material data.

Dependencies

• Base
• LineCableModels.Commons
• Measurements

Exports

• Material
• MaterialsLibrary

struct Material{T<:Union{Float64, Measurements.Measurement{Float64}}}

Defines electromagnetic and thermal properties of a material used in cable modeling:

• rho::Union{Float64, Measurements.Measurement{Float64}}: Electrical resistivity of the material [Ω·m].

• eps_r::Union{Float64, Measurements.Measurement{Float64}}: Relative permittivity [dimensionless].

• mu_r::Union{Float64, Measurements.Measurement{Float64}}: Relative permeability [dimensionless].

• T0::Union{Float64, Measurements.Measurement{Float64}}: Reference temperature for property evaluations [°C].

• alpha::Union{Float64, Measurements.Measurement{Float64}}: Temperature coefficient of resistivity [1/°C].

Material(rho, eps_r, mu_r, T0, alpha) -> Material

Weakly-typed constructor that infers the target scalar type T from the arguments, coerces values to T, and calls the strict numeric kernel.

Arguments

• rho: Resistivity [Ω·m].
• eps_r: Relative permittivity [1].
• mu_r: Relative permeability [1].
• T0: Reference temperature [°C].
• alpha: Temperature coefficient of resistivity [1/°C].

Returns

• Material{T} where T = resolve_T(rho, eps_r, mu_r, T0, alpha).

mutable struct MaterialsLibrary <: AbstractDict{String, Material}

Stores a collection of predefined materials for cable modeling, indexed by material name:

• data::Dict{String, Material}: Dictionary mapping material names to Material objects.

MaterialsLibrary(; add_defaults) -> MaterialsLibrary

Constructs an empty MaterialsLibrary instance and initializes with default materials.

Arguments

• None.

Returns

• A MaterialsLibrary object populated with default materials.

Examples

# Create a new, empty library
library = MaterialsLibrary()

See also

• Material
• _add_default_materials!

LineCableModels.Utils

The Utils module provides utility functions for the LineCableModels.jl package. This module includes functions for handling measurements, numerical comparisons, and other common tasks.

Overview

• Provides general constants used throughout the package.
• Includes utility functions for numerical comparisons and handling measurements.
• Contains functions to compute uncertainties and bounds for measurements.

Dependencies

• Base
• Dates
• LineCableModels.Commons
• LinearAlgebra
• Logging
• Plots
• Printf
• Statistics

Exports

• _bessel_diff
• _to_σ
• bias_to_uncertain
• coerce_to_T
• display_path
• is_headless
• is_in_testset
• line_transpose!
• percent_error
• percent_to_uncertain
• resolve_T
• set_verbosity!
• symtrans!
• to_certain
• to_lower
• to_nominal
• to_upper

bias_to_uncertain(
    nominal::Float64,
    measurements::Vector{<:Measurements.Measurement}
) -> Any

Computes the uncertainty of a measurement by incorporating systematic bias.

Arguments

• nominal: The deterministic nominal value (Float64).
• measurements: A vector of Measurement values from the Measurements.jl package.

Returns

• A new Measurement object representing the mean measurement value with an uncertainty that accounts for both statistical variation and systematic bias.

Notes

• Computes the mean value and its associated uncertainty from the given measurements.
• Determines the bias as the absolute difference between the deterministic nominal value and the mean measurement.
• The final uncertainty is the sum of the standard uncertainty (sigma_mean) and the systematic bias.

Examples

using Measurements

nominal = 10.0
measurements = [10.2 ± 0.1, 9.8 ± 0.2, 10.1 ± 0.15]
result = bias_to_uncertain(nominal, measurements)
println(result)  # Output: Measurement with adjusted uncertainty

Public coercion API. Converts scalars and containers to a target type T, applying element‑wise coercion recursively. Complex numbers are handled by splitting into real and imaginary parts and coercing each side independently.

Arguments

• x: Input value (scalar or container) [dimensionless].
• ::Type{T}: Target type [dimensionless].

Returns

• Value coerced to the target type:
  • For Real → Complex{P}: constructs Complex{P}(coerce_to_T(re, P), coerce_to_T(im, P)) (imaginary part from 0).
  • For Complex → Real: discards the imaginary part and coerces the real part.
  • For AbstractArray, Tuple, NamedTuple: coerces each element recursively.
  • For other types: defers to _coerce_elt_to_T.

Examples

using Measurements

# Scalar
coerce_to_T(1.2, Float32)                         # 1.2f0
coerce_to_T(1.2, Measurement{Float64})            # 1.2 ± 0.0
coerce_to_T(1 + 2im, Complex{Float32})            # 1.0f0 + 2.0f0im
coerce_to_T(1 + 2im, Float64)                     # 1.0

# Containers
coerce_to_T([1.0, 2.0], Measurement{Float64})     # measurement array
coerce_to_T((1.0, 2.0), Float32)                  # (1.0f0, 2.0f0)
coerce_to_T((; a=1.0, b=2.0), Float32)            # (a = 1.0f0, b = 2.0f0)

Methods

coerce_to_T(x, _)

defined at typecoercion.jl:262.

coerce_to_T(x, _)

defined at typecoercion.jl:266.

coerce_to_T(x, _)

defined at typecoercion.jl:269.

coerce_to_T(x, _)

defined at typecoercion.jl:272.

coerce_to_T(x, _)

defined at typecoercion.jl:276.

coerce_to_T(x, _)

defined at typecoercion.jl:279.

coerce_to_T(A, _)

defined at typecoercion.jl:283.

coerce_to_T(A, _)

defined at typecoercion.jl:284.

coerce_to_T(t, _)

defined at typecoercion.jl:287.

coerce_to_T(t, _)

defined at typecoercion.jl:288.

coerce_to_T(nt, _)

defined at typecoercion.jl:292.

coerce_to_T(nt, _)

defined at typecoercion.jl:294.

coerce_to_T(x, _)

defined at typecoercion.jl:298.

See also

• _coerce_elt_to_T
• resolve_T

is_headless() -> Bool

Determines if the current execution environment is headless (without display capability).

Returns

• true if running in a continuous integration environment or without display access.
• false otherwise when a display is available.

Examples

if is_headless()
	# Use non-graphical backend
	gr()
else
	# Use interactive backend
	plotlyjs()
end

is_in_testset() -> Any

Checks if the code is running inside a @testset by checking if Test is loaded in the current session and then calling get_testset_depth().

percent_error(m::Number) -> Any

Computes the percentage uncertainty of a measurement.

Arguments

• m: A numerical value, expected to be of type Measurement from the Measurements.jl package.

Returns

• The percentage uncertainty, computed as 100 * uncertainty(m) / value(m), if m is a Measurement.
• NaN if m is not a Measurement.

Examples

using Measurements

m = 10.0 ± 2.0
percent_err = percent_error(m)  # Output: 20.0

not_a_measurement = 5.0
percent_err_invalid = percent_error(not_a_measurement)  # Output: NaN

percent_to_uncertain(val, perc) -> Any

Converts a value to a measurement with uncertainty based on percentage.

Arguments

• val: The nominal value.
• perc: The percentage uncertainty (0 to 100).

Returns

• A Measurement type with the given value and calculated uncertainty.

Examples

using Measurements

percent_to_uncertain(100.0, 5)  # Output: 100.0 ± 5.0
percent_to_uncertain(10.0, 10)  # Output: 10.0 ± 1.0

resolve_T(args...) -> Type

Resolves the promotion target type to be used by constructors and coercion utilities based on the runtime arguments. The decision uses structure‑aware predicates for Measurement and Complex:

• If any argument contains Measurement and any contains Complex, returns Complex{Measurement{BASE_FLOAT}}.
• Else if any contains Measurement, returns Measurement{BASE_FLOAT}.
• Else if any contains Complex, returns Complex{BASE_FLOAT}.
• Otherwise returns BASE_FLOAT.

Arguments

• args...: Values whose types will drive the promotion decision [dimensionless].

Returns

• A Type suitable for numeric promotion in subsequent coercion.

Examples

using Measurements

T = resolve_T(1.0, 2.0)                       # BASE_FLOAT
T = resolve_T(1 + 0im, 2.0)                    # Complex{BASE_FLOAT}
T = resolve_T(measurement(1.0, 0.1), 2.0)      # Measurement{BASE_FLOAT}
T = resolve_T(measurement(1.0, 0.1), 2 + 0im)  # Complex{Measurement{BASE_FLOAT}}

to_certain(value) -> Any

Converts a measurement to a value with zero uncertainty, retaining the numeric type Measurement.

Arguments

• value: Input value that may be a Measurement type or another type.

Returns

• If input is a Measurement, returns the same value with zero uncertainty; otherwise returns the original value unchanged.

Examples

x = 5.0 ± 0.1
result = to_certain(x)  # Output: 5.0 ± 0.0

y = 10.0
result = to_certain(y)  # Output: 10.0

to_lower(m::Number) -> Any

Computes the lower bound of a measurement value.

Arguments

• m: A numerical value, expected to be of type Measurement from the Measurements.jl package.

Returns

• The lower bound, computed as value(m) - uncertainty(m) if m is a Measurement.
• NaN if m is not a Measurement.

Examples

using Measurements

m = 10.0 ± 2.0
lower = to_lower(m)  # Output: 8.0

not_a_measurement = 5.0
lower_invalid = to_lower(not_a_measurement)  # Output: NaN

to_nominal(x::Measurements.Measurement) -> AbstractFloat

Returns the nominal (deterministic) value of inputs that may contain Measurements.Measurement numbers, recursively handling Complex and arrays.

Arguments

• x: Input value which can be a Measurement type or any other type.

Returns

• Measurement → its value
• Complex → complex(to_nominal(real(z)), to_nominal(imag(z)))
• AbstractArray → broadcasts to_nominal elementwise
• Anything else → returned unchanged

Examples

using Measurements

to_nominal(1.0)  # Output: 1.0
to_nominal(5.2 ± 0.3)  # Output: 5.2

to_upper(m::Number) -> Any

Computes the upper bound of a measurement value.

Arguments

• m: A numerical value, expected to be of type Measurement from the Measurements.jl package.

Returns

• The upper bound of m, computed as value(m) + uncertainty(m) if m is a Measurement.
• NaN if m is not a Measurement.

Examples

using Measurements

m = 10.0 ± 2.0
upper = to_upper(m)  # Output: 12.0

not_a_measurement = 5.0
upper_invalid = to_upper(not_a_measurement)  # Output: NaN

LineCableModels.UncertainBessels

Uncertainty-aware wrappers for Bessel functions.

UncertainBessels lifts selected functions from SpecialFunctions so they accept Measurement and Complex{Measurement} inputs. The wrapper evaluates the underlying function at the nominal complex argument and propagates uncertainty via first-order finite differences using the four partial derivatives $\frac{\partial \mathrm{Re} \, f}{\partial x}, \frac{\partial \mathrm{Re} \, f}{\partial y}, \frac{\partial \mathrm{Im} \, f}{\partial x}, \frac{\partial \mathrm{Im} \, f}{\partial y}$ with $x = \mathrm{Re}(z)$ and $y = \mathrm{Im}(z)$. No new Bessel algorithms are implemented: for plain numeric inputs, results and numerical behaviour are those of SpecialFunctions.

Numerical scaling (as defined by SpecialFunctions) is supported for the “x” variants (e.g. besselix, besselkx, besseljx, …) to improve stability for large or complex arguments. In particular, the modified functions use exponential factors to temper growth along $\mathrm{Re}(z)$ (e.g. $I_\nu$ and $K_\nu$); other scaled variants follow conventions in SpecialFunctions and DLMF guidance for complex arguments. See [19] and [20].

Overview

• Thin, uncertainty-aware wrappers around SpecialFunctions (besselj, bessely, besseli, besselk, besselh) and their scaled counterparts (…x).
• For Complex{Measurement} inputs, uncertainty is propagated using the 4-component gradient with respect to $\mathrm{Re}(z)$ and $\mathrm{Im}(z)$.
• For Measurement (real) inputs, a 1-D finite-difference derivative is used.
• No change in semantics for Real/Complex inputs: calls delegate to SpecialFunctions.

Dependencies

• Base
• LineCableModels.Commons

Exports

• besselh
• besselhx
• besseli
• besselix
• besselj
• besseljx
• besselk
• besselkx
• bessely
• besselyx

Usage

# do not import SpecialFunctions directly
using LineCableModels.UncertainBessels 
z = complex(1.0, 1.0 ± 0.5)
J0_cpl = besselj(0, z) 			# Complex{Measurement}
J0_nom = besselj(0, value(z)) 	# nominal comparison
I1 = besselix(1, z) 			# scaled I1 with uncertainty

Numerical notes

• Scaled modified Bessels remove large exponential factors along $\mathrm{Re}(z)$ (e.g., $I_\nu$ and $K_\nu$ are scaled by opposite signs of $|\mathrm{Re}(z)|$), improving conditioning. Scaled forms for the other families follow the definitions in SpecialFunctions and DLMF.
• Uncertainty propagation is first order (linearization at the nominal point). Large uncertainties or strong nonlinearity may reduce accuracy.

See also

• LineCableModels.Engine.InternalImpedance
• LineCableModels.Engine.EarthImpedance

DataFrame(design::CableDesign; ...) -> DataFrames.DataFrame
DataFrame(
    design::CableDesign,
    format::Symbol;
    S,
    rho_e
) -> DataFrames.DataFrame

Extracts and displays data from a CableDesign.

Arguments

• design: A CableDesign object to extract data from.
• format: Symbol indicating the level of detail:
  • :baseparams: Basic RLC parameters with nominal value comparison (default).
  • :components: Component-level equivalent properties.
  • :detailed: Individual cable part properties with layer-by-layer breakdown.
• S: Separation distance between cables [m] (only used for :baseparams format). Default: outermost cable diameter.
• rho_e: Resistivity of the earth [Ω·m] (only used for :baseparams format). Default: 100.

Returns

• A DataFrame containing the requested cable data in the specified format.

Examples

# Get basic RLC parameters
data = DataFrame(design)  # Default is :baseparams format

# Get component-level data
comp_data = DataFrame(design, :components)

# Get detailed part-by-part breakdown
detailed_data = DataFrame(design, :detailed)

# Specify earth parameters for core calculations
core_data = DataFrame(design, :baseparams, S=0.5, rho_e=150)

See also

• CableDesign
• calc_tubular_resistance
• calc_inductance_trifoil
• calc_shunt_capacitance

DataFrame(library::CablesLibrary) -> DataFrames.DataFrame

Lists the cable designs in a CablesLibrary object as a DataFrame.

Arguments

• library: An instance of CablesLibrary whose cable designs are to be displayed.

Returns

• A DataFrame object with the following columns:
  • cable_id: The unique identifier for each cable design.
  • nominal_data: A string representation of the nominal data for each cable design.
  • components: A comma-separated string listing the components of each cable design.

Examples

library = CablesLibrary()
design1 = CableDesign("example1", nominal_data=NominalData(...), components=Dict("A"=>...))
design2 = CableDesign("example2", nominal_data=NominalData(...), components=Dict("C"=>...))
add!(library, design1)
add!(library, design2)

# Display the library as a DataFrame
df = DataFrame(library)
first(df, 5)  # Show the first 5 rows of the DataFrame

See also

• CablesLibrary
• CableDesign
• add!

DataFrame(system::LineCableSystem) -> DataFrames.DataFrame

Generates a summary DataFrame for cable positions and phase mappings within a LineCableSystem.

Arguments

• system: A LineCableSystem object containing the cable definitions and their configurations.

Returns

• A DataFrame containing:
  • cable_id: Identifier of each cable design.
  • horz: Horizontal coordinate of each cable [m].
  • vert: Vertical coordinate of each cable [m].
  • phase_mapping: Human-readable string representation mapping each cable component to its assigned phase.

Examples

df = DataFrame(cable_system)
println(df)
# Output:
# │ cable_id   │ horz │ vert  │ phase_mapping           │
# │------------│------│-------│-------------------------│
# │ "Cable1"   │ 0.0  │ -0.5  │ core: 1, sheath: 0      │
# │ "Cable2"   │ 0.35 │ -1.25 │ core: 2, sheath: 0      │

See also

• LineCableSystem
• CablePosition

abstract type AbstractCablePart{T}

Abstract type representing a generic cable part.

abstract type AbstractConductorPart{T} <: LineCableModels.DataModel.AbstractCablePart{T}

Abstract type representing a conductive part of a cable.

Subtypes implement specific configurations:

• Tubular
• Strip

abstract type AbstractInsulatorPart{T} <: LineCableModels.DataModel.AbstractCablePart{T}

Abstract type representing an insulating part of a cable.

Subtypes implement specific configurations:

• Insulator
• Semicon

abstract type AbstractStrandsLayer{T} <: LineCableModels.DataModel.AbstractConductorPart{T}

Abstract type representing all stranded configurations composed of grouped discrete geometric shapes.

Subtypes implement specific configurations:

• CircStrands
• RectStrands

struct RectStrandsShape{T<:Union{Float64, Measurements.Measurement{Float64}}, U<:Int64} <: LineCableModels.DataModel.AbstractShapeGeometry

Holds the pure geometric layout for a concentric layer of rectangular/flat strands.

struct SectorGeometryValid <: LineCableModels.Validation.Rule

Rule that enforces specific Sector geometry constraints (discriminant, angle limits, no overlap).

delete!(library::CablesLibrary, cable_id::String)

Removes a cable design from a CablesLibrary object by its ID.

Arguments

• library: An instance of CablesLibrary from which the cable design will be removed.
• cable_id: The ID of the cable design to remove.

Returns

• Nothing. Modifies the data field of the CablesLibrary object in-place by removing the specified cable design if it exists.

Examples

library = CablesLibrary()
design = CableDesign("example", ...) # Initialize a CableDesign
add!(library, design)

# Remove the cable design
delete!(library, "example")
haskey(library, "example")  # Returns false

See also

• CablesLibrary
• add!

get(
    library::CablesLibrary,
    cable_id::String
) -> Union{Nothing, CableDesign}
get(
    library::CablesLibrary,
    cable_id::String,
    default
) -> Any

Retrieves a cable design from a CablesLibrary object by its ID.

Arguments

• library: An instance of CablesLibrary from which the cable design will be retrieved.
• cable_id: The ID of the cable design to retrieve.

Returns

• A CableDesign object corresponding to the given cable_id if found, otherwise nothing.

Examples

library = CablesLibrary()
design = CableDesign("example", ...) # Initialize a CableDesign
add!(library, design)

# Retrieve the cable design
retrieved_design = get(library, "cable1")
println(retrieved_design.id)  # Prints "example"

# Attempt to retrieve a non-existent design
missing_design = get(library, "nonexistent_id")
println(missing_design === nothing)  # Prints true

See also

• CablesLibrary
• CableDesign
• add!
• delete!

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    component::CableComponent
)

Defines the display representation of a CableComponent object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• component: The CableComponent object to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the object.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    design::CableDesign
)

Defines the display representation of a CableDesign object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• design: The CableDesign object to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the object.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    group::Union{ConductorGroup, InsulatorGroup}
)

Defines the display representation of a ConductorGroup or InsulatorGroupobjects for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• group: The ConductorGroup or InsulatorGroup instance to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the object.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    part::LineCableModels.DataModel.AbstractCablePart
)

Defines the display representation of an AbstractCablePart object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• part: The AbstractCablePart instance to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the object.

Stores a cable design in a CablesLibrary object.

Arguments

• library: An instance of CablesLibrary to which the cable design will be added.
• design: A CableDesign object representing the cable design to be added. This object must have a cable_id field to uniquely identify it.

Returns

• None. Modifies the data field of the CablesLibrary object in-place by adding the new cable design.

Examples

library = CablesLibrary()
design = CableDesign("example", ...) # Initialize CableDesign with required fields
add!(library, design)
println(library) # Prints the updated dictionary containing the new cable design

See also

• CablesLibrary
• CableDesign
• delete!

add!(
    group::ConductorGroup{T},
    part_type::Type{C<:LineCableModels.DataModel.AbstractConductorPart},
    args...;
    kwargs...
) -> ConductorGroup{Tg} where Tg

Add a new conductor part to a ConductorGroup, validating raw inputs, normalizing proxies, and promoting the group’s numeric type if required.

Behavior:

1. Apply part-level keyword defaults.
2. Default r_in to group.r_ex if absent.
3. Compute Tnew = resolve_T(group, r_in, args..., values(kwargs)...).
4. If Tnew === T, mutate in place; else coerce_to_T(group, Tnew) then mutate and return the promoted group.

Arguments

• group: ConductorGroup object to which the new part will be added.
• part_type: Type of conductor part to add (AbstractConductorPart).
• args...: Positional arguments specific to the constructor of the part_type (AbstractConductorPart) [various].
• kwargs...: Named arguments for the constructor including optional values specific to the constructor of the part_type (AbstractConductorPart) [various].

Returns

• The function modifies the ConductorGroup instance in place and does not return a value.

Notes

• Updates gmr, resistance, alpha, r_ex, cross_section, and num_wires to account for the new part.
• The temperature of the new part defaults to the temperature of the first layer if not specified.
• The r_in of the new part defaults to the external radius of the existing conductor if not specified.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
conductor = ConductorGroup(Strip(0.01, 0.002, 0.05, 10, material_props))
add!(conductor, CircStrands, 0.02, 0.002, 7, 15, material_props, temperature = 25)

See also

• ConductorGroup
• CircStrands
• Strip
• Tubular
• calc_equivalent_gmr
• calc_parallel_equivalent
• calc_equivalent_alpha

add!(
    group::InsulatorGroup{T},
    part_type::Type{C<:LineCableModels.DataModel.AbstractInsulatorPart},
    args...;
    f,
    kwargs...
) -> InsulatorGroup{Tg} where Tg

Adds a new part to an existing InsulatorGroup object and updates its equivalent electrical parameters.

Behavior:

1. Apply part-level keyword defaults (from Validation.keyword_defaults).
2. Default r_in to group.r_ex if absent.
3. Compute Tnew = resolve_T(group, r_in, args..., values(kwargs)..., f).
4. If Tnew === T, mutate in place; else coerce_to_T(group, Tnew) then mutate and return the promoted group.

Arguments

• group: InsulatorGroup object to which the new part will be added.
• part_type: Type of insulator part to add (AbstractInsulatorPart).
• args...: Positional arguments specific to the constructor of the part_type (AbstractInsulatorPart) [various].
• kwargs...: Named arguments for the constructor including optional values specific to the constructor of the part_type (AbstractInsulatorPart) [various].

Returns

• The function modifies the InsulatorGroup instance in place and does not return a value.

Notes

• Updates shunt_capacitance, shunt_conductance, r_ex, and cross_section to account for the new part.
• The r_in of the new part defaults to the external radius of the existing insulator group if not specified.

Examples

material_props = Material(1e10, 3.0, 1.0, 20.0, 0.0)
insulator_group = InsulatorGroup(Insulator(0.01, 0.015, material_props))
add!(insulator_group, Semicon, 0.015, 0.018, material_props)

See also

• InsulatorGroup
• Insulator
• Semicon
• calc_parallel_equivalent

add!(
    system::LineCableSystem{T},
    cable::CableDesign,
    horz::Number,
    vert::Number
) -> LineCableSystem{T} where T
add!(
    system::LineCableSystem{T},
    cable::CableDesign,
    horz::Number,
    vert::Number,
    conn::Union{Nothing, Dict{String, Int64}}
) -> LineCableSystem{T} where T

Convenience add! that accepts a cable design and coordinates (and optional mapping). Builds a CablePosition and forwards to add!(system, pos).

add!(
    system::LineCableSystem{T},
    pos::CablePosition
) -> LineCableSystem{T} where T

Adds a new cable position to an existing LineCableSystem, updating its phase mapping and cable count. If adding the position introduces a different numeric scalar type, the system is promoted and the promoted system is returned. Otherwise, mutation happens in place.

Arguments

• system: Instance of LineCableSystem to which the cable will be added.
• cable: A CableDesign object defining the cable structure.
• horz: Horizontal coordinate [m].
• vert: Vertical coordinate [m].
• conn: Dictionary mapping component names to phase indices, or nothing for automatic assignment.

Returns

• The modified LineCableSystem object with the new cable added.

Examples

cable_design = CableDesign("example", nominal_data, components_dict)

# Define coordinates for two cables
xa, ya = 0.0, -1.0
xb, yb = 1.0, -2.0

# Create initial system with one cable
cablepos1 = CablePosition(cable_design, xa, ya, Dict("core" => 1))
cable_system = LineCableSystem("test_case_1", 1000.0, cablepos1)

# Add second cable to system
add!(cable_system, cable_design, xb, yb, Dict("core" => 2))

println(cable_system.num_cables)  # Prints: 2

See also

• LineCableSystem
• CablePosition
• CableDesign

_coerced_args(_::Type{C}, ntv, Tp, order::Tuple) -> Tuple

Builds the positional argument tuple to feed the typed core constructor, coercing only the fields returned by coercive_fields(C) to type Tp. Non‑coercive fields (e.g., integer flags) are passed through unchanged. Field order is controlled by order (a tuple of symbols), typically (required_fields(C)..., keyword_fields(C)...).

Arguments

• ::Type{C}: Component type [dimensionless].
• ntv: Normalized NamedTuple returned by validate! [dimensionless].
• Tp: Target element type for numeric coercion [dimensionless].
• order::Tuple: Field order used to assemble the positional tuple [dimensionless].

Returns

• A Tuple of arguments in the requested order, with coercions applied where configured.

Examples

args = _coerced_args(Tubular, ntv, Float64, (:r_in, :r_ex, :material_props, :temperature))

_ctor_materialize(mod, x) -> Any

Utility for the constructor macro to materialize input tuples from either:

• A tuple literal expression (e.g., (:a, :b, :c)), or
• A bound constant tuple name (e.g., _REQ_TUBULAR).

Used to keep macro call sites short while allowing both styles.

Arguments

• mod: Module where constants are resolved [dimensionless].
• x: Expression or symbol representing a tuple [dimensionless].

Returns

• A standard Julia Tuple (of symbols or defaults).

Errors

• ErrorException if x is neither a tuple literal nor a bound constant name.

Examples

syms = _ctor_materialize(@__MODULE__, :( :a, :b ))
syms = _ctor_materialize(@__MODULE__, :_REQ_TUBULAR)

_do_add!(
    group::ConductorGroup{Tg},
    C::Type{<:LineCableModels.DataModel.AbstractConductorPart},
    args...;
    kwargs...
)

Internal, in-place insertion (no promotion logic). Assumes :r_in was materialized. Runs Validation → parsing, then coerces fields to the group’s T and updates equivalent properties and book-keeping.

_do_add!(
    group::InsulatorGroup{Tg},
    C::Type{<:LineCableModels.DataModel.AbstractInsulatorPart},
    args...;
    f,
    kwargs...
)

Do the actual insertion for InsulatorGroup with the group already at the correct scalar type. Validates/parses the part, coerces to the group’s T, constructs the strict numeric core, and updates geometry and admittances at the provided frequency.

Returns the mutated group (same object).

_extract_part_properties(part, properties) -> Any

Helper function to extract properties from a part for detailed format.

Arguments

• part: An instance of AbstractCablePart from which to extract properties.
• properties: A vector of symbols indicating which properties to extract (not used in the current implementation).

Returns

• A vector containing the extracted properties in the following order:
  • type: The lowercase string representation of the part's type.
  • r_in: The inner radius of the part, if it exists, otherwise missing.
  • r_ex: The outer radius of the part, if it exists, otherwise missing.
  • diameter_in: The inner diameter of the part (2 * rin), if `rinexists, otherwisemissing`.
  • diameter_ext: The outer diameter of the part (2 * rex), if `rexexists, otherwisemissing`.
  • thickness: The difference between r_ex and r_in, if both exist, otherwise missing.
  • cross_section: The cross-sectional area of the part, if it exists, otherwise missing.
  • num_wires: The number of wires in the part, if it exists, otherwise missing.
  • resistance: The resistance of the part, if it exists, otherwise missing.
  • alpha: The temperature coefficient of resistivity of the part or its material, if it exists, otherwise missing.
  • gmr: The geometric mean radius of the part, if it exists, otherwise missing.
  • gmr_ratio: The ratio of gmr to r_ex, if both exist, otherwise missing.
  • shunt_capacitance: The shunt capacitance of the part, if it exists, otherwise missing.
  • shunt_conductance: The shunt conductance of the part, if it exists, otherwise missing.

Notes

This function is used to create a standardized format for displaying detailed information about cable parts.

Examples

part = Conductor(...)
properties = [:r_in, :r_ex, :resistance]  # Example of properties to extract
extracted_properties = _extract_part_properties(part, properties)
println(extracted_properties)

_normalize_radii(_::Type{T}, rin, rex) -> Any

Resolves radius parameters for cable components, converting from various input formats to standardized inner radius, outer radius, and thickness values.

This function serves as a high-level interface to the radius resolution system. It processes inputs through a two-stage pipeline:

1. First normalizes input parameters to consistent forms using _parse_radius_operand.
2. Then delegates to specialized implementations via _do_resolve_radius based on the component type.

Arguments

• param_in: Inner boundary parameter (defaults to radius) [m]. Can be a number, a Diameter , a Thickness, or an AbstractCablePart.
• param_ext: Outer boundary parameter (defaults to radius) [m]. Can be a number, a Diameter , a Thickness, or an AbstractCablePart.
• object_type: Type associated to the constructor of the new AbstractCablePart.

Returns

• r_in: Normalized inner radius [m].
• r_ex: Normalized outer radius [m].
• thickness: Computed thickness or specialized dimension depending on the method [m]. For CircStrands components, this value represents the wire radius instead of thickness.

See also

• Diameter
• Thickness
• AbstractCablePart

Parses input values into radius representation based on object type and input type.

Arguments

• x: Input value that can be a raw number, a Diameter, a Thickness, or other convertible type [m].
• object_type: Type parameter used for dispatch.

Returns

• Parsed radius value in appropriate units [m].

Examples

radius = _parse_radius_operand(10.0, ...)   # Direct radius value
radius = _parse_radius_operand(Diameter(20.0), ...)  # From diameter object
radius = _parse_radius_operand(Thickness(5.0), ...)  # From thickness object

Methods

_parse_radius_operand(x, _)

defined at radii.jl:68.

_parse_radius_operand(d, _)

defined at radii.jl:69.

_parse_radius_operand(p, _)

defined at radii.jl:70.

_parse_radius_operand(p, _)

defined at radii.jl:71.

_parse_radius_operand(x, _)

defined at radii.jl:75.

_parse_radius_operand(x, _)

defined at radii.jl:81.

See also

• Diameter
• Thickness

_print_fields(
    io::IO,
    obj,
    fields_to_show::Vector{Symbol};
    sigdigits
) -> Int64

Print the specified fields of an object in a compact format.

Arguments

• io: The output stream.
• obj: The object whose fields will be displayed.
• fields_to_show: Vector of field names (as Symbols) to display.
• sigdigits: Number of significant digits for rounding numeric values.

Returns

• Number of fields that were actually displayed.

_promotion_T(_::Type{C}, ntv, _order::Tuple) -> Type

Determines the promoted numeric element type for convenience constructors of component C. The promotion is computed across the values of coercive_fields(C), extracted from the normalized NamedTuple ntv produced by validate!. This ensures all numeric fields that participate in calculations share a common element type (e.g., Float64, Measurement{Float64}).

Arguments

• ::Type{C}: Component type [dimensionless].
• ntv: Normalized NamedTuple returned by validate! [dimensionless].
• _order::Tuple: Ignored by this method; present for arity symmetry with _coerced_args [dimensionless].

Returns

• The promoted numeric element type [dimensionless].

Examples

Tp = _promotion_T(Tubular, (r_in=0.01, r_ex=0.02, material_props=mat, temperature=20.0), ())

_with_kwdefaults(
    _::Type{C},
    kwargs::NamedTuple
) -> NamedTuple

Merge per-part keyword defaults declared via Validation.keyword_defaults with user-provided kwargs and return a NamedTuple suitable for forwarding.

Defaults may be a NamedTuple or a Tuple zipped against Validation.keyword_fields(::Type{C}). User keys always win.

get_material_color_makie(material_props; mu_scale=1.0, eps_scale=1.0)

Piecewise ρ→base color (metals→silver, semiconductors→amber, etc.) with blue/purple magnetic overlay (μr) and teal/cyan permittivity overlay (εr). mu_scale and eps_scale scale overlay strength (1.0 = default).

nonsensify(originaldesign::CableDesign; newid::String="")::CableDesign

Recreates a cable design by bulldozing reality into a "simplified" shape with only the so-called "main" material properties.

Translation: if you wanted physics, you came to the wrong neighborhood.

For each component, this abomination does:

• ConductorGroup(Tubular(...)) with radii stolen from the first and last conductor layers, and material blindly copied from the first conductor layer. Because high-fidelity is for losers.

• InsulatorGroup(Insulator(...)) spanning from the new conductor outer radius to the original insulator group's outer radius; material is taken from the first Insulator layer available (or whatever warm body it can find).

⚠ WARNING: This is deliberately nonsensical. It laughs in the face of proper equivalent property corrections and just slaps the "main" props on like duct tape. Use only when you don’t give a damn about accuracy and just want something that looks cable-ish, e.g., never.

vdeparse(code::AbstractString) -> Dict{Symbol,String}

Parses VDE/DIN 0271/0276 cable codes:

• stub (first non-space token): designation → conductormaterial (default copper) → insulation (default paper) → screen → waterblocking → innersheath → armouring → sheath → grounding
• tail: cores × cross-section (optional screen csa), voltage, conductor type (R/S/O + E/M/H, optional /V ⇒ compact)

Only parsed keys are returned; defaults are materialized when omitted.

Identity: no allocation when already at T.

is_radius_input(
    _::Type{T},
    _::Val{:r_ex},
    _::LineCableModels.DataModel.AbstractCablePart
) -> Bool

Default policy for outer radius raw inputs (annular shells): reject AbstractCablePart proxies. Outer radius must be numeric or a Thickness wrapper to avoid creating zero‑thickness layers.

Arguments

• ::Type{T}: Component type [dimensionless].
• ::Val{:r_ex}: Field tag for the outer radius [dimensionless].
• ::AbstractCablePart: Proxy object [dimensionless].

Returns

• false always.

Examples

Validation.is_radius_input(Tubular, Val(:r_ex), prev_layer)  # false

is_radius_input(
    _::Type{T},
    _::Val{:r_ex},
    _::Thickness
) -> Bool

Default policy for outer radius raw inputs (annular shells): accept Thickness as a convenience wrapper. The thickness is expanded to an outer radius during parsing.

Arguments

• ::Type{T}: Component type [dimensionless].
• ::Val{:r_ex}: Field tag for the outer radius [dimensionless].
• ::Thickness: Thickness wrapper [dimensionless].

Returns

• Bool indicating acceptance (true).

Examples

Validation.is_radius_input(Tubular, Val(:r_ex), Thickness(1e-3))  # true

is_radius_input(
    _::Type{T},
    _::Val{:r_in},
    p::LineCableModels.DataModel.AbstractCablePart
) -> Bool

Default policy for inner radius raw inputs: accept proxies that expose an outer radius. This permits stacking by hijacking p.r_ex during parsing.

Arguments

• ::Type{T}: Component type [dimensionless].
• ::Val{:r_in}: Field tag for the inner radius [dimensionless].
• p::AbstractCablePart: Proxy object [dimensionless].

Returns

• Bool indicating acceptance (true if hasproperty(p, :r_ex)).

Examples

Validation.is_radius_input(Tubular, Val(:r_in), prev_layer)  # true if prev_layer has :r_ex

maxfill(_::Type{T}, args...) -> Any

Fallback method for the maxfill interface. Throws an explicit error indicating that the component type T has not implemented its physical capacity limit.

Arguments

• ::Type{T}: Component type [dimensionless].
• args...: Geometric parameters required for the calculation [dimensionless].

Returns

• Nothing. Always throws an ArgumentError.

Generates a weakly‑typed convenience constructor for a component T. The generated method:

1. Accepts exactly the positional fields listed in REQ.
2. Accepts keyword arguments listed in OPT with defaults DEFS.
3. Calls validate!(T, ...) forwarding variables (not defaults),
4. Computes the promotion type via _promotion_T(T, ntv, order),
5. Coerces only coercive_fields(T) via _coerced_args(T, ntv, Tp, order),
6. Delegates to the numeric core T(...) with the coerced positional tuple.

REQ, OPT, and DEFS can be provided as tuple literals or as names of bound constant tuples. order is implicitly (REQ..., OPT...).

Arguments

• T: Component type (bare name) [dimensionless].
• REQ: Tuple of required positional field names [dimensionless].
• OPT: Tuple of optional keyword field names [dimensionless]. Defaults to ().
• DEFS: Tuple of default values matching OPT [dimensionless]. Defaults to ().

Returns

• A method definition for the weakly‑typed constructor.

Examples

const _REQ_TUBULAR = (:r_in, :r_ex, :material_props)
const _OPT_TUBULAR = (:temperature,)
const _DEFS_TUBULAR = (T₀,)

@construct Tubular _REQ_TUBULAR _OPT_TUBULAR _DEFS_TUBULAR

# Expands roughly to:
# function Tubular(r_in, r_ex, material_props; temperature=T₀)
#   ntv = validate!(Tubular, r_in, r_ex, material_props; temperature=temperature)
#   Tp  = _promotion_T(Tubular, ntv, (:r_in, :r_ex, :material_props, :temperature))
#   args = _coerced_args(Tubular, ntv, Tp, (:r_in, :r_ex, :material_props, :temperature))
#   return Tubular(args...)
# end

Notes

• Defaults supplied in DEFS are escaped into the method signature (evaluated at macro expansion time).
• Forwarding into validate! always uses variables (e.g., temperature=temperature), never literal defaults.
• The macro is hygiene‑aware; identifiers validate!, _promotion_T, _coerced_args, and the type name are properly escaped.

Errors

• ErrorException if length(OPT) != length(DEFS).

DataFrame(earth_model::EarthModel) -> DataFrames.DataFrame

Generates a DataFrame summarizing basic properties of earth layers from an EarthModel.

Arguments

• earth_model: Instance of EarthModel containing earth layers.

Returns

• A DataFrame with columns:
  • rho_g: Base (DC) resistivity of each layer [Ω·m].
  • epsr_g: Base (DC) relative permittivity of each layer [dimensionless].
  • mur_g: Base (DC) relative permeability of each layer [dimensionless].
  • thickness: Thickness of each layer [m].

Examples

df = DataFrame(earth_model)
println(df)

abstract type AbstractFDEMFormulation

Abstract type representing different frequency-dependent earth models (FDEM). Used in the multi-dispatch implementations in modules LineCableModels.EarthProps and LineCableModels.Engine.

Currently available formulations

• CPEarth: Constant properties (CP) model.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    model::EarthModel
)

Defines the display representation of a EarthModel object for REPL or text output.

Arguments

• io: The output stream to write the representation to [IO].
• mime: The MIME type for plain text output [MIME"text/plain"].
• model: The EarthModel instance to be displayed.

Returns

• Nothing. Modifies io to format the output.

add!(
    model::EarthModel{T<:Union{Float64, Measurements.Measurement{Float64}}},
    frequencies::Array{T<:Union{Float64, Measurements.Measurement{Float64}}, 1},
    base_rho_g::Union{Float64, Measurements.Measurement{Float64}},
    base_epsr_g::Union{Float64, Measurements.Measurement{Float64}},
    base_mur_g::Union{Float64, Measurements.Measurement{Float64}};
    t
) -> EarthModel

Adds a new earth layer to an existing EarthModel.

Arguments

• model: Instance of EarthModel to which the new layer will be added.
• frequencies: Vector of frequency values [Hz].
• base_rho_g: Base electrical resistivity of the new earth layer [Ω·m].
• base_epsr_g: Base relative permittivity of the new earth layer [dimensionless].
• base_mur_g: Base relative permeability of the new earth layer [dimensionless].
• t: Thickness of the new earth layer [m] (default: Inf).

Returns

• Modifies model in place by appending a new EarthLayer.

Notes

For horizontal layering (vertical_layers = false):

• Layer 1 (air) is always infinite (t = Inf).
• Layer 2 (first earth layer) can be infinite if modeling a homogeneous half-space.
• If adding a third layer (length(EarthModel.layers) == 3), it can be infinite only if the previous layer is finite.
• No two successive earth layers (length(EarthModel.layers) > 2) can have infinite thickness.

For vertical layering (vertical_layers = true):

• Layer 1 (air) is always horizontal and infinite at z > 0.
• Layer 2 (first vertical layer) is always infinite in z < 0 and y < 0. The first vertical layer is assumed to always end at y = 0.
• Layer 3 (second vertical layer) can be infinite (establishing a vertical interface at y = 0).
• Subsequent layers can be infinite only if the previous is finite.
• No two successive vertical layers (length(EarthModel.layers) > 3) can both be infinite.

Examples

frequencies = [1e3, 1e4, 1e5]

# Define a horizontal model with finite thickness for the first earth layer
horz_earth_model = EarthModel(frequencies, 100, 10, 1, t=5)

# Add a second horizontal earth layer
add!(horz_earth_model, frequencies, 200, 15, 1, t=10)
println(length(horz_earth_model.layers)) # Output: 3

# The bottom layer should be set to infinite thickness
add!(horz_earth_model, frequencies, 300, 15, 1, t=Inf)
println(length(horz_earth_model.layers)) # Output: 4

# Initialize a vertical-layered model with first interface at y = 0.
vert_earth_model = EarthModel(frequencies, 100, 10, 1, t=Inf, vertical_layers=true)

# Add a second vertical layer at y = 0 (this can also be infinite)
add!(vert_earth_model, frequencies, 150, 12, 1, t=Inf)
println(length(vert_earth_model.layers)) # Output: 3

# Attempt to add a third infinite layer (invalid case)
try
	add!(vert_earth_model, frequencies, 120, 12, 1, t=Inf)
catch e
	println(e) # Error: Cannot add consecutive vertical layers with infinite thickness.
end

# Fix: Set a finite thickness to the currently rightmost layer
vert_earth_model.layers[end].t = 3

# Add the third layer with infinite thickness now
add!(vert_earth_model, frequencies, 120, 12, 1, t=Inf)
println(length(vert_earth_model.layers)) # Output: 4

See also

• EarthLayer

coerce_to_T(model::EarthModel, _::Type{T}) -> EarthModel

Converts an EarthModel{S} to EarthModel{T} by reconstructing the model with all layers coerced to the new scalar type T. Layer conversion is delegated to coerce_to_T(::EarthLayer, ::Type), and non-numeric metadata are forwarded unchanged.

Arguments

• model: Source Earth model [dimensionless].
• ::Type{T}: Target element type for numeric fields [dimensionless].

Returns

• EarthModel{T} rebuilt with each layer and numeric payload converted to T.

Examples

m64 = coerce_to_T(model, Float64)
mM  = coerce_to_T(model, Measurement{Float64})

See also

• coerce_to_T
• resolve_T

coerce_to_T(
    layer::LineCableModels.EarthProps.EarthLayer,
    _::Type{T}
) -> LineCableModels.EarthProps.EarthLayer

Converts an EarthLayer{S} to EarthLayer{T} by coercing each stored field to the target element type T and rebuilding the layer via its inner constructor. Scalar and array fields are converted using the generic coerce_to_T machinery.

Arguments

• layer: Source Earth layer [dimensionless].
• ::Type{T}: Target element type for numeric fields [dimensionless].

Returns

• EarthLayer{T} with all numeric state converted to T.

Examples

ℓ64 = coerce_to_T(layer, Float64)
ℓM  = coerce_to_T(layer, Measurement{Float64})

See also

• coerce_to_T
• resolve_T

DataFrame(library::MaterialsLibrary) -> DataFrames.DataFrame

Lists the contents of a MaterialsLibrary as a DataFrame.

Arguments

• library: Instance of MaterialsLibrary to be displayed.

Returns

• A DataFrame containing the material properties.

Examples

library = MaterialsLibrary()
df = DataFrame(library)

See also

• LineCableModels.ImportExport.save

delete!(library::MaterialsLibrary, name::String)

Removes a material from a MaterialsLibrary.

Arguments

• library: Instance of MaterialsLibrary from which the material will be removed.
• name: Name of the material to be removed.

Returns

• The modified instance of MaterialsLibrary without the specified material.

Errors

Throws an error if the material does not exist in the library.

Examples

library = MaterialsLibrary()
delete!(library, "copper")

See also

• add!

get(
    library::MaterialsLibrary,
    name::String
) -> Union{Nothing, Material}
get(library::MaterialsLibrary, name::String, default) -> Any

Retrieves a material from a MaterialsLibrary by name.

Arguments

• library: Instance of MaterialsLibrary containing the materials.
• name: Name of the material to retrieve.

Returns

• The requested Material if found, otherwise nothing.

Examples

library = MaterialsLibrary()
material = get(library, "copper")

See also

• add!
• delete!

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    dict::Dict{String, Material}
)

Defines the display representation of a MaterialsLibrary object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• dict: The MaterialsLibrary contents to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the library.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    library::MaterialsLibrary
)

Defines the display representation of a MaterialsLibrary object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• library: The MaterialsLibrary instance to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the library.

show(
    io::IO,
    _::MIME{Symbol("text/plain")},
    material::Material
)

Defines the display representation of a Material object for REPL or text output.

Arguments

• io: Output stream.
• ::MIME"text/plain": MIME type for plain text output.
• material: The Material instance to be displayed.

Returns

• Nothing. Modifies io by writing text representation of the material.

add!(
    library::MaterialsLibrary,
    name::AbstractString,
    material::Material
) -> MaterialsLibrary

Adds a new material to a MaterialsLibrary.

Arguments

• library: Instance of MaterialsLibrary where the material will be added.
• name: Name of the material.
• material: Instance of Material containing its properties.

Returns

• The modified instance of MaterialsLibrary with the new material added.

Errors

Throws an error if a material with the same name already exists in the library.

Examples

library = MaterialsLibrary()
material = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
add!(library, "copper", material)

_add_default_materials!(
    library::MaterialsLibrary
) -> MaterialsLibrary

Populates a MaterialsLibrary with commonly used materials, assigning predefined electrical and thermal properties.

Arguments

• library: Instance of MaterialsLibrary to be populated.

Returns

• The modified instance of MaterialsLibrary containing the predefined materials.

Examples

library = MaterialsLibrary()
_add_default_materials!(library)

See also

• add!

Element‑wise coercion kernel. Converts a single leaf value to the target type T while preserving semantics for Measurement, numeric types, and sentinels.

Arguments

• x: Input leaf value [dimensionless].
• ::Type{T}: Target type [dimensionless].

Returns

• Value coerced to the target, according to the rules below.

Notes

• Number → R<:AbstractFloat: uses convert(R, x).
• Number → M<:Measurement: embeds the number as a zero‑uncertainty measurement (i.e., zero(M) + x).
• Measurement → M<:Measurement: recreates with the target inner type (value and uncertainty cast to _meas_inner(M)).
• Measurement → R<:AbstractFloat: drops uncertainty and converts the nominal value.
• nothing and missing pass through unchanged.
• Bool, Symbol, String, Function, DataType: passed through unchanged for measurement/real targets.
• Fallback: returns x unchanged.

Examples

using Measurements

_coerce_elt_to_T(1.2, Float32)                         # 1.2f0
_coerce_elt_to_T(1.2, Measurement{Float64})            # 1.2 ± 0.0
_coerce_elt_to_T(measurement(2.0, 0.1), Float32)       # 2.0f0
_coerce_elt_to_T(measurement(2.0, 0.1), Measurement{Float32})  # 2.0 ± 0.1 (Float32 inner)
_coerce_elt_to_T(missing, Float64)                     # missing

Methods

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:205.

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:206.

_coerce_elt_to_T(m, _)

defined at typecoercion.jl:207.

_coerce_elt_to_T(m, _)

defined at typecoercion.jl:209.

_coerce_elt_to_T(_, _)

defined at typecoercion.jl:210.

_coerce_elt_to_T(_, _)

defined at typecoercion.jl:211.

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:212.

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:213.

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:214.

_coerce_elt_to_T(x, _)

defined at typecoercion.jl:215.

Determines whether a Type contains or is a Complex number type somewhere in its structure. The check is recursive over arrays, tuples (including variadic tuples), named tuples, and union types. For concrete struct types, the predicate descends into field types. Guards are present to avoid infinite recursion through known self‑referential types (e.g., Measurements.Measurement).

Arguments

• ::Type: Type to inspect [dimensionless].

Returns

• Bool indicating whether a Complex type occurs anywhere within the type structure.

Notes

• For AbstractArray{S}, only the element type S is inspected.
• For Tuple and NamedTuple{N,T}, the parameters are traversed.
• For Union, both branches are inspected.
• Concrete Measurement types are treated as terminal and are not descended.

Examples

_hascomplex_type(Float64)                  # false
_hascomplex_type(Complex{Float64})         # true
_hascomplex_type(Vector{ComplexF64})       # true
_hascomplex_type(Tuple{Int, ComplexF64})   # true

Methods

_hascomplex_type(_)

defined at typecoercion.jl:81.

_hascomplex_type(_)

defined at typecoercion.jl:82.

_hascomplex_type(_)

defined at typecoercion.jl:83.

_hascomplex_type(_)

defined at typecoercion.jl:84.

_hascomplex_type(_)

defined at typecoercion.jl:86.

_hascomplex_type(T)

defined at typecoercion.jl:87.

_hascomplex_type(T)

defined at typecoercion.jl:88.

_hascomplex_type(_)

defined at typecoercion.jl:94.

_hasmeas_type(_::Type{<:Measurements.Measurement}) -> Bool

Determines whether a Type contains or is a Measurements.Measurement somewhere in its structure. The check is recursive over arrays, tuples (including variadic tuples), named tuples, and union types. For concrete struct types, the predicate descends into field types. Guards are present to avoid infinite recursion through known self‑contained types (e.g., Complex).

Arguments

• ::Type: Type to inspect [dimensionless].

Returns

• Bool indicating whether a Measurement occurs anywhere within the type structure.

Notes

• For AbstractArray{S}, only the element type S is inspected.
• For Tuple and NamedTuple{N,T}, the parameters are traversed.
• For Union, both branches are inspected.
• Concrete Complex types are treated as terminal and are not descended.

Examples

using Measurements

_hasmeas_type(Float64)                    # false
_hasmeas_type(Measurement{Float64})       # true
_hasmeas_type(Vector{Measurement{Float64}}) # true
_hasmeas_type(Tuple{Int, Float64})        # false
_hasmeas_type(Union{Int, Measurement{Float64}}) # true

_meas_inner(_::Type{Measurements.Measurement{S}}) -> Any

Extracts the real inner type S from Measurement{S}.

Arguments

• ::Type{Measurement{S}}: Measurement type wrapper [dimensionless].

Returns

• The inner floating‐point type S [dimensionless].

Examples

using Measurements

S = _meas_inner(Measurement{Float64})  # Float64

Apply f to every square block of M defined by map, in-place.

• M: n×n or n×n×nf (any eltype).
• map: length-n; equal ids => same block (non-contiguous ok).
• f: function like f(B::AbstractMatrix, args...) -> k×k Matrix.
• args...: extra positional args passed to f.
• slice_positions: positions in args that should be indexed as args[i][idx] per block (useful for phase_map).

Returns M.