Document EMT line parameter models

GridKit/Model/EMT/Parameters/Effects/Carson/README.md

@@ -0,0 +1,117 @@
+# Carson Model
+
+`Carson` computes frequency-dependent earth-return resistance and inductance
+matrices for overhead conductors using the Deri-Semlyen approximation to
+Carson's homogeneous-earth return term.
+
+## Model Parameters
+
+Symbol | Units | JSON | Description | Note
+------ | ----- | ---- | ----------- | ----
+`tower` | [-] | - | Static conductor tower | [`Tower`](../../Geometry/Tower/README.md)
+$\sigma_g$ | [S/m] | `earth_conductivity` | Earth conductivity | $\sigma_g\ge0$
+$\varepsilon_g$ | [F/m] | `earth_permittivity` | Earth permittivity | $\varepsilon_g\ge\varepsilon_0$
+$\mu_0$ | [H/m] | - | Vacuum permeability | constant
+$\varepsilon_0$ | [F/m] | - | Vacuum permittivity | constant
+
+### Parameter Validation
+
+```math
+\sigma_g\ge0,\qquad
+\varepsilon_g\ge\varepsilon_0,\qquad
+\omega > 0,\qquad
+(\gamma_g^{\mathrm r})^2+(\gamma_g^{\mathrm i})^2 > 0
+```
+
+The connected tower model owns its geometry validation.
+
+### Model Derived Parameters
+
+For conductor pair $(i,j)$,
+
+```math
+\begin{aligned}
+d_{ij} &= |x_i-x_j| \\
+s_{ij} &= h_i+h_j \\
+\Delta_g &= (\gamma_g^{\mathrm r})^2+(\gamma_g^{\mathrm i})^2 \\
+p^{\mathrm r} &= \frac{\gamma_g^{\mathrm r}}{\Delta_g} \\
+p^{\mathrm i} &= -\frac{\gamma_g^{\mathrm i}}{\Delta_g} \\
+H_{ij}^{\mathrm r} &= s_{ij}+2p^{\mathrm r} \\
+H_{ij}^{\mathrm i} &= 2p^{\mathrm i} \\
+A_{ij} &= d_{ij}^2+(H_{ij}^{\mathrm r})^2-(H_{ij}^{\mathrm i})^2 \\
+B_{ij} &= 2H_{ij}^{\mathrm r}H_{ij}^{\mathrm i} \\
+M_{ij} &= A_{ij}^2+B_{ij}^2 \\
+\theta_{ij} &= \operatorname{atan2}(B_{ij},A_{ij}) \\
+\Lambda_{ij} &= \frac{1}{4}\ln M_{ij}-\ln D'_{ij}
+\end{aligned}
+```
+
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\eta_g$ | [1/m$^2$] | Magnitude of earth-return propagation radicand | real
+$\gamma_g^{\mathrm r}$ | [1/m] | Real earth-return propagation constant component | real
+$\gamma_g^{\mathrm i}$ | [1/m] | Imaginary earth-return propagation constant component | real
+$\mathbf{R}^{\mathrm{carson}}$ | [$\Omega$/m] | Carson earth-return resistance | $\mathbb{R}^{K\times K}$
+$\mathbf{L}^{\mathrm{carson}}$ | [H/m] | Carson earth-return inductance | $\mathbb{R}^{K\times K}$
+
+### External Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+None.
+
+## Model Equations
+
+### Differential Equations
+
+None.
+
+### Algebraic Equations
+
+```math
+\begin{aligned}
+0 &= -\eta_g^2
+  + (\omega^2\mu_0\varepsilon_g)^2
+  + (\omega\mu_0\sigma_g)^2 \\
+0 &= -2(\gamma_g^{\mathrm r})^2
+  + \eta_g - \omega^2\mu_0\varepsilon_g \\
+0 &= -2(\gamma_g^{\mathrm i})^2
+  + \eta_g + \omega^2\mu_0\varepsilon_g \\
+0 &= -4\pi R_{ij}^{\mathrm{carson}}
+  - \omega\mu_0\theta_{ij} \\
+0 &= -2\pi L_{ij}^{\mathrm{carson}}
+  + \mu_0\Lambda_{ij}
+\end{aligned}
+```
+
+## Initialization
+
+Initialize $\eta_g$, $\gamma_g^{\mathrm r}$, $\gamma_g^{\mathrm i}$,
+$\mathbf{R}^{\mathrm{carson}}$, and $\mathbf{L}^{\mathrm{carson}}$ from the
+algebraic equations at the current $\omega$.
+
+## Model Outputs
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\sigma_g$ | [S/m] | Earth conductivity | real
+$\varepsilon_g$ | [F/m] | Earth permittivity | real
+$\eta_g$ | [1/m$^2$] | Magnitude of earth-return propagation radicand | real
+$\gamma_g^{\mathrm r}$ | [1/m] | Real earth-return propagation constant component | real
+$\gamma_g^{\mathrm i}$ | [1/m] | Imaginary earth-return propagation constant component | real
+$\mathbf{R}^{\mathrm{carson}}$ | [$\Omega$/m] | Carson earth-return resistance | $\mathbb{R}^{K\times K}$
+$\mathbf{L}^{\mathrm{carson}}$ | [H/m] | Carson earth-return inductance | $\mathbb{R}^{K\times K}$

GridKit/Model/EMT/Parameters/Effects/GeometricInductance/README.md

@@ -0,0 +1,78 @@
+# GeometricInductance Model
+
+`GeometricInductance` computes the external geometric series inductance matrix
+for the physical conductors.
+
+## Model Parameters
+
+For $K$ physical conductors:
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+`tower` | [-] | Static conductor tower | [`Tower`](../../Geometry/Tower/README.md)
+`conductor` | [-] | Static conductor data | [`Conductor`](../../Geometry/Conductor/README.md)
+$\mu_0$ | [H/m] | Vacuum permeability | constant
+
+### Parameter Validation
+
+The tower and conductor models must pass their own validation.
+
+### Model Derived Parameters
+
+The tower model provides $h_i$, $D_{ij}$, and $D'_{ij}$. The conductor model
+provides $r_i$.
+
+```math
+\left(\boldsymbol{\Lambda}^{\mathrm{geo}}\right)_{ij} =
+\begin{cases}
+\ln\dfrac{2h_i}{r_i}, & i=j \\
+\ln\dfrac{D'_{ij}}{D_{ij}}, & i\ne j
+\end{cases}
+```
+
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\mathbf{L}^{\mathrm{geo}}$ | [H/m] | External geometric inductance | $\mathbb{R}^{K\times K}$
+
+### External Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+None.
+
+## Model Equations
+
+### Differential Equations
+
+None.
+
+### Algebraic Equations
+
+```math
+\mathbf{0} = -2\pi\mathbf{L}^{\mathrm{geo}}
+  + \mu_0 \boldsymbol{\Lambda}^{\mathrm{geo}}
+```
+
+## Initialization
+
+None beyond the static tower and conductor initialization.
+
+## Model Outputs
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\mathbf{L}^{\mathrm{geo}}$ | [H/m] | External geometric inductance | $\mathbb{R}^{K\times K}$

GridKit/Model/EMT/Parameters/Effects/InsulatorLeakage/README.md

@@ -0,0 +1,71 @@
+# InsulatorLeakage Model
+
+`InsulatorLeakage` computes an empirical direct shunt conductance effect for
+the physical conductors.
+
+## Model Parameters
+
+For $K$ physical conductors:
+
+Symbol | Units | JSON | Description | Note
+------ | ----- | ---- | ----------- | ----
+$g_i^{\mathrm{leak}}$ | [S/m] | `leakage_conductance` | Insulator leakage conductance to ground | $g_i^{\mathrm{leak}}\ge0$
+
+### Parameter Validation
+
+```math
+g_i^{\mathrm{leak}}\ge0,\qquad i=1,\dots,K
+```
+
+### Model Derived Parameters
+
+For a vector $\mathbf a\in\mathbb{R}^K$, let
+$\operatorname{diag}(\mathbf a)$ denote the diagonal matrix with $\mathbf a$ on
+the main diagonal.
+
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\mathbf{G}^{\mathrm{leak}}$ | [S/m] | Insulator leakage shunt conductance | diagonal
+
+### External Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+None.
+
+## Model Equations
+
+### Differential Equations
+
+None.
+
+### Algebraic Equations
+
+```math
+\mathbf{0} = -\mathbf{G}^{\mathrm{leak}}
+  + \operatorname{diag}(\mathbf{g}^{\mathrm{leak}})
+```
+
+## Initialization
+
+Validate the leakage conductance vector.
+
+## Model Outputs
+
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\mathbf{G}^{\mathrm{leak}}$ | [S/m] | Insulator leakage shunt conductance | $\mathbb{R}^{K\times K}$

GridKit/Model/EMT/Parameters/Effects/README.md

@@ -0,0 +1,37 @@
+# Effect Models
+
+`Effects` contains the physical effect models that assemble full-conductor
+per-unit-length overhead-line data:
+
+```math
+\mathbf{R}'(\omega),\quad \mathbf{L}'(\omega),\quad
+\mathbf{G}'(\omega),\quad \mathbf{C}'(\omega)
+```
+
+These models are frequency-domain parameter models, not EMT network components.
+They consume geometry, conductor, and earth data and produce algebraic signals
+for the response models. They are evaluated at the current system parameter
+$\omega$; sweep endpoints, sampling, and linear or logarithmic grids belong to
+the application or study driver.
+
+Model | Description
+----- | -----------
+[`SeriesImpedance`](SeriesImpedance/README.md) | Builds full-conductor per-unit-length series resistance and inductance
+[`GeometricInductance`](GeometricInductance/README.md) | Computes external geometric inductance entries
+[`SkinEffect`](SkinEffect/README.md) | Computes conductor-internal skin-effect resistance and inductance entries
+[`ShuntAdmittance`](ShuntAdmittance/README.md) | Builds full-conductor per-unit-length shunt conductance and capacitance
+[`ShuntPotential`](ShuntPotential/README.md) | Computes potential-derived zero conductance and capacitance
+[`InsulatorLeakage`](InsulatorLeakage/README.md) | Computes direct shunt leakage conductance
+[`Carson`](Carson/README.md) | Computes Carson earth-return resistance and inductance entries
+
+## Assembly
+
+Output | Built From
+------ | ----------
+$\mathbf{R}'$ | Internal skin-effect resistance and Carson earth-return resistance
+$\mathbf{L}'$ | Internal skin-effect inductance, geometric inductance, and Carson earth-return inductance
+$\mathbf{G}'$ | Shunt potential terms and optional direct leakage terms
+$\mathbf{C}'$ | Shunt potential terms
+
+The aggregate [`Overhead`](../README.md#overhead-aggregate) model wires these
+effect outputs into the response models.