Earth return

Physical model

The air above the interface y = 0 and the earth below it are homogeneous half-spaces, each with its resistivity $\rho$, relative permittivity $\varepsilon_r$ and relative permeability $\mu_r$. A layered earth enters as its equivalent earth, which Properties of the air and the earth describes. Each cable is a source of circumferential currents on its exterior circle, which lies wholly in one medium. A pair of cables lies in the air, in the earth or across the interface, the mixed domain.

An earth-return formula gives the earth-return impedance Zg, the earth-return potential coefficients Pg, or both, per pair of cables and from their exterior surfaces. They are the matrices $\mathbf Z_{\mathrm{env}}$ and $\mathbf P_{\mathrm{env}}$ of the matrix formulation, added to every pair of conductors of each pair of cables. Each formula treats the domains that Line parameters lists.

The default formula, :martins2026, treats the three domains and gives both quantities. It closes the circumferential currents of all cables completely through its current matrix $\mathbf T$. The fields vary along the line as $e^{-\Gamma x}$, with a prescribed longitudinal wavenumber $\Gamma$, zero by default.

The other formulas are classical expressions of the literature, each with the assumptions that its block below states. They take each cable as a line source at its center, with the current matrix $\mathbf T = \mathbf I$. Of these, :xue2018 alone reads the prescribed $\Gamma$.

The fields of each medium are spectral integrals over the real line of the transverse wavenumber. A spectral formula evaluates them on a complex path. The constructor of SpectralIntegral chooses the path with the breakpoints of the quadrature, and integrate evaluates each integral by adaptive quadrature. The option integral of the formula selects the method and its controls, integral = (method = :quad, rtol, atol, maxevals).

Validity of the default formula

The default formula, :martins2026, holds within two ranges.

  • Prescribed Γ. A nonzero Γ lies between the propagation constants of the two media. It is in range at a frequency where Im γair ≤ Im Γ ≤ Im γearth and Re Γ ≤ Re γ_earth. Γ = 0, the default, always lies in range.
  • Thick receiver. The formula represents each receiving conductor by the mean field on its exterior circumference. A conductor that is thick compared with the transverse wavelength of its medium receives a voltage that departs from the full-field value. The error grows as (κm rp)², where κm is the outgoing root of γm² − Γ² in the medium of conductor p and rp is its exterior radius, the jacket for an insulated cable. The range is |κm r_p| ≤ 0.1. Emission from a thick conductor is accurate.

The calibration below is indicative. It compares the default formula with a finite-element reference for two bare copper conductors buried at 1 m depth and 2 m apart, in earth of 1000 Ω·m and relative permittivity 12, at 100 MHz with Γ = 0, where |κ_earth| ≈ 7.26 1/m.

Radii (m)κrScaled Y errorP error, thick receiverP error, thin receiver
0.002 / 0.0020.0150.74 %none≤ 1.0 % (all entries)
0.01 / 0.010.0731.08 %nonenot reported
0.0425 / 0.0020.31 / 0.0151.55 %11.0 % (mutual)2.0 % (mutual)
0.0425 / 0.04250.315.18 %11 % mutual, 4.5 % selfnone

The scaled Y error is max|ΔY| / max|diag Y_ref|. P = jω Y⁻¹, with one row per receiver. The reference itself has an error floor of about 0.7 %, the first row. The calibration covers buried conductors only. In air at Γ = 0, κ ≈ k₀, so a 20 mm radius reaches κr ≈ 0.13 at 300 MHz, a regime outside the calibration.

Properties of the air and the earth

The law of the slot earth_properties gives the resistivity, the relative permittivity and the relative permeability of each earth layer at each frequency. The air keeps its declared values. The model of the slot equivalent_earth then reduces the described layers below the air to the one earth that the earth-return formulas read. The default law, :constant, gives the static values of each layer at every frequency, and the nine soil laws of EarthProperties give values that vary with it. The default model, :bottommost, takes the deepest layer, and :martins2020 and :xue2021 reduce all the layers to one equivalent layer.

Earth-return formulas

LineCableModels.Engine.EarthReturn — Module
LineCableModels.Engine.EarthReturn

Compute the earth-return impedances and potential coefficients of cables. A formula gives the impedance, the potential coefficients, or both, by the methods it defines. It treats the pairs of conductors it declares by their layers: input.earth_layer gives 1 for the air and k for the (k - 1)-th earth layer.

Formulas

Formula{:martins2026}

Earth-return impedances and potential coefficients of conductors in two homogeneous half-spaces, the air, medium 1 with $y > 0$, and the earth, medium 2 with $y < 0$, for fields with the dependence $e^{-\Gamma \ell}$ along the line, where $\ell$ is the axial coordinate. Each cable enters as a solid conductor bounded by its exterior circumference, which lies wholly in one medium. The field of each conductor is that of one axial line source, and each conductor takes the circumferential mean of the field on its circumference, the zeroth azimuthal harmonic. The formula contains the solutions of the underground case [4] and of the mixed overhead and underground case [5]. Its form follows [13].

For each medium $t$, the complex conductivity $\widetilde\sigma_t$ [S/m], the permeability $\mu_t$ [H/m], the transverse propagation parameter $\kappa_t$ [1/m] and the vertical decay parameter $a_t$ [1/m] are

\[\widetilde\sigma_t = \frac{1}{\rho_t} + s \varepsilon_0 \varepsilon_{r,t}, \qquad \mu_t = \mu_0 \mu_{r,t}, \qquad \kappa_t^2 = s \mu_t \widetilde\sigma_t - \Gamma^2, \qquad a_t = \sqrt{\lambda^2 + \kappa_t^2},\]

where $s = \mathrm{j} 2 \pi f$ is the complex frequency [1/s], $\rho_t$ is the resistivity [Ω·m], $\varepsilon_{r,t}$ and $\mu_{r,t}$ are the relative permittivity and permeability [dimensionless], $\Gamma$ is the longitudinal wavenumber [1/m], and $\lambda$ is the transverse Fourier variable [1/m]. The constants $\varepsilon_0$ and $\mu_0$ are ε₀ and μ₀. The square roots take the decaying branch. The spectral denominators are

\[\Delta_\mu = \mu_2 a_1 + \mu_1 a_2, \qquad \Delta_\sigma = \widetilde\sigma_2 a_1 + \widetilde\sigma_1 a_2.\]

Conductor $i$ has its center at $(x_i, y_i)$, the distance $h_i = |y_i|$ to the interface, the exterior radius $r_i$ [m] and the medium $t = m(i)$. In a coefficient $ij$, conductor $i$ is the target and conductor $j$ the source, in the medium $s = m(j)$, and $\bar s$ is the other medium. The distance between the centers is $D_{ij}$, the distance from conductor $i$ to the image of conductor $j$ is $D'_{ij} = \sqrt{x_{ij}^2 + (h_i + h_j)^2}$, with $D'_{ii} = 2 h_i$, and $x_{ij} = x_i - x_j$ [m].

For conductors in the same medium, $t = s$, the means of the direct and image fields and the interface corrections are

\[\begin{aligned} \Lambda_{ii} &= K_0(\kappa_s r_i) - I_0(\kappa_s r_i) K_0(2 \kappa_s h_i), \qquad \Lambda_{ij} = I_0(\kappa_s r_i) \left[K_0(\kappa_s D_{ij}) - K_0(\kappa_s D'_{ij})\right], \\ J_{ij} &= \int_0^\infty \frac{\mu_{\bar s}}{\Delta_\mu} e^{-a_s (h_i + h_j)} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda, \qquad M_{ij} = \int_0^\infty \frac{\widetilde\sigma_s (\mu_s a_s + \mu_{\bar s} a_{\bar s})}{\Delta_\mu \Delta_\sigma} e^{-a_s (h_i + h_j)} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda, \end{aligned}\]

where $I_\nu$ and $K_\nu$ are the modified Bessel functions of order $\nu$. The axial vector-potential kernel $\widetilde L_{ij}$ [H/m] and the scalar-potential kernel $\widetilde\Phi_{ij}$ [m/F] are

\[\widetilde L_{ij} = \frac{\mu_s}{2 \pi} \left[\Lambda_{ij} + 2 I_0(\kappa_s r_i) J_{ij}\right], \qquad \widetilde\Phi_{ij} = \frac{s}{2 \pi \widetilde\sigma_s} \left[\Lambda_{ij} + 2 I_0(\kappa_s r_i) M_{ij}\right]\]

for $t = s$, and, from the transmitted fields,

\[\begin{aligned} \widetilde L_{ij} &= \frac{\mu_t \mu_s}{\pi} I_0(\kappa_t r_i) \int_0^\infty \frac{e^{-a_t h_i - a_s h_j}}{\Delta_\mu} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda, \\ \widetilde\Phi_{ij} &= \frac{s}{\pi} I_0(\kappa_t r_i) \int_0^\infty \frac{\mu_1 a_1 + \mu_2 a_2}{\Delta_\mu \Delta_\sigma} e^{-a_t h_i - a_s h_j} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda \end{aligned}\]

for $t \neq s$. The kernel $\widetilde K_{ij} = s \widetilde L_{ij} - (\Gamma^2 / s) \widetilde\Phi_{ij}$ [Ω/m] is the negative mean axial electric field at conductor $i$ per source amplitude at conductor $j$.

The voltage of a conductor is the circumferential mean of the integral of the vertical electric field from a reference level. A conductor in the earth is referred to infinite depth, and a conductor in the air to the interface below it. The source-normalized voltage coefficients $\widetilde P_{ij}$ [m/F] are

\[\begin{aligned} \widetilde P_{ij} &= \delta_{ts} \frac{s}{2 \pi \widetilde\sigma_2} \Lambda_{ij} + \frac{s}{\pi} I_0(\kappa_2 r_i) \int_0^\infty \frac{a_1}{a_2 \Delta_\sigma} e^{-a_2 h_i - a_s h_j} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda, & t &= 2, \\ \widetilde P_{ij} &= \delta_{ts} \frac{s}{2 \pi \widetilde\sigma_1} \Lambda_{ij} + \frac{s}{\pi} \int_0^\infty \frac{a_2}{a_1 \Delta_\sigma} \left[I_0(\kappa_1 r_i) e^{-a_1 h_i} - J_0(\lambda r_i)\right] e^{-a_s h_j} \cos(\lambda x_{ij}) \, \mathrm{d}\lambda, & t &= 1, \end{aligned}\]

where $\delta$ is the Kronecker delta and $J_0$ is the Bessel function of order zero, which averages the interface endpoint over the horizontal extent of the circumference. For $s = 1$, the integral of the line $t = 1$ is $-\Theta_{ij} / \widetilde\sigma_1$, with $\Theta_{ij}$ the averaged interface correction of [13]. The kernels evaluate it as one integral for a nominal $|\operatorname{Re} \kappa_1 r_i| < 300$ and as its two endpoint terms above.

The enclosed currents follow from the complete field on the circumferences, with the reflected and mutual fields, through the dimensionless current matrix $\mathbf T$, the key T of the formula's block, and the diagonal matrices $\mathbf W$ [dimensionless] and $\mathbf F$ [m/Ω]. Elimination of the source amplitudes gives the earth-return potential coefficients $\mathbf P_g$ [m/F] and impedances $\mathbf Z_g$ [Ω/m]:

\[\mathbf T = \mathbf W^{-1} - \mathbf F \widetilde{\mathbf K}, \qquad W_{ii} = I_0(\kappa_t r_i), \qquad F_{ii} = \frac{2 \pi \widetilde\sigma_t r_i I_1(\kappa_t r_i)}{\kappa_t I_0(\kappa_t r_i)},\]

\[\mathbf P_g = \widetilde{\mathbf P} \mathbf T^{-1}, \qquad \mathbf Z_g = \left(\widetilde{\mathbf K} + \frac{\Gamma^2}{s} \widetilde{\mathbf P}\right) \mathbf T^{-1}.\]

The internal impedances of the conductors are not part of $\mathbf Z_g$: the impedance inside each cable, Zin, gives them.

The integrals run along the complex path that each SpectralIntegral chooses, and integrate evaluates them. The kernel $\widetilde\Phi_{ij}$ enters only for $\Gamma \neq 0$. With $\xi = \kappa_t r_i$, the ratio $I_1(\xi) / (\xi I_0(\xi))$ in $F_{ii}$ is the series $1/2 - \xi^2/16 + \xi^4/96 - 11 \xi^6/6144$ for a nominal $|\xi| < 10^{-3}$. The direct and image terms are evaluated together for a nominal $|\kappa_s D'_{ij}| < 0.5$, and their difference is $\ln(D'_{ij} / D_{ij})$ for $\kappa_s = 0$, with $D_{ii} = r_i$. The implementation scales the column of each source $j$ by $e^{|\operatorname{Re} \kappa_s r_j|}$ with exponentially scaled Bessel functions, and the scaling cancels in $\mathbf P_g$ and $\mathbf Z_g$.

Callables

The kernels are the integrands of the integrals of a pair in $\lambda$, with the states medium and pair that to_buffer! builds:

  • formula(Val(:J), λ, medium, pair): the magnetic coupling.
  • formula(Val(:M), λ, medium, pair): the scalar-potential correction.
  • formula(Val(:P̃), λ, medium, pair): the voltage correction.
  • formula(Val(:Θ), λ, medium, pair): the averaged interface correction of a target in the air.
  • formula(Val(:Θ), Val(:interface), λ, medium, pair): the interface endpoint of that correction.

The entries read the block of the formula, with i the target and j the source:

  • formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k): an entry of $\mathbf Z_g$ [Ω/m].
  • formula(Val(:P), Val(:self), i, buffers, input, media, s, k) and formula(Val(:P), Val(:mutual), i, j, buffers, input, media, s, k): an entry of $\mathbf P_g$ [m/F].

Formula{:ideal}

Potential coefficients of conductors over an earth of infinite conductivity, from the images of the sources, for conductors in the air:

\[P_{g,ii} = \frac{\ln(2 h_i / r_i)}{2 \pi \varepsilon_1}, \qquad P_{g,ij} = \frac{\ln(D'_{ij} / D_{ij})}{2 \pi \varepsilon_1},\]

where $\varepsilon_1 = \varepsilon_0 \varepsilon_{r,1}$ is the permittivity of the air [F/m]. These are $\Lambda_{ii}$ and $\Lambda_{ij}$ at $\kappa = 0$. The earth shields a buried conductor, so each coefficient of a buried or mixed pair is zero. The formula gives the potential coefficients alone.

Callables

formula(Val(:P), Val(:self), i, buffers, input, media, s, k) and formula(Val(:P), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf P_g$ [m/F], with i the target and j the source.

Formula{:gary1976}

Impedance of conductors in the air over a nonmagnetic earth, from an image plane at the complex depth $p$ [m] [14, 15]:

\[\begin{aligned} p &= \frac{1}{\sqrt{s \mu_0 \sigma_2}}, \\ Z_{g,ii} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{2 h_i}{r_i} + \ln\frac{h_i + p}{h_i}\right], \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{D'_{ij}}{D_{ij}} + \ln\frac{\sqrt{y_{ij}^2 + (H_{ij} + 2 p)^2}}{D'_{ij}}\right], \end{aligned}\]

where $\sigma_2 = 1 / \rho_2$ [S/m] is the conductivity of the earth. The lengths [m] are the height $h_i$, the exterior radius $r_i$, the horizontal distance $y_{ij}$ and $H_{ij} = h_i + h_j$. The first logarithm of each entry is $\Lambda_{ii}$ or $\Lambda_{ij}$ at $\kappa = 0$. The formula leaves out the displacement current of the earth, and it gives the impedance alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source.

Formula{:wedepohl1973}

Impedance of buried conductors by the low-order expansion of Wedepohl and Wilcox [3]. The earth has the permeability $\mu_2 = \mu_0 \mu_{r,2}$, with $m = \sqrt{s \mu_2 / \rho_2}$ [1/m], and $e_c$ is the exponential of Euler's constant:

\[\begin{aligned} Z_{g,ii} &= \frac{s \mu_2}{2 \pi} \left[-\ln\frac{e_c m r_i}{2} + \frac{1}{2} - \frac{4 m h_i}{3}\right], \\ Z_{g,ij} &= \frac{s \mu_2}{2 \pi} \left[-\ln\frac{e_c m D_{ij}}{2} + \frac{1}{2} - \frac{2 m H_{ij}}{3}\right], \end{aligned}\]

where $h_i$ is the depth [m]. The formula leaves out the displacement current of the earth, and it gives the impedance alone. The source bounds the entries by $|m r_i| < 0.25$ and $|m D_{ij}| < 0.25$. A computation warns when the highest frequency of its scan leaves that bound, with $m$ from the static resistivity and permeability of the deepest layer.

Callables

formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source.

Formula{:saad1996}

Impedance of buried conductors in a nonmagnetic earth by the closed form of Saad, Gaba and Giroux [16], with $m = \sqrt{s \mu_0 / \rho_2}$ [1/m]:

\[\begin{aligned} Z_{g,ii} &= \frac{s \mu_0}{2 \pi} \left[K_0(m r_i) + \frac{2 e^{-2 m h_i}}{4 + m^2 r_i^2}\right], \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[K_0(m D_{ij}) + \frac{2 e^{-m H_{ij}}}{4 + m^2 y_{ij}^2}\right], \end{aligned}\]

where $K_0$ is the modified Bessel function of the second kind and order zero. The source proves the form for $y_{ij} / H_{ij} < 1$. The formula leaves out the displacement current of the earth, and it gives the impedance alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source.

Formula{:lucca1994}

Mutual impedance between a conductor in the air and a conductor in a nonmagnetic earth, by the approximation of Lucca [17]. Equation (28) of [18] prints the expression. With the complex depth $p = 1 / \sqrt{s \mu_0 \sigma_2}$ [m]:

\[\begin{aligned} V &= h_a + h_g, \qquad H_c = V + 2 p, \qquad S = \sqrt{H_c^2 + y_{ij}^2}, \qquad D = \sqrt{V^2 + y_{ij}^2}, \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{S}{D} - \frac{2}{3} \left(\frac{p}{S^2}\right)^3 H_c \left(H_c^2 - 3 y_{ij}^2\right)\right], \end{aligned}\]

where $h_a$ is the height of the conductor in the air and $h_g$ the depth of the conductor in the earth [m]. The horizontal distance is $y_{ij}$ [m], and $\sigma_2 = 1 / \rho_2$ [S/m]. The formula leaves out the displacement current of the earth. It gives the entries of a mixed pair alone, so other formulas fill the air and earth places. A computation refuses a magnetic earth layer.

Callables

formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) returns an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source, in either order of a mixed pair.

Formula{:ametani2009}

Mutual impedance between a conductor in the air and a conductor in a nonmagnetic earth, by equation (27) of Ametani, Yoneda, Baba and Nagaoka [18]. With $m = \sqrt{s \mu_0 / \rho_2}$ [1/m] and the complex depth $p = 1 / m$ [m]:

\[\begin{aligned} S &= \sqrt{(h_a + h_g + 2 p)^2 + y_{ij}^2}, \qquad D = \sqrt{(h_a + h_g)^2 + y_{ij}^2}, \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} e^{-h_g / p} \ln\frac{S}{D}, \end{aligned}\]

where $h_a$, $h_g$ and $y_{ij}$ are the lengths of Formula{:lucca1994}. The exponential takes $h_g$ as a positive depth. The formula leaves out the displacement current of the earth. It gives the entries of a mixed pair alone, so other formulas fill the air and earth places. A computation refuses a magnetic earth layer.

Callables

formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) returns an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source, in either order of a mixed pair.

Formula{:carson1926}

Impedance of conductors in the air over a nonmagnetic earth, by the correction integral of Carson [19], with $\gamma^2 = s \mu_0 \sigma_2$ [1/m²]:

\[\begin{aligned} J_{ij} &= \int_0^\infty \frac{e^{-H_{ij} \lambda} \cos(y_{ij} \lambda)} {\lambda + \sqrt{\lambda^2 + \gamma^2}} \, \mathrm{d}\lambda, \\ Z_{g,ii} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{2 h_i}{r_i} + 2 J_{ii}\right], \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{D'_{ij}}{D_{ij}} + 2 J_{ij}\right], \end{aligned}\]

where $\sigma_2 = 1 / \rho_2$ [S/m], $J_{ij}$ is in [dimensionless], and the lengths are those of Formula{:gary1976}. The first logarithm of each entry is $\Lambda_{ii}$ or $\Lambda_{ij}$ at $\kappa = 0$. The integral of the source is $\mathrm{j} J_{ij} = P + \mathrm{j} Q$, at $p = H_{ij} \sqrt{\omega \mu_0 \sigma_2}$ and $q = y_{ij} \sqrt{\omega \mu_0 \sigma_2}$. Its series evaluate that integral, and this formula evaluates it on the path of SpectralIntegral, under the options integral of integrate. The formula leaves out the displacement currents of the air and the earth, and it gives the impedance alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:J), λ, γ², H, y) returns the integrand of $J_{ij}$ [m] at the spectral coordinate λ [1/m], with γ² [1/m²], H and y [m]. formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source.

Formula{:pollaczek1926}

Impedance of conductors in a nonmagnetic earth and of a pair across the interface, by the Green functions of Pollaczek [20]. The symbols are $\gamma^2 = s \mu_0 \sigma_2$ [1/m²] and $a = \sqrt{\lambda^2 + \gamma^2}$ [1/m]. For conductors in the earth, his equation (20b) gives:

\[\begin{aligned} J_{ij} &= \int_0^\infty \frac{e^{-a H_{ij}} \cos(y_{ij} \lambda)}{\lambda + a} \, \mathrm{d}\lambda, \\ Z_{g,ii} &= \frac{s \mu_0}{2 \pi} \left[K_0(\gamma r_i) - K_0(2 \gamma h_i) + 2 J_{ii}\right], \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[K_0(\gamma D_{ij}) - K_0(\gamma D'_{ij}) + 2 J_{ij}\right]. \end{aligned}\]

For a pair across the interface, his equations (19a) and (20a) are one expression, since (9) makes the field symmetric in the two points:

\[Z_{g,ij} = \frac{s \mu_0}{\pi} \int_0^\infty \frac{e^{-h_a \lambda - h_g a} \cos(y_{ij} \lambda)}{\lambda + a} \, \mathrm{d}\lambda,\]

where $\sigma_2 = 1 / \rho_2$ [S/m] and $J_{ij}$ is in [dimensionless]. The lengths are those of Formula{:gary1976}, with $h_i$ the depth of the conductor, and $h_a$ and $h_g$ those of Formula{:lucca1994}. The formula evaluates the integrals on the path of SpectralIntegral, under the options integral of integrate. Each cable enters as a filament of its exterior radius. The formula leaves out the displacement currents of the air and the earth, and it gives the impedance alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:J), Val(:earth), λ, γ², H, y) and formula(Val(:J), Val(:mixed), λ, γ², h_g, H, y) return the integrands [m] at the spectral coordinate λ [1/m], with γ² [1/m²] and the lengths [m]. formula(Val(:Z), Val(:earth), i, j, buffers, input, media, s) and formula(Val(:Z), Val(:mixed), i, j, buffers, input, media, s) return an off-diagonal entry of $\mathbf Z_g$ [Ω/m] for a pair in the earth and for a pair across the interface. In each, i is the target and j the source. formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) calls the one that the pair needs. formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) returns a diagonal entry.

Formula{:papadopoulos2010}

Impedance and potential coefficients of conductors in the earth, by Papadopoulos and coauthors [21], under the longitudinal constant of the earth, $k_x^2 = \omega^2 \mu_2 \varepsilon_0 \varepsilon_{r,2}$ [1/m²]. The symbols are $\gamma_t^2 = s \mu_t \tilde\sigma_t$ and $\kappa_t^2 = \gamma_t^2 + k_x^2$ [1/m²], and $a_t = \sqrt{\lambda^2 + \kappa_t^2}$ [1/m], the air $t = 1$ and the earth $t = 2$. Their equations (5) and (6) give:

\[\begin{aligned} \Delta &= a_2 \mu_0 + a_1 \mu_2, \\ J_{ij} &= \int_0^\infty \frac{\mu_0}{\Delta} e^{-a_2 H_{ij}} \cos(y_{ij} \lambda) \, \mathrm{d}\lambda, \\ \tilde P_{ij} &= \int_0^\infty \frac{\mu_0}{\Delta} \left[1 + \frac{\mu_2 a_2 (\gamma_2^2 - \gamma_1^2)}{a_2 \gamma_1^2 \mu_2 + a_1 \gamma_2^2 \mu_0}\right] e^{-a_2 H_{ij}} \cos(y_{ij} \lambda) \, \mathrm{d}\lambda, \\ \Lambda_{ij} &= K_0(\kappa_2 D_{ij}) - K_0(\kappa_2 D'_{ij}), \\ Z_{g,ij} &= \frac{s \mu_2}{2 \pi} (\Lambda_{ij} + 2 J_{ij}), \qquad P_{g,ij} = \frac{s}{2 \pi \tilde\sigma_2} (\Lambda_{ij} + 2 \tilde P_{ij}), \end{aligned}\]

where $\tilde\sigma_1 = s \varepsilon_0 \varepsilon_{r,1}$ and $\tilde\sigma_2 = 1 / \rho_2 + s \varepsilon_0 \varepsilon_{r,2}$ [S/m], $\mu_1 = \mu_0$ and $\mu_2 = \mu_0 \mu_{r,2}$ [H/m], and $J_{ij}$ and $\tilde P_{ij}$ are in [dimensionless]. The lengths are those of Formula{:gary1976}, with $h_i$ the depth of the conductor. A diagonal entry takes $y_{ii} = r_i$, $D_{ii} = r_i$ and $D'_{ii} = \sqrt{r_i^2 + 4 h_i^2}$, by the substitution of the source.

The earth's displacement current cancels in $\kappa_2^2 = s \mu_2 / \rho_2$. The source writes the direct and image term as a spectral integral, and $\Lambda_{ij}$ is its closed form. The integrals run on the path of SpectralIntegral, under the options integral of integrate. Each cable enters as a filament of its exterior radius. At $\varepsilon_{r,2} = \varepsilon_{r,1}$ for a nonmagnetic earth, $a_1 = \lambda$, and the integrand of $\tilde P_{ij}$ has a pole off the real axis near $\lambda = 0$.

Callables

formula(Val(:J), λ, κ₁², κ₂², μ₂, H, y) and formula(Val(:P̃), λ, κ₁², κ₂², γ₁², γ₂², μ₂, H, y) return the integrands [m] at the spectral coordinate λ [1/m], with κ₁², κ₂², γ₁², γ₂² [1/m²], μ₂ [H/m], H and y [m]. formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], and formula(Val(:P), Val(:self), i, buffers, input, media, s, k) and formula(Val(:P), Val(:mutual), i, j, buffers, input, media, s, k) an entry of $\mathbf P_g$ [m/F], with i the target and j the source.

Formula{:wise1934}

Impedance of conductors in the air over a nonmagnetic earth, by the correction integral of Wise [22]. The symbols are $\kappa_t^2 = s \mu_0 \tilde\sigma_t$ [1/m²], the air $t = 1$ and the earth $t = 2$:

\[\begin{aligned} J_{ij} &= \int_0^\infty \frac{e^{-H_{ij} \lambda} \cos(y_{ij} \lambda)} {\lambda + \sqrt{\lambda^2 + \kappa_2^2 - \kappa_1^2}} \, \mathrm{d}\lambda, \\ Z_{g,ii} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{2 h_i}{r_i} + 2 J_{ii}\right], \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} \left[\ln\frac{D'_{ij}}{D_{ij}} + 2 J_{ij}\right], \end{aligned}\]

where $\tilde\sigma_1 = s \varepsilon_0 \varepsilon_{r,1}$ and $\tilde\sigma_2 = 1 / \rho_2 + s \varepsilon_0 \varepsilon_{r,2}$ [S/m], $J_{ij}$ is in [dimensionless], and the lengths are those of Formula{:gary1976}. The displacement current of the earth enters through $\kappa_2^2$. The source fixes the longitudinal constant at that of the air, as a first approximation. Where the earth has the permittivity of the air, $J_{ij}$ is that of Formula{:carson1926}. Otherwise the series of Carson hold with their argument multiplied by $\sqrt{(\kappa_2^2 - \kappa_1^2) \rho_2 / (s \mu_0)}$.

The formula evaluates the integral on the path of SpectralIntegral, under the options integral of integrate, and it gives the impedance alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:J), λ, κ₁², κ₂², H, y) returns the integrand of $J_{ij}$ [m] at the spectral coordinate λ [1/m], with κ₁², κ₂² [1/m²], H and y [m]. formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], with i the target and j the source.

Formula{:wise1948}

Potential coefficients of conductors in the air over a nonmagnetic earth, by equations (7) and (8) of Wise [23], with the symbols of Formula{:wise1934}:

\[\begin{aligned} M_{ij} + \mathrm{j} N_{ij} &= \int_0^\infty \frac{e^{-H_{ij} \lambda} \cos(y_{ij} \lambda)} {(\tilde\sigma_2 / \tilde\sigma_1) \lambda + \sqrt{\lambda^2 + \kappa_2^2 - \kappa_1^2}} \, \mathrm{d}\lambda, \\ P_{g,ii} &= \frac{1}{2 \pi \varepsilon_1} \left[\ln\frac{2 h_i}{r_i} + 2 (M_{ii} + \mathrm{j} N_{ii})\right], \\ P_{g,ij} &= \frac{1}{2 \pi \varepsilon_1} \left[\ln\frac{D'_{ij}}{D_{ij}} + 2 (M_{ij} + \mathrm{j} N_{ij})\right], \end{aligned}\]

where $\varepsilon_1 = \varepsilon_0 \varepsilon_{r,1}$ [F/m], and $M_{ij}$ and $N_{ij}$ are in [dimensionless]. The source fixes the longitudinal constant at that of the air, as a first approximation. Its charts and its closed approximation evaluate the same integral.

The formula evaluates the integral on the path of SpectralIntegral, under the options integral of integrate, and it gives the potential coefficients alone. A computation refuses a magnetic earth layer.

Callables

formula(Val(:P̃), λ, κ₁², κ₂², σ̃₁, σ̃₂, H, y) returns the integrand [m] at the spectral coordinate λ [1/m]. Its arguments κ₁² and κ₂² are in [1/m²], σ̃₁ and σ̃₂ in [S/m], H and y in [m]. formula(Val(:P), Val(:self), i, buffers, input, media, s, k) and formula(Val(:P), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf P_g$ [m/F], with i the target and j the source.

Formula{:xue2018}

Impedance and potential coefficients of conductors in a nonmagnetic earth, by the complete field of Xue and coauthors [24]. The voltage refers to infinite depth. The formulation's $\Gamma$ takes the place of the modal constant of the source, $\Gamma = \mathrm{j} k_v$. The symbols are $\kappa_t^2 = s \mu_0 \tilde\sigma_t - \Gamma^2$ [1/m²] and $a_t = \sqrt{\lambda^2 + \kappa_t^2}$ [1/m], the air $t = 1$ and the earth $t = 2$. Their equations (25) and (31) give:

\[\begin{aligned} \Delta &= \tilde\sigma_2 a_1 + \tilde\sigma_1 a_2, \\ J_{ij} &= \int_0^\infty \frac{e^{-a_2 H_{ij}} \cos(y_{ij} \lambda)}{a_1 + a_2} \, \mathrm{d}\lambda, \\ M_{ij} &= \int_0^\infty \frac{(\tilde\sigma_2 - \tilde\sigma_1) e^{-a_2 H_{ij}} \cos(y_{ij} \lambda)} {a_2 (a_1 + a_2) \Delta} \, \mathrm{d}\lambda, \\ \tilde P_{ij} &= \int_0^\infty \frac{\tilde\sigma_2 a_1 e^{-a_2 H_{ij}} \cos(y_{ij} \lambda)}{a_2 \Delta} \, \mathrm{d}\lambda, \\ \Lambda_{ij} &= K_0(\kappa_2 D_{ij}) - K_0(\kappa_2 D'_{ij}), \\ Z_{g,ij} &= \frac{s \mu_0}{2 \pi} (\Lambda_{ij} + 2 J_{ij} - 2 \Gamma^2 M_{ij}), \qquad P_{g,ij} = \frac{s}{2 \pi \tilde\sigma_2} (\Lambda_{ij} + 2 \tilde P_{ij}), \end{aligned}\]

where $\tilde\sigma_1 = s \varepsilon_0 \varepsilon_{r,1}$ and $\tilde\sigma_2 = 1 / \rho_2 + s \varepsilon_0 \varepsilon_{r,2}$ [S/m]. $J_{ij}$ and $\tilde P_{ij}$ are in [dimensionless], and $M_{ij}$ is in [m²]. The lengths are those of Formula{:gary1976}, with $h_i$ the depth of the conductor. A diagonal entry takes $y_{ii} = r_i$, $D_{ii} = r_i$ and $D'_{ii} = \sqrt{r_i^2 + 4 h_i^2}$.

At $\Gamma = 0$ the formula is the quasi-TEM form of their equations (33) and (34), and the diagonal entry is the prescription of that form. The source solves a modal equation for $k_v$, and the formula reads the prescribed $\Gamma$ instead. The integrals run on the path of SpectralIntegral, under the options integral of integrate. Each cable enters as a filament of its exterior radius. A computation refuses a magnetic earth layer.

Callables

formula(Val(:J), λ, κ₁², κ₂², H, y), formula(Val(:M), λ, κ₁², κ₂², σ̃₁, σ̃₂, H, y) and formula(Val(:P̃), λ, κ₁², κ₂², σ̃₁, σ̃₂, H, y) return the integrands at the spectral coordinate λ [1/m]. The arguments κ₁² and κ₂² are in [1/m²], σ̃₁ and σ̃₂ in [S/m], H and y in [m]. formula(Val(:Z), Val(:self), i, buffers, input, media, s, k) and formula(Val(:Z), Val(:mutual), i, j, buffers, input, media, s, k) return an entry of $\mathbf Z_g$ [Ω/m], and formula(Val(:P), Val(:self), i, buffers, input, media, s, k) and formula(Val(:P), Val(:mutual), i, j, buffers, input, media, s, k) an entry of $\mathbf P_g$ [m/F], with i the target and j the source.

source
LineCableModels.Engine.EarthReturn.Formula — Type
struct Formula{ID, O<:LineCableModels.Commons.FormulationOptions} <: LineCableModels.Engine.AbstractEarthReturn

Represent an earth-return impedance and potential-coefficient formula. Its options form a record of type FormulationOptions{Formula{ID}}, with ID the formula identifier.

  • options::LineCableModels.Commons.FormulationOptions: Options of the formula.
source
LineCableModels.Engine.EarthReturn.Formula — Method
Formula(
    ::Val{ID};
    kw...
) -> LineCableModels.Engine.EarthReturn.Formula

Build the formula named by ID with its declared defaults and supplied options.

Arguments

  • Val{ID}: formula identifier from FORMULAS.

Keywords

  • kw...: options declared by defaults for Formula{ID}.

Returns

  • A Formula with a typed option record.

Errors

  • Throws ArgumentError for an unknown identifier or option.
  • Throws ArgumentError for invalid integration controls.
source
LineCableModels.Engine.Λ — Function
Λ(formula, Val(:self), κ, r, h)
Λ(formula, Val(:mutual), κ, r, D, D′)

Return the circumferential mean of the direct and image fields of a source on a receiver in one medium:

\[\Lambda_{ii} = K_0(\kappa r) - I_0(\kappa r) K_0(2 \kappa h), \qquad \Lambda_{ij} = I_0(\kappa r) \left[K_0(\kappa D) - K_0(\kappa D')\right].\]

Arguments

  • formula: earth-return formula.
  • κ: transverse propagation parameter of the medium [1/m].
  • r: exterior radius of the receiver [m].
  • h: distance from the receiver to the interface [m].
  • D: distance from the center of the receiver to the source [m].
  • D′: distance from the center of the receiver to the image of the source [m].

Returns

  • The mean [dimensionless].

Notes

The earth-return family defines the method that each of its formulas gets. A formula with another direct and image term defines its own method.

source
LineCableModels.Commons.defaults — Method
defaults(
    _::Type{LineCableModels.Engine.EarthReturn.Formula{:martins2026}}
) -> @NamedTuple{integral::Pair{typeof(LineCableModels.Engine.integrate), Symbol}}

Return the declared options of the earth-return formula Formula{:martins2026}.

Arguments

  • Formula{:martins2026}: earth-return formula type.

Returns

  • integral: the default integration selection, integrate => :quad.
source
LineCableModels.Commons.validate — Method
validate(
    options::LineCableModels.Commons.FormulationOptions{LineCableModels.Engine.EarthReturn.Formula{:martins2026}}
) -> LineCableModels.Commons.FormulationOptions{LineCableModels.Engine.EarthReturn.Formula{:martins2026}}

Check the integration controls of the earth-return formula Formula{:martins2026}.

Arguments

  • options: formula options with an integration section.

Returns

  • options, unchanged.

Errors

  • Throws ArgumentError for a negative or nonfinite tolerance, two zero tolerances, or a nonpositive evaluation limit.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:martins2026}
) -> LineParametersProblem

Check that each outer cable circumference lies strictly within one medium. The circumference-current formula requires an outer radius smaller than the distance from the cable center to the interface.

Arguments

  • problem: cable geometry and earth model.
  • formula: earth-return formula Formula{:martins2026} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for a cable whose outer circumference touches or crosses the interface.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:gary1976}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:gary1976} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:wedepohl1973}
) -> LineParametersProblem

Warn once when the highest frequency of the scan leaves the bound of the paper on the buried cables. The bound reads the static resistivity and permeability of the deepest layer.

Arguments

  • problem: cable geometry, earth model and frequencies.
  • formula: earth-return formula Formula{:wedepohl1973} that consumes the problem.

Returns

  • problem, unchanged.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:saad1996}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:saad1996} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:lucca1994}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:lucca1994} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:ametani2009}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:ametani2009} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:carson1926}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:carson1926} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:pollaczek1926}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:pollaczek1926} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:wise1934}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:wise1934} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:wise1948}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:wise1948} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Commons.validate — Method
validate(
    problem::LineParametersProblem,
    formula::LineCableModels.Engine.EarthReturn.Formula{:xue2018}
) -> LineParametersProblem

Refuse a magnetic earth layer: the formula assumes the permeability of vacuum on both sides of the interface.

Arguments

  • problem: earth layers of the computation.
  • formula: earth-return formula Formula{:xue2018} that consumes the problem.

Returns

  • problem, unchanged.

Errors

  • Throws DomainError for an earth layer whose relative permeability differs from 1.
source
LineCableModels.Engine.initialize_buffers — Method
initialize_buffers(
    formula::LineCableModels.Engine.EarthReturn.Formula{:martins2026},
    input::LineCableModels.Engine.CoaxialInput{T, L} where L<:(AbstractArray{<:Material{T}, 1}),
    buffers
) -> Union{NamedTuple, DataStructures.SortedMultiDict}

Allocate cable matrices and state vectors under martins2026, then add the integral arrays for the selected quadrature method.

Arguments

  • formula: earth-return formula Formula{:martins2026} with integration controls.
  • input: numerical cable geometry.
  • buffers: computation arrays already allocated.

Returns

  • buffers extended with the martins2026 and integral blocks. to_buffer! fills the martins2026 arrays.
source
LineCableModels.Engine.to_buffer! — Method
to_buffer!(
    f::LineCableModels.Engine.EarthReturn.Formula{:martins2026},
    buffers,
    input::LineCableModels.Engine.CoaxialInput,
    media,
    s,
    k
) -> Any

Compute the earth-return impedances and potential coefficients of the cables at the frequency of index k by the formula Formula{:martins2026}, whose equations are in the section "Formulas" of EarthReturn. The longitudinal wavenumber is buffers.gamma[k]. The results and the shared state of the two quantities stay in buffers.martins2026, which the pair variants read.

Arguments

  • f: earth-return formula Formula{:martins2026} with integration controls.
  • buffers: computation arrays with gamma, integral, and martins2026.
  • input: cable centers and outer radii.
  • media: air and earth records with resistivity rho in [Ω·m] and relative eps_r, mu_r [dimensionless].
  • s: complex frequency, j 2π f, [1/s].
  • k: frequency index.

Returns

  • buffers, with martins2026.Zg [Ω/m], martins2026.Pg [m/F], and their shared state filled.

Errors

  • Throws DomainError for a nonfinite weighted earth kernel, a nonfinite integral, or a spectral path whose geometric weight grows.
source
LineCableModels.Engine.impedance! — Method
impedance!(
    formulation::CoaxialFormulation,
    Zg::AbstractMatrix,
    buffers,
    input::LineCableModels.Engine.CoaxialInput,
    media,
    s,
    k
) -> AbstractMatrix

Write into Zg the earth-return impedances of the cables, pair by pair, from the formula of each pair's domain in the slot earth_impedance. The recipe alone writes the matrix.

Arguments

  • formulation: coaxial formulation with its earth-return formulas.
  • Zg: destination matrix of cable impedances [Ω/m].
  • buffers: preallocated computation arrays.
  • input: numerical cable geometry and connections.
  • media: the air and the equivalent earth at the frequency.
  • s: complex frequency, j 2π f, in [1/s].
  • k: frequency index.

Returns

  • Zg, its entries in [Ω/m].
source
LineCableModels.Engine.potential! — Method
potential!(
    formulation::CoaxialFormulation,
    Pg::AbstractMatrix,
    buffers,
    input::LineCableModels.Engine.CoaxialInput,
    media,
    s,
    k
) -> AbstractMatrix

Write into Pg the earth-return potential coefficients of the cables, pair by pair, from the formula of each pair's domain in the slot earth_admittance. The recipe alone writes the matrix.

Arguments

  • formulation: coaxial formulation with its earth-return formulas.
  • Pg: destination matrix of cable potential coefficients [m/F].
  • buffers: preallocated computation arrays.
  • input: numerical cable geometry and connections.
  • media: the air and the equivalent earth at the frequency.
  • s: complex frequency, j 2π f, in [1/s].
  • k: frequency index.

Returns

  • Pg, its entries in [m/F].
source

Spectral integrals

LineCableModels.Engine.SpectralIntegral — Type
struct SpectralIntegral{F<:Function, C<:Number}

Represent the integral of an integrand over $[0, \infty)$ along a complex path. The integrand is a function of the spectral coordinate $\lambda$ and includes the weights of its formula. integrate applies the path's Jacobian.

  • integrand::Function: Complete integrand in the spectral coordinate λ of its formula, the path's Jacobian excluded.

  • ζ::Number: Path of the integral: λ equals ζ times t, for t ≥ 0 [1/m].

source
LineCableModels.Engine.integrate — Function
integrate(
    integral::LineCableModels.Engine.SpectralIntegral,
    _::Val{:quad},
    section::NamedTuple,
    buffers
) -> Tuple{Any, Any}

Evaluate an integral along its path by adaptive Gauss–Kronrod quadrature with QuadGK. Substitute $\lambda = \zeta u$ for $u \geq 0$ and transform $u$ into $t$:

\[\int_0^{\infty} g(\zeta u)\,\zeta\,\mathrm{d}u = \int_0^1 \zeta\, g\!\left(\frac{\zeta t}{1-t}\right)\frac{\mathrm{d}t}{(1-t)^2}.\]

Here $g$ is the integrand and $\zeta$ the path. Map each breakpoint $u_b$ to $t_b = u_b / (1 + u_b)$ in $[0, 1)$ and seed one segment between adjacent points. The error norm is the magnitude of the nominal value.

Arguments

  • integral: integrand and its path.
  • Val(:quad): adaptive quadrature method tag.
  • section: controls rtol, atol, and maxevals from defaults.
  • buffers: computation arrays. The points of the integral block are the breakpoints in the coordinate $u$, finite and nonnegative.

Returns

  • The integral value, in the unit of the integrand times its coordinate.
  • The estimated absolute error, in the unit of the integral value.

Notes

An estimated error above max(atol, rtol * abs(nominal(value))), or a nonfinite estimate, produces a warning. The method still returns the value.

Errors

  • Throws DomainError for a negative or nonfinite breakpoint, or a nonfinite integral value.
source
LineCableModels.Commons.defaults — Method
defaults(
    _::typeof(LineCableModels.Engine.integrate),
    _::Val{:quad}
) -> @NamedTuple{method::Symbol, rtol::Float64, atol::Float64, maxevals::Int64}

Return the declared controls of adaptive Gauss–Kronrod quadrature.

Arguments

  • integrate: integral evaluation function.
  • Val(:quad): adaptive quadrature method tag.

Returns

  • method: :quad.
  • rtol: relative tolerance, 1e-8.
  • atol: absolute tolerance in the unit of the integral, 0.0.
  • maxevals: evaluation limit, 10^7.
source
LineCableModels.Commons.validate — Method
validate(
    section::NamedTuple,
    _::typeof(LineCableModels.Engine.integrate),
    _::Val{:quad}
) -> NamedTuple

Check the quadrature controls before an integral evaluation.

Arguments

  • section: integration controls.
  • integrate: consumer of the controls.
  • Val(:quad): adaptive quadrature method tag.

Returns

  • section, unchanged.

Errors

  • Throws ArgumentError for a negative or nonfinite tolerance, two zero tolerances, or a nonpositive evaluation limit.
source
LineCableModels.Commons.select — Method
select(
    default::Pair{typeof(LineCableModels.Engine.integrate), Symbol},
    given::NamedTuple
) -> NamedTuple

Build an integration section from method defaults and supplied controls, then replace its method identifier with a Val tag.

Arguments

  • default: pair of integrate and the default method identifier.
  • given: supplied controls, with or without a method key.

Returns

  • A named tuple with the method keys and their declared value types.

Errors

  • Throws ArgumentError for an unknown method or an unknown control key.
source
LineCableModels.Engine.initialize_buffers — Method
initialize_buffers(
    _::Type{LineCableModels.Engine.SpectralIntegral},
    _::Val{:quad},
    _::Type{T},
    buffers
) -> Union{NamedTuple, DataStructures.SortedMultiDict}

Allocate the integral arrays. Coordinates use the type of the nominal value of T, and integrand values use Complex{T}.

Arguments

  • SpectralIntegral: integral type whose arrays the computation needs.
  • Val(:quad): adaptive quadrature method tag.
  • T: numerical type of the formula.
  • buffers: arrays already allocated.

Returns

  • buffers extended with the integral block. It holds breakpoint and scale vectors plus mapped points, QuadGK segment arrays, and a zero prototype.
source

Earth properties

LineCableModels.Engine.EarthProperties — Module
LineCableModels.Engine.EarthProperties

Compute the resistivity, relative permittivity, and relative permeability of the earth layers, and their equivalent earth.

A soil law reads the resistivity $\rho_\mathrm{low}$ [Ω·m] of a layer, its conductivity $\sigma_\mathrm{low} = 1 / \rho_\mathrm{low}$ [S/m] and the frequency $f$ [Hz]. It gives the resistivity $\rho(f)$ [Ω·m], which is $1 / \sigma(f)$ unless the law states otherwise, and the relative permittivity $\varepsilon_r(f)$ [dimensionless]. The described layer keeps the relative permeability and the thickness of layer. The constant $\varepsilon_0$ is ε₀.

Formulas

Formula{:constant}

Properties of an earth layer independent of the frequency $f$:

\[\rho(f) = \rho, \qquad \varepsilon_r(f) = \varepsilon_r, \qquad \mu_r(f) = \mu_r,\]

where $\rho$ is the resistivity of the layer [Ω·m], and $\varepsilon_r$ and $\mu_r$ are its relative permittivity and permeability [dimensionless].

Callable

formula(layer, f) returns layer, whose properties hold at every frequency.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:bottommost}

Equivalent earth of the layers below the air: the deepest described layer, the identity for one layer.

Callable

formula(layers, f) returns the last of layers.

  • layers: the layers below the air, as the law describes them at f.
  • f: frequency [Hz].

Formula{:alipio2014}

Causal soil law of Alipio and Visacro [25], with $\sigma_\mathrm{low} = 1000 / \rho_\mathrm{low}$ [mS/m] and $D = a \sigma_\mathrm{low}^{b}$:

\[\begin{aligned} \sigma(f) &= \sigma_\mathrm{low} \left[1 + D \left(f / 10^6\right)^\gamma\right], \\ \varepsilon_r(f) &= \varepsilon_\mathrm{high} + \tan\left(\frac{\pi \gamma}{2}\right) \frac{10^{-3} \sigma_\mathrm{low} D f^{\gamma - 1}}{2 \pi \varepsilon_0 10^{6 \gamma}}, \end{aligned}\]

and $\rho(f) = 1000 / \sigma(f)$. The options are exponent $\gamma$, epsilon_high $\varepsilon_\mathrm{high}$, scale $a$ and sigma_exponent $b$. A computation warns outside 100 Hz to 4 MHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:cigre2019}

Soil law of CIGRE Technical Brochure 781 [26]:

\[\begin{aligned} \varepsilon_r(f) &= \varepsilon_\mathrm{high} + a \sigma_\mathrm{low}^{b} f^{c}, \\ \sigma(f) &= \sigma_\mathrm{low} + d \sigma_\mathrm{low}^{b} f^{e}. \end{aligned}\]

The options are epsilon_high $\varepsilon_\mathrm{high}$, epsilon_scale $a$, epsilon_sigma_exponent $b$, epsilon_frequency_exponent $c$, sigma_scale $d$ and sigma_frequency_exponent $e$. A computation warns outside 100 Hz to 4 MHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:datsios2019}

Two-limit fit of Datsios and Mikropoulos for sandy soil [27], with $\sigma_\mathrm{low} = 10^4 / \rho_\mathrm{low}$ [μS/cm] at 42 Hz and the option epsilon_dry $\varepsilon_\mathrm{dry}$:

\[\begin{aligned} p &= 0.537 \sigma_\mathrm{low}^{0.16}, \\ \varepsilon_\mathrm{high} &= 1.24 \sigma_\mathrm{low}^{0.415} \varepsilon_\mathrm{dry}, \\ \varepsilon_{3k} &= 4 \sigma_\mathrm{low}^{0.463} (2.9 \varepsilon_\mathrm{dry} - 3.8), \\ \varepsilon_r(f) &= \varepsilon_\mathrm{high} + \left(\frac{3000}{\max(f, 3000)}\right)^p (\varepsilon_{3k} - \varepsilon_\mathrm{high}), \\ \sigma_\mathrm{high} &= \sigma_\mathrm{low} (1 + 0.65 \sigma_\mathrm{low}^{-0.57}), \\ \sigma(f) &= 10^{-6} \sigma_\mathrm{high} f + 42 \left[1 - 10^{-6} (f - 42)\right] \left(\frac{\sigma_\mathrm{low}}{42} - 10^{-6} \sigma_\mathrm{high}\right), \end{aligned}\]

and $\rho(f) = 10^4 / \sigma(f)$. A computation warns outside 42 Hz to 1 MHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:longmire1975}

Thirteen-term relaxation law of Longmire and Smith [28], with the corner frequency $f_c = (a \sigma_\mathrm{low})^{b}$ and $f_n = 10^{n - 1} f_c$:

\[\begin{aligned} \varepsilon_r(f) &= \varepsilon_\mathrm{high} + \sum_{n = 1}^{13} \frac{a_n}{1 + (f / f_n)^2}, \\ \sigma(f) &= \sigma_\mathrm{low} + 2 \pi f \varepsilon_0 \sum_{n = 1}^{13} \frac{a_n (f / f_n)}{1 + (f / f_n)^2}, \end{aligned}\]

where $a_n$ are the coefficients of the report. The options are epsilon_high $\varepsilon_\mathrm{high}$, corner_scale $a$ and corner_exponent $b$. A computation warns outside 5 Hz to 30 GHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:messier1985}

Square-root soil law of Messier [29]:

\[\begin{aligned} \varepsilon_r(f) &= \varepsilon_\mathrm{high} + \sqrt{\frac{\sigma_\mathrm{low} \varepsilon_\mathrm{high}}{\pi f \varepsilon_0}}, \\ \sigma(f) &= \sigma_\mathrm{low} + \sqrt{4 \pi f \sigma_\mathrm{low} \varepsilon_0 \varepsilon_\mathrm{high}}. \end{aligned}\]

The option is epsilon_high $\varepsilon_\mathrm{high}$. A computation warns outside 100 Hz to 1 MHz [29, 30].

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:portela1999}

Power-law soil dispersion of Portela [31], with $\omega = 2 \pi f$:

\[\begin{aligned} \sigma(f) &= \sigma_\mathrm{low} + 10^{-6} \beta \omega^\alpha, \\ \varepsilon_r(f) &= 10^{-6} \beta \tan\left(\frac{\pi \alpha}{2}\right) \frac{\omega^{\alpha - 1}}{\varepsilon_0}. \end{aligned}\]

The options are beta $\beta$ and exponent $\alpha$. A computation warns outside 100 Hz to 2 MHz [30, 31].

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:scott1967}

Empirical fit of Scott, Carroll and Cunningham for moist rock [32], with $u = \log_{10}(1000 / \rho_\mathrm{low})$ and $x = \log_{10} f$:

\[\begin{aligned} \log_{10} \varepsilon_r(f) &= 5.491 + 0.946 u - 1.097 x + 0.069 u^2 - 0.114 u x + 0.067 x^2, \\ \log_{10} \sigma(f) &= 0.028 + 1.098 u - 0.068 x + 0.036 u^2 - 0.046 u x + 0.018 x^2, \end{aligned}\]

and $\rho(f) = 1000 / \sigma(f)$, with $\sigma$ in [mS/m]. A computation warns outside 100 Hz to 1 MHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:visacro1987}

Empirical soil law of Visacro and Portela [33]:

\[\begin{aligned} \varepsilon_r(f) &= 2.34 \cdot 10^6 \sigma_\mathrm{low}^{0.535} f^{-0.597}, \\ \sigma(f) &= \sigma_\mathrm{low} \left(f / f_0\right)^{0.072}, \end{aligned}\]

where the option normalization_frequency is $f_0$ [Hz]. A computation warns outside 40 Hz to 2 MHz [33, 34].

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:visacro2012}

Empirical soil law of Visacro and Alipio [35], with $f_e = \max(f, f_0)$:

\[\begin{aligned} \varepsilon_r(f) &= 1.3 + 7.6 \cdot 10^3 f_e^{-0.4}, \\ \sigma(f) &= \sigma_\mathrm{low} + 1.2 \cdot 10^{-6} \sigma_\mathrm{low}^{0.27} (f_e - f_0)^{0.65}, \end{aligned}\]

where the option frequency_boundary is $f_0$ [Hz]. Below it, the law keeps its value at $f_0$. A computation warns outside 100 Hz to 4 MHz.

Callable

formula(layer, f) returns the layer that the law describes at f.

  • layer: earth layer.
  • f: frequency [Hz].

Formula{:martins2020}

Equivalent conductivity of Martins-Britto, Lopes and Rondineau [6]. From $\sigma_{\mathrm{eq},N} = \sigma_N$ at the deepest layer, the recursion climbs to the layer below the air, where $\sigma_\mathrm{eq} = \sigma_{\mathrm{eq},1}$:

\[\sigma_{\mathrm{eq},k} = \sigma_k \left[ \frac{\sqrt{\sigma_k} + \sqrt{\sigma_{\mathrm{eq},k+1}} - \left(\sqrt{\sigma_k} - \sqrt{\sigma_{\mathrm{eq},k+1}}\right) e^{-2 h_k \sqrt{\pi f \mu_k \sigma_k}}} {\sqrt{\sigma_k} + \sqrt{\sigma_{\mathrm{eq},k+1}} + \left(\sqrt{\sigma_k} - \sqrt{\sigma_{\mathrm{eq},k+1}}\right) e^{-2 h_k \sqrt{\pi f \mu_k \sigma_k}}} \right]^2,\]

where layer $k$ has the conductivity $\sigma_k = 1 / \rho_k$ [S/m], the thickness $h_k$ [m] and the permeability $\mu_k = \mu_0 \mu_{r,k}$ [H/m], and $\mu_0$ is μ₀. The layer it returns has the resistivity $1 / \sigma_\mathrm{eq}$ and takes the relative permittivity and the relative permeability of the deepest layer. The source validates the equivalent on overhead conductors from 1 Hz to 2 MHz.

Callable

formula(layers, f) returns one semi-infinite layer.

  • layers: the layers below the air, as the law describes them at f.
  • f: frequency [Hz].

Formula{:xue2021}

Equivalent propagation constant of Xue and coauthors for a nonmagnetic earth [7]. With $s = \mathrm{j} \omega$, $\omega = 2 \pi f$ and the constants $\varepsilon_0$ and $\mu_0$, layer $k$ of conductivity $\sigma_k$ [S/m], relative permittivity $\varepsilon_{r,k}$ and thickness $h_k$ [m] has the constant $\gamma_k$ [1/m] relative to the air. From $\gamma_{\mathrm{eq},N} = \gamma_N$ at the deepest layer, the recursion climbs to the layer below the air, where $\gamma_\mathrm{eq} = \gamma_{\mathrm{eq},1}$:

\[\begin{aligned} \gamma_k^2 &= s \mu_0 \left(\sigma_k + s \varepsilon_0 \varepsilon_{r,k}\right) - s^2 \mu_0 \varepsilon_0, \\ \gamma_{\mathrm{eq},k} &= \gamma_k \frac{\gamma_k + \gamma_{\mathrm{eq},k+1} - \left(\gamma_k - \gamma_{\mathrm{eq},k+1}\right) e^{-2 h_k \gamma_k}} {\gamma_k + \gamma_{\mathrm{eq},k+1} + \left(\gamma_k - \gamma_{\mathrm{eq},k+1}\right) e^{-2 h_k \gamma_k}}. \end{aligned}\]

The layer it returns parametrizes $\gamma_\mathrm{eq}^2$ by its resistivity $1 / \sigma_\mathrm{eq}$ and its relative permittivity:

\[\sigma_\mathrm{eq} = \frac{\Im\left(\gamma_\mathrm{eq}^2\right)}{\omega \mu_0}, \qquad \varepsilon_{r,\mathrm{eq}} = 1 - \frac{\Re\left(\gamma_\mathrm{eq}^2\right)}{\omega^2 \mu_0 \varepsilon_0}.\]

This $\varepsilon_{r,\mathrm{eq}}$ is negative where the layers are inductive. The layer takes the relative permeability of the deepest layer. A computation refuses an earth layer whose relative permeability differs from 1. The source reports errors below 4 % from 1 Hz to 5 MHz on overhead conductors.

Callable

formula(layers, f) returns one semi-infinite layer.

  • layers: the layers below the air, as the law describes them at f.
  • f: frequency [Hz].
source
LineCableModels.Engine.EarthProperties.Formula — Type
struct Formula{ID, O<:LineCableModels.Commons.FormulationOptions} <: LineCableModels.Engine.AbstractEarthProperties

Represent a law of the properties of an earth layer, or a model of the equivalent earth. Its options form a record of type FormulationOptions{Formula{ID}}, with ID the formula identifier.

  • options::LineCableModels.Commons.FormulationOptions: Options of the formula.
source
LineCableModels.Engine.EarthProperties.Formula — Method
Formula(
    ::Val{ID};
    kw...
) -> LineCableModels.Engine.EarthProperties.Formula

Build the formula named by ID with its declared defaults and supplied options.

Arguments

  • Val{ID}: formula identifier from FORMULAS.

Keywords

  • kw...: options declared by defaults for Formula{ID}.

Returns

  • A Formula with a typed option record.

Errors

  • Throws ArgumentError for an unknown identifier or option.
source

Back to Contents