Refactor and enhance the LineCableModels.jl package

- Introduced a mapping function `map_verbosity_to_getdp` to standardize verbosity levels for GetDP solver.
- Updated `run_getdp` to utilize the new verbosity mapping and improved command construction for solving and plotting.
- Modified `make_space_geometry` to correctly determine the number of earth layers and validate layer indices.
- Renamed `CommonDeps.jl` to `common_deps.jl` for consistency across modules.
- Added a new `Core.jl` module to encapsulate core functionalities, including problem definitions and formulation types.
- Implemented `AbstractEHEMFormulation` and `EnforceLayer` for enhanced earth model handling.
- Removed the obsolete `ProblemDefs.jl` file to streamline the codebase.
- Updated tests to reflect changes in function names and ensure proper DataFrame generation.
- Enhanced utility functions for better readability and consistency in handling measurements and uncertainties.

Author: amaurigmartins

examples/525kV_1600mm2_bipole_export.pscx

@@ -343,13 +343,13 @@ In this section, the cable design is examined and the calculated parameters are
 =#
 
 # Compare with datasheet information (R, L, C values):
-core_df = cabledesign_todf(cable_design, :baseparams)
+core_df = to_df(cable_design, :baseparams)
 
 # Obtain the equivalent electromagnetic properties of the cable:
-components_df = cabledesign_todf(cable_design, :components)
+components_df = to_df(cable_design, :components)
 
 # Get detailed description of all cable parts:
-detailed_df = cabledesign_todf(cable_design, :detailed)
+detailed_df = to_df(cable_design, :detailed)
 
 #=
 ## Saving the cable design
@@ -386,7 +386,7 @@ f = 10.0 .^ range(0, stop=6, length=10)  # Frequency range
 earth_params = EarthModel(f, 100.0, 10.0, 1.0)  # 100 Ω·m resistivity, εr=10, μr=1
 
 # Earth model base (DC) properties:
-earthmodel_df = earthmodel_todf(earth_params)
+earthmodel_df = to_df(earth_params)
 
 #=
 ### Three-phase system in trifoil configuration
@@ -425,7 +425,7 @@ In this section the complete three-phase cable system is examined.
 =#
 
 # Display system details:
-system_df = linecablesystem_todf(cable_system)
+system_df = to_df(cable_system)
 
 # Visualize the cross-section of the three-phase system:
 plt4 = preview_linecablesystem(cable_system, zoom_factor=0.15)

examples/tutorial2.jl

@@ -218,10 +218,10 @@ In this section, the cable design is examined and the calculated parameters are
 =#
 
 # Summarize DC lumped parameters (R, L, C):
-core_df = cabledesign_todf(cable_design, :baseparams)
+core_df = to_df(cable_design, :baseparams)
 
 # Obtain the equivalent electromagnetic properties of the cable:
-components_df = cabledesign_todf(cable_design, :components)
+components_df = to_df(cable_design, :components)
 
 #=
 ## Saving the cable design
@@ -255,7 +255,7 @@ f = 10.0 .^ range(0, stop=6, length=10)  # Frequency range
 earth_params = EarthModel(f, 100.0, 10.0, 1.0)  # 100 Ω·m resistivity, εr=10, μr=1
 
 # Earth model base (DC) properties:
-earthmodel_df = earthmodel_todf(earth_params)
+earthmodel_df = to_df(earth_params)
 
 #=
 ### Underground bipole configuration
@@ -282,7 +282,7 @@ In this section the complete bipole cable system is examined.
 =#
 
 # Display system details:
-system_df = linecablesystem_todf(cable_system)
+system_df = to_df(cable_system)
 
 # Visualize the cross-section of the three-phase system:
 plt4 = preview_linecablesystem(cable_system, zoom_factor=0.15)
@@ -337,16 +337,16 @@ mesh_transition2 = MeshTransition(
     n_regions=5);
 
 # Define the FEM formulation with the specified parameters
-formulation = FEMFormulation(
+formulation = FormulationSet(
+    impedance=FEMDarwin(),
+    admittance=FEMElectrodynamics(),
     domain_radius=domain_radius,
     domain_radius_inf=domain_radius * 1.25,
     elements_per_length_conductor=1,
     elements_per_length_insulator=2,
     elements_per_length_semicon=1,
     elements_per_length_interfaces=5,
     points_per_circumference=16,
-    analysis_type=(FEMDarwin(),
-        FEMElectrodynamics()),
     mesh_size_min=1e-6,
     mesh_size_max=domain_radius / 5,
     mesh_transitions=[mesh_transition1,
@@ -373,7 +373,7 @@ opts = FEMOptions(
 
 # Display primary core results
 if !opts.mesh_only
-    println("\nR = $(round(real(line_params.Z[1,1,1])*1000, sigdigits=4)) Ω/km")
+    println("R = $(round(real(line_params.Z[1,1,1])*1000, sigdigits=4)) Ω/km")
     println("L = $(round(imag(line_params.Z[1,1,1])/(2π*f)*1e6, sigdigits=4)) mH/km")
     println("C = $(round(imag(line_params.Y[1,1,1])/(2π*f)*1e9, sigdigits=4)) μF/km")
 end

examples/tutorial3.jl

@@ -23,7 +23,7 @@ $(EXPORTS)
 module BaseParams
 
 # Load common dependencies
-include("CommonDeps.jl")
+include("common_deps.jl")
 using ...Utils
 
 # Module-specific dependencies

src/BaseParams.jl

@@ -0,0 +1,153 @@
+"""
+    LineCableModels.Core
+
+The [`Core`](@ref) module provides the main functionalities of the [`LineCableModels.jl`](index.md) package. This module implements data structures, methods and functions for calculating frequency-dependent electrical parameters (Z/Y matrices) of line and cable systems with uncertainty quantification. 
+
+# Overview
+
+- Calculation of frequency-dependent series impedance (Z) and shunt admittance (Y) matrices.
+- Uncertainty propagation for geometric and material parameters using `Measurements.jl`.
+- Internal impedance computation for solid, tubular and multi-layered coaxial conductors.
+- Earth return impedances/admittances for overhead lines and underground cables (valid up to 10 MHz).
+- Support for frequency-dependent soil properties.
+- Handling of arbitrary polyphase systems with multiple conductors per phase.
+- Phase and sequence domain calculations with uncertainty quantification.
+- Novel N-layer concentric cable formulation with semiconductor modeling.
+
+# Dependencies
+
+$(IMPORTS)
+
+# Exports
+
+$(EXPORTS)
+"""
+module Core
+
+# Load common dependencies
+include("common_deps.jl")
+using ..Utils
+using ..Materials
+using ..EarthProps
+using ..DataModel
+import ..LineCableModels: FormulationSet, _get_description
+
+# Module-specific dependencies
+using Measurements
+using LinearAlgebra
+using SpecialFunctions
+
+# Export public API
+export LineParametersProblem, LineParameters
+export AbstractFormulationSet, AbstractImpedanceFormulation, AbstractAdmittanceFormulation,
+    FormulationOptions
+
+"""
+$(TYPEDEF)
+
+Abstract base type for all problem definitions in the [`LineCableModels.jl`](index.md) computation framework.
+"""
+abstract type ProblemDefinition end
+
+# Formulation abstract types
+abstract type AbstractFormulationSet end
+abstract type AbstractImpedanceFormulation <: AbstractFormulationSet end
+abstract type AbstractAdmittanceFormulation <: AbstractFormulationSet end
+abstract type InternalImpedanceFormulation <: AbstractImpedanceFormulation end
+abstract type EarthImpedanceFormulation <: AbstractImpedanceFormulation end
+abstract type InternalAdmittanceFormulation <: AbstractAdmittanceFormulation end
+abstract type EarthAdmittanceFormulation <: AbstractAdmittanceFormulation end
+
+"""
+$(TYPEDEF)
+
+Represents a line parameters computation problem for a given physical cable system.
+
+$(TYPEDFIELDS)
+"""
+struct LineParametersProblem <: ProblemDefinition
+    "The physical cable system to analyze."
+    system::LineCableSystem
+    "Operating temperature [°C]."
+    temperature::Number
+    "Earth properties model."
+    earth_props::EarthModel
+    "Frequencies at which to perform the analysis [Hz]."
+    frequencies::Vector{Float64}
+
+    function LineParametersProblem(
+        system::LineCableSystem;
+        temperature::Number=T₀,
+        earth_props::EarthModel,
+        frequencies::Vector{Float64}=[f₀]
+    )
+        return new(system, temperature, earth_props, frequencies)
+    end
+end
+
+"""
+$(TYPEDEF)
+
+Formulation base type for defining solver options in the computation framework.
+Solver options define execution-related parameters such as output options,
+solver command line arguments, and post-processing settings.
+
+Concrete implementations should define how the solution process is controlled,
+including file handling, previewing options, and external tool integration.
+"""
+abstract type FormulationOptions end
+
+struct LineParameters{T<:Union{Complex{Float64},Complex{Measurement{Float64}}}}
+    "Series impedance matrices [Ω/m]"
+    Z::Array{T,3}
+    "Shunt admittance matrices [S/m]"
+    Y::Array{T,3}
+
+    # Inner constructor with validation
+    function LineParameters(Z::Array{T,3}, Y::Array{T,3}) where {T<:Union{Complex{Float64},Complex{Measurement{Float64}}}}
+        # Validate dimensions
+        size(Z, 1) == size(Z, 2) || throw(DimensionMismatch("Z matrix must be square"))
+        size(Y, 1) == size(Y, 2) || throw(DimensionMismatch("Y matrix must be square"))
+        size(Z) == size(Y) || throw(DimensionMismatch("Z and Y must have same dimensions"))
+
+        new{T}(Z, Y)
+    end
+end
+
+struct EMTFormulation <: AbstractFormulationSet
+    internal_impedance::InternalImpedanceFormulation
+    earth_impedance::EarthImpedanceFormulation
+    internal_admittance::InternalAdmittanceFormulation
+    earth_admittance::EarthAdmittanceFormulation
+
+    function EMTFormulation(;
+        internal_impedance::InternalImpedanceFormulation=nothing,
+        earth_impedance::EarthImpedanceFormulation=nothing,
+        internal_admittance::InternalAdmittanceFormulation=nothing,
+        earth_admittance::EarthAdmittanceFormulation=nothing
+    )
+        return new(
+            internal_impedance, earth_impedance,
+            internal_admittance, earth_admittance
+        )
+    end
+end
+
+function FormulationSet(; internal_impedance::InternalImpedanceFormulation,
+    earth_impedance::EarthImpedanceFormulation,
+    internal_admittance::InternalAdmittanceFormulation,
+    earth_admittance::EarthAdmittanceFormulation)
+    return EMTFormulation(; internal_impedance, earth_impedance,
+        internal_admittance, earth_admittance)
+end
+
+# Pretty printing with uncertainty information if present
+function Base.show(io::IO, params::LineParameters{T}) where {T}
+    n_cond, _, n_freq = size(params.Z)
+    print(io, "LineParameters with $(n_cond) conductors at $(n_freq) frequencies")
+    if T <: Complex{Measurement{Float64}}
+        print(io, " (with uncertainties)")
+    end
+end
+
+end # module Core

src/Core.jl

@@ -0,0 +1,137 @@
+"""
+$(TYPEDEF)
+
+Abstract type representing different equivalent homogeneous earth models (EHEM). Used in the multi-dispatch implementation of [`_calc_ehem_properties!`](@ref).
+
+# Currently available formulations
+
+- [`EnforceLayer`](@ref): Effective parameters defined according to a specific earth layer.
+"""
+abstract type AbstractEHEMFormulation end
+
+"""
+$(TYPEDEF)
+
+Represents a homogeneous earth model defined using the properties of a specific earth layer, with atttribute:
+
+$(TYPEDFIELDS)
+"""
+struct EnforceLayer <: AbstractEHEMFormulation
+    "Index of the enforced earth layer."
+    layer::Int
+
+    @doc """
+    $(TYPEDSIGNATURES)
+
+    Constructs an [`EnforceLayer`](@ref) 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`](@ref) instance with the specified layer index.
+
+    # Examples
+
+    ```julia
+    # Enforce the bottommost layer
+    bottom_layer = $(FUNCTIONNAME)(-1)
+    println(_get_description(bottom_layer)) # Output: "Bottom layer"
+
+    # Enforce the topmost earth layer
+    first_layer = $(FUNCTIONNAME)(2)
+    println(_get_description(first_layer)) # Output: "Top layer"
+
+    # Enforce a specific layer
+    specific_layer = $(FUNCTIONNAME)(3)
+    println(_get_description(specific_layer)) # Output: "Layer 3"
+    ```
+    """
+    function EnforceLayer(layer::Int)
+        @assert (layer == -1 || layer >= 2) "Invalid earth layer choice."
+        return new(layer)
+    end
+end
+
+function _get_description(formulation::EnforceLayer)
+    if formulation.layer == -1
+        return "Bottom layer"
+    elseif formulation.layer == 2
+        return "Top layer"
+    else
+        return "Layer $(formulation.layer)"
+    end
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Computes the effective homogeneous earth model (EHEM) properties for an [`EarthModel`](@ref), overriding the layered model with the properties of the layer defined in [`EnforceLayer`](@ref).
+
+# Arguments
+
+- `model`: Instance of [`EarthModel`](@ref) for which effective properties are computed.
+- `frequencies`: Vector of frequency values \\[Hz\\].
+- `formulation`: Instance of [`AbstractEHEMFormulation`](@ref) 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`](@ref), 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
+
+```julia
+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
+$(FUNCTIONNAME)(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`](@ref)
+- [`AbstractEHEMFormulation`](@ref)
+"""
+function _calc_ehem_properties!(
+    model::EarthModel,
+    frequencies::Vector{<:Number},
+    formulation::AbstractEHEMFormulation=EnforceLayer(-1),
+)
+    layer_idx = formulation.layer
+
+    if layer_idx == -1
+        layer_idx = length(model.layers)  # Use last layer
+    elseif layer_idx < 2 || layer_idx > length(model.layers)
+        error(
+            "Invalid layer index: $layer_idx. Must be between 2 and $(length(model.layers))",
+        )
+    end
+
+    layer = model.layers[layer_idx]
+
+    # Just reference the selected layer
+    model.rho_eff = layer.rho_g
+    model.eps_eff = layer.eps_g
+    model.mu_eff = layer.mu_g
+end
+
+# Compute effective parameters **only if we have at least 2 earth layers**
+# if model.num_layers > 2 && !isnothing(model.AbstractEHEMFormulation) &&
+#    !(model.vertical_layers)
+#     _calc_ehem_properties!(model, frequencies, model.AbstractEHEMFormulation)
+# end