Skip to main content

powerio_dist/
overhead.rs

1//! Overhead line conductor equations shared by the OpenDSS and GridLAB-D
2//! geometry readers: the simplified Carson earth return impedance and
3//! Maxwell's potential coefficients.
4
5use num_complex::Complex64;
6
7/// The earth return of the simplified Carson equations, in the unit system
8/// the caller works in (ohms per unit length and the length unit of its
9/// distances).
10#[derive(Clone, Copy, Debug, PartialEq)]
11#[non_exhaustive]
12pub struct CarsonEarth {
13    /// `ω μ₀ / 8`, the earth return resistance per unit length.
14    pub resistance: f64,
15    /// `ω μ₀ / 2π`, the reactance per unit length per neper of distance.
16    pub reactance: f64,
17    /// `ln D_e`, the natural log of the equivalent earth return depth
18    /// (`658.5 √(ρ / f)` metres), in the caller's distance unit.
19    pub log_depth: f64,
20}
21
22impl CarsonEarth {
23    /// The earth return from its three coefficients.
24    #[must_use]
25    pub const fn new(resistance: f64, reactance: f64, log_depth: f64) -> Self {
26        Self {
27            resistance,
28            reactance,
29            log_depth,
30        }
31    }
32}
33
34/// How [`calc_earth_return_log_depth`] spells the equivalent earth return
35/// depth. The forms are the same depth in different length units and
36/// roundings.
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38#[non_exhaustive]
39pub enum EarthDepthForm {
40    /// OpenDSS, metres: `ln(658.5 √(ρ / f))` (`Line.pas` and the line
41    /// geometry's Carson earth).
42    OpenDss,
43    /// GridLAB-D, feet: `ln(ρ / f) / 2 + 7.6786`, its rounding of
44    /// `ln(2160 √(ρ / f))` (`overhead_line_conductor`'s Carson terms).
45    GridLabD,
46}
47
48/// `ln D_e` of the equivalent earth return depth `D_e = 658.5 √(ρ / f)`
49/// metres (`2160 √(ρ / f)` feet), for an earth resistivity `rho` in ohm
50/// metres and a frequency in hertz, spelled as `form` states. The one earth
51/// return depth: the OpenDSS geometry's [`CarsonEarth::log_depth`], the
52/// OpenDSS line's earth return reactance coefficient `Kxg = Xg / ln D_e`
53/// and the GridLAB-D Carson earth read it.
54#[must_use]
55pub fn calc_earth_return_log_depth(rho: f64, frequency: f64, form: EarthDepthForm) -> f64 {
56    match form {
57        EarthDepthForm::OpenDss => (658.5 * (rho / frequency).sqrt()).ln(),
58        EarthDepthForm::GridLabD => (rho / frequency).ln() / 2.0 + 7.6786,
59    }
60}
61
62/// The simplified Carson impedance of a conductor pair with earth return,
63/// per unit length, without the conductor's own internal impedance:
64///
65/// ```text
66/// z = ω μ₀ / 8 + j (ω μ₀ / 2π · ln(1 / D) + ω μ₀ / 2π · ln D_e)
67/// ```
68///
69/// with `D` the pair's distance, or a conductor's geometric mean radius for
70/// its self term. The one simplified Carson equation: the OpenDSS geometry
71/// (`EarthModel::Carson`, SI units) and the GridLAB-D overhead configuration
72/// (feet and miles, its own rounded coefficients) read it.
73#[must_use]
74pub fn calc_carson_impedance(distance: f64, earth: CarsonEarth) -> Complex64 {
75    Complex64::new(
76        earth.resistance,
77        calc_conductor_loop_reactance(earth.reactance, distance)
78            + earth.reactance * earth.log_depth,
79    )
80}
81
82/// The free space term of a conductor pair's loop reactance, `ω μ₀ / 2π ·
83/// ln(1 / D)` per unit length, for `reactance` the coefficient `ω μ₀ / 2π`
84/// ([`CarsonEarth::reactance`]) and `distance` the pair's distance (or a
85/// conductor's geometric mean radius). The one free space loop term:
86/// [`calc_carson_impedance`] and the OpenDSS geometry's Deri and full
87/// Carson earth models add their earth correction to it.
88#[must_use]
89pub fn calc_conductor_loop_reactance(reactance: f64, distance: f64) -> f64 {
90    reactance * (1.0 / distance).ln()
91}
92
93/// Maxwell's potential coefficient between two conductors (without the
94/// `1 / 2πε` factor): `ln(S / D)`, with `S` the distance to the other
95/// conductor's earth image and `D` the direct distance. A conductor's self
96/// coefficient takes `S = 2h` and `D` its radius. The one potential
97/// coefficient: the OpenDSS and GridLAB-D geometry capacitances read it.
98#[must_use]
99pub fn calc_potential_coefficient(image_distance: f64, distance: f64) -> f64 {
100    (image_distance / distance).ln()
101}