diff --git a/GridKit/Model/EMT/Bus/README.md b/GridKit/Model/EMT/Bus/README.md deleted file mode 100644 index 77c884144..000000000 --- a/GridKit/Model/EMT/Bus/README.md +++ /dev/null @@ -1,90 +0,0 @@ -# Bus Model - -`Bus` represents a three-phase bus in instantaneous abc coordinates. The -bus voltages are differential variables, and the model equations enforce -three-phase current balance at the bus. - -## Model Parameters - -None. - -## Model Derived Parameters - -None. - -## Model Variables - -### Internal Variables - -#### Differential - -Symbol | Units | Description | Note ----------|-------|--------------------|-------------------------------- -$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -### External Variables - -#### Differential - -None. - -#### Algebraic - -None. - -## Model Equations - -### Differential Equations - -An explicit representation for $\dot{\mathbf{v}}$ is not used because -the effective shunt admittances depend on connected components and are not -known at the bus level. The implicit DAE solver operates directly on -the accumulated KCL residual: - -``` math -\begin{aligned} -0 &= \sum_{e \in \mathcal{E}} \mathbf{i}^\text{inj}_e -\end{aligned} -``` - -where $\mathbf{i}^\text{inj}_e$ is the vector of phase-current injections -of connected component $e$ into the bus, which are a function of the bus voltage and bus voltage derivative. - -### Algebraic Equations - -None. - -## Initialization - -For a balanced three-phase initialization derived from the phasor voltage -$V = |V| \angle \phi$ and nominal angular frequency $\omega_0 = 2 \pi f_0$, - -``` math -\mathbf{v}(0) = \sqrt{2}\,|V| -\begin{bmatrix} - \cos(\phi) \\ - \cos(\phi - \tfrac{2\pi}{3}) \\ - \cos(\phi + \tfrac{2\pi}{3}) -\end{bmatrix} -``` - -and - -``` math -\dot{\mathbf{v}}(0) = -\sqrt{2}\,|V|\,\omega_0 -\begin{bmatrix} - \sin(\phi) \\ - \sin(\phi - \tfrac{2\pi}{3}) \\ - \sin(\phi + \tfrac{2\pi}{3}) -\end{bmatrix} -``` - -## Model Outputs - -Phase voltages $v_a$, $v_b$, and $v_c$ are monitorable model outputs. - -Phase-voltage derivatives $\dot{v}_a$, $\dot{v}_b$, and $\dot{v}_c$ are also available as monitorable outputs. diff --git a/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md b/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md deleted file mode 100644 index 0ec665ed2..000000000 --- a/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md +++ /dev/null @@ -1,121 +0,0 @@ -# BranchLumpedConstant Model - -`BranchLumpedConstant` represents a lumped-parameter EMT transmission line. -The nominal $\pi$-model is obtained by spatially discretizing the telegrapher equations over -a segment of length $\Delta x$, with a half shunt placed at each port. -Series current $\mathbf{i}$ is directed from bus 1 to bus 2. Bus residual -current injections are positive into buses. All electrical parameter matrices -are $3 \times 3$ and capture self and mutual coupling between phases. - -![](../../../../../../docs/Figures/EMT/lumped_constant_diagram.svg) - -Figure 1: Lumped constant EMT branch model - -## Model Parameters - -Symbol | Units | Description | Note ------------------|----------------|------------------------------------------|--------------------------------- -$\mathbf{R}'$ | [$\Omega$/m] | Series resistance matrix per unit length | $\mathbb{R}^{3 \times 3}$ -$\mathbf{L}'$ | [H/m] | Series inductance matrix per unit length | $\mathbb{R}^{3 \times 3}$ -$\mathbf{G}'$ | [S/m] | Shunt conductance matrix per unit length | $\mathbb{R}^{3 \times 3}$ -$\mathbf{C}'$ | [F/m] | Shunt capacitance matrix per unit length | $\mathbb{R}^{3 \times 3}$ -$\Delta x$ | [m] | Line segment length | $\mathbb{R}$ - -## Model Derived Parameters - -``` math -\begin{aligned} - \mathbf{R} &= \mathbf{R}'\Delta x & \mathbf{G} &= \mathbf{G}'\Delta x \\ - \mathbf{L} &= \mathbf{L}'\Delta x & \mathbf{C} &= \mathbf{C}'\Delta x -\end{aligned} -``` - -## Model Variables - -### Internal Variables - -#### Differential - -Symbol | Units | Description | Note ------------------|--------|-----------------------|--------------------------------- -$\mathbf{i}$ | [A] | Series branch current, directed bus 1 to bus 2 | $\mathbf{i} = [i_a, i_b, i_c]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -### External Variables - -External variables enter component model equations but are owned by -other components. The EMT bus at each port owns the voltage -variable and provides the equation needed to have a balanced system -of equations. - -#### Differential - -Symbol | Units | Description | Note ------------------|--------|--------------------------|------------------ -$\mathbf{v}_1$ | [V] | Port voltage at bus 1, owned by bus 1 | $\mathbf{v}_1 = [v_{1,a}, v_{1,b}, v_{1,c}]^T \in \mathbb{R}^3$ -$\mathbf{v}_2$ | [V] | Port voltage at bus 2, owned by bus 2 | $\mathbf{v}_2 = [v_{2,a}, v_{2,b}, v_{2,c}]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -## Model Equations - -### Differential Equations - - -``` math -0 = \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v}_2 - \mathbf{v}_1 -``` - -### Algebraic Equations - -None. - -### Bus Residual Contributions - -The lumped line contributes to the KCL residual at each port bus. -Each expression is accumulated into the owning bus residual. - -``` math -\mathbf{i}^\text{inj}_1 := - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_1 - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_1 - \mathbf{i} -``` - -``` math -\mathbf{i}^\text{inj}_2 := - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_2 - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_2 + \mathbf{i} -``` - -## Initialization - -The initialization assumes a balanced three-phase system. Given bus -voltages $\mathbf{v}_1(0)$, $\mathbf{v}_2(0)$ and their time -derivatives $\dot{\mathbf{v}}_1(0)$, $\dot{\mathbf{v}}_2(0)$ from -the EMT bus, and the power flow phasor series current -$I = |I| \angle \theta$, the initial series current is: - -``` math -\mathbf{i}(0) = \sqrt{2}\,|I| -\begin{bmatrix} - \cos(\theta) \\ - \cos(\theta - \tfrac{2\pi}{3}) \\ - \cos(\theta + \tfrac{2\pi}{3}) -\end{bmatrix} -``` - -The initial derivative is then given by the series branch equation for -DAE consistency: - -``` math -\dot{\mathbf{i}}(0) = \mathbf{L}^{-1}\left(\mathbf{v}_1(0) - \mathbf{v}_2(0) - \mathbf{R}\,\mathbf{i}(0)\right) -``` - -## Model Outputs - -Candidate monitorable outputs include the series branch current components -$i_a$, $i_b$, and $i_c$. - -Port current injection expressions are documented above as -$\mathbf{i}^\text{inj}_1$ and $\mathbf{i}^\text{inj}_2$. diff --git a/GridKit/Model/EMT/Component/Branch/README.md b/GridKit/Model/EMT/Component/Branch/README.md deleted file mode 100644 index 2c61d4bf5..000000000 --- a/GridKit/Model/EMT/Component/Branch/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Branch Model - -## Introduction - -EMT branch models represent three-phase network connections between buses in instantaneous abc coordinates. - -## Types - -### Lumped Parameter - -Lumped transmission line models approximate the branch with finite network elements (sometimes referred to as the $\pi$-model). GridKit currently only implements constant parameter. - -- `BranchLumpedConstant` (See [BranchLumpedConstant](BranchLumpedConstant/README.md)) -- `BranchLumpedFrequencyDependent` - -### Distributed Parameter - -Distributed transmission line models preserve traveling-wave propagation and delay. GridKit cannot implement these until model internal signal delays are supported. - -- `BranchDistributedConstant` -- `BranchDistributedFrequencyDependent` diff --git a/GridKit/Model/EMT/Component/Bus/README.md b/GridKit/Model/EMT/Component/Bus/README.md new file mode 100644 index 000000000..2c771cf08 --- /dev/null +++ b/GridKit/Model/EMT/Component/Bus/README.md @@ -0,0 +1,90 @@ +# Bus Model + +`Bus` represents an $N$-phase bus in instantaneous phase coordinates. The +bus voltages are differential variables, and the model equations enforce +current balance at the bus. + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$M$ | [-] | `M` | Number of connected-device ports | Required, positive integer +$N$ | [-] | `N` | Number of phases | Required, positive integer +$\mathbf{v}_0$ | [V] | `v0` | Initial bus voltage vector | $\mathbf{v}_0 \in \mathbb{R}^N$ + +### Parameter Validation + +```math +\begin{aligned} +M &> 0 \\ +N &> 0 \\ +\mathbf{v}_0 &\in \mathbb{R}^N +\end{aligned} +``` + +### Model Derived Parameters + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}^{\mathrm{inj}}_m$ | `i` | Input | [A] | Current injection from connected device $m$ | $m=1,\ldots,M$, $\mathbf{i}^{\mathrm{inj}}_m \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= \sum_{m=1}^{M} \mathbf{i}^{\mathrm{inj}}_m +\end{aligned} +``` + +Each $\mathbf{i}^{\mathrm{inj}}_m$ may depend on the bus voltage and bus voltage derivative. + +### Algebraic Equations + +None. + +## Initialization + +The initial bus voltage is given by the parameter vector $\mathbf{v}_0$: + +```math +\mathbf{v}(0)=\mathbf{v}_0 +``` + +Only $\mathbf{v}(0)$ is initialized. The solver computes +$\dot{\mathbf{v}}(0)$ from the differential residual. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`v` | [V] | Bus voltage | $\mathbf{v} \in \mathbb{R}^N$ diff --git a/GridKit/Model/EMT/Component/Line/LineDistributed/README.md b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md new file mode 100644 index 000000000..91fb9e5ec --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md @@ -0,0 +1,137 @@ +# LineDistributed Model + +`LineDistributed` represents a distributed EMT line with characteristic +admittance $\mathbf{y}_c$ and propagation model $\mathbf{h}$. + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/LineDistributed/diagram.png) + +Figure 1: LineDistributed model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +----------------- | ----- | ------------ | ------------------------------------------------------ | ---- +$\mathbf{P}_\phi$ | [-] | `conductors` | Permutation matrix mapping each conductor to its phase | $\mathbf{P}_\phi \in \mathbb{R}^{N \times K}$ + +### Parameter Validation + +None. + +### Model Derived Parameters + +The number of phases $N$ and conductors $K$ are the row and column counts of +$\mathbf{P}_\phi$, respectively. + +### Submodels + +Submodel | Inputs | Parameters | Outputs +-------- | ------ | ---------- | ------- +[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) characteristic admittance $\mathbf{y}_c$ | $\mathbf{v}_{1}\in\mathbb{R}^N$ | `Yc` | $\mathbf{i}^{\mathrm{sh}}_{1}\in\mathbb{R}^K$ +[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) characteristic admittance $\mathbf{y}_c$ | $\mathbf{v}_{2}\in\mathbb{R}^N$ | `Yc` | $\mathbf{i}^{\mathrm{sh}}_{2}\in\mathbb{R}^K$ +[`Propagation`](../../../Operators/Shift/Propagation/README.md) $\mathbf{h}$ | $2\mathbf{i}^{\mathrm{sh}}_{2}-\mathbf{i}^{\mathrm{inc}}_{2}$ | `H` | $\mathbf{i}^{\mathrm{inc}}_{1}\in\mathbb{R}^K$ +[`Propagation`](../../../Operators/Shift/Propagation/README.md) $\mathbf{h}$ | $2\mathbf{i}^{\mathrm{sh}}_{1}-\mathbf{i}^{\mathrm{inc}}_{1}$ | `H` | $\mathbf{i}^{\mathrm{inc}}_{2}\in\mathbb{R}^K$ + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +External variables are owned by the EMT bus. + +#### Differential + +Symbol | Units | Description | Note +-------------------------------------|-------|------------------------------------------|----- +$\mathbf{v}_{1}$ | [V] | Terminal `1` voltage owned by EMT bus | $\mathbf{v}_{1} \in \mathbb{R}^N$ +$\mathbf{v}_{2}$ | [V] | Terminal `2` voltage owned by EMT bus | $\mathbf{v}_{2} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}^{\mathrm{inj}}_{1}$ | `i1` | Output | [A] | Current injection at terminal `1` | $\mathbf{i}^{\mathrm{inj}}_{1} \in \mathbb{R}^N$ +$\mathbf{i}^{\mathrm{inj}}_{2}$ | `i2` | Output | [A] | Current injection at terminal `2` | $\mathbf{i}^{\mathrm{inj}}_{2} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +### Wiring + +```math +\begin{aligned} +\mathbf{i}^{\mathrm{sh}}_{1} &= + \mathbf{y}_c*\mathbf{v}_{1} \\ +\mathbf{i}^{\mathrm{sh}}_{2} &= + \mathbf{y}_c*\mathbf{v}_{2} \\ +\mathbf{i}^{\mathrm{inc}}_{1} &= + \mathbf{h}*\left( + 2\mathbf{i}^{\mathrm{sh}}_{2} + - + \mathbf{i}^{\mathrm{inc}}_{2} + \right) \\ +\mathbf{i}^{\mathrm{inc}}_{2} &= + \mathbf{h}*\left( + 2\mathbf{i}^{\mathrm{sh}}_{1} + - + \mathbf{i}^{\mathrm{inc}}_{1} + \right) \\ +\mathbf{i}^{\mathrm{inj}}_{1} &= + \mathbf{P}_\phi\left( + \mathbf{i}^{\mathrm{inc}}_{1} + - + \mathbf{i}^{\mathrm{sh}}_{1} + \right) \\ +\mathbf{i}^{\mathrm{inj}}_{2} &= + \mathbf{P}_\phi + \left( + \mathbf{i}^{\mathrm{inc}}_{2} + - + \mathbf{i}^{\mathrm{sh}}_{2} + \right) +\end{aligned} +``` + +## Initialization + +Let subscript $0$ denote initial values. Initial values satisfy the wiring +equations: + +```math +\begin{aligned} +\mathbf{i}^{\mathrm{sh}}_{1,0} &= \mathbf{y}_c*\mathbf{v}_{1,0} \\ +\mathbf{i}^{\mathrm{sh}}_{2,0} &= \mathbf{y}_c*\mathbf{v}_{2,0} \\ +\mathbf{i}^{\mathrm{inc}}_{1,0} &= \mathbf{h}*\left(2\mathbf{i}^{\mathrm{sh}}_{2,0} - \mathbf{i}^{\mathrm{inc}}_{2,0}\right) \\ +\mathbf{i}^{\mathrm{inc}}_{2,0} &= \mathbf{h}*\left(2\mathbf{i}^{\mathrm{sh}}_{1,0} - \mathbf{i}^{\mathrm{inc}}_{1,0}\right) +\end{aligned} +``` + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i_sh_1` | [A] | Shunt current at terminal `1` | $\mathbf{i}^{\mathrm{sh}}_{1} \in \mathbb{R}^K$ +`i_sh_2` | [A] | Shunt current at terminal `2` | $\mathbf{i}^{\mathrm{sh}}_{2} \in \mathbb{R}^K$ +`i_inc_1` | [A] | Incident current at terminal `1` | $\mathbf{i}^{\mathrm{inc}}_{1} \in \mathbb{R}^K$ +`i_inc_2` | [A] | Incident current at terminal `2` | $\mathbf{i}^{\mathrm{inc}}_{2} \in \mathbb{R}^K$ diff --git a/GridKit/Model/EMT/Component/Line/LineLumped/README.md b/GridKit/Model/EMT/Component/Line/LineLumped/README.md new file mode 100644 index 000000000..b4dce478b --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/LineLumped/README.md @@ -0,0 +1,125 @@ +# LineLumped Model + +`LineLumped` represents a lumped-parameter EMT transmission line using a +$\pi$-section equivalent over length $\Delta x$. Series current $\mathbf{i}$ +is directed from terminal 1 to terminal 2. + +Notes: +- $\mathbf{Z}'$ and $\mathbf{Y}'$ may be supplied as per-unit-length + `VectorFit` models or derived from constant `Rp`, `Lp`, `Gp`, and `Cp` + matrices. + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/LineLumped/diagram.png) + +Figure 1: LineLumped model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +---------------- | ------------ | ---- | ---------------------------------- | ---- +$\mathbf{Z}'$ | [$\Omega$/m] | `Zp` | Series impedance per unit length | $\mathbf{Z}'\in\mathbb{C}^{N \times N}$ +$\mathbf{Y}'$ | [S/m] | `Yp` | Shunt admittance per unit length | $\mathbf{Y}'\in\mathbb{C}^{N \times N}$ +$\Delta x$ | [m] | `dx` | Line segment length | $\mathbb{R}$ + +### Parameter Validation + +None. + +### Model Derived Parameters + +The per-unit-length impedance and admittance models are: + +```math +\begin{aligned} + \mathbf{Z}'(s) &= \mathbf{R}' + s\mathbf{L}' + \mathbf{Z}'_{\mathrm{rat}}(s) \\ + \mathbf{Y}'(s) &= \mathbf{G}' + s\mathbf{C}' + \mathbf{Y}'_{\mathrm{rat}}(s) +\end{aligned} +``` + +The segment impedance and shunt admittance operators used by the equations are: + +```math +\begin{aligned} + \mathbf{Z} &= \Delta x \mathbf{Z}' \\ + \mathbf{Y} &= \dfrac{\Delta x \mathbf{Y}'}{2} +\end{aligned} +``` + +### Submodels + +Submodel | Inputs | Parameters | Outputs +-------- | ------ | ---------- | ------- +[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) series impedance $\mathbf{z}$ | $\mathbf{i}\in\mathbb{R}^N$ | `Zp`, `dx` | $\mathbf{z}*\mathbf{i}$ +[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) shunt admittance $\mathbf{y}_1$ | $\mathbf{v}_1\in\mathbb{R}^N$ | `Yp`, `dx` | $\mathbf{y}_1*\mathbf{v}_1$ +[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) shunt admittance $\mathbf{y}_2$ | $\mathbf{v}_2\in\mathbb{R}^N$ | `Yp`, `dx` | $\mathbf{y}_2*\mathbf{v}_2$ + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +-----------------|--------|-----------------------|--------------------------------- +$\mathbf{i}$ | [A] | Series current, directed terminal `1` to terminal `2` | $\mathbf{i} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +-----------------|--------|--------------------------|------------------ +$\mathbf{v}_1$ | [V] | Terminal `1` voltage owned by EMT bus | $\mathbf{v}_1 \in \mathbb{R}^N$ +$\mathbf{v}_2$ | [V] | Terminal `2` voltage owned by EMT bus | $\mathbf{v}_2 \in \mathbb{R}^N$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}^{\mathrm{inj}}_{1}$ | `i1` | Output | [A] | Current injection at terminal `1` | $\mathbf{i}^{\mathrm{inj}}_{1} \in \mathbb{R}^N$ +$\mathbf{i}^{\mathrm{inj}}_{2}$ | `i2` | Output | [A] | Current injection at terminal `2` | $\mathbf{i}^{\mathrm{inj}}_{2} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +0 = \mathbf{z}*\mathbf{i}+ \mathbf{v}_2 - \mathbf{v}_1 +``` + +### Algebraic Equations + +None. + +### Wiring + +```math +\begin{aligned} +\mathbf{i}^{\mathrm{inj}}_{1} &= + - \mathbf{y}_1*\mathbf{v}_1 + - \mathbf{i} \\ +\mathbf{i}^{\mathrm{inj}}_{2} &= + - \mathbf{y}_2*\mathbf{v}_2 + + \mathbf{i} +\end{aligned} +``` + +## Initialization + +Since this component is a member of the network, the power flow solution must initialize this model. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i` | [A] | Series current | $\mathbf{i} \in \mathbb{R}^N$ diff --git a/GridKit/Model/EMT/Component/Line/README.md b/GridKit/Model/EMT/Component/Line/README.md new file mode 100644 index 000000000..1c28bad8d --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/README.md @@ -0,0 +1,145 @@ +# Line Model + +EMT line models represent network connections between buses in instantaneous +phase coordinates. + +## Types + +Lumped transmission line models approximate the line with finite network +elements, sometimes referred to as the $\pi$-model. + +Distributed transmission line models preserve propagation and delay. +The formulation allows this model to be used for either constant or +frequency-dependent line parameters. + +- `LineLumped` (See [documentation](LineLumped/README.md)) +- `LineDistributed` (See [documentation](LineDistributed/README.md)) + +## Examples + +The snippets below show model composition only. Final `.case.json` syntax may +change when the EMT line models are implemented. + +### Nominal Pi Model + +The nominal pi model is the constant-parameter lumped case. + +```js +{ + "class": "LineLumped", + "params": { + "Rp": ..., + "Lp": ..., + "Gp": ..., + "Cp": ..., + "dx": ... + } +} +``` + +### Frequency-Dependent Pi Model + +The frequency-dependent pi model keeps the lumped topology and replaces the +constant line matrices with rational parameter models. +Note: using `VectorFit` models for `Zp` and `Yp` with no poles or residues +is an equivalent way to define the nominal pi model: for `Zp`, +$\mathbf{D}=\mathbf{R}'$ and $\mathbf{E}=\mathbf{L}'$. For `Yp`, +$\mathbf{D}=\mathbf{G}'$ and $\mathbf{E}=\mathbf{C}'$. + +```js +{ + "class": "LineLumped", + "params": { + "Zp": { + "class": "VectorFit", + "params": { + "D": ..., + "E": ..., + "poles": [...], + "residues": [...] + } + }, + "Yp": { + "class": "VectorFit", + "params": { + "D": ..., + "E": ..., + "poles": [...], + "residues": [...] + } + }, + "dx": ... + } +} +``` + +### Bergeron Model + +The constant parameter case uses constant characteristic admittance +$\mathbf{y}_c=\mathbf{Y}_0$ and a lossless transport delay +$\mathbf{H}(s)=e^{-s\tau}$. + +```js +{ + "class": "LineDistributed", + "params": { + "conductors": [...], + "Yc": ..., + "H": { + "class": "Delay", + "params": { + "tau": ..., + "fmax": ... + } + } + } +} +``` + +### Universal Line Model + +The ULM is the general case with characteristic admittance `Yc` and +current-form propagation function `H`. + +```js +{ + "class": "LineDistributed", + "params": { + "conductors": [...], + "Yc": { + "class": "VectorFit", + "params": { + "D": ..., + "E": ..., + "poles": [...], + "residues": [...] + } + }, + "H": { + "class": "Propagation", + "params": { + "input": { + "class": "VectorFit", + "params": { + "D": ..., + "E": ..., + "poles": [...], + "residues": [...] + } + }, + "tau": [...], + "fmax": ..., + "output": { + "class": "VectorFit", + "params": { + "D": ..., + "E": ..., + "poles": [...], + "residues": [...] + } + } + } + } + } +} +``` diff --git a/GridKit/Model/EMT/Component/Load/LoadRL/README.md b/GridKit/Model/EMT/Component/Load/LoadRL/README.md new file mode 100644 index 000000000..51b4673ca --- /dev/null +++ b/GridKit/Model/EMT/Component/Load/LoadRL/README.md @@ -0,0 +1,109 @@ +# LoadRL Model + +`LoadRL` represents a three-phase RL load in instantaneous abc coordinates. +The load owns the three-phase differential current vector $\mathbf{i}$, +which is the current injection from the load into the EMT bus. + +## Model Parameters + +Symbol | Units | JSON | Description | Note +--------|------------|------|-------------------------|----- +$R_a$ | [$\Omega$] | `Ra` | Load resistance, phase a | +$R_b$ | [$\Omega$] | `Rb` | Load resistance, phase b | +$R_c$ | [$\Omega$] | `Rc` | Load resistance, phase c | +$L_a$ | [H] | `La` | Load inductance, phase a | +$L_b$ | [H] | `Lb` | Load inductance, phase b | +$L_c$ | [H] | `Lc` | Load inductance, phase c | + +### Parameter Validation + +```math +\begin{aligned} +R_a, R_b, R_c &\ge 0 \\ +L_a, L_b, L_c &> 0 +\end{aligned} +``` + +### Model Derived Parameters + +```math +\begin{aligned} + \mathbf{R} &= \operatorname{diag}(R_a, R_b, R_c) \\ + \mathbf{L} &= \operatorname{diag}(L_a, L_b, L_c) +\end{aligned} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +--------------------|-------|------------------------------------------------|--------------------------------- +$\mathbf{i}$ | [A] | Current injection from load into EMT bus | $\mathbf{i} = [i_a, i_b, i_c]^T \in \mathbb{R}^3$ + +#### Algebraic + +None. + +### External Variables + +External variables are owned by the EMT bus. + +#### Differential + +Symbol | Units | Description | Note +-----------------|-------|----------------------------------------------|--------------------------------- +$\mathbf{v}$ | [V] | Port voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}^{\mathrm{inj}}$ | `i` | Output | [A] | Current injection at load port | $\mathbf{i}^{\mathrm{inj}} \in \mathbb{R}^3$ + +## Model Equations + +### Differential Equations + +```math +0 = \mathbf{R}\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v} +``` + +### Algebraic Equations + +None. + +### Wiring + +```math +\mathbf{i}^{\mathrm{inj}} = \mathbf{i} +``` + +## Initialization + +For a balanced three-phase initialization derived from phasor current injection +$I^{\mathrm{inj}} = |I^{\mathrm{inj}}| \angle \theta$: + +```math +\mathbf{i}_0 = \sqrt{2}|I^{\mathrm{inj}}| +\begin{bmatrix} + \cos(\theta) \\ + \cos(\theta - \tfrac{2\pi}{3}) \\ + \cos(\theta + \tfrac{2\pi}{3}) +\end{bmatrix} +``` + +Only $\mathbf{i}_0$ is initialized. The solver computes +$\dot{\mathbf{i}}_0$ from the differential residual. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i` | [A] | Load current injection | $\mathbf{i} \in \mathbb{R}^3$ diff --git a/GridKit/Model/EMT/Component/Load/README.md b/GridKit/Model/EMT/Component/Load/README.md new file mode 100644 index 000000000..8fdfa2c16 --- /dev/null +++ b/GridKit/Model/EMT/Component/Load/README.md @@ -0,0 +1,3 @@ +# Load Models + +- `LoadRL` (See [LoadRL](LoadRL/README.md)) diff --git a/GridKit/Model/EMT/Component/LoadRL/README.md b/GridKit/Model/EMT/Component/LoadRL/README.md deleted file mode 100644 index e4cff5970..000000000 --- a/GridKit/Model/EMT/Component/LoadRL/README.md +++ /dev/null @@ -1,104 +0,0 @@ -# LoadRL Model - -`LoadRL` represents a three-phase RL load in instantaneous abc coordinates. -The load owns the three-phase differential current vector $\mathbf{i}$, -which is directed from the load into the bus. - -## Model Parameters - -Symbol | Units | Description | Note ---------|------------|----------------------------|-------------------------------- -$R_a$ | [$\Omega$] | Load resistance, phase a | -$R_b$ | [$\Omega$] | Load resistance, phase b | -$R_c$ | [$\Omega$] | Load resistance, phase c | -$L_a$ | [H] | Load inductance, phase a | -$L_b$ | [H] | Load inductance, phase b | -$L_c$ | [H] | Load inductance, phase c | - -## Model Derived Parameters - -``` math -\begin{aligned} - \mathbf{R} &= \operatorname{diag}(R_a, R_b, R_c) \\ - \mathbf{L} &= \operatorname{diag}(L_a, L_b, L_c) -\end{aligned} -``` - -## Model Variables - -### Internal Variables - -#### Differential - -Symbol | Units | Description | Note ---------------------|-------|------------------------------------------------|--------------------------------- -$\mathbf{i}$ | [A] | Load current vector, directed from load into bus | $\mathbf{i} = [i_a, i_b, i_c]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -### External Variables - -External variables enter component model equations but are owned by -other components. The EMT bus at the load port owns the voltage -variable and provides the equation needed to have a balanced system -of equations. - -#### Differential - -Symbol | Units | Description | Note ------------------|-------|----------------------------------------------|--------------------------------- -$\mathbf{v}$ | [V] | Port voltage vector, owned by EMT bus | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -## Model Equations - -### Differential Equations - -``` math -0 = \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v} -``` - -### Algebraic Equations - -None. - -### Bus Residual Contributions - -The RL load contributes to the KCL residual at its port bus. The -expression is accumulated into the owning bus residual. - -``` math -\mathbf{i}^\text{inj} := \mathbf{i} -``` - -## Initialization - -The initialization assumes a balanced three-phase system. Given the power -flow phasor load current $I = |I| \angle \theta$, the initial load -current is: - -``` math -\mathbf{i}(0) = \sqrt{2}\,|I| -\begin{bmatrix} - \cos(\theta) \\ - \cos(\theta - \tfrac{2\pi}{3}) \\ - \cos(\theta + \tfrac{2\pi}{3}) -\end{bmatrix} -``` - -The initial derivative is then given by the RL load equation for DAE -consistency: - -``` math -\dot{\mathbf{i}}(0) = -\mathbf{L}^{-1}\left(\mathbf{v}(0) + \mathbf{R}\,\mathbf{i}(0)\right) -``` - -## Model Outputs - -Candidate monitorable outputs include the load current components $i_a$, $i_b$, -and $i_c$ into the bus. diff --git a/GridKit/Model/EMT/Component/README.md b/GridKit/Model/EMT/Component/README.md index f394ca4e7..d87c6633e 100644 --- a/GridKit/Model/EMT/Component/README.md +++ b/GridKit/Model/EMT/Component/README.md @@ -3,16 +3,17 @@ This directory contains EMT component model notes for devices connected to EMT buses. -A component README should include: +A model README should include: 1. Model parameters and derived parameters 2. Internal and external variables 3. Differential and algebraic equations -4. Bus residual contributions, when applicable +4. Wiring equations, when applicable 5. Initialization notes 6. Monitorable outputs -## Types +## Directories -- `BranchLumpedConstant` (See [BranchLumpedConstant](Branch/BranchLumpedConstant/README.md)) -- `LoadRL` (See [LoadRL](LoadRL/README.md)) -- `VoltageSource` (See [VoltageSource](VoltageSource/README.md)) +- `Bus` (See [Bus](Bus/README.md)) +- `Line` (See [Line](Line/README.md)) +- `Load` (See [Load](Load/README.md)) +- `Source` (See [Source](Source/README.md)) diff --git a/GridKit/Model/EMT/Component/Source/README.md b/GridKit/Model/EMT/Component/Source/README.md new file mode 100644 index 000000000..f295507a7 --- /dev/null +++ b/GridKit/Model/EMT/Component/Source/README.md @@ -0,0 +1,6 @@ +# Source Models + +Source models prescribe EMT waveforms and inject currents into EMT buses through +wiring equations. + +- `VoltageSource` (See [VoltageSource](VoltageSource/README.md)) diff --git a/GridKit/Model/EMT/Component/Source/VoltageSource/README.md b/GridKit/Model/EMT/Component/Source/VoltageSource/README.md new file mode 100644 index 000000000..03a20dcb3 --- /dev/null +++ b/GridKit/Model/EMT/Component/Source/VoltageSource/README.md @@ -0,0 +1,100 @@ +# VoltageSource Model + +`VoltageSource` represents a sinusoidal EMT voltage source in instantaneous +phase coordinates. The source voltage vector is connected to the EMT bus +through terminal conductance $\mathbf{g}_{\mathrm{s}}$. + +## Model Parameters + +For phase count $N$: + +Symbol | Units | JSON | Description | Note +-------------------------------|---------|----------|-----------------------------------|----- +$\mathbf{E}$ | [V] | `E` | Source voltage magnitudes | $\mathbf{E}\in\mathbb{R}^N$, RMS +$\boldsymbol{\phi}$ | [rad] | `phi` | Source phase offsets | $\boldsymbol{\phi}\in\mathbb{R}^N$ +$\omega$ | [rad/s] | `omega` | Source angular frequency | +$\mathbf{g}_{\mathrm{s}}$ | [S] | `G` | Terminal conductance | $\mathbf{g}_{\mathrm{s}}\in\mathbb{R}^N$ + +### Parameter Validation + +```math +\begin{aligned} +\mathbf{E} &\ge \mathbf{0} \\ +\omega &> 0 \\ +\mathbf{g}_{\mathrm{s}} &> \mathbf{0} +\end{aligned} +``` + +### Model Derived Parameters + +The phase count $N$ is the length of $\mathbf{E}$. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +External variables are owned by the EMT bus. + +#### Differential + +Symbol | Units | Description | Note +-----------------|-------|----------------------------------------------|--------------------------------- +$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}^{\mathrm{inj}}$ | `i` | Output | [A] | Current injection at source port | $\mathbf{i}^{\mathrm{inj}} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +### Wiring + +```math +i^{\mathrm{inj}}_n += +g_{\mathrm{s},n} +\left( +\sqrt{2}E_n\cos\left(\omega t + \phi_n\right) - v_n +\right) +``` + +## Initialization + +No internal state is initialized. Initial values satisfy the wiring equations: + +```math +i^{\mathrm{inj}}_{n,0} += +g_{\mathrm{s},n} +\left( +\sqrt{2}E_n\cos\left(\phi_n\right) - v_{n,0} +\right) +``` + +## Monitors + +None. diff --git a/GridKit/Model/EMT/Component/VoltageSource/README.md b/GridKit/Model/EMT/Component/VoltageSource/README.md deleted file mode 100644 index df6277ecf..000000000 --- a/GridKit/Model/EMT/Component/VoltageSource/README.md +++ /dev/null @@ -1,109 +0,0 @@ -# VoltageSource Model - -`VoltageSource` represents a three-phase voltage source in instantaneous abc -coordinates. The source waveform is configurable by phase magnitude and phase -offset for each phase and is otherwise constant. Each source port is -connected to the EMT bus through a phase resistance. - -## Model Parameters - -Symbol | Units | Description | Note ---------------|------------|-------------------------------------|-------------------------------- -$E_a$ | [V] | Source voltage magnitude, phase a | RMS -$E_b$ | [V] | Source voltage magnitude, phase b | RMS -$E_c$ | [V] | Source voltage magnitude, phase c | RMS -$\phi_a$ | [rad] | Source phase offset, phase a | -$\phi_b$ | [rad] | Source phase offset, phase b | -$\phi_c$ | [rad] | Source phase offset, phase c | -$\omega_0$ | [rad/s] | Source angular frequency | -$R_a$ | [$\Omega$] | Terminal resistance, phase a | -$R_b$ | [$\Omega$] | Terminal resistance, phase b | -$R_c$ | [$\Omega$] | Terminal resistance, phase c | - -## Model Derived Parameters - -None. - -## Model Variables - -### Internal Variables - -#### Differential - -None. - -#### Algebraic - -None. - -### External Variables - -External variables enter component model equations but are owned by -other components. The EMT bus at the source port owns the voltage -variable and provides the equation needed to have a balanced system -of equations. - -#### Differential - -Symbol | Units | Description | Note ------------------|-------|----------------------------------------------|--------------------------------- -$\mathbf{v}$ | [V] | Port voltage vector, owned by EMT bus | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$ - -#### Algebraic - -None. - -## Model Equations - -### Differential Equations - -None. - -### Algebraic Equations - -None. - -### Bus Residual Contributions - -The source contributes current to the KCL residual at its port bus. -The injection vector is accumulated into the owning bus residual. Given source -angular frequency $\omega_0$, the source waveform is: - -``` math -\begin{aligned} -e_a(t) &= \sqrt{2}\,E_a\cos(\omega_0 t + \phi_a) \\ -e_b(t) &= \sqrt{2}\,E_b\cos(\omega_0 t + \phi_b) \\ -e_c(t) &= \sqrt{2}\,E_c\cos(\omega_0 t + \phi_c) -\end{aligned} -``` - -The current contribution is positive into the bus: - -``` math -\mathbf{i}^\text{inj} := -\begin{bmatrix} - \dfrac{e_a(t)-v_a}{R_a} \\ - \dfrac{e_b(t)-v_b}{R_b} \\ - \dfrac{e_c(t)-v_c}{R_c} -\end{bmatrix} -``` - -## Initialization - -No internal state is initialized. At $t = 0$, the source waveform is: - -``` math -\begin{aligned} -e_a(0) &= \sqrt{2}\,E_a\cos(\phi_a) \\ -e_b(0) &= \sqrt{2}\,E_b\cos(\phi_b) \\ -e_c(0) &= \sqrt{2}\,E_c\cos(\phi_c) -\end{aligned} -``` - -## Model Outputs - -Candidate monitorable outputs include the source waveform components -$e_a(t)$, $e_b(t)$, and $e_c(t)$. - -The port current injection expression is documented above as -$\mathbf{i}^\text{inj}$. diff --git a/GridKit/Model/EMT/Operators/README.md b/GridKit/Model/EMT/Operators/README.md new file mode 100644 index 000000000..b090d4e69 --- /dev/null +++ b/GridKit/Model/EMT/Operators/README.md @@ -0,0 +1,8 @@ +# Operator Models + +Operator models are reusable EMT signal blocks used by component models. + +## Directories + +- `Rational` (See [Rational](Rational/README.md)) +- `Shift` (See [Shift](Shift/README.md)) diff --git a/GridKit/Model/EMT/Operators/Rational/README.md b/GridKit/Model/EMT/Operators/Rational/README.md new file mode 100644 index 000000000..46e90507b --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/README.md @@ -0,0 +1,4 @@ +# Rational Operators + +- `VectorFit` (See [VectorFit](VectorFit/README.md)) +- `StateSpace` (See [StateSpace](StateSpace/README.md)) diff --git a/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md b/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md new file mode 100644 index 000000000..2939c2957 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md @@ -0,0 +1,154 @@ +# StateSpace Model + +`StateSpace` represents a vector-fitted matrix rational approximation with +complex poles and factorized residues. + +Notes: +- This cannot be used in general to replace `VectorFit`, as that model can support full-rank residuals, while this only supports rank-1 residuals. + +The rational approximation is represented in state-space form: + +```math +\mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} + + \mathbf{C}(s\mathbf{I} - \mathbf{P})^{-1}\mathbf{B} +``` +The Laplace domain representation of this model is: +```math +\mathbf{Y}(s) = \mathbf{H}(s)\mathbf{U}(s) +``` + +The time domain representation of this model is: +```math +\mathbf{y}(t) = (\mathbf{h}*\mathbf{u})(t) +``` + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/StateSpace/diagram.png) + +Figure 1: StateSpace rational approximation model + +## Model Parameters + +For output dimension $N$, input dimension $K$, and pole count $Q$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\mathbf{D}$ | [-] | `D` | Constant coefficient | $\mathbf{D}\in\mathbb{R}^{N\times K}$ +$\mathbf{E}$ | [s] | `E` | Linear coefficient | $\mathbf{E}\in\mathbb{R}^{N\times K}$ +$\mathbf{p}$ | [1/s] | `poles` | Poles | $\mathbf{p}\in\mathbb{C}^Q$ +$\mathbf{C}$ | [-] | `C` | Output matrix | $\mathbf{C}\in\mathbb{C}^{N\times Q}$ +$\mathbf{B}$ | [1/s] | `B` | Input matrix | $\mathbf{B}\in\mathbb{C}^{Q\times K}$ + +### Parameter Validation + +Complex-valued poles and factors must be ordered as adjacent conjugate pairs. For +each pair, with $q$ the first index: + +```math +\begin{aligned} +p_q &\ne 0 \\ +p_q &= (p_{q+1})^* +\end{aligned} +``` + +The corresponding columns of $\mathbf{C}$ and rows of $\mathbf{B}$ must follow +the same conjugate-pair ordering. + +### Model Derived Parameters + +```math +\begin{aligned} +\mathbf{P} &= \text{diag}(p_1,\dots,p_Q) \\ +\mathbf{a} &= \text{Re}(\mathbf{p}) \\ +\boldsymbol{\omega} &= \text{Im}(\mathbf{p}) \\ +\mathbf{A} &= \text{diag}(a_1,\dots,a_Q) \\ +\boldsymbol{\Omega} &= \text{diag}(\omega_1,\dots,\omega_Q) \\ +\mathbf{C}_{\mathrm{r}} &= \text{Re}(\mathbf{C}) \\ +\mathbf{C}_{\mathrm{i}} &= \text{Im}(\mathbf{C}) \\ +\mathbf{B}_{\mathrm{r}} &= \text{Re}(\mathbf{B}) \\ +\mathbf{B}_{\mathrm{i}} &= \text{Im}(\mathbf{B}) +\end{aligned} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{w}$ | [-] | Real memory states | $\mathbf{w}\in\mathbb{R}^Q$ +$\mathbf{v}$ | [-] | Imaginary memory states | $\mathbf{v}\in\mathbb{R}^Q$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | [-] | Input vector | $\mathbf{u} \in \mathbb{R}^K$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | [-] | Input vector port | $\mathbf{u} \in \mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | [-] | Output contribution port | $\mathbf{y} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= -\dot{\mathbf{w}} + + \mathbf{A}\mathbf{w} + - \boldsymbol{\Omega}\mathbf{v} + + \mathbf{B}_{\mathrm{r}}\mathbf{u} \\ +0 &= -\dot{\mathbf{v}} + + \boldsymbol{\Omega}\mathbf{w} + + \mathbf{A}\mathbf{v} + + \mathbf{B}_{\mathrm{i}}\mathbf{u} +\end{aligned} +``` + +### Algebraic Equations + +None. + +### Wiring + +```math +\mathbf{y} += \mathbf{D}\mathbf{u} + + \mathbf{E}\dot{\mathbf{u}} + + \mathbf{C}_{\mathrm{r}}\mathbf{w} + - \mathbf{C}_{\mathrm{i}}\mathbf{v} +``` + +## Initialization + +For an affine initial input trajectory, let subscript $0$ denote initial values: + +```math +\begin{aligned} +\mathbf{x}_0 &= -\mathbf{P}^{-1}\mathbf{B}\mathbf{u}_0 - \mathbf{P}^{-2}\mathbf{B}\dot{\mathbf{u}}_0 \\ +\mathbf{w}_0 &= \text{Re}(\mathbf{x}_0) \\ +\mathbf{v}_0 &= \text{Im}(\mathbf{x}_0) \\ +\mathbf{y}_0 &= \mathbf{D}\mathbf{u}_0 + \mathbf{E}\dot{\mathbf{u}}_0 + \mathbf{C}_{\mathrm{r}}\mathbf{w}_0 - \mathbf{C}_{\mathrm{i}}\mathbf{v}_0 +\end{aligned} +``` + +## Monitors + +None. diff --git a/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md b/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md new file mode 100644 index 000000000..ee983dfec --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md @@ -0,0 +1,142 @@ +# VectorFit Model + +`VectorFit` represents a vector-fitted matrix rational approximation with +complex poles and residues. + +The rational approximation is represented in pole form: + +```math +\mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} + + \sum_{q=1}^{Q} \frac{\mathbf{R}_q}{s - p_q} +``` + +The Laplace domain representation of this model is: +```math +\mathbf{Y}(s) = \mathbf{H}(s)\mathbf{U}(s) +``` + +The time domain representation of this model is: +```math +\mathbf{y}(t) = (\mathbf{h}*\mathbf{u})(t) +``` + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/VecFit/diagram.png) + +Figure 1: VectorFit model + +## Model Parameters + +For output dimension $N$, input dimension $K$, and pole count $Q$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\mathbf{D}$ | [-] | `D` | Constant coefficient | $\mathbf{D}\in\mathbb{R}^{N\times K}$ +$\mathbf{E}$ | [s] | `E` | Linear coefficient | $\mathbf{E}\in\mathbb{R}^{N\times K}$ +$\mathbf{p}$ | [1/s] | `poles` | Poles | $\mathbf{p}\in\mathbb{C}^Q$ +$\mathbf{R}$ | [1/s] | `residues` | Residues | $\mathbf{R}\in\mathbb{C}^{N\times K\times Q}$ + +### Parameter Validation + +Complex-valued poles and residues must be ordered as adjacent conjugate pairs. +For each pair, with $q$ the first index: + +```math +\begin{aligned} +p_q &= (p_{q+1})^* & +\mathbf{R}_q &= (\mathbf{R}_{q+1})^* +\end{aligned} +``` + +### Model Derived Parameters + +```math +\begin{aligned} +\mathbf{a} &= \text{Re}(\mathbf{p}) \\ +\boldsymbol{\omega} &= \text{Im}(\mathbf{p}) \\ +\mathbf{A} &= \text{Re}(\mathbf{R}) \\ +\mathbf{B} &= \text{Im}(\mathbf{R}) +\end{aligned} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{w}_q$ | [-] | Real memory states | $\mathbf{w}_q\in\mathbb{R}^K$ +$\mathbf{v}_q$ | [-] | Imaginary memory states | $\mathbf{v}_q\in\mathbb{R}^K$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | [-] | Input vector | $\mathbf{u} \in \mathbb{R}^K$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | [-] | Input vector port | $\mathbf{u} \in \mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | [-] | Output contribution port | $\mathbf{y} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= -\dot{\mathbf{w}}_q + + a_q\mathbf{w}_q + - \omega_q\mathbf{v}_q + + \mathbf{u} \\ +0 &= -\dot{\mathbf{v}}_q + + \omega_q\mathbf{w}_q + + a_q\mathbf{v}_q +\end{aligned} +``` + +### Algebraic Equations + +None. + +### Wiring + +```math +\mathbf{y} = \mathbf{D}\mathbf{u} + \mathbf{E}\dot{\mathbf{u}} + + \sum_{q=1}^{Q} + \left( + \mathbf{A}_q\mathbf{w}_q + - \mathbf{B}_q\mathbf{v}_q + \right) +``` + +## Initialization + +For an affine initial input trajectory, let subscript $0$ denote initial values: + +```math +\begin{aligned} +\mathbf{w}_{q,0} &= -\frac{a_q}{a_q^2 + \omega_q^2}\mathbf{u}_0 - \frac{a_q^2 - \omega_q^2}{(a_q^2 + \omega_q^2)^2}\dot{\mathbf{u}}_0 \\ +\mathbf{v}_{q,0} &= \frac{\omega_q}{a_q^2 + \omega_q^2}\mathbf{u}_0 + \frac{2a_q\omega_q}{(a_q^2 + \omega_q^2)^2}\dot{\mathbf{u}}_0 \\ +\mathbf{y}_0 &= \mathbf{D}\mathbf{u}_0 + \mathbf{E}\dot{\mathbf{u}}_0 + \sum_{q=1}^{Q}\left(\mathbf{A}_q\mathbf{w}_{q,0} - \mathbf{B}_q\mathbf{v}_{q,0}\right) +\end{aligned} +``` + +## Monitors + +None. diff --git a/GridKit/Model/EMT/Operators/Shift/Delay/README.md b/GridKit/Model/EMT/Operators/Shift/Delay/README.md new file mode 100644 index 000000000..b009f2da5 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/Delay/README.md @@ -0,0 +1,103 @@ +# Delay Model + +`Delay` represents a scalar EMT delay operator using a lag-block chain. +The model maps input signal $u$ to delayed output $y_{\mathrm{out}}$. + +Note: +- This is exact with forward Euler when the integration step satisfies $h=T$. +- For other integration methods or time steps, this is a smooth approximation only. + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/Delay/diagram.png) + +Figure 1: Delay model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\tau$ | [s] | `tau` | Total delay | Required, positive +$f_{\max}$ | [Hz] | `fmax` | Highest frequency of interest | Required, positive + +### Parameter Validation + +```math +\begin{aligned} +\tau &> 0 \\ +f_{\max} &> 0 +\end{aligned} +``` + +### Model Derived Parameters + +```math +\begin{aligned} +N &= \text{ceil}(f_{\max}\tau) \\ +T &= \dfrac{\tau}{N} +\end{aligned} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{y}$ | [-] | Section differential states | $\mathbf{y}\in\mathbb{R}^N$ + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$u$ | [-] | Input signal | $u\in\mathbb{R}$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$u$ | `input` | Input | [-] | Input signal port | $u\in\mathbb{R}$ +$y_{\mathrm{out}}$ | `out` | Output | [-] | Delayed output port | $y_{\mathrm{out}} = y_{N-1}$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= -T\dot{y}_0 - y_0 + u \\ +0 &= -T\dot{y}_n - y_n + y_{n-1} +\end{aligned} +``` + +### Algebraic Equations + +None. + +## Initialization + +For an affine initial input trajectory, let subscript $0$ denote initial values: + +```math +\begin{aligned} +y_{n,0} &= u_0 - (n+1)T\dot{u}_0 \\ +\dot{y}_{n,0} &= \dot{u}_0 \\ +y_{\mathrm{out},0} &= u_0 - \tau\dot{u}_0 +\end{aligned} +``` + +## Monitors + +None. diff --git a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md new file mode 100644 index 000000000..eb1781d34 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -0,0 +1,127 @@ +# Propagation Model + +`Propagation` represents the current-form EMT propagation operator used by +`LineDistributed`. It composes two fitted `VectorFit` factors with scalar +`Delay` blocks, one per propagation mode. + +```math +\mathbf{H}_i(s) += +\mathbf{F}_{\mathrm{out}}(s) +\boldsymbol{\Delta}_{\tau}(s) +\mathbf{F}_{\mathrm{in}}(s) +``` + +where + +```math +\begin{aligned} +\mathbf{F}_{\mathrm{in}}(s) &\approx +\widehat{\mathbf{H}}^{\mathrm{mps}}(s)\mathbf{T}_v(s)^{\mathsf H} \\ +\boldsymbol{\Delta}_{\tau}(s) &= +\operatorname{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\ +\mathbf{F}_{\mathrm{out}}(s) &\approx +\mathbf{T}_i(s). +\end{aligned} +``` + +The fitted factors are [`VectorFit`](../../Rational/VectorFit/README.md) +operators. + +## Block Diagram + +![](../../../../../../docs/Figures/EMT/Propagation/diagram.png) + +Figure 1: Propagation model + +## Model Parameters + +For conductor count $K$ and modal count $M$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\mathbf{F}_{\mathrm{in}}$ | [-] | `input` | Input-side fitted factor | `VectorFit`, $M\times K$ +$\boldsymbol{\tau}$ | [s] | `tau` | Modal propagation delays | $\boldsymbol{\tau}\in\mathbb{R}^M$ +$f_{\max}$ | [Hz] | `fmax` | Delay highest frequency of interest | passed to each scalar `Delay` +$\mathbf{F}_{\mathrm{out}}$ | [-] | `output` | Output-side fitted factor | `VectorFit`, $K\times M$ + +### Parameter Validation + +```math +\begin{aligned} +\mathbf{F}_{\mathrm{in}} &: M \times K \\ +\boldsymbol{\tau} &\in \mathbb{R}^M \\ +\mathbf{F}_{\mathrm{out}} &: K \times M +\end{aligned} +``` + +### Model Derived Parameters + +None. + +### Submodels + +Submodel | Inputs | Parameters | Outputs +-------- | ------ | ---------- | ------- +[`VectorFit`](../../Rational/VectorFit/README.md) $\mathbf{F}_{\mathrm{in}}$ | $\mathbf{u}\in\mathbb{R}^K$ | `input` | $\mathbf{w}\in\mathbb{R}^M$ +[`Delay`](../Delay/README.md) $\boldsymbol{\delta}_{\tau}$ | $\mathbf{w}\in\mathbb{R}^M$ | `tau`, `fmax` | $\mathbf{z}\in\mathbb{R}^M$ +[`VectorFit`](../../Rational/VectorFit/README.md) $\mathbf{F}_{\mathrm{out}}$ | $\mathbf{z}\in\mathbb{R}^M$ | `output` | $\mathbf{y}\in\mathbb{R}^K$ + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | [-] | Input vector | $\mathbf{u}\in\mathbb{R}^K$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | [-] | Input vector port | $\mathbf{u}\in\mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | [-] | Output contribution port | $\mathbf{y}\in\mathbb{R}^K$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +### Wiring + +```math +\begin{aligned} +\mathbf{w} &= \mathbf{f}_{\mathrm{in}} * \mathbf{u} \\ +\mathbf{z} &= \boldsymbol{\delta}_{\tau} * \mathbf{w} \\ +\mathbf{y} &= \mathbf{f}_{\mathrm{out}} * \mathbf{z}. +\end{aligned} +``` + +## Initialization + +None. + +## Monitors + +None. diff --git a/GridKit/Model/EMT/Operators/Shift/README.md b/GridKit/Model/EMT/Operators/Shift/README.md new file mode 100644 index 000000000..167873db6 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/README.md @@ -0,0 +1,4 @@ +# Shift Operators + +- `Delay` (See [Delay](Delay/README.md)) +- `Propagation` (See [Propagation](Propagation/README.md)) diff --git a/GridKit/Model/EMT/README.md b/GridKit/Model/EMT/README.md index abc526839..0b3e15a00 100644 --- a/GridKit/Model/EMT/README.md +++ b/GridKit/Model/EMT/README.md @@ -1,7 +1,7 @@ # Electromagnetic Transients (EMT) This directory contains design documentation for electromagnetic transient -(EMT) component models in instantaneous abc coordinates. +(EMT) models and reusable operators in instantaneous abc coordinates. ## Conventions @@ -12,18 +12,9 @@ EMT design and implementation develop. - Equations use SI units unless a model states otherwise. - Current injection terms are written as positive into buses. +## Directories -## Model Categories +The current EMT documentation is organized into: -The current EMT documentation is organized into two categories: -- `Bus` -- `Component` - -Branch models such as `BranchLumpedConstant` are documented under -`Component/Branch` because they are EMT components connected to buses. - -## Open Design Notes - -Distributed parameter lines are placeholders until internal signal delay support -is designed. -- Initial electrical wiring will use Delta configuration only +- `Component` (See [Component](Component/README.md)) +- `Operators` (See [Operators](Operators/README.md)) diff --git a/docs/Figures/EMT/Delay/diagram.png b/docs/Figures/EMT/Delay/diagram.png new file mode 100644 index 000000000..a4571d118 Binary files /dev/null and b/docs/Figures/EMT/Delay/diagram.png differ diff --git a/docs/Figures/EMT/Delay/diagram.tex b/docs/Figures/EMT/Delay/diagram.tex new file mode 100644 index 000000000..aaea6154d --- /dev/null +++ b/docs/Figures/EMT/Delay/diagram.tex @@ -0,0 +1,38 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small} +] + +% Lag-block chain: u -> 1/(1+sT) -> ... -> y_{N-1} = y_out +\foreach \k/\x in {0/0, 1/3.3, n/7.9} + \node[block] (b\k) at (\x, 0) {$\dfrac{1}{1 + sT}$}; +\node[inner sep=1pt] (dots) at (5.6, 0) {$\cdots$}; + +% input node (outside box) +\node[signal, label={[sig]above:$u$}] at (-2.4, 0) {}; +\draw[->, line] (-2.4, 0) -- (b0.west); + +% inter-block connections +\draw[->, line] (b0.east) -- (b1.west); +\draw[->, line] (b1.east) -- (dots); +\draw[->, line] (dots) -- (bn.west); + +% output node (inside box) with port arrow out +\node[signal, label={[sig]above:$y_{\mathrm{out}}$}] (yout) at (9.7, 0) {}; +\draw[->, line] (bn.east) -- (yout); +\draw[->, line] (yout) -- (12.1, 0); + +% model enclosure +\draw[dashed, semithick, rounded corners=4pt] (-1.55, -1.1) rectangle (10.6, 1.1); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/LineDistributed/diagram.png b/docs/Figures/EMT/LineDistributed/diagram.png new file mode 100644 index 000000000..ca8a33124 Binary files /dev/null and b/docs/Figures/EMT/LineDistributed/diagram.png differ diff --git a/docs/Figures/EMT/LineDistributed/diagram.tex b/docs/Figures/EMT/LineDistributed/diagram.tex new file mode 100644 index 000000000..f109bdb5e --- /dev/null +++ b/docs/Figures/EMT/LineDistributed/diagram.tex @@ -0,0 +1,74 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick, rounded corners=6pt}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + sum/.style = {draw, semithick, fill=white, circle, inner sep=2.6pt}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small}, + pm/.style = {font=\scriptsize} +] + +% ================= Terminal k (left column) ================= +\node[sum] (Sk) at (-4.4, 2.4) {$\Sigma$}; % KCL at k +\node[block] (Yck) at (-4.4, 0.0) {$\mathbf{Y}_c(s)$}; +\node[sum] (sk) at (-4.4, -2.4) {$\Sigma$}; % wave former at k + +\draw[->, line] (-8.4, 0) -- (Yck.west); +\node[signal, label={[sig]above:$\mathbf{v}_{1}$}] at (-7.6, 0) {}; + +\draw[->, line] (Yck.north) -- (Sk); +\draw[->, line] (Yck.south) -- (sk); +\draw[->, line] (Sk.west) -- (-8.4, 2.4) node[sig, pos=0.79, above] {$\mathbf{i}^{\text{inj}}_{1}$}; + +% i_k tap into wave former (hops over the v_k lead) +\draw[line] (-6.0, 2.4) -- (-6.0, 0.14); +\draw[->, line] (-6.0, -0.14) -- (-6.0, -2.4) -- (sk); + +% ================= Terminal m (right column) ================= +\node[sum] (sm) at (4.4, 2.4) {$\Sigma$}; % wave former at m +\node[block] (Ycm) at (4.4, 0.0) {$\mathbf{Y}_c(s)$}; +\node[sum] (Sm) at (4.4, -2.4) {$\Sigma$}; % KCL at m + +\draw[->, line] (8.4, 0) -- (Ycm.east); +\node[signal, label={[sig]above:$\mathbf{v}_{2}$}] at (7.6, 0) {}; + +\draw[->, line] (Ycm.north) -- (sm); +\draw[->, line] (Ycm.south) -- (Sm); +\draw[->, line] (Sm.east) -- (8.4, -2.4) node[sig, pos=0.79, above] {$\mathbf{i}^{\text{inj}}_{2}$}; + +% i_m tap into wave former (hops over the v_m lead) +\draw[line] (6.0, -2.4) -- (6.0, -0.14); +\draw[->, line] (6.0, 0.14) -- (6.0, 2.4) -- (sm); + +% ================= Propagation channels (straight rows) ================= +% k -> m (lower row, left to right) +\node[block] (Hlo) at (0, -2.4) {$\mathbf{H}(s)$}; +\draw[->, line] (sk.east) -- (Hlo.west) node[sig, pos=0.65, above] {reflected}; +\draw[->, line] (Hlo.east) -- (Sm.west) node[sig, pos=0.35, above] {incident}; + +% m -> k (upper row, right to left) +\node[block] (Hup) at (0, 2.4) {$\mathbf{H}(s)$}; +\draw[->, line] (sm.west) -- (Hup.east) node[sig, pos=0.65, above] {reflected}; +\draw[->, line] (Hup.west) -- (Sk.east) node[sig, pos=0.35, above] {incident}; + +% ================= Summation signs ================= +\node[pm] at (-4.14, 1.90) {$-$}; % Sk: Y_c v_k (admittance subtracts) +\node[pm] at (-3.68, 2.66) {$+$}; % Sk: incident current (adds) +\node[pm] at (-4.14, -1.90) {$+$}; % sk: Y_c v_k +\node[pm] at (-5.12, -2.16) {$-$}; % sk: i_k +\node[pm] at ( 4.14, -1.90) {$-$}; % Sm: Y_c v_m (admittance subtracts) +\node[pm] at ( 3.66, -2.14) {$+$}; % Sm: incident current (adds) +\node[pm] at ( 4.14, 1.90) {$+$}; % sm: Y_c v_m +\node[pm] at ( 5.12, 2.66) {$-$}; % sm: i_m + +% ================= Model enclosure ================= +\draw[dashed, semithick, rounded corners=4pt] (-6.8, -3.6) rectangle (6.8, 3.6); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/LineLumped/diagram.png b/docs/Figures/EMT/LineLumped/diagram.png new file mode 100644 index 000000000..c720d3881 Binary files /dev/null and b/docs/Figures/EMT/LineLumped/diagram.png differ diff --git a/docs/Figures/EMT/LineLumped/diagram.tex b/docs/Figures/EMT/LineLumped/diagram.tex new file mode 100644 index 000000000..bf39648f5 --- /dev/null +++ b/docs/Figures/EMT/LineLumped/diagram.tex @@ -0,0 +1,59 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick, rounded corners=6pt}, + % series element: long axis ALONG the horizontal wire + hblock/.style = {draw, semithick, fill=white, + minimum width=2.8cm, minimum height=1.3cm}, + % shunt element: same proportion, long axis ALONG the vertical wire + vblock/.style = {draw, semithick, fill=white, + minimum width=1.3cm, minimum height=2.8cm}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small} +] + +% ================= Series branch Z(s) ================= +\node[hblock] (Z) at (0, 2.1) {$\mathbf{Z}(s)$}; + +% ================= Shunt branches Y(s) ================= +\node[vblock] (Yk) at (-3.4, -0.2) {$\mathbf{Y}(s)$}; +\node[vblock] (Ym) at ( 3.4, -0.2) {$\mathbf{Y}(s)$}; + +% ================= Top rail + injection leads (current leaving) ================= +\draw[->, line] (Z.west) -- (-7.0, 2.1); +\draw[->, line] (Z.east) -- ( 7.0, 2.1); + +% shunt taps (T-junctions on the rail) +\node[signal] (Tk) at (-3.4, 2.1) {}; +\node[signal] (Tm) at ( 3.4, 2.1) {}; + +% ================= Shunt wiring ================= +\draw[line] (Tk) -- (Yk.north); +\draw[line] (Tm) -- (Ym.north); +\draw[line] (Yk.south) -- (-3.4, -2.5); +\draw[line] (Ym.south) -- ( 3.4, -2.5); + +% ================= Ground symbols ================= +\draw[semithick] (-3.75,-2.50) -- (-3.05,-2.50); +\draw[semithick] (-3.62,-2.65) -- (-3.18,-2.65); +\draw[semithick] (-3.49,-2.80) -- (-3.31,-2.80); + +\draw[semithick] ( 3.05,-2.50) -- ( 3.75,-2.50); +\draw[semithick] ( 3.18,-2.65) -- ( 3.62,-2.65); +\draw[semithick] ( 3.31,-2.80) -- ( 3.49,-2.80); + +% ================= Terminals + labels ================= +\node[signal, label={[sig]above:$\mathbf{v}_{1}$}] at (-6.2, 2.1) {}; +\node[signal, label={[sig]above:$\mathbf{v}_{2}$}] at ( 6.2, 2.1) {}; +\node[sig] at (-6.35, 1.62) {$\mathbf{i}^{\text{inj}}_{1}$}; +\node[sig] at ( 6.35, 1.62) {$\mathbf{i}^{\text{inj}}_{2}$}; + +% ================= Model enclosure ================= +\draw[dashed, semithick, rounded corners=4pt] (-5.4, -3.6) rectangle (5.4, 3.6); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Propagation/diagram.png b/docs/Figures/EMT/Propagation/diagram.png new file mode 100644 index 000000000..86e484f60 Binary files /dev/null and b/docs/Figures/EMT/Propagation/diagram.png differ diff --git a/docs/Figures/EMT/Propagation/diagram.tex b/docs/Figures/EMT/Propagation/diagram.tex new file mode 100644 index 000000000..0e95b2d40 --- /dev/null +++ b/docs/Figures/EMT/Propagation/diagram.tex @@ -0,0 +1,46 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick, rounded corners=6pt}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small} +] + +% Three-block current propagation: StateSpace -> scalar modal delays -> StateSpace +\node[block, minimum width=2.6cm] (Fin) at (-3.5, 0) {$\mathbf{F}_{\mathrm{in}}(s)$}; +\node[block, minimum width=2.7cm] (Fout) at ( 4.9, 0) {$\mathbf{F}_{\mathrm{out}}(s)$}; + +\foreach \i/\lab/\y in {1/1/1.6, 2/2/0, N/M/-2.3} + \node[block, minimum width=2.1cm] (D\i) at (0.7, \y) {$e^{-s\tau_{\lab}}$}; +\node at (0.7, -1.15) {$\vdots$}; + +% Fan-out from a single internal point +\coordinate (split) at (-1.35, 0); +\draw[->, line] (-6.6, 0) -- (Fin.west); +\draw[line] (Fin.east) -- (split); +\draw[->, line] (split) -- (D2.west); +\foreach \b in {D1, DN} + \draw[->, line] (split) |- (\b.west); + +% Fan-in to the output state-space factor +\coordinate (join) at (2.75, 0); +\draw[line] (D2.east) -- (join); +\foreach \b in {D1, DN} + \draw[line] (\b.east) -| (join); +\draw[->, line] (join) -- (Fout.west); +\draw[->, line] (Fout.east) -- (7.6, 0) node[sig, pos=0.62, above] {$\mathbf{y}$}; + +% Signal node: u external +\node[signal, label={[sig]above:$\mathbf{u}$}] at (-5.8, 0) {}; + +% Model enclosure +\draw[dashed, semithick, rounded corners=4pt] (-5.1, -3.3) rectangle (6.4, 2.6); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/StateSpace/diagram.png b/docs/Figures/EMT/StateSpace/diagram.png new file mode 100644 index 000000000..d3a343327 Binary files /dev/null and b/docs/Figures/EMT/StateSpace/diagram.png differ diff --git a/docs/Figures/EMT/StateSpace/diagram.tex b/docs/Figures/EMT/StateSpace/diagram.tex new file mode 100644 index 000000000..dcca22a7b --- /dev/null +++ b/docs/Figures/EMT/StateSpace/diagram.tex @@ -0,0 +1,50 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick, rounded corners=6pt}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + sum/.style = {draw, semithick, fill=white, circle, inner sep=2.6pt}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small} +] + +% Feedthrough paths +\node[block] (D) at (0, 1.9) {$\mathbf{D}$}; +\node[block] (E) at (0, -1.9) {$s\mathbf{E}$}; + +% State-space chain: input map -> resolvent state bank -> output map +\node[block, minimum width=1.5cm] (BT) at (-2.6, 0) {$\mathbf{B}$}; +\node[block, minimum width=2.9cm] (res) at ( 0.0, 0) {$\dfrac{\mathbf{I}}{s\mathbf{I} - \mathbf{P}}$}; +\node[block, minimum width=1.5cm] (C) at ( 2.6, 0) {$\mathbf{C}$}; + +% Fan-out from a single internal point +\coordinate (split) at (-4.6, 0); +\draw[line] (-6.8, 0) -- (split); +\draw[->, line] (split) -- (BT.west); +\draw[->, line] (split) |- (D.west); +\draw[->, line] (split) |- (E.west); + +% Chain series connections +\draw[->, line] (BT.east) -- (res.west); +\draw[->, line] (res.east) -- (C.west); + +% Fan-in to summation +\node[sum] (S) at (4.5, 0) {$\Sigma$}; +\draw[->, line] (C.east) -- (S); +\draw[->, line] (D.east) -| (S.north); +\draw[->, line] (E.east) -| (S.south); +\draw[->, line] (S.east) -- (7.4, 0) node[sig, pos=0.62, above] {$\mathbf{y}$}; + +% Signal node: u external +\node[signal, label={[sig]above:$\mathbf{u}$}] at (-6.0, 0) {}; + +% Model enclosure +\draw[dashed, semithick, rounded corners=4pt] (-5.0, -3.0) rectangle (5.7, 3.0); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/VecFit/diagram.png b/docs/Figures/EMT/VecFit/diagram.png new file mode 100644 index 000000000..77ec0c0dc Binary files /dev/null and b/docs/Figures/EMT/VecFit/diagram.png differ diff --git a/docs/Figures/EMT/VecFit/diagram.tex b/docs/Figures/EMT/VecFit/diagram.tex new file mode 100644 index 000000000..9d98aea7a --- /dev/null +++ b/docs/Figures/EMT/VecFit/diagram.tex @@ -0,0 +1,44 @@ +\documentclass[tikz,border=12pt]{standalone} +\usepackage{amsmath} +\usetikzlibrary{arrows.meta} + +\begin{document} +\begin{tikzpicture}[ + >={Stealth[length=2.4mm]}, + line/.style = {semithick, rounded corners=6pt}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + sum/.style = {draw, semithick, fill=white, circle, inner sep=2.6pt}, + signal/.style = {circle, fill, inner sep=1.4pt, label distance=3pt}, + sig/.style = {font=\small} +] + +% Parallel branches +\node[block] (D) at (0, 3.2) {$\mathbf{D}$}; +\node[block] (E) at (0, 1.6) {$s\mathbf{E}$}; +\foreach \q/\y in {1/0, 2/-1.6, Q/-3.9} + \node[block] (R\q) at (0, \y) {$\dfrac{\mathbf{R}_{\q}}{s - p_{\q}}$}; +\node at (0, -2.75) {$\vdots$}; + +% Fan-out from a single internal point +\coordinate (split) at (-2.2, 0); +\draw[line] (-4.9, 0) -- (split); +\draw[->, line] (split) -- (R1.west); +\foreach \b in {D, E, R2, RQ} + \draw[->, line] (split) |- (\b.west); + +% Fan-in to summation +\node[sum] (S) at (2.6, 0) {$\Sigma$}; +\draw[->, line] (R1.east) -- (S); +\foreach \b/\a in {D/north, E/north, R2/south, RQ/south} + \draw[->, line] (\b.east) -| (S.\a); +\draw[->, line] (S.east) -- (5.5, 0) node[sig, pos=0.6, above] {$\mathbf{y}$}; + +% Signal node: u external +\node[signal, label={[sig]above:$\mathbf{u}$}] at (-3.85, 0) {}; + +% Model enclosure +\draw[dashed, semithick, rounded corners=4pt] (-2.8, -4.9) rectangle (3.4, 4.2); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/lumped_constant_diagram.svg b/docs/Figures/EMT/lumped_constant_diagram.svg deleted file mode 100644 index ee4945dc4..000000000 --- a/docs/Figures/EMT/lumped_constant_diagram.svg +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/GridKit/Model/EMT/Bus/README.md b/docs/GridKit/Model/EMT/Bus/README.md deleted file mode 100644 index 251bb5167..000000000 --- a/docs/GridKit/Model/EMT/Bus/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Bus - -```{include} ../../../../../GridKit/Model/EMT/Bus/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md b/docs/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md deleted file mode 100644 index 9f3caaec5..000000000 --- a/docs/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# BranchLumpedConstant - -```{include} ../../../../../../../GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/EMT/Component/Branch/README.md b/docs/GridKit/Model/EMT/Component/Branch/README.md deleted file mode 100644 index 27dca5bee..000000000 --- a/docs/GridKit/Model/EMT/Component/Branch/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Branch - -```{toctree} -:maxdepth: 4 -:titlesonly: -:hidden: - -BranchLumpedConstant -``` - -```{include} ../../../../../../GridKit/Model/EMT/Component/Branch/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/EMT/Component/Bus/README.md b/docs/GridKit/Model/EMT/Component/Bus/README.md new file mode 100644 index 000000000..74284a188 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Bus/README.md @@ -0,0 +1,6 @@ +# Bus + +```{include} ../../../../../../GridKit/Model/EMT/Component/Bus/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Line/LineDistributed/README.md b/docs/GridKit/Model/EMT/Component/Line/LineDistributed/README.md new file mode 100644 index 000000000..d6c0f6982 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Line/LineDistributed/README.md @@ -0,0 +1,6 @@ +# LineDistributed + +```{include} ../../../../../../../GridKit/Model/EMT/Component/Line/LineDistributed/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Line/LineLumped/README.md b/docs/GridKit/Model/EMT/Component/Line/LineLumped/README.md new file mode 100644 index 000000000..d9be74289 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Line/LineLumped/README.md @@ -0,0 +1,6 @@ +# LineLumped + +```{include} ../../../../../../../GridKit/Model/EMT/Component/Line/LineLumped/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Line/README.md b/docs/GridKit/Model/EMT/Component/Line/README.md new file mode 100644 index 000000000..ecb2b2c65 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Line/README.md @@ -0,0 +1,15 @@ +# Line + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +LineLumped +LineDistributed +``` + +```{include} ../../../../../../GridKit/Model/EMT/Component/Line/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Load/LoadRL/README.md b/docs/GridKit/Model/EMT/Component/Load/LoadRL/README.md new file mode 100644 index 000000000..a2aa76f46 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Load/LoadRL/README.md @@ -0,0 +1,6 @@ +# LoadRL + +```{include} ../../../../../../../GridKit/Model/EMT/Component/Load/LoadRL/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Load/README.md b/docs/GridKit/Model/EMT/Component/Load/README.md new file mode 100644 index 000000000..53c8b8ac9 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Load/README.md @@ -0,0 +1,14 @@ +# Load + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +LoadRL +``` + +```{include} ../../../../../../GridKit/Model/EMT/Component/Load/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/LoadRL/README.md b/docs/GridKit/Model/EMT/Component/LoadRL/README.md deleted file mode 100644 index ce5aa7f65..000000000 --- a/docs/GridKit/Model/EMT/Component/LoadRL/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# LoadRL - -```{include} ../../../../../../GridKit/Model/EMT/Component/LoadRL/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/EMT/Component/README.md b/docs/GridKit/Model/EMT/Component/README.md index 587ecb957..63a9bbf72 100644 --- a/docs/GridKit/Model/EMT/Component/README.md +++ b/docs/GridKit/Model/EMT/Component/README.md @@ -5,9 +5,10 @@ :titlesonly: :hidden: -Branch -LoadRL -VoltageSource +Bus +Line +Load +Source ``` ```{include} ../../../../../GridKit/Model/EMT/Component/README.md diff --git a/docs/GridKit/Model/EMT/Component/Source/README.md b/docs/GridKit/Model/EMT/Component/Source/README.md new file mode 100644 index 000000000..aa9f58e62 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Source/README.md @@ -0,0 +1,14 @@ +# Source + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +VoltageSource +``` + +```{include} ../../../../../../GridKit/Model/EMT/Component/Source/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/Source/VoltageSource/README.md b/docs/GridKit/Model/EMT/Component/Source/VoltageSource/README.md new file mode 100644 index 000000000..385def25c --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Source/VoltageSource/README.md @@ -0,0 +1,6 @@ +# VoltageSource + +```{include} ../../../../../../../GridKit/Model/EMT/Component/Source/VoltageSource/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Component/VoltageSource/README.md b/docs/GridKit/Model/EMT/Component/VoltageSource/README.md deleted file mode 100644 index fd8ce8d32..000000000 --- a/docs/GridKit/Model/EMT/Component/VoltageSource/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# VoltageSource - -```{include} ../../../../../../GridKit/Model/EMT/Component/VoltageSource/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/EMT/Operators/README.md b/docs/GridKit/Model/EMT/Operators/README.md new file mode 100644 index 000000000..372c54e6b --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/README.md @@ -0,0 +1,15 @@ +# Operators + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +Rational +Shift +``` + +```{include} ../../../../../GridKit/Model/EMT/Operators/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Rational/README.md b/docs/GridKit/Model/EMT/Operators/Rational/README.md new file mode 100644 index 000000000..bc0812680 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Rational/README.md @@ -0,0 +1,15 @@ +# Rational + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +VectorFit +StateSpace +``` + +```{include} ../../../../../../GridKit/Model/EMT/Operators/Rational/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md b/docs/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md new file mode 100644 index 000000000..accca8421 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md @@ -0,0 +1,6 @@ +# StateSpace + +```{include} ../../../../../../../GridKit/Model/EMT/Operators/Rational/StateSpace/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md b/docs/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md new file mode 100644 index 000000000..1f7c04488 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md @@ -0,0 +1,6 @@ +# VectorFit + +```{include} ../../../../../../../GridKit/Model/EMT/Operators/Rational/VectorFit/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Shift/Delay/README.md b/docs/GridKit/Model/EMT/Operators/Shift/Delay/README.md new file mode 100644 index 000000000..3dfee5db2 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Shift/Delay/README.md @@ -0,0 +1,6 @@ +# Delay + +```{include} ../../../../../../../GridKit/Model/EMT/Operators/Shift/Delay/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/docs/GridKit/Model/EMT/Operators/Shift/Propagation/README.md new file mode 100644 index 000000000..d9dda68a4 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -0,0 +1,6 @@ +# Propagation + +```{include} ../../../../../../../GridKit/Model/EMT/Operators/Shift/Propagation/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/Operators/Shift/README.md b/docs/GridKit/Model/EMT/Operators/Shift/README.md new file mode 100644 index 000000000..deff02d2f --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Shift/README.md @@ -0,0 +1,15 @@ +# Shift + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +Delay +Propagation +``` + +```{include} ../../../../../../GridKit/Model/EMT/Operators/Shift/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/EMT/README.md b/docs/GridKit/Model/EMT/README.md index 7a6e5fe76..ee402f347 100644 --- a/docs/GridKit/Model/EMT/README.md +++ b/docs/GridKit/Model/EMT/README.md @@ -5,8 +5,8 @@ :titlesonly: :hidden: -Bus Component +Operators ``` ```{include} ../../../../GridKit/Model/EMT/README.md