Toolbox 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: WireArray, 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
• Core
• DataFrames
• DocStringExtensions
• ForceImport
• LineCableModels.DataModel.BaseParams
• LineCableModels.EarthProps
• LineCableModels.Materials
• LineCableModels.Utils
• Measurements
• Pkg
• Plots
• Reexport

Exports

• AbstractCablePart
• AbstractConductorPart
• AbstractInsulatorPart
• BaseParams
• CableComponent
• CableDef
• CableDesign
• CablesLibrary
• ConductorGroup
• Diameter
• Insulator
• InsulatorGroup
• LineCableSystem
• NominalData
• Semicon
• Strip
• Thickness
• Tubular
• WireArray
• addto_cabledesign!
• addto_conductorgroup!
• addto_insulatorgroup!
• addto_linecablesystem!
• cabledesign_todf
• 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_wirearray_coords
• calc_wirearray_gmr
• flat_formation
• get_cabledesign
• linecablesystem_todf
• list_cableslibrary
• preview_cabledesign
• preview_linecablesystem
• remove_cableslibrary!
• store_cableslibrary!
• trifoil_formation

abstract type AbstractCablePart

Abstract type representing a generic cable part.

abstract type AbstractConductorPart <: AbstractCablePart

Abstract type representing a conductive part of a cable.

Subtypes implement specific configurations:

• WireArray
• Tubular
• Strip

abstract type AbstractInsulatorPart <: AbstractCablePart

Abstract type representing an insulating part of a cable.

Subtypes implement specific configurations:

• Insulator
• Semicon

mutable struct CableComponent

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

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.

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

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

Constructs a CableDef 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 CableDef 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
cabledef1 = CableDef(cable_design, xa, ya, Dict("core" => 1))

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

See also

• CableDesign

struct CableDef

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

• cable::CableDesign: The CableDesign object assigned to this cable definition.

• horz::Number: Horizontal coordinate [m].

• vert::Number: Vertical coordinate [m].

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

mutable struct CableDesign

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::NominalData: Informative reference data.

• components::Vector{CableComponent}: Vector of cable components.

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

Constructs a CableDesign instance.

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

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

Constructs a CableDesign instance from conductor and insulator groups.

Arguments

• cable_id: Unique identifier for the cable design.
• conductor_group: The ConductorGroup for the component.
• insulator_group: The InsulatorGroup for the component.
• component_id: ID for the cable component. Default: "core".
• 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)
design = CableDesign("example", conductor_group, insulator_group)

mutable struct CablesLibrary

Represents a library of cable designs stored as a dictionary.

• cable_designs::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
• store_cableslibrary!
• remove_cableslibrary!
• LineCableModels.ImportExport.save_cableslibrary
• list_cableslibrary

mutable struct ConductorGroup <: AbstractConductorPart

Represents a composite conductor group assembled from multiple conductive layers or stranded wires.

This structure serves as a container for different AbstractConductorPart elements (such as wire arrays, strips, and tubular conductors) arranged in concentric layers. The ConductorGroup aggregates these individual parts and provides equivalent electrical properties that represent the composite behavior of the entire assembly.

Attributes

• radius_in::Number: Inner radius of the conductor group [m].

• radius_ext::Number: Outer radius of the conductor group [m].

• cross_section::Number: Cross-sectional area of the entire conductor group [m²].

• num_wires::Number: Number of individual wires in the conductor group [dimensionless].

• num_turns::Number: Number of turns per meter of each wire strand [1/m].

• resistance::Number: DC resistance of the conductor group [Ω].

• alpha::Number: Temperature coefficient of resistance [1/°C].

• gmr::Number: Geometric mean radius of the conductor group [m].

• layers::Vector{AbstractConductorPart}: Vector of conductor layer components.

ConductorGroup(
    central_conductor::AbstractConductorPart
) -> ConductorGroup

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.

Examples

material_props = Material(1.7241e-8, 1.0, 0.999994, 20.0, 0.00393)
central_strip = Strip(0.01, 0.002, 0.05, 10, material_props)
conductor_group = ConductorGroup(central_strip)
println(conductor_group.layers)      # Output: [central_strip]
println(conductor_group.resistance)  # Output: Resistance in \[Ω\]

struct Diameter{T<:Number} <: Number

Represents the diameter of a cable component.

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

mutable struct Insulator <: AbstractInsulatorPart

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

• radius_in::Number: Internal radius of the insulating layer [m].

• radius_ext::Number: External radius of the insulating layer [m].

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

• temperature::Number: Operating temperature of the insulator [°C].

• cross_section::Number: Cross-sectional area of the insulating layer [m²].

• resistance::Number: Electrical resistance of the insulating layer [Ω/m].

• gmr::Number: Geometric mean radius of the insulator [m].

• shunt_capacitance::Number: Shunt capacitance per unit length of the insulating layer [F/m].

• shunt_conductance::Number: Shunt conductance per unit length of the insulating layer [S·m].

Insulator(
    radius_in::Union{Number, AbstractCablePart},
    radius_ext::Number,
    material_props::Material;
    temperature
) -> Insulator

Constructs an Insulator object with specified geometric and material parameters.

Arguments

• radius_in: Internal radius of the insulating layer [m].
• radius_ext: 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 <: AbstractInsulatorPart

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:

• radius_in::Number: Inner radius of the insulator group [m].

• radius_ext::Number: Outer radius of the insulator group [m].

• cross_section::Number: Cross-sectional area of the entire insulator group [m²].

• shunt_capacitance::Number: Shunt capacitance per unit length of the insulator group [F/m].

• shunt_conductance::Number: Shunt conductance per unit length of the insulator group [S·m].

• layers::Vector{AbstractInsulatorPart}: Vector of insulator layer components.

InsulatorGroup(
    initial_insulator::AbstractInsulatorPart
) -> InsulatorGroup

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]

mutable struct LineCableSystem

Represents a cable system configuration, defining the structure, earth resistivity, operating temperature, and phase assignments.

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

• T::Number: Operating temperature [°C].

• earth_props::EarthModel: Earth properties model.

• line_length::Number: 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::Vector{CableDef}: Cross-section cable definition.

LineCableSystem(
    case_id::String,
    T::Number,
    earth_props::EarthModel,
    line_length::Number,
    cable::CableDef
) -> LineCableSystem

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

Arguments

• case_id: Identifier for the cable system.
• T: Operating temperature [°C].
• earth_props: Instance of EarthModel defining the earth properties.
• line_length: Length of the cable system [m].
• cable: Initial CableDef object defining a cable position and phase mapping.

Returns

• A LineCableSystem object initialized with a single cable definition.

Examples

earth_params = EarthModel(10.0 .^ range(0, stop=6, length=10), 100, 10, 1)
cable_design = CableDesign("example", nominal_data, components_dict)
cabledef1 = CableDef(cable_design, 0.0, 0.0, Dict("core" => 1))

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

See also

• CableDef
• EarthModel
• CableDesign

struct NominalData

Stores the nominal electrical and geometric parameters for a cable design, with attributes:

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

• U0::Union{Nothing, Number}: Rated phase-to-earth voltage [kV].

• U::Union{Nothing, Number}: Cross-sectional area of the conductor [mm²].

• conductor_cross_section::Union{Nothing, Number}

• screen_cross_section::Union{Nothing, Number}: Cross-sectional area of the screen [mm²].

• armor_cross_section::Union{Nothing, Number}: Cross-sectional area of the armor [mm²].

• resistance::Union{Nothing, Number}: Base (DC) resistance of the cable core [Ω/km].

• capacitance::Union{Nothing, Number}: Capacitance of the main insulation [μF/km].

• inductance::Union{Nothing, Number}: 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

Initializes a NominalData object with optional default values.

Arguments

• designation_code: Cable designation (default: nothing).
• U0: Phase-to-earth voltage rating [kV] (default: nothing).
• U: Phase-to-phase voltage rating [kV] (default: nothing).
• conductor_cross_section: Conductor cross-section [mm²] (default: nothing).
• screen_cross_section: Screen cross-section [mm²] (default: nothing).
• armor_cross_section: Armor cross-section [mm²] (default: nothing).
• resistance: Cable resistance [Ω/km] (default: nothing).
• capacitance: Cable capacitance [μF/km] (default: nothing).
• inductance: Cable inductance (trifoil) [mH/km] (default: nothing).

Returns

An instance of NominalData with the specified nominal properties.

Examples

nominal_data = NominalData(
	conductor_cross_section=1000,
	resistance=0.0291,
	capacitance=0.39,
)
println(nominal_data.conductor_cross_section)
println(nominal_data.resistance)
println(nominal_data.capacitance)

mutable struct Semicon <: AbstractInsulatorPart

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

• radius_in::Number: Internal radius of the semiconducting layer [m].

• radius_ext::Number: External radius of the semiconducting layer [m].

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

• temperature::Number: Operating temperature of the semiconductor [°C].

• cross_section::Number: Cross-sectional area of the semiconducting layer [m²].

• resistance::Number: Electrical resistance of the semiconducting layer [Ω/m].

• gmr::Number: Geometric mean radius of the semiconducting layer [m].

• shunt_capacitance::Number: Shunt capacitance per unit length of the semiconducting layer [F/m].

• shunt_conductance::Number: Shunt conductance per unit length of the semiconducting layer [S·m].

Semicon(
    radius_in::Union{Number, AbstractCablePart},
    radius_ext::Number,
    material_props::Material;
    temperature
) -> Semicon

Constructs a Semicon instance with calculated electrical and geometric properties.

Arguments

• radius_in: Internal radius of the semiconducting layer [m].
• radius_ext: 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 <: AbstractConductorPart

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

• radius_in::Number: Internal radius of the strip [m].

• radius_ext::Number: External radius of the strip [m].

• thickness::Number: Thickness of the strip [m].

• width::Number: Width of the strip [m].

• lay_ratio::Number: Ratio defining the lay length of the strip (twisting factor) [dimensionless].

• mean_diameter::Number: Mean diameter of the strip's helical path [m].

• pitch_length::Number: 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::Number: Temperature at which the properties are evaluated [°C].

• cross_section::Number: Cross-sectional area of the strip [m²].

• resistance::Number: Electrical resistance of the strip [Ω/m].

• gmr::Number: Geometric mean radius of the strip [m].

Strip(
    radius_in::Union{Number, AbstractCablePart},
    radius_ext::Number,
    width::Number,
    lay_ratio::Number,
    material_props::Material;
    temperature,
    lay_direction
) -> Strip

Constructs a Strip object with specified geometric and material parameters.

Arguments

• radius_in: Internal radius of the strip [m].
• radius_ext: 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<:Number} <: Number

Represents the thickness of a cable component.

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

struct Tubular <: AbstractConductorPart

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

• radius_in::Number: Internal radius of the tubular conductor [m].

• radius_ext::Number: External radius of the tubular conductor [m].

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

• temperature::Number: Temperature at which the properties are evaluated [°C].

• cross_section::Number: Cross-sectional area of the tubular conductor [m²].

• resistance::Number: Electrical resistance (DC) of the tubular conductor [Ω/m].

• gmr::Number: Geometric mean radius of the tubular conductor [m].

Tubular(
    radius_in::Union{Number, AbstractCablePart},
    radius_ext::Number,
    material_props::Material;
    temperature
) -> Tubular

Initializes a Tubular object with specified geometric and material parameters.

Arguments

• radius_in: Internal radius of the tubular conductor [m].
• radius_ext: 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

struct WireArray <: AbstractConductorPart

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

• radius_in::Number: Internal radius of the wire array [m].

• radius_ext::Number: External radius of the wire array [m].

• radius_wire::Number: Radius of each individual wire [m].

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

• lay_ratio::Number: Ratio defining the lay length of the wires (twisting factor) [dimensionless].

• mean_diameter::Number: Mean diameter of the wire array [m].

• pitch_length::Number: 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::Number: Temperature at which the properties are evaluated [°C].

• cross_section::Number: Cross-sectional area of all wires in the array [m²].

• resistance::Number: Electrical resistance per wire in the array [Ω/m].

• gmr::Number: Geometric mean radius of the wire array [m].

WireArray(
    radius_in::Union{Number, AbstractCablePart},
    radius_wire::Number,
    num_wires::Int64,
    lay_ratio::Number,
    material_props::Material;
    temperature,
    lay_direction
) -> WireArray

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

Arguments

• radius_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 WireArray object with calculated geometric and electrical properties.

Examples

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

See also

• Material
• ConductorGroup
• calc_tubular_resistance
• calc_wirearray_gmr
• calc_helical_params

addto_cabledesign!(
    design::CableDesign,
    component::CableComponent
) -> CableDesign

Adds a cable component to an existing CableDesign.

Arguments

• design: A CableDesign object where the component will be added.
• component: A CableComponent to add to the design.

Returns

• The modified CableDesign object.

Notes

If a component with the same ID already exists, it will be overwritten, and a warning will be logged.

Examples

conductor_group = ConductorGroup(wire_array)
insulator_group = InsulatorGroup(insulation)
component = CableComponent("sheath", conductor_group, insulator_group)
addto_cabledesign!(design, component)

See also

• CableDesign
• CableComponent

addto_cabledesign!(
    design::CableDesign,
    component_id::String,
    conductor_group::ConductorGroup,
    insulator_group::InsulatorGroup
) -> CableDesign

Adds a cable component to an existing CableDesign using separate conductor and insulator groups. Performs as a convenience wrapper to construct the CableComponent object with reduced boilerplate.

Arguments

• design: A CableDesign object where the component will be added.
• component_id: ID for the new component.
• conductor_group: A ConductorGroup for the component.
• insulator_group: An InsulatorGroup for the component.

Returns

• The modified CableDesign object.

Examples

conductor_group = ConductorGroup(wire_array)
insulator_group = InsulatorGroup(insulation)
addto_cabledesign!(design, "shield", conductor_group, insulator_group)

See also

• CableDesign
• CableComponent

addto_conductorgroup!(
    group::ConductorGroup,
    part_type::Type{T<:AbstractConductorPart},
    args...;
    kwargs...
) -> ConductorGroup

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

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, radius_ext, 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 radius_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))
addto_conductorgroup!(conductor, WireArray, 0.02, 0.002, 7, 15, material_props, temperature = 25)

See also

• ConductorGroup
• WireArray
• Strip
• Tubular
• calc_equivalent_gmr
• calc_parallel_equivalent
• calc_equivalent_alpha

addto_insulatorgroup!(
    group::InsulatorGroup,
    part_type::Type{T<:AbstractInsulatorPart},
    args...;
    f,
    kwargs...
) -> InsulatorGroup

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

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, radius_ext, and cross_section to account for the new part.
• The radius_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))
addto_insulatorgroup!(insulator_group, Semicon, 0.015, 0.018, material_props)

See also

• InsulatorGroup
• Insulator
• Semicon
• calc_equivalent_gmr # This should be removed
• calc_parallel_equivalent
• calc_equivalent_alpha # This should be removed

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

Adds a new cable definition to an existing LineCableSystem, updating its phase mapping and cable count.

Arguments

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

Returns

• Nothing. Modifies system in place by adding a new CableDef and updating num_cables and num_phases.

Examples

earth_params = EarthModel(...)
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
cabledef1 = CableDef(cable_design, xa, ya, Dict("core" => 1))
cable_system = LineCableSystem("test_case_1", 20.0, earth_params, 1000.0, cabledef1)

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

println(cable_system.num_cables)  # Prints: 2

See also

• LineCableSystem
• CableDef
• CableDesign

cabledesign_todf(design::CableDesign; ...) -> Any
cabledesign_todf(
    design::CableDesign,
    format::Symbol;
    S,
    rho_e
) -> Any

Extracts and displays data from a CableDesign.

Arguments

• design: A CableDesign object to extract data from.
• format: Symbol indicating the level of detail:
  • :core: 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 :core format). Default: outermost cable diameter.
• rho_e: Resistivity of the earth [Ω·m] (only used for :core format). Default: 100.

Returns

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

Examples

# Get basic RLC parameters
data = cabledesign_todf(design)  # Default is :core format

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

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

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

See also

• CableDesign
• calc_tubular_resistance
• calc_inductance_trifoil
• calc_shunt_capacitance

flat_formation(xc, yc, s; vertical) -> NTuple{6, Any}

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)

get_cabledesign(
    library::CablesLibrary,
    cable_id::String
) -> Union{Nothing, CableDesign}

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
store_cableslibrary!(library, design)

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

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

See also

• CablesLibrary
• CableDesign
• store_cableslibrary!
• remove_cableslibrary!

linecablesystem_todf(
    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 = linecablesystem_todf(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
• CableDef

list_cableslibrary(
    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"=>...))
store_cableslibrary!(library, design1)
store_cableslibrary!(library, design2)

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

See also

• CablesLibrary
• CableDesign
• store_cableslibrary!

preview_cabledesign(
    design::CableDesign;
    x_offset,
    y_offset,
    plt,
    display_plot,
    display_legend,
    backend,
    sz
) -> Any

Displays the cross-section of a cable design.

Arguments

• design: A CableDesign object representing the cable structure.
• x_offset: Horizontal offset for the plot [m].
• y_offset: Vertical offset for the plot [m].
• plt: An optional Plots.Plot object to use for plotting.
• display_plot: Boolean flag to display the plot after rendering.
• display_legend: Boolean flag to display the legend in the plot.
• backend: Optional plotting backend to use. If not specified, the function will choose a suitable backend based on the environment (e.g., GR for headless, PlotlyJS for interactive).
• sz: Optional plot dimensions (width, height). Default: (800, 600).

Returns

• A Plots.Plot object representing the visualized cable design.

Examples

conductor_group = ConductorGroup(central_conductor)
insulator_group = InsulatorGroup(main_insulation)
component = CableComponent("core", conductor_group, insulator_group)
design = CableDesign("example", component)
cable_plot = preview_cabledesign(design)  # Cable cross-section is displayed

See also

• CableDesign
• ConductorGroup
• InsulatorGroup
• WireArray
• Tubular
• Strip
• Semicon

preview_linecablesystem(
    system::LineCableSystem;
    zoom_factor,
    backend,
    sz
) -> Plots.Plot

Displays the cross-section of a cable system, including earth layers and cables.

Arguments

• system: A LineCableSystem object containing the cable arrangement and earth properties.
• zoom_factor: A scaling factor for adjusting the x-axis limits [dimensionless].
• backend: Optional plotting backend to use. If not specified, the function will choose a suitable backend based on the environment (e.g., GR for headless, PlotlyJS for interactive).
• sz: Optional plot dimensions (width, height). Default: (800, 600).

Returns

• Nothing. Displays a plot of the cable system cross-section with cables, earth layers (if applicable), and the air/earth interface.

Examples

system = LineCableSystem("test_system", 20.0, earth_model, 1000.0, cable_def)
preview_linecablesystem(system, zoom_factor=0.5)

See also

• LineCableSystem
• EarthModel
• CableDef

remove_cableslibrary!(
    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 cable_designs 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
store_cableslibrary!(library, design)

# Remove the cable design
remove_cableslibrary!(library, "example")
haskey(library.cable_designs, "example")  # Returns false

See also

• CablesLibrary
• store_cableslibrary!

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 cable_designs field of the CablesLibrary object in-place by adding the new cable design.

Examples

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

See also

• CablesLibrary
• CableDesign
• remove_cableslibrary!

trifoil_formation(xc, yc, r_ext) -> NTuple{6, Any}

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

Arguments

• xc: X-coordinate of the center point [m].
• yc: 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
• Core
• DocStringExtensions
• ForceImport
• LineCableModels.Utils
• Measurements
• Pkg
• Reexport

Exports

• 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_wirearray_coords
• calc_wirearray_gmr

calc_equivalent_alpha(
    alpha1::Number,
    R1::Number,
    alpha2::Number,
    R2::Number
) -> Any

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::Number,
    radius_ext::Number,
    radius_in::Number
) -> Any

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].
• radius_ext: External radius of the insulation [m].
• radius_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::AbstractCablePart,
    new_layer::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 = WireArray(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::Number,
    C_eq::Number,
    ω::Number
) -> Any

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::Number,
    radius_ext::Number,
    radius_in::Number
) -> Any

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].
• radius_ext: External radius of the conductor [m].
• radius_in: Internal radius of the conductor [m].

Returns

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

Errors

• Throws ArgumentError if radius_ext is less than radius_in.

Notes

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

Examples

gmr = 0.015
radius_ext = 0.02
radius_in = 0.01
mu_r = calc_equivalent_mu(gmr, radius_ext, radius_in)
println(mu_r) # Expected output: ~1.5 [dimensionless]

See also

• calc_tubular_gmr

calc_equivalent_rho(
    R::Number,
    radius_ext_con::Number,
    radius_in_con::Number
) -> Any

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::AbstractCablePart,
    co2::AbstractCablePart
) -> Any

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

\[\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)
wire_array1 = WireArray(0.01, 0.002, 7, 10, material_props)
wire_array2 = WireArray(0.02, 0.002, 7, 15, material_props)
gmd = calc_gmd(wire_array1, wire_array2)  # 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_wirearray_coords
• calc_equivalent_gmr

calc_helical_params(
    radius_in::Number,
    radius_ext::Number,
    lay_ratio::Number
) -> Tuple{Any, Any, Any}

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 $\lambda$ is the pitch length, $D_e$ and $L_p$ are the dimensions represented in the figure.

Arguments

• radius_in: Inner radius of the cable layer [m].
• radius_ext: 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

radius_in = 0.01
radius_ext = 0.015
lay_ratio = 12

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

calc_inductance_trifoil(
    r_in_co::Number,
    r_ext_co::Number,
    rho_co::Number,
    mu_r_co::Number,
    r_in_scr::Number,
    r_ext_scr::Number,
    rho_scr::Number,
    mu_r_scr::Number,
    S::Number;
    rho_e,
    f
) -> Any

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::Number, Z2::Number) -> 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.WireArray objects, implements the formula for the hexagonal wiring pattern described in CIGRE TB-345 [1] [15]:

\[\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(
    radius_in::Number,
    radius_ext::Number,
    epsr::Number
) -> Any

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

\[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

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

Returns

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

Examples

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

calc_shunt_conductance(
    radius_in::Number,
    radius_ext::Number,
    rho::Number
) -> Any

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

\[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

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

Returns

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

Examples

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

calc_sigma_lossfact(
    G_eq::Number,
    radius_in::Number,
    radius_ext::Number
) -> Any

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

\[\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].
• radius_in: Internal radius of the coaxial structure [m].
• radius_ext: 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, radius_in, radius_ext)

calc_solenoid_correction(
    num_turns::Number,
    radius_ext_con::Number,
    radius_ext_ins::Number
) -> Any

Calculates the solenoid correction factor for magnetic permeability in insulated cables with helical conductors (WireArray), 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::Number,
    width::Number,
    rho::Number,
    alpha::Number,
    T0::Number,
    T::Number
) -> Any

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].
• T: 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: ~8.62e-7 Ω

See also

• calc_temperature_correction

calc_temperature_correction(alpha::Number, T::Number) -> Any
calc_temperature_correction(
    alpha::Number,
    T::Number,
    T0::Number
) -> Any

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

\[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.2158

calc_tubular_gmr(
    radius_ext::Number,
    radius_in::Number,
    mu_r::Number
) -> Any

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

• radius_ext: External radius of the tubular conductor [m].
• radius_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 radius_ext is less than radius_in.

Examples

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

calc_tubular_inductance(
    radius_in::Number,
    radius_ext::Number,
    mu_r::Number
) -> Any

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

\[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

• radius_in: Internal radius of the tubular conductor [m].
• radius_ext: 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

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

See also

• calc_tubular_resistance

calc_tubular_resistance(
    radius_in::Number,
    radius_ext::Number,
    rho::Number,
    alpha::Number,
    T0::Number,
    T::Number
) -> Any

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

• radius_in: Internal radius of the tubular conductor [m].
• radius_ext: 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].
• T: Operating temperature of the conductor [°C].

Returns

• DC resistance of the tubular conductor [Ω].

Examples

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

See also

• calc_temperature_correction

calc_wirearray_coords(
    num_wires::Number,
    radius_wire::Number,
    radius_in::Number;
    C
) -> Vector{Any}

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].
• radius_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_wirearray_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_wirearray_coords(7, 0.002, 0.01, C=(0.5, 0.3))

See also

• LineCableModels.DataModel.WireArray

calc_wirearray_gmr(
    lay_rad::Number,
    N::Number,
    rad_wire::Number,
    mu_r::Number
) -> Any

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

\[GMR = \sqrt[a] {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_wirearray_gmr(lay_rad, N, rad_wire, mu_r)
println(gmr) # Expected output: 0.01187... [m]

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 and equivalent homogeneous 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 and equivalent homogeneous earth models via AbstractEHEMFormulation.
• Contains utility functions for building complex multi-layered earth models and generating data summaries.

Dependencies

• Base
• Core
• DataFrames
• DocStringExtensions
• ForceImport
• LineCableModels.Utils
• Measurements
• Pkg
• Reexport

Exports

• AbstractEHEMFormulation
• AbstractFDEMFormulation
• CPEarth
• EarthLayer
• EarthModel
• EnforceLayer
• addto_earthmodel!
• earthmodel_todf

abstract type AbstractEHEMFormulation

Abstract type representing different equivalent homogeneous earth models (EHEM). Used in the multi-dispatch implementation of _calc_ehem_properties!.

Currently available formulations

• EnforceLayer: Effective parameters defined according to a specific earth layer.

abstract type AbstractFDEMFormulation

Abstract type representing different frequency-dependent earth models (FDEM). Used in the multi-dispatch implementation of _calc_earth_properties.

Currently available formulations

• CPEarth: Constant properties (CP) model.

struct CPEarth <: AbstractFDEMFormulation

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

mutable struct EarthLayer

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

• base_rho_g::Number: Base (DC) electrical resistivity [Ω·m].

• base_epsr_g::Number: Base (DC) relative permittivity [dimensionless].

• base_mur_g::Number: Base (DC) relative permeability [dimensionless].

• t::Number: Thickness of the layer [m].

• rho_g::Vector{Number}: Computed resistivity values [Ω·m] at given frequencies.

• eps_g::Vector{Number}: Computed permittivity values [F/m] at given frequencies.

• mu_g::Vector{Number}: Computed permeability values [H/m] at given frequencies.

EarthLayer(
    frequencies,
    base_rho_g,
    base_epsr_g,
    base_mur_g,
    t,
    FDformulation::AbstractFDEMFormulation
) -> 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].
• FDformulation: 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

• _calc_earth_properties

mutable struct EarthModel

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

• num_layers::Int64: Total number of layers in the model, including the air layer.

• FDformulation::AbstractFDEMFormulation: Selected frequency-dependent formulation for earth properties.

• EHEMformulation::Union{Nothing, AbstractEHEMFormulation}: Selected equivalent homogeneous earth formulation (or nothing).

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

• layers::Vector{EarthLayer}: Vector of EarthLayer objects, starting with an air layer and the specified first earth layer.

• rho_eff::Union{Missing, Vector{Number}}: Effective resistivity values [Ω·m] at the given frequencies (missing initially, computed later if needed).

• eps_eff::Union{Missing, Vector{Number}}: Effective permittivity values [F/m] at the given frequencies (missing initially, computed later if needed).

• mu_eff::Union{Missing, Vector{Number}}: Effective permeability values [H/m] at the given frequencies (missing initially, computed later if needed).

EarthModel(
    frequencies::Vector{<:Number},
    rho_g::Number,
    epsr_g::Number,
    mur_g::Number;
    t,
    FDformulation,
    EHEMformulation,
    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.
• FDformulation: Instance of a subtype of AbstractFDEMFormulation defining the computation method for frequency-dependent properties (default: CPEarth).
• EHEMformulation: Optional instance of a subtype of AbstractEHEMFormulation defining the equivalent homogeneous medium formulation (default: nothing).
• 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, FDformulation)).

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
• addto_earthmodel!

struct EnforceLayer <: AbstractEHEMFormulation

Represents a homogeneous earth model defined using the properties of a specific earth layer, with atttribute:

• layer::Int64: Index of the enforced earth layer.

EnforceLayer(layer::Int64) -> EnforceLayer

Constructs an EnforceLayer instance, meaning that the properties of the specified layer are extended to the entire semi-infinite earth.

Arguments

• layer: Integer specifying the layer to be enforced as the equivalent homogeneous layer.
• -1 selects the bottommost layer.
• 2 selects the topmost earth layer (excluding air).
• Any integer ≥ 2 selects a specific layer.

Returns

• An EnforceLayer instance with the specified layer index.

Examples

# Enforce the bottommost layer
bottom_layer = EnforceLayer(-1)
println(_get_earth_formulation_tag(bottom_layer)) # Output: "Bottom layer"

# Enforce the topmost earth layer
first_layer = EnforceLayer(2)
println(_get_earth_formulation_tag(first_layer)) # Output: "Top layer"

# Enforce a specific layer
specific_layer = EnforceLayer(3)
println(_get_earth_formulation_tag(specific_layer)) # Output: "Layer 3"

addto_earthmodel!(
    model::EarthModel,
    frequencies::Vector{<:Number},
    base_rho_g::Number,
    base_epsr_g::Number,
    base_mur_g::Number;
    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 and updating num_layers.
• If the model contains at least two earth layers and an AbstractEHEMFormulation is defined, effective homogeneous parameters are computed.

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 (num_layers = 3), it can be infinite only if the previous layer is finite.
• No two successive earth layers (num_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 (num_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
addto_earthmodel!(horz_earth_model, frequencies, 200, 15, 1, t=10)
println(horz_earth_model.num_layers) # Output: 3

# The bottom layer should be set to infinite thickness
addto_earthmodel!(horz_earth_model, frequencies, 300, 15, 1, t=Inf)
println(horz_earth_model.num_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)
addto_earthmodel!(vert_earth_model, frequencies, 150, 12, 1, t=Inf)
println(vert_earth_model.num_layers) # Output: 3

# Attempt to add a third infinite layer (invalid case)
try
	addto_earthmodel!(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
addto_earthmodel!(vert_earth_model, frequencies, 120, 12, 1, t=Inf)
println(vert_earth_model.num_layers) # Output: 4

See also

• EarthLayer
• _calc_ehem_properties!

earthmodel_todf(
    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 = earthmodel_todf(earth_model)
println(df)

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 format.
• 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
• Core
• Dates
• DocStringExtensions
• EzXML
• ForceImport
• JSON3
• LineCableModels.DataModel
• LineCableModels.EarthProps
• LineCableModels.Materials
• LineCableModels.Utils
• Measurements
• Pkg
• Reexport
• Serialization

Exports

• export_pscad_lcp
• load_cableslibrary!
• load_materialslibrary!
• save_cableslibrary
• save_materialslibrary

export_pscad_lcp(
    cable_system::LineCableSystem;
    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.
• 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("example", 20.0, earth_model, 1000.0, cable_def)
export_pscad_lcp(cable_system, base_freq=50)

See also

• LineCableSystem

load_cableslibrary!(
    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_materialslibrary!(
    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_cableslibrary(
    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_materialslibrary(
    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
• Core
• DataFrames
• DocStringExtensions
• ForceImport
• LineCableModels.Utils
• Measurements
• Pkg
• Reexport

Exports

• Material
• MaterialsLibrary
• get_material
• list_materialslibrary
• remove_materialslibrary!
• store_materialslibrary!

struct Material

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

• rho::Number: Electrical resistivity of the material [Ω·m].

• eps_r::Number: Relative permittivity [dimensionless].

• mu_r::Number: Relative permeability [dimensionless].

• T0::Number: Reference temperature for property evaluations [°C].

• alpha::Number: Temperature coefficient of resistivity [1/°C].

mutable struct MaterialsLibrary

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

• materials::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!

get_material(
    library::MaterialsLibrary,
    name::String
) -> Union{Nothing, Material}

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_material(library, "copper")

See also

• store_materialslibrary!
• remove_materialslibrary!

list_materialslibrary(
    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 = list_materialslibrary(library)

See also

• LineCableModels.ImportExport.save_materialslibrary

remove_materialslibrary!(
    library::MaterialsLibrary,
    name::String
) -> MaterialsLibrary

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()
remove_materialslibrary!(library, "copper")

See also

• store_materialslibrary!

store_materialslibrary!(
    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)
store_materialslibrary!(library, "copper", material)

LineCableModels.Utils

The Utils module provides utility functions and constants 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
• Core
• DocStringExtensions
• ForceImport
• Measurements
• Pkg
• Reexport
• Statistics

Exports

• TOL
• T₀
• bias_to_uncertain
• equals
• f₀
• percent_error
• percent_to_uncertain
• strip_uncertainty
• to_lower
• to_nominal
• to_upper
• ε₀
• μ₀
• ρ₀

Default tolerance for floating-point comparisons, TOL = 1e-6.

Base temperature for conductor properties, T₀ = 20 [°C].

Base power system frequency, f₀ = 50 [Hz].

Electric constant (vacuum permittivity), ε₀ = 8.8541878128e-12 [F/m].

Magnetic constant (vacuum permeability), μ₀ = 4π * 1e-7 [H/m].

Annealed copper reference resistivity, ρ₀ = 1.724e-08 [Ω·m].

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

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

equals(x, y; atol) -> Any

Checks if two numerical values are approximately equal within a given tolerance.

Arguments

• x: First numeric value.
• y: Second numeric value.
• atol: Absolute tolerance for comparison (default: TOL).

Returns

• true if x and y are approximately equal within the given tolerance.
• false otherwise.

Examples

equals(1.00001, 1.0, atol=1e-4) # Output: true
equals(1.0001, 1.0, atol=1e-5)  # Output: false

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
) -> Union{Missing, Measurements.Measurement}

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

strip_uncertainty(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 = strip_uncertainty(x)  # Output: 5.0 ± 0.0

y = 10.0
result = strip_uncertainty(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) -> Any

Extracts the nominal value from a measurement or returns the original value.

Arguments

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

Returns

• The nominal value if x is a Measurement, otherwise returns x 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

Modified _CLEANMETHODLIST abbreviation with sanitized file paths.

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::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.

Resolves radii values based on input types and object type, handling both direct radius specifications and thickness-based specifications.

Arguments

• radius_in: Inner radius value [m].
• radius_ext: Outer radius value or thickness specification [m].
• object_type: Type parameter used for dispatch.

Returns

• inner_radius: Resolved inner radius [m].
• outer_radius: Resolved outer radius [m].
• thickness: Radial thickness between inner and outer surfaces [m].

Examples

# Direct radius specification
inner, outer, thickness = _do_resolve_radius(0.01, 0.02, ...)
# Output: inner = 0.01, outer = 0.02, thickness = 0.01

# Thickness-based specification
inner, outer, thickness = _do_resolve_radius(0.01, Thickness(0.005), ...)
# Output: inner = 0.01, outer = 0.015, thickness = 0.005

See also

• Thickness

_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.
  • radius_in: The inner radius of the part, if it exists, otherwise missing.
  • radius_ext: The outer radius of the part, if it exists, otherwise missing.
  • diameter_in: The inner diameter of the part (2 * radiusin), if `radiusinexists, otherwisemissing`.
  • diameter_ext: The outer diameter of the part (2 * radiusext), if `radiusextexists, otherwisemissing`.
  • thickness: The difference between radius_ext and radius_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 radius_ext, 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 = [:radius_in, :radius_ext, :resistance]  # Example of properties to extract
extracted_properties = _extract_part_properties(part, properties)
println(extracted_properties)

_get_material_color(
    material_props;
    rho_weight,
    epsr_weight,
    mur_weight
) -> Any

Generates a color representation for a Material based on its physical properties.

Arguments

• material_props: Dictionary containing material properties:
  • rho: Electrical resistivity [Ω·m].
  • eps_r: Relative permittivity [dimensionless].
  • mu_r: Relative permeability [dimensionless].
• rho_weight: Weight assigned to resistivity in color blending (default: 1.0) [dimensionless].
• epsr_weight: Weight assigned to permittivity in color blending (default: 0.1) [dimensionless].
• mur_weight: Weight assigned to permeability in color blending (default: 0.1) [dimensionless].

Returns

• An RGBA object representing the combined color based on the material's properties.

Notes

Colors are normalized and weighted using property-specific gradients:

• Conductors (ρ ≤ 5ρ₀): White → Dark gray
• Poor conductors (5ρ₀ < ρ ≤ 10⁴): Bronze → Greenish-brown
• Insulators (ρ > 10⁴): Greenish-brown → Black
• Permittivity: Gray → Orange
• Permeability: Silver → Purple
• The overlay function combines colors with their respective alpha/weight values.

Examples

material_props = Dict(
	:rho => 1.7241e-8,
	:eps_r => 2.3,
	:mu_r => 1.0
)
color = _get_material_color(material_props)
println(color) # Expected output: RGBA(0.9, 0.9, 0.9, 1.0)

_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

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_inputs_radius(10.0, ...)   # Direct radius value
radius = _parse_inputs_radius(Diameter(20.0), ...)  # From diameter object
radius = _parse_inputs_radius(Thickness(5.0), ...)  # From thickness object

Methods

_parse_inputs_radius(x, object_type)

defined at src/DataModel.jl:870.

_parse_inputs_radius(d, object_type)

defined at src/DataModel.jl:871.

_parse_inputs_radius(p, object_type)

defined at src/DataModel.jl:872.

_parse_inputs_radius(x, object_type)

defined at src/DataModel.jl:873.

_parse_inputs_radius(p, object_type)

defined at src/DataModel.jl:876.

See also

• Diameter
• Thickness
• strip_uncertainty

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

_resolve_backend(

) -> Union{Plots.GRBackend, Plots.PlotlyJSBackend}
_resolve_backend(backend) -> Any

Selects the appropriate plotting backend based on the environment.

Arguments

• backend: Optional explicit backend to use. If provided, this backend will be activated.

Returns

Nothing. The function activates the chosen backend.

Notes

Automatically selects GR for headless environments (CI or no DISPLAY) and PlotlyJS for interactive use when no backend is explicitly specified. This is particularly needed when running within CI environments.

Examples

choose_proper_backend()           # Auto-selects based on environment
choose_proper_backend(pyplot)     # Explicitly use PyPlot backend

_resolve_radius(
    param_in,
    param_ext
) -> Union{Tuple{Number, Any, Number}, Tuple{Number, Number, Any}}
_resolve_radius(
    param_in,
    param_ext,
    object_type
) -> Tuple{Number, Any, 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_inputs_radius.
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

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

See also

• Diameter
• Thickness
• AbstractCablePart

Modified _CLEANMETHODLIST abbreviation with sanitized file paths.

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.

_calc_earth_properties(
    frequencies::Vector{<:Number},
    base_rho_g::Number,
    base_epsr_g::Number,
    base_mur_g::Number,
    _::CPEarth
) -> Tuple{Vector{T} where T<:Number, Vector, Vector}

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 = _calc_earth_properties(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
• AbstractFDEMFormulation

_calc_ehem_properties!(
    model::EarthModel,
    frequencies::Vector{<:Number}
) -> Vector{Number}
_calc_ehem_properties!(
    model::EarthModel,
    frequencies::Vector{<:Number},
    formulation::AbstractEHEMFormulation
) -> Any

Computes the effective homogeneous earth model (EHEM) properties for an EarthModel, overriding the layered model with the properties of the layer defined in EnforceLayer.

Arguments

• model: Instance of EarthModel for which effective properties are computed.
• frequencies: Vector of frequency values [Hz].
• formulation: Instance of AbstractEHEMFormulation specifying how the effective properties should be determined.

Returns

• Modifies model in place by updating rho_eff, eps_eff, and mu_eff with the corresponding values.

Notes

• If formulation is an EnforceLayer, the effective properties (rho_eff, eps_eff, mu_eff) are directly assigned from the specified layer.
• If layer_idx = -1, the last layer in model.layers is used.
• If layer_idx < 2 or layer_idx > length(model.layers), an error is raised.

Examples

frequencies = [1e3, 1e4, 1e5]
earth_model = EarthModel(frequencies, 100, 10, 1, t=5)
earth_model.AbstractEHEMFormulation = EnforceLayer(-1)  # Enforce the last layer as the effective
_calc_ehem_properties!(earth_model, frequencies, EnforceLayer(-1))

println(earth_model.rho_eff) # Should match the last layer rho_g = 100
println(earth_model.eps_eff) # Should match the last layer eps_g = 10*ε₀
println(earth_model.mu_eff)  # Should match the last layer mu_g = 1*μ₀

See also

• EarthModel
• AbstractEHEMFormulation

Returns a standardized identifier string for earth model formulations.

Arguments

• A concrete implementation of AbstractFDEMFormulation or AbstractEHEMFormulation representing the earth model formulation.

Returns

• A string identifier used consistently across plots, tables, and parametric analyses.

Examples

cp = CPEarth()
tag = _get_earth_formulation_tag(cp)  # Returns "CP model"

Methods

_get_earth_formulation_tag(_)

defined at src/EarthProps.jl:129.

_get_earth_formulation_tag(formulation)

defined at src/EarthProps.jl:191.

See also

• AbstractFDEMFormulation
• AbstractEHEMFormulation
• _calc_earth_properties

Modified _CLEANMETHODLIST abbreviation with sanitized file paths.

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

• store_materialslibrary!

Modified _CLEANMETHODLIST abbreviation with sanitized file paths.

Automatically exports public functions, types, and modules from a module.

Arguments

• None.

Returns

• An export expression containing all public symbols that should be exported.

Notes

This macro scans the current module for all defined symbols and automatically generates an export statement for public functions, types, and submodules, excluding built-in and private names. Private names are considered those starting with an underscore ('_'), as per standard Julia conventions.

Examples

@_autoexport

using ..Utils
# ...
Utils.@_autoexport