diff --git a/GridKit/Model/EMT/Parameters/Effects/Carson/README.md b/GridKit/Model/EMT/Parameters/Effects/Carson/README.md new file mode 100644 index 000000000..51b828f00 --- /dev/null +++ b/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}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/GeometricInductance/README.md b/GridKit/Model/EMT/Parameters/Effects/GeometricInductance/README.md new file mode 100644 index 000000000..8a93b1647 --- /dev/null +++ b/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}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/InsulatorLeakage/README.md b/GridKit/Model/EMT/Parameters/Effects/InsulatorLeakage/README.md new file mode 100644 index 000000000..31446451a --- /dev/null +++ b/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}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/README.md b/GridKit/Model/EMT/Parameters/Effects/README.md new file mode 100644 index 000000000..04fbe9446 --- /dev/null +++ b/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. diff --git a/GridKit/Model/EMT/Parameters/Effects/SeriesImpedance/README.md b/GridKit/Model/EMT/Parameters/Effects/SeriesImpedance/README.md new file mode 100644 index 000000000..85873fe65 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Effects/SeriesImpedance/README.md @@ -0,0 +1,93 @@ +# SeriesImpedance Model + +`SeriesImpedance` builds the full-conductor per-unit-length series resistance +and inductance matrices for one angular frequency. + +## Model Parameters + +None. `SeriesImpedance` combines effect-model outputs for $K$ physical +conductors. + +### Parameter Validation + +None. + +### 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{R}^{\mathrm{int}}$ | [$\Omega$/m] | Internal conductor resistance | diagonal +$\mathbf{L}^{\mathrm{int}}$ | [H/m] | Internal conductor inductance | diagonal +$\mathbf{R}^{\mathrm{ext}}$ | [$\Omega$/m] | External series resistance | full matrix +$\mathbf{L}^{\mathrm{ext}}$ | [H/m] | External series inductance | full matrix +$\mathbf{R}'$ | [$\Omega$/m] | Full-conductor series resistance | $\mathbb{R}^{K\times K}$ +$\mathbf{L}'$ | [H/m] | Full-conductor series inductance | $\mathbb{R}^{K\times K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{r}^{\mathrm{skin}}$ | [$\Omega$/m] | Internal conductor resistance vector | from connected `SkinEffect` models +$\mathbf{l}^{\mathrm{skin}}$ | [H/m] | Internal conductor inductance vector | from connected `SkinEffect` models +$\mathbf{L}^{\mathrm{geo}}$ | [H/m] | External geometric inductance | from connected `GeometricInductance` model +$\mathbf{R}^{\mathrm{carson}}$ | [$\Omega$/m] | Carson earth-return resistance | from connected `Carson` models +$\mathbf{L}^{\mathrm{carson}}$ | [H/m] | Carson earth-return inductance | from connected `Carson` models + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -\mathbf{R}^{\mathrm{int}} + + \operatorname{diag}(\mathbf{r}^{\mathrm{skin}}) \\ +\mathbf{0} &= -\mathbf{L}^{\mathrm{int}} + + \operatorname{diag}(\mathbf{l}^{\mathrm{skin}}) \\ +\mathbf{0} &= -\mathbf{R}^{\mathrm{ext}} + + \mathbf{R}^{\mathrm{carson}} \\ +\mathbf{0} &= -\mathbf{L}^{\mathrm{ext}} + + \mathbf{L}^{\mathrm{geo}} + + \mathbf{L}^{\mathrm{carson}} \\ +\mathbf{0} &= -\mathbf{R}' + + \mathbf{R}^{\mathrm{int}} + + \mathbf{R}^{\mathrm{ext}} \\ +\mathbf{0} &= -\mathbf{L}' + + \mathbf{L}^{\mathrm{int}} + + \mathbf{L}^{\mathrm{ext}} +\end{aligned} +``` + +## Initialization + +None. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}'$ | [$\Omega$/m] | Full-conductor series resistance | $\mathbb{R}^{K\times K}$ +$\mathbf{L}'$ | [H/m] | Full-conductor series inductance | $\mathbb{R}^{K\times K}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/ShuntAdmittance/README.md b/GridKit/Model/EMT/Parameters/Effects/ShuntAdmittance/README.md new file mode 100644 index 000000000..0d06b70eb --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Effects/ShuntAdmittance/README.md @@ -0,0 +1,91 @@ +# ShuntAdmittance Model + +`ShuntAdmittance` builds the full-conductor per-unit-length shunt conductance +and capacitance matrices from connected shunt-effect outputs. Potential-derived +conductance is zero; direct shunt losses are represented explicitly and set to +zero until a leakage model is wired. + +## Model Parameters + +None. `ShuntAdmittance` combines effect-model outputs for $K$ physical +conductors. + +### Parameter Validation + +None. + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}^{\mathrm{ext}}$ | [S/m] | Direct shunt conductance effects | $\mathbb{R}^{K\times K}$ +$\mathbf{C}^{\mathrm{ext}}$ | [F/m] | Direct shunt capacitance effects | $\mathbb{R}^{K\times K}$ +$\mathbf{G}'$ | [S/m] | Full-conductor shunt conductance | $\mathbb{R}^{K\times K}$ +$\mathbf{C}'$ | [F/m] | Full-conductor shunt capacitance | $\mathbb{R}^{K\times K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}^{\mathrm{pot}}$ | [S/m] | Potential-derived shunt conductance | zero matrix from connected `ShuntPotential` model +$\mathbf{C}^{\mathrm{pot}}$ | [F/m] | Potential-derived shunt capacitance | from connected `ShuntPotential` model + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -\mathbf{G}^{\mathrm{ext}} \\ +\mathbf{0} &= -\mathbf{C}^{\mathrm{ext}} \\ +\mathbf{0} &= -\mathbf{G}' + + \mathbf{G}^{\mathrm{pot}} + + \mathbf{G}^{\mathrm{ext}} \\ +\mathbf{0} &= -\mathbf{C}' + + \mathbf{C}^{\mathrm{pot}} + + \mathbf{C}^{\mathrm{ext}} +\end{aligned} +``` + +## Initialization + +The direct shunt-effect terms are initialized to zero. The assembled matrices +are initialized from the connected `ShuntPotential` output: + +```math +\begin{aligned} +\mathbf{G}^{\mathrm{ext}} &= \mathbf{0} \\ +\mathbf{C}^{\mathrm{ext}} &= \mathbf{0} \\ +\mathbf{G}' &= \mathbf{G}^{\mathrm{pot}} \\ +\mathbf{C}' &= \mathbf{C}^{\mathrm{pot}} +\end{aligned} +``` + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}'$ | [S/m] | Full-conductor shunt conductance | $\mathbb{R}^{K\times K}$ +$\mathbf{C}'$ | [F/m] | Full-conductor shunt capacitance | $\mathbb{R}^{K\times K}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/ShuntPotential/README.md b/GridKit/Model/EMT/Parameters/Effects/ShuntPotential/README.md new file mode 100644 index 000000000..da5bda389 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Effects/ShuntPotential/README.md @@ -0,0 +1,92 @@ +# ShuntPotential Model + +`ShuntPotential` computes the real overhead-line potential-coefficient matrix +and the corresponding full-conductor shunt capacitance. The potential-derived +conductance is set to zero; direct shunt losses are added by separate passive +shunt models. + +TODO: high frequnecy earth return correction + +## 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) +$\varepsilon_0$ | [F/m] | Vacuum permittivity | 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 +\Lambda^{\mathrm{pot}}_{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{P}$ | [m/F] | Potential-coefficient matrix | $\mathbb{R}^{K\times K}$ +$\mathbf{G}^{\mathrm{pot}}$ | [S/m] | Potential-derived shunt conductance | zero matrix +$\mathbf{C}^{\mathrm{pot}}$ | [F/m] | Potential-derived shunt capacitance | $\mathbb{R}^{K\times K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -2\pi\varepsilon_0\mathbf{P} + + \boldsymbol{\Lambda}^{\mathrm{pot}} \\ +\mathbf{0} &= -\mathbf{G}^{\mathrm{pot}} \\ +\mathbf{0} &= \mathbf{P}\mathbf{C}^{\mathrm{pot}} + - \mathbf{I}_{K} +\end{aligned} +``` + +## Initialization + +Initialize $\mathbf{P}$ from the log-distance terms, set +$\mathbf{G}^{\mathrm{pot}}=\mathbf{0}$, and solve +$\mathbf{P}\mathbf{C}^{\mathrm{pot}}=\mathbf{I}_{K}$. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}^{\mathrm{pot}}$ | [S/m] | Potential-derived shunt conductance | zero matrix +$\mathbf{C}^{\mathrm{pot}}$ | [F/m] | Potential-derived shunt capacitance | $\mathbb{R}^{K\times K}$ diff --git a/GridKit/Model/EMT/Parameters/Effects/SkinEffect/README.md b/GridKit/Model/EMT/Parameters/Effects/SkinEffect/README.md new file mode 100644 index 000000000..7d4b6b6f9 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Effects/SkinEffect/README.md @@ -0,0 +1,122 @@ +# SkinEffect Model + +`SkinEffect` computes frequency-dependent internal resistance and inductance +vectors for overhead conductors using the simplified skin-effect formulation of +Monteiro et al. [1]. + +## Model Parameters + +For $K$ physical conductors: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$r_i$ | [m] | `radius` | Outer radius | from [`Conductor`](../../Geometry/Conductor/README.md) +$\sigma_i$ | [S/m] | `conductivity` | Conductivity | from [`Conductor`](../../Geometry/Conductor/README.md) +$\mu_i$ | [H/m] | `permeability` | Permeability | from [`Conductor`](../../Geometry/Conductor/README.md) + +### Parameter Validation + +The connected conductor model owns vector validation. This model requires + +```math +\omega>0 . +``` + +The formulation uses the solid cylindrical-conductor approximation in [1]. + +### Model Derived Parameters + +The number of retained root terms is fixed by the model: + +```math +N_s=8 . +``` + +For conductor $i$ and retained root $k=1,\dots,N_s$, + +```math +\begin{aligned} +\xi_k &= \left(k-\frac{1}{4}\right)\pi \\ +R_{ik}^{\mathrm{br}} &= + \frac{\xi_k^2}{4\pi\sigma_i r_i^2} \\ +L_i^{\mathrm{br}} &= + \frac{\mu_i}{4\pi} +\end{aligned} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{Q}$ | [$(\Omega/\mathrm{m})^2$] | Branch denominator | $\mathbb{R}^{K\times N_s}$ +$\mathbf{G}$ | [m/$\Omega$] | Real internal-admittance sum | $\mathbb{R}^{K}$ +$\mathbf{H}$ | [s m/$\Omega$] | Inductive internal-admittance sum | $\mathbb{R}^{K}$ +$\mathbf{W}$ | [$(\mathrm{m}/\Omega)^2$] | Internal-impedance denominator | $\mathbb{R}^{K}$ +$\mathbf{r}^{\mathrm{skin}}$ | [$\Omega$/m] | Internal conductor resistance | $\mathbb{R}^{K}$ +$\mathbf{l}^{\mathrm{skin}}$ | [H/m] | Internal conductor inductance | $\mathbb{R}^{K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +0 &= -Q_{ik} + + (R_{ik}^{\mathrm{br}})^2 + + \omega^2(L_i^{\mathrm{br}})^2 \\ +0 &= -G_i + + \sum_{k=1}^{N_s} + \frac{R_{ik}^{\mathrm{br}}}{Q_{ik}} \\ +0 &= -H_i + + \sum_{k=1}^{N_s} + \frac{L_i^{\mathrm{br}}}{Q_{ik}} \\ +0 &= -W_i + + G_i^2 + + \omega^2H_i^2 \\ +0 &= -W_i r_i^{\mathrm{skin}} + + G_i \\ +0 &= -W_i l_i^{\mathrm{skin}} + + H_i +\end{aligned} +``` + +## Initialization + +Initialize all algebraic variables from the algebraic equations at the current +$\omega$. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{r}^{\mathrm{skin}}$ | [$\Omega$/m] | Internal conductor resistance | $\mathbb{R}^{K}$ +$\mathbf{l}^{\mathrm{skin}}$ | [H/m] | Internal conductor inductance | $\mathbb{R}^{K}$ + +## References + +[1] J. H. A. Monteiro, E. C. M. Costa, A. J. G. Pinto, S. Kurokawa, +O. M. O. Gatous, and J. Pissolato, "Simplified skin-effect formulation +for power transmission lines," IET Science, Measurement & Technology, +vol. 8, no. 2, pp. 47-53, 2014. doi:10.1049/iet-smt.2013.0072. diff --git a/GridKit/Model/EMT/Parameters/Geometry/Conductor/README.md b/GridKit/Model/EMT/Parameters/Geometry/Conductor/README.md new file mode 100644 index 000000000..74abcc6c0 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Geometry/Conductor/README.md @@ -0,0 +1,91 @@ +# Conductor Model + +`Conductor` stores conductor dimensions, material properties, weight, and phase +labels for the physical conductors in an overhead line. + +

+ +

+ +## Model Parameters + +For $K$ physical conductors: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$r_i$ | [m] | `radius` | Outer radius | $r_i>0$ +$q_i$ | [m] | `inner_radius` | Inner radius | $0\le q_i0$ +$\mu_i$ | [H/m] | `permeability` | Permeability | $\mu_i>0$ +$w_i$ | [N/m] | `weight` | Conductor weight per unit length | $w_i>0$ +$\phi_i$ | [-] | `phase` | Conductor phase label | optional; one of `a`, `b`, `c`, `n`, or `g` + +### Parameter Validation + +```math +r_i>q_i\ge0,\qquad +\sigma_i>0,\qquad +\mu_i>0,\qquad +w_i>0,\qquad +i=1,\dots,K +``` + +The conductor vectors use the same conductor order as the other +conductor-indexed parameter models. +If supplied, phase labels use the same conductor order. Each phase label +$\phi_i$ is one of `a`, `b`, `c`, `n`, or `g`, where `g` marks a grounded +conductor. + +### Model Derived Parameters + +None. + +## Model Variables + +`Conductor` is a static data model. + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +## Initialization + +Validate the conductor dimension, material, weight, and optional phase-label +vectors. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{r}$ | [m] | Outer-radius vector | $\mathbb{R}^{K}$ +$\mathbf{q}$ | [m] | Inner-radius vector | $\mathbb{R}^{K}$ +$\boldsymbol{\sigma}$ | [S/m] | Conductor conductivity vector | $\mathbb{R}^{K}$ +$\boldsymbol{\mu}$ | [H/m] | Conductor permeability vector | $\mathbb{R}^{K}$ +$\mathbf{w}$ | [N/m] | Conductor weight per-unit-length vector | $\mathbb{R}^{K}$ +$\boldsymbol{\phi}$ | [-] | Phase-label vector | optional; entries in `a`, `b`, `c`, `n`, or `g` diff --git a/GridKit/Model/EMT/Parameters/Geometry/Path/README.md b/GridKit/Model/EMT/Parameters/Geometry/Path/README.md new file mode 100644 index 000000000..28df9ed8a --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Geometry/Path/README.md @@ -0,0 +1,122 @@ +# Path Model + +`Path` computes the path length $\ell$ used by finite-line response models from +an explicit length or an ordered GIS route. + +

+ +

+ +## Model Parameters + +For GIS points $n=1,\dots,N_p$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\ell^{\mathrm{in}}$ | [m] | `length` | Explicit path length | optional; overrides GIS-derived length +$\Phi_n$ | [deg] | `path[*].latitude` | Latitude of point $n$ | +$\Lambda_n$ | [deg] | `path[*].longitude` | Longitude of point $n$ | +`tower` | [-] | - | Sagged-to-span ratio | from [`Tower`](../Tower/README.md) + +The GIS path intervals are not tower spans. GIS points define a long-route +centerline; `Tower` supplies the sagged-to-span ratio. + +### Parameter Validation + +When supplied: + +```math +\ell^{\mathrm{in}}>0 +``` + +When GIS path data is supplied: + +```math +N_p\ge2,\qquad +-90\le\Phi_n\le90,\qquad +-180\le\Lambda_n\le180 +``` + +If `length` is not supplied, the GIS route length and sagged-to-span ratio must +give $\ell>0$. + +### Model Derived Parameters + +For fixed mean earth radius + +```math +R_\oplus = 6371008.8\ \mathrm{m} +``` + +If `length` is supplied, + +```math +\ell=\ell^{\mathrm{in}} +``` + +Otherwise, for GIS intervals $n=1,\dots,N_p-1$: + +```math +\begin{aligned} +\phi_n &= \frac{\pi}{180}\Phi_n \\ +\lambda_n &= \frac{\pi}{180}\Lambda_n \\ +\Delta\phi_n &= \phi_{n+1}-\phi_n \\ +\Delta\lambda_n &= \lambda_{n+1}-\lambda_n \\ +a_n &= \sin^2\left(\frac{\Delta\phi_n}{2}\right) + + \cos\phi_n\cos\phi_{n+1} + \sin^2\left(\frac{\Delta\lambda_n}{2}\right) \\ +c_n &= 2\operatorname{atan2}\left(\sqrt{a_n},\sqrt{1-a_n}\right) \\ +s_n &= R_\oplus c_n \\ +S_{\mathrm{path}} &= \sum_{n=1}^{N_p-1} s_n +\end{aligned} +``` + +With sagged-to-span ratio from `Tower`, + +```math +\ell=\rho_{\mathrm{sag}}S_{\mathrm{path}} +``` + +## Model Variables + +`Path` is a static data model. + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +## Initialization + +Compute the path length from the explicit length or the GIS route. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\ell$ | [m] | Path length | scalar diff --git a/GridKit/Model/EMT/Parameters/Geometry/README.md b/GridKit/Model/EMT/Parameters/Geometry/README.md new file mode 100644 index 000000000..f6a5c9114 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Geometry/README.md @@ -0,0 +1,33 @@ +# Geometry Models + +`Geometry` contains static parameter models that describe the line layout and +conductor data used by overhead-line calculations. + +These models do not own EMT network ports. They provide static inputs or +derived geometry quantities to the effect and response models. + +Model | Description +----- | ----------- +[`Path`](Path/README.md) | Computes path length for finite-line response models +[`Tower`](Tower/README.md) | Stores conductor attachment coordinates and span-scale geometry +[`Conductor`](Conductor/README.md) | Stores conductor dimensions, material properties, weight, and phase labels + +## Shared Inputs + +Quantity | Description +-------- | ----------- +`tower.x` | Horizontal conductor attachment coordinates +`tower.height` | Conductor attachment heights above earth +`tower.span` | Support-to-support span length +`tower.tension` | Optional span tension parameter +`conductors[*].radius` | Outer conductor radius +`conductors[*].inner_radius` | Inner conductor radius +`conductors[*].conductivity` | Conductor conductivity +`conductors[*].permeability` | Conductor permeability +`conductors[*].weight` | Conductor weight per unit length +`conductors[*].phase` | Conductor phase label +`length`, `path` | Explicit length or GIS path data + +The number of physical conductors $K$ is inferred from the conductor list. +Child models own their detailed validation for geometry, material, and path +inputs. diff --git a/GridKit/Model/EMT/Parameters/Geometry/Tower/README.md b/GridKit/Model/EMT/Parameters/Geometry/Tower/README.md new file mode 100644 index 000000000..5be6c9b84 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Geometry/Tower/README.md @@ -0,0 +1,113 @@ +# Tower Model + +`Tower` stores conductor attachment coordinates and span-scale geometry. + +

+ +

+ +## Model Parameters + +For physical conductors $i=1,\dots,K$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +`conductor` | [-] | - | Static conductor data | [`Conductor`](../Conductor/README.md) +$x_i$ | [m] | `tower.x` | Horizontal attachment coordinate | real +$H_i$ | [m] | `tower.height` | Attachment height above earth | $H_i>0$ +$S$ | [m] | `tower.span` | Support-to-support span length | $S>0$ +$T_i$ | [N] | `tower.tension` | Tension | optional + +`Tower` does not own conductor phase labels. Phase labels are conductor +metadata owned by [`Conductor`](../Conductor/README.md). + +

+ +

+ +### Parameter Validation + +Require finite $x_i$, $H_i>0$, $S>0$, and $D'_{ij}>D_{ij}>0$ for +$i\ne j$. When tension is supplied, require $T_i>0$, $w_i>0$, and +$h_i^{\min}>0$. + +### Model Derived Parameters + +When tension data is supplied, + +```math +\begin{aligned} +a_i &= \frac{T_i}{w_i} \\ +D_i^\mathrm{sag} &= a_i\left[\cosh\left(\frac{S}{2a_i}\right)-1\right] \\ +\ell_i^{\mathrm{span}} &= 2a_i\sinh\left(\frac{S}{2a_i}\right) \\ +h_i^{\min} &= H_i-D_i^\mathrm{sag} \\ +h_i &= H_i-D_i^\mathrm{sag} + + \frac{2a_i^2}{S}\sinh\left(\frac{S}{2a_i}\right)-a_i \\ +d_{ij} &= |x_i-x_j| \\ +D_{ij} &= \sqrt{d_{ij}^2+(h_i-h_j)^2} \\ +D'_{ij} &= \sqrt{d_{ij}^2+(h_i+h_j)^2} \\ +\rho_{\mathrm{sag}} &= \frac{1}{K}\sum_{i=1}^{K} + \frac{\ell_i^{\mathrm{span}}}{S} +\end{aligned} +``` + +Here $w_i$ is supplied by `Conductor`. $\rho_{\mathrm{sag}}$ is one +conductor-averaged scalar. + +

+ +

+ +## Model Variables + +`Tower` is a static data model. + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +## Initialization + +Compute the span-scale geometry and distance matrices from the tower and +conductor data. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$x_i$ | [m] | Horizontal attachment coordinate | $\mathbb{R}^{K}$ +$h_i$ | [m] | Conductor height above earth | $\mathbb{R}^{K}$ +$S$ | [m] | Support-to-support span length | scalar +$d_{ij}$ | [m] | Horizontal separation | $\mathbb{R}^{K\times K}$ +$D_{ij}$ | [m] | Direct conductor distance | $\mathbb{R}^{K\times K}$ +$D'_{ij}$ | [m] | Image-conductor distance | $\mathbb{R}^{K\times K}$ +$D_i^\mathrm{sag}$ | [m] | Midspan sag below attachment height | $\mathbb{R}^{K}$ +$\ell_i^{\mathrm{span}}$ | [m] | Span path length for conductor $i$ | $\mathbb{R}^{K}$ +$h_i^{\min}$ | [m] | Minimum conductor height | $\mathbb{R}^{K}$ +$\rho_{\mathrm{sag}}$ | [-] | Sagged-to-span ratio | scalar diff --git a/GridKit/Model/EMT/Parameters/README.md b/GridKit/Model/EMT/Parameters/README.md new file mode 100644 index 000000000..27ba3da46 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/README.md @@ -0,0 +1,188 @@ +# EMT Parameters + +`Parameters` contains frequency-domain EMT parameter models for overhead-line +studies. The family READMEs describe the model groups: + +Family | Description +------ | ----------- +[`Geometry`](Geometry/README.md) | Static line geometry, conductor data, span data, and path length +[`Effects`](Effects/README.md) | Physical effects used to assemble per-unit-length series and shunt quantities +[`Response`](Response/README.md) | Propagation, finite-length response, and characteristic quantities derived from the assembled parameters + +## Overhead Aggregate + +`Overhead` aggregates the implemented overhead-line parameter models for one +angular frequency. It owns global state layout, submodel wiring, and monitor +selection for frequency sweeps. + +`Overhead` is not an EMT network component and does not own bus ports. Sweep +endpoints, sampling, and linear or logarithmic grids belong to the application +or study driver. + +### Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +`path` | [-] | `length`, `path` | Path definition used to compute line length | passed to [`Path`](Geometry/Path/README.md) +`tower` | [-] | `tower.x`, `tower.height`, `tower.span`, `tower.tension` | Tower attachment and span geometry | passed to [`Tower`](Geometry/Tower/README.md) +`conductor` | [-] | `conductors[*].radius`, `conductors[*].inner_radius`, `conductors[*].conductivity`, `conductors[*].permeability`, `conductors[*].weight`, `conductors[*].phase` | Conductor dimensions, material, weight, and phase data | passed to [`Conductor`](Geometry/Conductor/README.md) +$\sigma_g$ | [S/m] | `earth_conductivity` | Earth conductivity | passed to [`Carson`](Effects/Carson/README.md) +$\varepsilon_g$ | [F/m] | `earth_permittivity` | Earth permittivity | passed to [`Carson`](Effects/Carson/README.md) + +#### Parameter Validation + +The aggregate parser rejects invalid line-data fields before constructing the +child models. Detailed validation belongs to the child models. + +#### Model Derived Parameters + +None. The aggregate constructs and wires submodels from the parsed line data. + +### Model Submodels + +Submodel | Inputs | Outputs +-------- | ------ | ------- +[`Conductor`](Geometry/Conductor/README.md) | `conductor` | $r_i$, $q_i$, $\sigma_i$, $\mu_i$, $w_i$, $\phi_i$ +[`Tower`](Geometry/Tower/README.md) | `tower`, `conductor` | $x_i$, $h_i$, $S$, $d_{ij}$, $D_{ij}$, $D'_{ij}$, $\ell_i^{\mathrm{span}}$, $\rho_{\mathrm{sag}}$ +[`Path`](Geometry/Path/README.md) | `length`, `path`, `Tower` | $\ell$ +[`GeometricInductance`](Effects/GeometricInductance/README.md) | `tower`, `conductor` | $\mathbf{L}^{\mathrm{geo}}$ +[`SkinEffect`](Effects/SkinEffect/README.md) | `conductor` | $\mathbf{r}^{\mathrm{skin}}$, $\mathbf{l}^{\mathrm{skin}}$ +[`Carson`](Effects/Carson/README.md) | `tower`, $\sigma_g$, $\varepsilon_g$ | $\mathbf{R}^{\mathrm{carson}}$, $\mathbf{L}^{\mathrm{carson}}$ +[`SeriesImpedance`](Effects/SeriesImpedance/README.md) | `SkinEffect`, `GeometricInductance`, `Carson` | $\mathbf{R}'$, $\mathbf{L}'$ +[`ShuntPotential`](Effects/ShuntPotential/README.md) | `tower`, `conductor` | $\mathbf{G}^{\mathrm{pot}}$, $\mathbf{C}^{\mathrm{pot}}$ +[`ShuntAdmittance`](Effects/ShuntAdmittance/README.md) | `ShuntPotential` | $\mathbf{G}'$, $\mathbf{C}'$ +[`Gamma`](Response/Gamma/README.md) | `SeriesImpedance`, `ShuntAdmittance` | $\boldsymbol{\Gamma}$, $\mathbf{T}_v$, $\mathbf{T}_i$, $\mathbf{a}$, $\mathbf{b}$ +[`Tau`](Response/Tau/README.md) | `Gamma`, `Path` | $\boldsymbol{\tau}$ +[`H`](Response/H/README.md) | `Gamma`, `Path` | $\mathbf{H}$ +[`Yc`](Response/Yc/README.md) | `SeriesImpedance`, `ShuntAdmittance` | $\mathbf{Y}_c$ +[`Zc`](Response/Zc/README.md) | `SeriesImpedance`, `ShuntAdmittance` | $\mathbf{Z}_c$ + +### Signal Wiring + +A typical sweep wires static line data into geometry and effect models, assembles +per-unit-length quantities, and then evaluates response models. Arrows point +from the producer to the consumer. + +```mermaid +flowchart LR + path[Path] + tower[Tower] + + subgraph effects["Effect models"] + direction TB + geo[GeometricInductance] + skin[SkinEffect] + carson[Carson] + shuntpot[ShuntPotential] + end + + subgraph assembled["Assembled parameters"] + direction TB + series[SeriesImpedance] + shuntadm[ShuntAdmittance] + end + + subgraph response["Response"] + direction TB + tau[Tau] + h[H] + gamma[Gamma] + yc[Yc] + zc[Zc] + end + + path --> tau + path --> h + + tower --> path + + tower --> geo + tower --> carson + tower --> shuntpot + + geo --> series + skin --> series + carson --> series + shuntpot --> shuntadm + + series --> gamma + shuntadm --> gamma + series --> yc + shuntadm --> yc + series --> zc + shuntadm --> zc + + gamma --> tau + gamma --> h + + classDef geometry fill:#edf3e6,stroke:#78915c,stroke-width:1.2px,color:#243315; + classDef effect fill:#f5ecd9,stroke:#9a7b43,stroke-width:1.2px,color:#3b2b11; + classDef assembled fill:#e4f1df,stroke:#698b5e,stroke-width:1.2px,color:#1f3319; + classDef derived fill:#efe8f6,stroke:#77608f,stroke-width:1.2px,color:#2d2038; + class tower,path geometry; + class geo,skin,carson,shuntpot effect; + class series,shuntadm assembled; + class gamma,tau,h,yc,zc derived; +``` + +#### Directional Wiring Table + +Stage | Source | Target | Values +----- | ------ | ------ | ------ +Geometry data | `tower` | [`GeometricInductance`](Effects/GeometricInductance/README.md) | $h_i$, $D_{ij}$, $D'_{ij}$ +Geometry data | `conductor` | [`GeometricInductance`](Effects/GeometricInductance/README.md) | $r_i$ +Geometry data | `tower` | [`Carson`](Effects/Carson/README.md) | $h_i$, $h_j$, $d_{ij}$ +Geometry data | `tower` | [`ShuntPotential`](Effects/ShuntPotential/README.md) | $h_i$, $D_{ij}$, $D'_{ij}$ +Geometry data | `conductor` | [`ShuntPotential`](Effects/ShuntPotential/README.md) | $r_i$ +Material data | `conductor` | [`SkinEffect`](Effects/SkinEffect/README.md) | $r_i$, $\sigma_i$, $\mu_i$ +Earth material | `earth_conductivity`, `earth_permittivity` | [`Carson`](Effects/Carson/README.md) | $\sigma_g$, $\varepsilon_g$ +Span geometry | `tower`, `conductor` | [`Tower`](Geometry/Tower/README.md) | $S$, $\ell_i^{\mathrm{span}}$, $\rho_{\mathrm{sag}}$ +Series assembly | [`SkinEffect`](Effects/SkinEffect/README.md) | [`SeriesImpedance`](Effects/SeriesImpedance/README.md) | $\mathbf{r}^{\mathrm{skin}}$, $\mathbf{l}^{\mathrm{skin}}$ +Series assembly | [`GeometricInductance`](Effects/GeometricInductance/README.md) | [`SeriesImpedance`](Effects/SeriesImpedance/README.md) | $\mathbf{L}^{\mathrm{geo}}$ +Series assembly | [`Carson`](Effects/Carson/README.md) | [`SeriesImpedance`](Effects/SeriesImpedance/README.md) | $\mathbf{R}^{\mathrm{carson}}$, $\mathbf{L}^{\mathrm{carson}}$ +Shunt assembly | [`ShuntPotential`](Effects/ShuntPotential/README.md) | [`ShuntAdmittance`](Effects/ShuntAdmittance/README.md) | $\mathbf{G}^{\mathrm{pot}}$, $\mathbf{C}^{\mathrm{pot}}$ +Response inputs | [`SeriesImpedance`](Effects/SeriesImpedance/README.md) | [`Gamma`](Response/Gamma/README.md), [`Yc`](Response/Yc/README.md), [`Zc`](Response/Zc/README.md) | $\mathbf{R}'$, $\mathbf{L}'$ +Response inputs | [`ShuntAdmittance`](Effects/ShuntAdmittance/README.md) | [`Gamma`](Response/Gamma/README.md), [`Yc`](Response/Yc/README.md), [`Zc`](Response/Zc/README.md) | $\mathbf{G}'$, $\mathbf{C}'$ +Finite-line inputs | `length`, `path`, [`Tower`](Geometry/Tower/README.md) | [`Path`](Geometry/Path/README.md) | $\ell$ +Finite-line response | [`Gamma`](Response/Gamma/README.md) | [`Tau`](Response/Tau/README.md) | $\mathbf{b}$ +Finite-line response | [`Path`](Geometry/Path/README.md) | [`Tau`](Response/Tau/README.md) | $\ell$ +Finite-line response | [`Gamma`](Response/Gamma/README.md) | [`H`](Response/H/README.md) | $\mathbf{a}$, $\mathbf{b}$, $\dot{\mathbf{a}}$, $\dot{\mathbf{b}}$ +Finite-line response | [`Path`](Geometry/Path/README.md) | [`H`](Response/H/README.md) | $\ell$ + +### Model Variables + +The aggregate stores one concatenated state vector across the submodels listed +above. Each child README documents the variables and residuals owned by that +child model. + +### Model Equations + +`Overhead` owns no additional residual equations. It binds the child models into +one evaluator and calls each child residual and Jacobian. + +### Initialization + +Construct the child models from the parsed line data, bind their states into the +aggregate vector, initialize each child model at the current $\omega$, and start +the configured monitor sinks. + +### Model Outputs + +Model outputs are the child-model outputs listed in the submodel table. + +### Monitors + +Monitor | Symbol | Units | Shape | Description +------- | ------ | ----- | ----- | ----------- +`R` | $\mathbf{R}'$ | [$\Omega$/m] | $K\times K$ | Series resistance +`L` | $\mathbf{L}'$ | [H/m] | $K\times K$ | Series inductance +`G` | $\mathbf{G}'$ | [S/m] | $K\times K$ | Shunt conductance +`C` | $\mathbf{C}'$ | [F/m] | $K\times K$ | Shunt capacitance +`Tv` | $\mathbf{T}_v$ | [-] | $K\times K$ | Voltage modal transformation matrix +`Ti` | $\mathbf{T}_i$ | [-] | $K\times K$ | Current modal transformation matrix +`Alpha` | $\mathbf{a}$ | [1/m] | $K$ | Modal attenuation constants +`Beta` | $\mathbf{b}$ | [1/m] | $K$ | Modal phase constants +`Tau` | $\boldsymbol{\tau}$ | [s] | $K$ | Modal phase delay +`H` | $\mathbf{H}$ | [-] | $K$ | Modal finite-length propagation function +`Yc` | $\mathbf{Y}_c=\mathbf{G}_c+j\mathbf{B}_c$ | [S] | $K\times K$ | Characteristic admittance +`Zc` | $\mathbf{Z}_c=\mathbf{R}_c+j\mathbf{X}_c$ | [$\Omega$] | $K\times K$ | Characteristic impedance diff --git a/GridKit/Model/EMT/Parameters/Response/Gamma/README.md b/GridKit/Model/EMT/Parameters/Response/Gamma/README.md new file mode 100644 index 000000000..282ce4ffb --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/Gamma/README.md @@ -0,0 +1,228 @@ +# Gamma Model + +`Gamma` computes the full-conductor propagation constant matrix and tracks its +modal propagation constants. + +Notes: +- This model uses the V-definition: the series matrix pair is on the left of + the shunt matrix pair. +- The real and imaginary parts of $\boldsymbol{\Gamma}$ are + $\boldsymbol{\alpha}$ and $\boldsymbol{\beta}$. +- Eigenvalue computation is not expressed as a DAE, so modal branches are + initialized from $\boldsymbol{\Gamma}^2$ at one value of $\omega$ and tracked + as $\omega$ changes. +- The modal tracking equations assume each tracked modal branch is simple. + +The propagation constant is decomposed as +$\boldsymbol{\Gamma}=\boldsymbol{\alpha}+j\boldsymbol{\beta}$. + +The complex form typically given for this convention is: + +```math +\boldsymbol{\Gamma} = +\sqrt{ +(\mathbf{R}' + j\mathbf{X}') +(\mathbf{G}' + j\mathbf{B}') +} +``` + +Equivalently, + +```math +\boldsymbol{\Gamma}^2 = +(\mathbf{R}' + j\mathbf{X}') +(\mathbf{G}' + j\mathbf{B}') +``` + +## Model Parameters + +None. `Gamma` combines full-conductor parameter outputs for $K$ physical +conductors. + +### Parameter Validation + +The full-conductor inputs must be square and have the same dimension. + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +A dot denotes derivative with respect to $\omega$. + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\boldsymbol{\alpha}$ | [1/m] | Attenuation constant matrix | $\mathbb{R}^{K\times K}$ +$\boldsymbol{\beta}$ | [1/m] | Phase constant matrix | $\mathbb{R}^{K\times K}$ +$a_m$ | [1/m] | Modal attenuation constant for mode $m$ | real +$b_m$ | [1/m] | Modal phase constant for mode $m$ | real +$\mathbf{t}^{\mathrm r}_{v,m}$ | [-] | Real part of voltage modal transformation vector | $\mathbf{t}^{\mathrm r}_{v,m}\in\mathbb{R}^K$ +$\mathbf{t}^{\mathrm i}_{v,m}$ | [-] | Imaginary part of voltage modal transformation vector | $\mathbf{t}^{\mathrm i}_{v,m}\in\mathbb{R}^K$ +$\mathbf{t}^{\mathrm r}_{i,m}$ | [-] | Real part of current modal transformation vector | $\mathbf{t}^{\mathrm r}_{i,m}\in\mathbb{R}^K$ +$\mathbf{t}^{\mathrm i}_{i,m}$ | [-] | Imaginary part of current modal transformation vector | $\mathbf{t}^{\mathrm i}_{i,m}\in\mathbb{R}^K$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}'$ | [$\Omega$/m] | Full-conductor resistance | from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{X}'$ | [$\Omega$/m] | Full-conductor reactance | $\omega\mathbf{L}'$ from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{G}'$ | [S/m] | Full-conductor shunt conductance | from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) +$\mathbf{B}'$ | [S/m] | Full-conductor shunt susceptance | $\omega\mathbf{C}'$ from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) + +## Model Equations + +### Differential Equations + +For each mode $m=1,\dots,K$: + +```math +\begin{aligned} +\mathbf{0} &= + \dot{\boldsymbol{\alpha}}\mathbf{t}^{\mathrm r}_{v,m} + - \dot{\boldsymbol{\beta}}\mathbf{t}^{\mathrm i}_{v,m} + + \left(\boldsymbol{\alpha}-a_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm r}_{v,m} + - \left(\boldsymbol{\beta}-b_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm i}_{v,m} + - \dot{a}_m\mathbf{t}^{\mathrm r}_{v,m} + + \dot{b}_m\mathbf{t}^{\mathrm i}_{v,m} \\ +\mathbf{0} &= + \dot{\boldsymbol{\alpha}}\mathbf{t}^{\mathrm i}_{v,m} + + \dot{\boldsymbol{\beta}}\mathbf{t}^{\mathrm r}_{v,m} + + \left(\boldsymbol{\beta}-b_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm r}_{v,m} + + \left(\boldsymbol{\alpha}-a_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm i}_{v,m} + - \dot{a}_m\mathbf{t}^{\mathrm i}_{v,m} + - \dot{b}_m\mathbf{t}^{\mathrm r}_{v,m} \\ +\mathbf{0} &= + \dot{\boldsymbol{\alpha}}^{\mathsf{T}}\mathbf{t}^{\mathrm r}_{i,m} + + \dot{\boldsymbol{\beta}}^{\mathsf{T}}\mathbf{t}^{\mathrm i}_{i,m} + + \left(\boldsymbol{\alpha}^{\mathsf{T}}-a_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm r}_{i,m} + + \left(\boldsymbol{\beta}^{\mathsf{T}}-b_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm i}_{i,m} + - \dot{a}_m\mathbf{t}^{\mathrm r}_{i,m} + - \dot{b}_m\mathbf{t}^{\mathrm i}_{i,m} \\ +\mathbf{0} &= + \dot{\boldsymbol{\alpha}}^{\mathsf{T}}\mathbf{t}^{\mathrm i}_{i,m} + - \dot{\boldsymbol{\beta}}^{\mathsf{T}}\mathbf{t}^{\mathrm r}_{i,m} + - \left(\boldsymbol{\beta}^{\mathsf{T}}-b_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm r}_{i,m} + + \left(\boldsymbol{\alpha}^{\mathsf{T}}-a_m\mathbf{I}\right)\dot{\mathbf{t}}^{\mathrm i}_{i,m} + - \dot{a}_m\mathbf{t}^{\mathrm i}_{i,m} + + \dot{b}_m\mathbf{t}^{\mathrm r}_{i,m} +\end{aligned} +``` + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -\mathbf{R}'\mathbf{G}' + + \mathbf{X}'\mathbf{B}' + + \boldsymbol{\alpha}\boldsymbol{\alpha} + - \boldsymbol{\beta}\boldsymbol{\beta} \\ +\mathbf{0} &= -\mathbf{R}'\mathbf{B}' + - \mathbf{X}'\mathbf{G}' + + \boldsymbol{\alpha}\boldsymbol{\beta} + + \boldsymbol{\beta}\boldsymbol{\alpha} \\ +0 &= \left(\mathbf{t}^{\mathrm r}_{i,m}\right)^{\mathsf{T}}\mathbf{t}^{\mathrm r}_{v,m} + + \left(\mathbf{t}^{\mathrm i}_{i,m}\right)^{\mathsf{T}}\mathbf{t}^{\mathrm i}_{v,m} + - 1 \\ +0 &= \left(\mathbf{t}^{\mathrm r}_{i,m}\right)^{\mathsf{T}}\mathbf{t}^{\mathrm i}_{v,m} + - \left(\mathbf{t}^{\mathrm i}_{i,m}\right)^{\mathsf{T}}\mathbf{t}^{\mathrm r}_{v,m} +\end{aligned} +``` + +## Initialization + +At the initial frequency, compute the eigenvalues and right eigenvectors of +$\boldsymbol{\Gamma}^2$: + +```math +\boldsymbol{\Gamma}^2\mathbf{t}_m + = \mu_m\mathbf{t}_m +``` + +Then initialize +$\lambda_m=\sqrt{\mu_m}=a_m+jb_m$ and construct +$\boldsymbol{\Gamma}$ with the same eigenvectors: + +```math +\begin{aligned} +\boldsymbol{\Gamma}\mathbf{t}_m + &= \lambda_m\mathbf{t}_m,\qquad +\mathbf{l}_m^*\mathbf{t}_m=1 +\end{aligned} +``` + +Use $\lambda_m=a_m+jb_m$, +$\mathbf{t}_m=\mathbf{t}^{\mathrm r}_{v,m}+j\mathbf{t}^{\mathrm i}_{v,m}$, and +$\mathbf{l}_m=\mathbf{t}^{\mathrm r}_{i,m}+j\mathbf{t}^{\mathrm i}_{i,m}$. + +## Monitors + +Monitor | Symbol | Units | Shape | Description +------- | ------ | ----- | ----- | ----------- +`Tv` | $\mathbf{T}_v$ | [-] | $K\times K$ | Voltage modal transformation matrix +`Ti` | $\mathbf{T}_i$ | [-] | $K\times K$ | Current modal transformation matrix +`Alpha` | $\mathbf{a}$ | [1/m] | $K$ | Modal attenuation constants +`Beta` | $\mathbf{b}$ | [1/m] | $K$ | Modal phase constants + +The monitored transformation matrices use + +```math +\mathbf{T}_v = +\mathbf{T}^{\mathrm r}_v+j\mathbf{T}^{\mathrm i}_v,\qquad +\mathbf{T}_i = +\mathbf{T}^{\mathrm r}_i+j\mathbf{T}^{\mathrm i}_i,\qquad +\mathbf{T}_i^{\mathsf H}\mathbf{T}_v=\mathbf{I}. +``` + +Both $\mathbf{T}_v$ and $\mathbf{T}_i$ are reported as $K\times K$ +conductor-by-mode matrices. Column $m$ matches the ordering of `Alpha_m` and +`Beta_m`. + +The voltage and current modal transforms are dual: + +```math +\mathbf{v}=\mathbf{T}_v\hat{\mathbf{v}},\qquad +\hat{\mathbf{v}}=\mathbf{T}_i^{\mathsf H}\mathbf{v} +``` + +```math +\mathbf{i}=\mathbf{T}_i\hat{\mathbf{i}},\qquad +\hat{\mathbf{i}}=\mathbf{T}_v^{\mathsf H}\mathbf{i}. +``` + +GridKit uses the current-form propagation matrix because `LineDistributed` +propagates reflected current to incident current: + +```math +\mathbf{H}^{\mathrm{mps}}_i(s) += +\mathbf{T}_i(s)\widehat{\mathbf{H}}^{\mathrm{mps}}(s) +\mathbf{T}_v(s)^{\mathsf H}. +``` + +The dual voltage-form propagation matrix is + +```math +\mathbf{H}^{\mathrm{mps}}_v(s) += +\mathbf{T}_v(s)\widehat{\mathbf{H}}^{\mathrm{mps}}(s) +\mathbf{T}_i(s)^{\mathsf H}. +``` + +The phase-domain matrices $\boldsymbol{\alpha}$ and $\boldsymbol{\beta}$ are +internal `Gamma` states and are not monitors. diff --git a/GridKit/Model/EMT/Parameters/Response/H/README.md b/GridKit/Model/EMT/Parameters/Response/H/README.md new file mode 100644 index 000000000..a03138264 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/H/README.md @@ -0,0 +1,134 @@ +# H Model + +`H` computes the modal-domain finite-length propagation function from modal +propagation constants. + +The model is real-valued in implementation. The real and imaginary parts of +$h_m$ are owned as separate differential states. + +`H` uses derivative signals from `Gamma`. In logarithmic frequency sweeps, +`LogEvaluator` converts solver derivatives to derivatives with respect to +angular frequency before `H` is evaluated. + +```math +h_m = \exp(-\gamma_m \ell),\qquad +\gamma_m = a_m + j b_m +``` + +Equivalently, + +```math +\begin{aligned} +h^{\mathrm r}_m &= +e^{-a_m\ell}\cos(b_m\ell) \\ +h^{\mathrm i}_m &= +-e^{-a_m\ell}\sin(b_m\ell) +\end{aligned} +``` + +The differential form used during the sweep is + +```math +\dot h_m = -\ell \dot\gamma_m h_m,\qquad +\dot\gamma_m = \dot a_m + j\dot b_m . +``` + +## Model Parameters + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\ell$ | [m] | Path length | from [`Path`](../../Geometry/Path/README.md) + +### Parameter Validation + +The path length must satisfy + +```math +\ell > 0 . +``` + +The connected `Gamma` model owns modal-vector validation. + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$h^{\mathrm r}_m$ | [-] | Real part of modal propagation function for mode $m$ | real +$h^{\mathrm i}_m$ | [-] | Imaginary part of modal propagation function for mode $m$ | real + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\dot a_m$ | [s/m] | Modal attenuation derivative for mode $m$ | from [`Gamma`](../Gamma/README.md) +$\dot b_m$ | [s/m] | Modal phase derivative for mode $m$ | from [`Gamma`](../Gamma/README.md) + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$a_m$ | [1/m] | Modal attenuation constant for mode $m$ | from [`Gamma`](../Gamma/README.md) +$b_m$ | [1/m] | Modal phase constant for mode $m$ | from [`Gamma`](../Gamma/README.md) + +## Model Equations + +### Differential Equations + +For each mode $m=1,\dots,K$: + +```math +\begin{aligned} +0 &= -\dot h^{\mathrm r}_m + - \ell\left(\dot a_m h^{\mathrm r}_m + - \dot b_m h^{\mathrm i}_m\right) \\ +0 &= -\dot h^{\mathrm i}_m + - \ell\left(\dot a_m h^{\mathrm i}_m + + \dot b_m h^{\mathrm r}_m\right) +\end{aligned} +``` + +### Algebraic Equations + +None. + +## Initialization + +Initialize $h^{\mathrm r}_m$ and $h^{\mathrm i}_m$ from the current $a_m$ and +$b_m$ inputs using the closed-form expression above. Initialize the derivatives +from $\dot h_m=-\ell\dot\gamma_m h_m$. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{h}^{\mathrm r}$ | [-] | Real part of modal propagation function | $\mathbb{R}^K$ +$\mathbf{h}^{\mathrm i}$ | [-] | Imaginary part of modal propagation function | $\mathbb{R}^K$ + +## Monitors + +Monitor | Symbol | Units | Shape | Description +------- | ------ | ----- | ----- | ----------- +`H` | $\mathbf{h}^{\mathrm r}+j\mathbf{h}^{\mathrm i}$ | [-] | $K$ | Modal propagation function + +CSV output uses explicit real and imaginary columns: + +```text +Overhead_H_real_m +Overhead_H_imag_m +``` + +No complex-valued states, residuals, monitor storage, or model API are used. diff --git a/GridKit/Model/EMT/Parameters/Response/README.md b/GridKit/Model/EMT/Parameters/Response/README.md new file mode 100644 index 000000000..a4ae4c0f1 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/README.md @@ -0,0 +1,36 @@ +# Response Models + +`Response` contains the propagation and characteristic models derived from +assembled full-conductor overhead-line parameters. + +These models consume the per-unit-length matrices from +[`SeriesImpedance`](../Effects/SeriesImpedance/README.md) and +[`ShuntAdmittance`](../Effects/ShuntAdmittance/README.md). Finite-line response +models also consume the path length from [`Path`](../Geometry/Path/README.md). +They are evaluated at the current system parameter $\omega$. + +Model | Description +----- | ----------- +[`Gamma`](Gamma/README.md) | Computes propagation constant matrices and modal propagation constants +[`Tau`](Tau/README.md) | Computes finite-length modal phase delay +[`H`](H/README.md) | Computes modal finite-length propagation function +[`Yc`](Yc/README.md) | Computes characteristic admittance +[`Zc`](Zc/README.md) | Computes characteristic impedance + +## Inputs + +Quantity | Source | Used By +-------- | ------ | ------- +$\mathbf{R}'$, $\mathbf{L}'$ | [`SeriesImpedance`](../Effects/SeriesImpedance/README.md) | `Gamma`, `Yc`, `Zc` +$\mathbf{G}'$, $\mathbf{C}'$ | [`ShuntAdmittance`](../Effects/ShuntAdmittance/README.md) | `Gamma`, `Yc`, `Zc` +$\ell$ | [`Path`](../Geometry/Path/README.md) | `Tau`, `H` + +## Outputs + +Quantity | Produced By +-------- | ----------- +$\boldsymbol{\Gamma}$, $\mathbf{T}_v$, $\mathbf{T}_i$, $\mathbf{a}$, $\mathbf{b}$ | [`Gamma`](Gamma/README.md) +$\boldsymbol{\tau}$ | [`Tau`](Tau/README.md) +$\mathbf{H}$ | [`H`](H/README.md) +$\mathbf{Y}_c$ | [`Yc`](Yc/README.md) +$\mathbf{Z}_c$ | [`Zc`](Zc/README.md) diff --git a/GridKit/Model/EMT/Parameters/Response/Tau/README.md b/GridKit/Model/EMT/Parameters/Response/Tau/README.md new file mode 100644 index 000000000..608f502e9 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/Tau/README.md @@ -0,0 +1,74 @@ +# Tau Model + +`Tau` computes modal phase delay for a finite line length from modal +phase constants. + +## Model Parameters + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\ell$ | [m] | Path length | from [`Path`](../../Geometry/Path/README.md) + +### Parameter Validation + +The connected `Gamma` model owns modal-vector validation. This model requires the +path length and current sweep point to satisfy + +```math +\ell > 0,\qquad \omega > 0 . +``` + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\tau_m$ | [s] | Modal phase delay for mode $m$ | real + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$b_m$ | [1/m] | Modal phase constant for mode $m$ | from [`Gamma`](../Gamma/README.md) + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +For each mode $m=1,\dots,K$: + +```math +0 = -\tau_m + \frac{\ell b_m}{\omega} +``` + +## Initialization + +Initialize $\tau_m$ from $\ell$, the current $\omega$, and the current $b_m$ +inputs. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\boldsymbol{\tau}$ | [s] | Modal phase delay | $\boldsymbol{\tau}\in\mathbb{R}^K$ diff --git a/GridKit/Model/EMT/Parameters/Response/Yc/README.md b/GridKit/Model/EMT/Parameters/Response/Yc/README.md new file mode 100644 index 000000000..ff235c839 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/Yc/README.md @@ -0,0 +1,105 @@ +# Yc Model + +`Yc` computes the full-conductor characteristic admittance from the +per-unit-length series impedance and shunt admittance matrices. + +Notes: +- For multiconductor lines, the V-definition and I-definition differ by the + ordering of the matrix products. +- This model uses the V-definition: the series matrix pair multiplies + $\mathbf{Y}_c^2$ on the left. +- The I-definition places the series matrix pair on the right. +- The real and imaginary parts of $\mathbf{Y}_c$ are $\mathbf{G}_c$ and + $\mathbf{B}_c$. + +The characteristic admittance is decomposed as +$\mathbf{Y}_c=\mathbf{G}_c+j\mathbf{B}_c$. + +The complex form typically given for this convention is: + +```math +\mathbf{Y}_c = +\sqrt{ +(\mathbf{R}' + j\mathbf{X}')^{-1} +(\mathbf{G}' + j\mathbf{B}') +} +``` + +## Model Parameters + +None. `Yc` combines full-conductor parameter outputs for $K$ physical +conductors. + +### Parameter Validation + +The full-conductor inputs must be square and have the same dimension. + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}_c$ | [S] | Characteristic conductance | $\mathbb{R}^{K\times K}$ +$\mathbf{B}_c$ | [S] | Characteristic susceptance | $\mathbb{R}^{K\times K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}'$ | [$\Omega$/m] | Full-conductor resistance | from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{X}'$ | [$\Omega$/m] | Full-conductor reactance | $\omega\mathbf{L}'$ from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{G}'$ | [S/m] | Full-conductor shunt conductance | from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) +$\mathbf{B}'$ | [S/m] | Full-conductor shunt susceptance | $\omega\mathbf{C}'$ from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -\mathbf{G}' + + \mathbf{R}'\left(\mathbf{G}_c\mathbf{G}_c + - \mathbf{B}_c\mathbf{B}_c\right) + - \mathbf{X}'\left(\mathbf{G}_c\mathbf{B}_c + + \mathbf{B}_c\mathbf{G}_c\right) \\ +\mathbf{0} &= -\mathbf{B}' + + \mathbf{R}'\left(\mathbf{G}_c\mathbf{B}_c + + \mathbf{B}_c\mathbf{G}_c\right) + + \mathbf{X}'\left(\mathbf{G}_c\mathbf{G}_c + - \mathbf{B}_c\mathbf{B}_c\right) +\end{aligned} +``` + +## Initialization + +Validate the full-conductor matrix dimensions. Initialize +$\mathbf{G}_c$ and $\mathbf{B}_c$ from the current $\mathbf{R}'$, +$\mathbf{X}'$, $\mathbf{G}'$, and $\mathbf{B}'$ inputs. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{G}_c$ | [S] | Characteristic conductance | $\mathbb{R}^{K\times K}$ +$\mathbf{B}_c$ | [S] | Characteristic susceptance | $\mathbb{R}^{K\times K}$ diff --git a/GridKit/Model/EMT/Parameters/Response/Zc/README.md b/GridKit/Model/EMT/Parameters/Response/Zc/README.md new file mode 100644 index 000000000..3a58c1437 --- /dev/null +++ b/GridKit/Model/EMT/Parameters/Response/Zc/README.md @@ -0,0 +1,105 @@ +# Zc Model + +`Zc` computes the full-conductor characteristic impedance from the +per-unit-length series impedance and shunt admittance matrices. + +Notes: +- For multiconductor lines, the V-definition and I-definition differ by the + ordering of the matrix products. +- This model uses the V-definition: the shunt matrix pair multiplies + $\mathbf{Z}_c^2$ on the left. +- The I-definition places the shunt matrix pair on the right. +- The real and imaginary parts of $\mathbf{Z}_c$ are $\mathbf{R}_c$ and + $\mathbf{X}_c$. + +The characteristic impedance is decomposed as +$\mathbf{Z}_c=\mathbf{R}_c+j\mathbf{X}_c$. + +The complex form typically given for this convention is: + +```math +\mathbf{Z}_c = +\sqrt{ +(\mathbf{G}' + j\mathbf{B}')^{-1} +(\mathbf{R}' + j\mathbf{X}') +} +``` + +## Model Parameters + +None. `Zc` combines full-conductor parameter outputs for $K$ physical +conductors. + +### Parameter Validation + +The full-conductor inputs must be square and have the same dimension. + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}_c$ | [$\Omega$] | Characteristic resistance | $\mathbb{R}^{K\times K}$ +$\mathbf{X}_c$ | [$\Omega$] | Characteristic reactance | $\mathbb{R}^{K\times K}$ + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}'$ | [$\Omega$/m] | Full-conductor resistance | from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{X}'$ | [$\Omega$/m] | Full-conductor reactance | $\omega\mathbf{L}'$ from [`SeriesImpedance`](../../Effects/SeriesImpedance/README.md) +$\mathbf{G}'$ | [S/m] | Full-conductor shunt conductance | from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) +$\mathbf{B}'$ | [S/m] | Full-conductor shunt susceptance | $\omega\mathbf{C}'$ from [`ShuntAdmittance`](../../Effects/ShuntAdmittance/README.md) + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{aligned} +\mathbf{0} &= -\mathbf{R}' + + \mathbf{G}'\left(\mathbf{R}_c\mathbf{R}_c + - \mathbf{X}_c\mathbf{X}_c\right) + - \mathbf{B}'\left(\mathbf{R}_c\mathbf{X}_c + + \mathbf{X}_c\mathbf{R}_c\right) \\ +\mathbf{0} &= -\mathbf{X}' + + \mathbf{G}'\left(\mathbf{R}_c\mathbf{X}_c + + \mathbf{X}_c\mathbf{R}_c\right) + + \mathbf{B}'\left(\mathbf{R}_c\mathbf{R}_c + - \mathbf{X}_c\mathbf{X}_c\right) +\end{aligned} +``` + +## Initialization + +Validate the full-conductor matrix dimensions. Initialize +$\mathbf{R}_c$ and $\mathbf{X}_c$ from the current $\mathbf{R}'$, +$\mathbf{X}'$, $\mathbf{G}'$, and $\mathbf{B}'$ inputs. + +## Model Outputs + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{R}_c$ | [$\Omega$] | Characteristic resistance | $\mathbb{R}^{K\times K}$ +$\mathbf{X}_c$ | [$\Omega$] | Characteristic reactance | $\mathbb{R}^{K\times K}$ diff --git a/GridKit/Model/EMT/README.md b/GridKit/Model/EMT/README.md index 0b3e15a00..e23413510 100644 --- a/GridKit/Model/EMT/README.md +++ b/GridKit/Model/EMT/README.md @@ -18,3 +18,11 @@ The current EMT documentation is organized into: - `Component` (See [Component](Component/README.md)) - `Operators` (See [Operators](Operators/README.md)) +- `Parameters` (See [Parameters](Parameters/README.md)) + +Component models are documented under `Component` because they are EMT models +connected to buses. Reusable transfer and coordinate tools are documented under +`Operators`. +Frequency-domain line-parameter models are documented under `Parameters` +because they generate sampled per-unit-length data rather than EMT bus +residuals. diff --git a/docs/Figures/EMT/Conductor/diagram.png b/docs/Figures/EMT/Conductor/diagram.png new file mode 100644 index 000000000..7e8dc3495 Binary files /dev/null and b/docs/Figures/EMT/Conductor/diagram.png differ diff --git a/docs/Figures/EMT/Conductor/diagram.tex b/docs/Figures/EMT/Conductor/diagram.tex new file mode 100644 index 000000000..aadc3581f --- /dev/null +++ b/docs/Figures/EMT/Conductor/diagram.tex @@ -0,0 +1,42 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../../utils/gridkit.tex} +\usetikzlibrary{patterns} + +\begin{document} +\begin{tikzpicture}[gk] + +% ===================================================================== +% Tubular conductor cross-section: outer radius r_i, hollow bore q_i. +% The metal annulus (section-hatched) carries the axial current +% (out of page) and has material properties sigma_i, mu_i. +% ===================================================================== + +\def\rO{2.5} % outer radius (screen units) +\def\rI{1.05} % inner (bore) radius +\pgfmathsetmacro{\rM}{(\rO+\rI)/2} % mid-metal radius + +% ---- metal annulus: light tint + section hatch, hollow bore -------- +\fill[gkConductor!12] (0,0) circle (\rO); +\fill[pattern=north east lines, pattern color=gkConductor!65] (0,0) circle (\rO); +\fill[white] (0,0) circle (\rI); +\draw[gkConductor, line width=1.9pt] (0,0) circle (\rO); +\draw[gkConductor, line width=1.4pt] (0,0) circle (\rI); + +% ---- axial current carried in the metal (out of page) ------------- +\foreach \a in {0,90,180,270}{% + \fill[white] (\a:\rM) circle (4.2pt); + \draw[gkConductor, line width=0.8pt] (\a:\rM) circle (3.3pt); + \fill[gkConductor] (\a:\rM) circle (1.0pt); +} + +% ---- geometry: outer radius r_i and inner radius q_i (right angle) -- +\gkradius{0}{0}{35}{\rO}{$r_i$} +\draw[->, thin, gkSteel] (0,0) -- (125:\rI) node[pos=0.66, gkdimlbl]{$q_i$}; +\fill[gkSteel] (0,0) circle (1.7pt); + +% ---- material properties (leader out of the metal) ---------------- +\draw[gkSteel, thin] (235:\rM) -- (-2.65,-2.0) + node[left, gksig]{$\sigma_i,\ \mu_i$}; + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Path/diagram.png b/docs/Figures/EMT/Path/diagram.png new file mode 100644 index 000000000..7d028e842 Binary files /dev/null and b/docs/Figures/EMT/Path/diagram.png differ diff --git a/docs/Figures/EMT/Path/diagram.tex b/docs/Figures/EMT/Path/diagram.tex new file mode 100644 index 000000000..d50a6d0ff --- /dev/null +++ b/docs/Figures/EMT/Path/diagram.tex @@ -0,0 +1,162 @@ +\documentclass[tikz,border=0pt]{standalone} +\input{../../utils/gridkit.tex} + +% ===================================================================== +% Path model: an ordered GIS route P_1,...,P_{Np} on the earth sphere. +% Each interval P_n -> P_{n+1} contributes the great-circle (haversine) +% arc length s_n = R_oplus c_n; the route is a smooth chain of geodesic +% segments. The globe is an offset, cropped, soft-lit sphere. +% +% Orthographic projection; each segment is sampled by spherical linear +% interpolation (slerp) of its endpoint unit vectors. +% ===================================================================== + +% modern globe palette (cool blue-gray, lit from upper-left) +\definecolor{gkGlobeLo}{RGB}{237,243,248} % highlight (near-white) +\definecolor{gkGlobeHi}{RGB}{151,174,196} % body / terminator +\tikzset{gkgrid/.style = {white, line width=0.4pt, opacity=0.5}} + +\def\Rs{5.2} % sphere screen radius (large) +\def\ox{2.7} % globe centre x (offset right) +\def\oy{-1.3} % globe centre y (offset down) +\def\vlat{16} % view latitude (deg) +\def\vlon{20} % view longitude (deg) +\def\Nseg{20} % samples per geodesic + +\begin{document} + +% ---- orthographic view basis (east, north, out) at (vlat,vlon) ----- +\pgfmathsetmacro{\eastx}{-sin(\vlon)} +\pgfmathsetmacro{\easty}{ cos(\vlon)} +\pgfmathsetmacro{\eastz}{0} +\pgfmathsetmacro{\northx}{-sin(\vlat)*cos(\vlon)} +\pgfmathsetmacro{\northy}{-sin(\vlat)*sin(\vlon)} +\pgfmathsetmacro{\northz}{ cos(\vlat)} +\pgfmathsetmacro{\outx}{cos(\vlat)*cos(\vlon)} +\pgfmathsetmacro{\outy}{cos(\vlat)*sin(\vlon)} +\pgfmathsetmacro{\outz}{sin(\vlat)} + +% project (lat,lon) -> screen (\sx,\sy); \sz>0 means front hemisphere +\newcommand{\proj}[2]{% + \pgfmathsetmacro{\vX}{cos(#1)*cos(#2)}% + \pgfmathsetmacro{\vY}{cos(#1)*sin(#2)}% + \pgfmathsetmacro{\vZ}{sin(#1)}% + \pgfmathsetmacro{\sx}{\Rs*(\vX*\eastx+\vY*\easty+\vZ*\eastz)}% + \pgfmathsetmacro{\sy}{\Rs*(\vX*\northx+\vY*\northy+\vZ*\northz)}% + \pgfmathsetmacro{\sz}{\vX*\outx+\vY*\outy+\vZ*\outz}% +} +\newcommand{\waypoint}[3]{\proj{#2}{#3}\coordinate (#1) at (\sx,\sy);} + +% great-circle polyline between (lat1,lon1) and (lat2,lon2) +\newcommand{\geoseg}[5]{% #1 lat1 #2 lon1 #3 lat2 #4 lon2 #5 style + \pgfmathsetmacro{\Ax}{cos(#1)*cos(#2)}% + \pgfmathsetmacro{\Ay}{cos(#1)*sin(#2)}% + \pgfmathsetmacro{\Az}{sin(#1)}% + \pgfmathsetmacro{\Bx}{cos(#3)*cos(#4)}% + \pgfmathsetmacro{\By}{cos(#3)*sin(#4)}% + \pgfmathsetmacro{\Bz}{sin(#3)}% + \pgfmathsetmacro{\dab}{min(1,max(-1,\Ax*\Bx+\Ay*\By+\Az*\Bz))}% + \pgfmathsetmacro{\Om}{acos(\dab)}% + \foreach \i in {0,...,\Nseg}{% + \pgfmathsetmacro{\tt}{\i/\Nseg}% + \pgfmathsetmacro{\wa}{sin((1-\tt)*\Om)/sin(\Om)}% + \pgfmathsetmacro{\wb}{sin(\tt*\Om)/sin(\Om)}% + \pgfmathsetmacro{\vX}{\wa*\Ax+\wb*\Bx}% + \pgfmathsetmacro{\vY}{\wa*\Ay+\wb*\By}% + \pgfmathsetmacro{\vZ}{\wa*\Az+\wb*\Bz}% + \pgfmathsetmacro{\px}{\Rs*(\vX*\eastx+\vY*\easty+\vZ*\eastz)}% + \pgfmathsetmacro{\py}{\Rs*(\vX*\northx+\vY*\northy+\vZ*\northz)}% + \coordinate (gc\i) at (\px,\py);% + }% + \draw[#5] (gc0) \foreach \i in {1,...,\Nseg}{ -- (gc\i)};% +} + +% front-hemisphere parallel (lat = #1) and meridian (lon = #1) +\newcommand{\parallelarc}[1]{% + \foreach \lo in {-180,-165,...,165}{% + \pgfmathsetmacro{\loB}{\lo+15}% + \proj{#1}{\lo}\edef\xa{\sx}\edef\ya{\sy}\edef\za{\sz}% + \proj{#1}{\loB}\edef\xb{\sx}\edef\yb{\sy}\edef\zb{\sz}% + \ifdim\za pt>0pt\ifdim\zb pt>0pt + \draw[gkgrid] (\xa,\ya) -- (\xb,\yb);\fi\fi}} +\newcommand{\meridianarc}[1]{% + \foreach \la in {-75,-60,...,75}{% + \pgfmathsetmacro{\laB}{\la+15}% + \proj{\la}{#1}\edef\xa{\sx}\edef\ya{\sy}\edef\za{\sz}% + \proj{\laB}{#1}\edef\xb{\sx}\edef\yb{\sy}\edef\zb{\sz}% + \ifdim\za pt>0pt\ifdim\zb pt>0pt + \draw[gkgrid] (\xa,\ya) -- (\xb,\yb);\fi\fi}} + +\begin{tikzpicture}[gk] + +% fixed figure frame (defines crop + bounding box) +\useasboundingbox (-4.6,-3.7) rectangle (4.6,3.7); + +\begin{scope} +\clip (-4.6,-3.7) rectangle (4.6,3.7); +\begin{scope}[shift={(\ox,\oy)}] + + % ---- soft-lit sphere: body + diffuse highlight (upper-left) ------- + \pgfmathsetmacro{\hlx}{-0.50*\Rs} + \pgfmathsetmacro{\hly}{ 0.52*\Rs} + \pgfmathsetmacro{\hlr}{ 1.35*\Rs} + \begin{scope} + \clip (0,0) circle (\Rs); + \fill[gkGlobeHi] (0,0) circle (\Rs); + \shade[inner color=gkGlobeLo, outer color=gkGlobeHi] (\hlx,\hly) circle (\hlr); + \end{scope} + + % ---- graticule (front hemisphere) and crisp limb ----------------- + \foreach \L in {-60,-30,0,30,60}{\parallelarc{\L}} + \foreach \L in {-60,-30,0,30,60,90}{\meridianarc{\L}} + \draw[gkGlobeHi!60!black, thin] (0,0) circle (\Rs); + + % ---- smooth GIS route P_1 ... P_8 on the upper-left surface ------- + \waypoint{P1}{36}{-24} + \waypoint{P2}{40}{-19} + \waypoint{P3}{42}{-14} + \waypoint{P4}{40}{ -9} + \waypoint{P5}{36}{ -4} + \waypoint{P6}{34}{ 1} + \waypoint{P7}{37}{ 5} + \waypoint{P8}{41}{ 10} + + \geoseg{36}{-24}{40}{-19}{gkcond} + \geoseg{40}{-19}{42}{-14}{gkcond} + \geoseg{42}{-14}{40}{ -9}{gkcond} + \geoseg{40}{ -9}{36}{ -4}{gkcond} + \geoseg{36}{ -4}{34}{ 1}{gkcond} + \geoseg{34}{ 1}{37}{ 5}{gkcond} + \geoseg{37}{ 5}{41}{ 10}{gkcond} + + \foreach \p in {P1,P2,P3,P4,P5,P6,P7,P8}{% + \fill[white] (\p) circle (3.4pt); + \fill[gkconddot] (\p) circle (2.6pt);} + \node[gksig, gkConductor, below=3pt] at (P1) {$P_1$}; + \node[gksig, gkConductor, right=3pt] at (P8) {$P_{N_p}$}; + +\end{scope} +\end{scope} + +% ---- title / coordinate note (top-left, off the globe) ------------- +\node[gksig, gkConductor, anchor=north west] at (-4.4,3.5) + {$P_n=(\Phi_n,\Lambda_n)$}; + +% ---- detail callout (lower-left): one segment's arc geometry ------- +\begin{scope}[shift={(-2.55,-1.95)}] + \def\ri{1.4} + \fill[white] (-1.55,-0.72) rectangle (1.55,2.18); + \draw[gkSteel, thin, rounded corners=3pt] (-1.55,-0.72) rectangle (1.55,2.18); + \draw[gkSteel, thin] (0,0) -- (110:\ri); + \draw[gkSteel, thin] (0,0) -- (70:\ri) node[pos=0.56, right=2pt, gksig, gkSteel]{$R_\oplus$}; + \draw[gkcond, line width=1.6pt] (70:\ri) arc (70:110:\ri); + \node[gksig] at (90:\ri+0.28) {$s_n$}; + \draw[thin, gkSteel] (70:0.55) arc (70:110:0.55); + \node[gksig, gkSteel] at (90:0.88) {$c_n$}; + \fill[gkconddot] (110:\ri) circle (2.4pt) node[gkConductor, above left=-2pt and -2pt, gksig]{$P_n$}; + \fill[gkconddot] ( 70:\ri) circle (2.4pt) node[gkConductor, above right=-2pt and -2pt, gksig]{$P_{n+1}$}; + \fill[gkSteel] (0,0) circle (1.5pt) node[below=1.5pt, gksig]{$O$}; +\end{scope} + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Tower/arrangement.png b/docs/Figures/EMT/Tower/arrangement.png new file mode 100644 index 000000000..6012bcdf0 Binary files /dev/null and b/docs/Figures/EMT/Tower/arrangement.png differ diff --git a/docs/Figures/EMT/Tower/arrangement.tex b/docs/Figures/EMT/Tower/arrangement.tex new file mode 100644 index 000000000..23199e6cd --- /dev/null +++ b/docs/Figures/EMT/Tower/arrangement.tex @@ -0,0 +1,44 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../../utils/gridkit.tex} + +\begin{document} +\begin{tikzpicture}[gk] + +% ===================================================================== +% Three-phase + neutral conductor arrangement. Each conductor attaches +% to the tower at coordinate (x_i, H_i) above the earth and carries a +% phase label phi_i in {a,b,c,n}. H_i is the attachment height. +% ===================================================================== + +\def\Hp{3.4} % phase attachment height H_{a,b,c} +\def\Hn{4.7} % neutral attachment height H_n +\def\Ya{4.1} % crossarm level +\def\xa{-2.5}\def\xb{0}\def\xc{2.5} + +% ---- earth ---------------------------------------------------------- +\gkground{-5.0}{5.2}{0} + +% ---- tower: mast, crossarm, shield peak ---------------------------- +\draw[gkSteel, line width=2.3pt] (0,0) -- (0,\Ya); % main mast +\draw[gkSteel, line width=2.3pt] (0,\Ya) -- (0,\Hn); % shield peak +\draw[gkSteel, line width=2.3pt] (-2.95,\Ya) -- (2.95,\Ya); % crossarm + +% ---- insulator strings + phase conductors -------------------------- +\foreach \x in {\xa,\xb,\xc}{\draw[gkSteel, thin] (\x,\Ya) -- (\x,\Hp);} +\fill[gkconddot] (\xa,\Hp) circle (3.6pt); +\fill[gkconddot] (\xb,\Hp) circle (3.6pt); +\fill[gkconddot] (\xc,\Hp) circle (3.6pt); +\fill[gkconddot] (0,\Hn) circle (3.6pt); % neutral at apex + +% ---- phase labels phi_i (relevant info) ---------------------------- +\node[gksig, gkConductor, below=3.5pt] at (\xa,\Hp) {$a$}; +\node[gksig, gkConductor, below right=0pt and 3pt] at (\xb,\Hp) {$b$}; +\node[gksig, gkConductor, below=3.5pt] at (\xc,\Hp) {$c$}; +\node[gksig, gkConductor, above right=0pt and 2.5pt] at (0,\Hn) {$n$}; + +% ---- attachment height H_i above earth ----------------------------- +\draw[gkSteel, thin] (\xc,\Hp) -- (4.0,\Hp); +\gkdimv{3.8}{0}{\Hp}{$H_i$} + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Tower/diagram.png b/docs/Figures/EMT/Tower/diagram.png new file mode 100644 index 000000000..3f60fb538 Binary files /dev/null and b/docs/Figures/EMT/Tower/diagram.png differ diff --git a/docs/Figures/EMT/Tower/diagram.tex b/docs/Figures/EMT/Tower/diagram.tex new file mode 100644 index 000000000..a37d77e53 --- /dev/null +++ b/docs/Figures/EMT/Tower/diagram.tex @@ -0,0 +1,36 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../../utils/gridkit.tex} + +\begin{document} +\begin{tikzpicture}[gk] + +% --- ground, supports, conductor ------------------------------------- +\gkground{-5.6}{5.6}{-1.1} +\gkpole{-4}{-1.1}{1.687} +\gkpole{ 4}{-1.1}{1.687} +\gkcatenary{-4}{4}{5} + +% support-level chord and span-average (representative) level +\draw[gkguide] (-4,1.687) -- (4,1.687); +\draw[gkguide] (-4,0.551) -- (4,0.551); + +% --- span S (top) ---------------------------------------------------- +\draw[gkSteel, thin] (-4,1.687) -- (-4,2.62); +\draw[gkSteel, thin] ( 4,1.687) -- ( 4,2.62); +\gkdimh{-4}{4}{2.46}{$S$} + +% --- midspan sag D_i^sag -------------------------------------------- +\gkdimv{0}{1.687}{0}{$D_i^{\mathrm{sag}}$} + +% --- attachment height H_i (right) and representative height h_i ----- +\draw[gkSteel, thin] (4,1.687) -- (5.0,1.687); +\gkdimv{4.8}{-1.1}{1.687}{$H_i$} +\draw[gkSteel, thin] (-5.0,0.551) -- (-4,0.551); +\gkdimv{-4.8}{-1.1}{0.551}{$h_i$} + +% attachment dots last (top z-order) +\fill[gkSteel] (-4,1.687) circle (2.4pt); +\fill[gkSteel] ( 4,1.687) circle (2.4pt); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Tower/images.png b/docs/Figures/EMT/Tower/images.png new file mode 100644 index 000000000..01f4b6ebe Binary files /dev/null and b/docs/Figures/EMT/Tower/images.png differ diff --git a/docs/Figures/EMT/Tower/images.tex b/docs/Figures/EMT/Tower/images.tex new file mode 100644 index 000000000..fe91e9dff --- /dev/null +++ b/docs/Figures/EMT/Tower/images.tex @@ -0,0 +1,57 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../../utils/gridkit.tex} + +\begin{document} +\begin{tikzpicture}[gk] + +% ===================================================================== +% Method of images for the distance matrices. Conductors i, j sit at +% representative heights h_i, h_j above the earth; their mirror images +% i', j' lie at equal depth below it. The direct distance is D_ij and +% the image distance D'_ij; d_ij is the horizontal separation. +% D_ij = sqrt(d_ij^2 + (h_i - h_j)^2) +% D'_ij = sqrt(d_ij^2 + (h_i + h_j)^2) +% ===================================================================== + +\coordinate (ci) at (-2.3, 3.0); % conductor i +\coordinate (cj) at ( 2.6, 1.8); % conductor j +\coordinate (cim) at (-2.3,-3.0); % image i' +\coordinate (cjm) at ( 2.6,-1.8); % image j' + +% ---- earth (mirror plane) ------------------------------------------ +\gkground{-5.0}{5.2}{0} +\node[gksig, gkSteel] at (-4.55,0.34) {earth}; + +% mirror-correspondence guides +\draw[gkguide] (ci) -- (cim); +\draw[gkguide] (cj) -- (cjm); + +% ---- direct distance D_ij and image distance D'_ij ----------------- +\draw[gkSteel, semithick] (ci) -- (cj) + node[pos=0.5, above, gkdimlbl]{$D_{ij}$}; +\draw[gkimage] (ci) -- (cjm) + node[pos=0.78, gkdimlbl, text=gkImage]{$D'_{ij}$}; + +% ---- horizontal separation d_ij ------------------------------------ +\draw[gkSteel, thin] (ci) -- (-2.3,3.7); +\draw[gkSteel, thin] (cj) -- ( 2.6,3.7); +\gkdimh{-2.3}{2.6}{3.55}{$d_{ij}$} + +% ---- representative heights h_i, h_j and mirrored image depths ------ +\draw[gkSteel, thin] (ci) -- (-3.7, 3.0); +\draw[gkSteel, thin] (cim) -- (-3.7,-3.0); +\gkdimv{-3.7}{0}{ 3.0}{$h_i$} +\gkdimv{-3.7}{0}{-3.0}{$h_i$} +\draw[gkSteel, thin] (cj) -- ( 4.3, 1.8); +\draw[gkSteel, thin] (cjm) -- ( 4.3,-1.8); +\gkdimv{4.3}{0}{ 1.8}{$h_j$} +\gkdimv{4.3}{0}{-1.8}{$h_j$} + +% ---- conductors and images (top z-order) --------------------------- +\fill[gkconddot] (ci) circle (3.4pt) node[above left =-1pt and 0pt, gkConductor, gksig]{$i$}; +\fill[gkconddot] (cj) circle (3.4pt) node[above right=-1pt and 0pt, gkConductor, gksig]{$j$}; +\fill[gkimagedot] (cim) circle (3.4pt) node[below left =-1pt and 0pt, gkImage, gksig]{$i'$}; +\fill[gkimagedot] (cjm) circle (3.4pt) node[below right=-1pt and 0pt, gkImage, gksig]{$j'$}; + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/utils/gridkit.tex b/docs/Figures/utils/gridkit.tex new file mode 100644 index 000000000..f1a5e8e96 --- /dev/null +++ b/docs/Figures/utils/gridkit.tex @@ -0,0 +1,108 @@ +%% ===================================================================== +%% gridkit.tex — shared TikZ utilities for GridKit documentation figures +%% --------------------------------------------------------------------- +%% Usage (from docs/Figures///diagram.tex): +%% +%% \documentclass[tikz,border=12pt]{standalone} +%% \input{../../utils/gridkit.tex} +%% \begin{document} +%% \begin{tikzpicture}[gk] +%% ... +%% \end{tikzpicture} +%% \end{document} +%% +%% Naming: colors gk, styles gk, macros \gk. +%% `\documentclass[tikz,...]{standalone}` already loads TikZ; this file +%% only adds packages, libraries, colors, styles, and macros. +%% +%% Extending this file: +%% * New measurement -> add a \newcommand{\gk} in MACROS, keeping +%% the signature {}{