diff --git a/CHANGELOG.md b/CHANGELOG.md index 93af90b6a..f084bdaeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,7 @@ - Added new `Rosenbrock` integrator. - Clarified naming conventions for macros. - Added `dt_fixed`, `rel_tol`, and `abs_tol` options to phasor dynamics solver JSON files and renamed the `dt` option to `dt_monitor`. +- Added EMT model and operator documentation. ## v0.1 diff --git a/GridKit/Model/EMT/Bus/README.md b/GridKit/Model/EMT/Bus/README.md index 77c884144..4d7c3a19e 100644 --- a/GridKit/Model/EMT/Bus/README.md +++ b/GridKit/Model/EMT/Bus/README.md @@ -1,14 +1,36 @@ # 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. +`Bus` represents an $N$-phase bus in instantaneous phase coordinates. It owns +the differential bus voltage and contributes the current-balance residual to +the assembled DAE. $\mathcal{E}$ denotes the set of connected devices. + +## Block Diagram + +![Bus model block diagram](../../../../docs/Figures/EMT/Bus/diagram.png) + +Figure 1: Bus model ## Model Parameters +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer + +### Parameter Validation + +```math +N \in \mathbb{Z}_{>0} +``` + +### Derived Parameters + +None. + +## Submodels + None. -## Model Derived Parameters +### Submodel Validation None. @@ -18,9 +40,9 @@ None. #### Differential -Symbol | Units | Description | Note ----------|-------|--------------------|-------------------------------- -$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$ +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} \in \mathbb{R}^N$ #### Algebraic @@ -36,55 +58,35 @@ None. None. +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{i}_e$ | `i` | Input | [A] | Current from connected device $e$ | One port per $e \in \mathcal{E}$, $\mathbf{i}_e \in \mathbb{R}^N$ +$\mathbf{v}$ | `v` | Output | [V] | Bus voltage supplied to connected devices | $\mathbf{v} \in \mathbb{R}^N$ + ## 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} +```math +0 = \sum_{e \in \mathcal{E}} \mathbf{i}_e ``` -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$, +### Wiring -``` 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 +None. -``` 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} -``` +## Initialization -## Model Outputs +None beyond the EMT initialization contract. -Phase voltages $v_a$, $v_b$, and $v_c$ are monitorable model outputs. +## Monitors -Phase-voltage derivatives $\dot{v}_a$, $\dot{v}_b$, and $\dot{v}_c$ are also available as monitorable outputs. +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`v` | [V] | Bus voltage | $\mathbf{v} \in \mathbb{R}^N$ 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/Line/LineDistributed/README.md b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md new file mode 100644 index 000000000..980e06ba1 --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md @@ -0,0 +1,205 @@ +# LineDistributed Model + +`LineDistributed` represents an $N$-phase, $K$-conductor distributed EMT line. + +## Block Diagram + +![LineDistributed model block diagram](../../../../../../docs/Figures/EMT/LineDistributed/diagram.png) + +Figure 1: LineDistributed model + +The conductor-to-phase mappings are shown in the equations and omitted from +the diagram for clarity. + +## Model Parameters + +Define the phase- and conductor-index sets + +```math +\mathcal{N} = \{1,\ldots,N\}, +\qquad +\mathcal{K} = \{1,\ldots,K\}. +``` + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer +$K$ | [-] | `K` | Number of conductors | Required, positive integer +$\mathbf{c}$ | [-] | `conductors` | Conductor phase-index list | $\mathbf{c} \in \mathcal{N}^K$ + +### Parameter Validation + +```math +\begin{aligned} +N &\in \mathbb{Z}_{>0} \\ +K &\in \mathbb{Z}_{>0} \\ +\mathbf{c} &\in \mathcal{N}^K \\ +\{c_k \mid k \in \mathcal{K}\} &= \mathcal{N} +\end{aligned} +``` + +### Derived Parameters + +```math +P_{\phi,nk} = +\begin{cases} +1, & n = c_k \\ +0, & n \ne c_k +\end{cases}, +\quad n \in \mathcal{N},\quad k \in \mathcal{K} +``` + +## Submodels + +Symbol | Description | Type | Order | JSON | Inputs | Outputs +------ | ----------- | ---- | ----- | ---- | ------ | ------- +$\mathbf{y}_1^\mathrm{c}$ | Characteristic admittance at terminal 1 | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $KQ_{\mathbf{y}^\mathrm{c}}$ | `Yc` | $\mathbb{R}^K$ | $\mathbb{R}^K$ +$\mathbf{y}_2^\mathrm{c}$ | Characteristic admittance at terminal 2 | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $KQ_{\mathbf{y}^\mathrm{c}}$ | `Yc` | $\mathbb{R}^K$ | $\mathbb{R}^K$ +$\mathbf{h}_{21}$ | Propagation from terminal 2 to terminal 1 | [Propagation](../../../Operators/Shift/Propagation/README.md) | Composite | `H` | $\mathbb{R}^K$ | $\mathbb{R}^K$ +$\mathbf{h}_{12}$ | Propagation from terminal 1 to terminal 2 | [Propagation](../../../Operators/Shift/Propagation/README.md) | Composite | `H` | $\mathbb{R}^K$ | $\mathbb{R}^K$ + +`Yc` and `H` each provide one coefficient set. The model assumes a reciprocal +uniform line, so + +```math +\mathbf{Y}_1^{\mathrm{c}}(s)=\mathbf{Y}_2^{\mathrm{c}}(s), +\qquad +\mathbf{H}_{12}(s)=\mathbf{H}_{21}(s). +``` + +The two terminal-admittance instances maintain independent states, and the two +directional propagation instances maintain independent states and histories. + +### Submodel Validation + +The characteristic-admittance fits must be stable, proper, and positive real. +Together with the propagation fits, they must produce a passive line model. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}_1^\mathrm{ref}$ | [A] | Reflected current at terminal 1 | $\mathbf{i}_1^\mathrm{ref} \in \mathbb{R}^K$ +$\mathbf{i}_2^\mathrm{ref}$ | [A] | Reflected current at terminal 2 | $\mathbf{i}_2^\mathrm{ref} \in \mathbb{R}^K$ + +### 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{v}_1$ | `v1` | Input | [V] | Terminal 1 bus voltage | $\mathbf{v}_1 \in \mathbb{R}^N$ +$\mathbf{v}_2$ | `v2` | Input | [V] | Terminal 2 bus voltage | $\mathbf{v}_2 \in \mathbb{R}^N$ +$\mathbf{i}_1$ | `i1` | Output | [A] | Current injection at terminal 1 | $\mathbf{i}_1 \in \mathbb{R}^N$ +$\mathbf{i}_2$ | `i2` | Output | [A] | Current injection at terminal 2 | $\mathbf{i}_2 \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +The residuals use the wiring signals defined below. + +```math +\begin{aligned} +0 &= -\mathbf{i}_1^\mathrm{ref} + + 2\mathbf{i}_1^\mathrm{c} + - \mathbf{i}_1^\mathrm{inc} \\ +0 &= -\mathbf{i}_2^\mathrm{ref} + + 2\mathbf{i}_2^\mathrm{c} + - \mathbf{i}_2^\mathrm{inc} +\end{aligned} +``` + +### Wiring + +```math +\begin{aligned} +\mathbf{i}_1^\mathrm{c} &\leftarrow + \mathbf{y}_1^\mathrm{c}[\mathbf{P}_\phi^\mathsf T\mathbf{v}_1] \\ +\mathbf{i}_2^\mathrm{c} &\leftarrow + \mathbf{y}_2^\mathrm{c}[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2] \\ +\mathbf{i}_1^\mathrm{inc} &\leftarrow + \mathbf{h}_{21}[\mathbf{i}_2^\mathrm{ref}] \\ +\mathbf{i}_2^\mathrm{inc} &\leftarrow + \mathbf{h}_{12}[\mathbf{i}_1^\mathrm{ref}] \\ +\mathbf{i}_1 &\leftarrow + \mathbf{P}_\phi(\mathbf{i}_1^\mathrm{inc}-\mathbf{i}_1^\mathrm{c}) \\ +\mathbf{i}_2 &\leftarrow + \mathbf{P}_\phi(\mathbf{i}_2^\mathrm{inc}-\mathbf{i}_2^\mathrm{c}) +\end{aligned} +``` + +## Initialization + +The characteristic-admittance and propagation submodels initialize according +to their own specifications. There is no additional line-level initialization +procedure. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i_c1` | [A] | Characteristic-admittance current at terminal 1 | $\mathbf{i}_1^\mathrm{c} \in \mathbb{R}^K$ +`i_c2` | [A] | Characteristic-admittance current at terminal 2 | $\mathbf{i}_2^\mathrm{c} \in \mathbb{R}^K$ +`i_inc1` | [A] | Incident current at terminal 1 | $\mathbf{i}_1^\mathrm{inc} \in \mathbb{R}^K$ +`i_inc2` | [A] | Incident current at terminal 2 | $\mathbf{i}_2^\mathrm{inc} \in \mathbb{R}^K$ + +## Development + +The initial three-phase formulation takes $N=K=3$ and +$\mathbf{P}_\phi=\mathbf{I}_3$. + +### Algebraic Equations + +```math +\begin{aligned} +0 &= -\mathbf{i}_1^\mathrm{ref} + + 2\mathbf{i}_1^\mathrm{c} + - \mathbf{i}_1^\mathrm{inc} \\ +0 &= -\mathbf{i}_2^\mathrm{ref} + + 2\mathbf{i}_2^\mathrm{c} + - \mathbf{i}_2^\mathrm{inc} +\end{aligned} +``` + +### Wiring + +```math +\begin{aligned} +\mathbf{i}_1^\mathrm{c} + &\leftarrow \mathbf{y}_1^\mathrm{c}[\mathbf{v}_1] \\ +\mathbf{i}_2^\mathrm{c} + &\leftarrow \mathbf{y}_2^\mathrm{c}[\mathbf{v}_2] \\ +\mathbf{i}_1^\mathrm{inc} + &\leftarrow \mathbf{h}_{21}[\mathbf{i}_2^\mathrm{ref}] \\ +\mathbf{i}_2^\mathrm{inc} + &\leftarrow \mathbf{h}_{12}[\mathbf{i}_1^\mathrm{ref}] \\ +\mathbf{i}_1 + &\leftarrow \mathbf{i}_1^\mathrm{inc}-\mathbf{i}_1^\mathrm{c} \\ +\mathbf{i}_2 + &\leftarrow \mathbf{i}_2^\mathrm{inc}-\mathbf{i}_2^\mathrm{c} +\end{aligned} +``` 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..1934861e1 --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/LineLumped/README.md @@ -0,0 +1,196 @@ +# LineLumped Model + +`LineLumped` represents an $N$-phase, $K$-conductor lumped EMT line over length +$\Delta x$. Series current $\mathbf{i}_{12}$ is directed from terminal 1 to +terminal 2. + +## Block Diagram + +![LineLumped model block diagram](../../../../../../docs/Figures/EMT/LineLumped/diagram.png) + +Figure 1: LineLumped model + +The conductor-to-phase mappings are shown in the equations and omitted from +the diagram for clarity. + +## Model Parameters + +Define the phase- and conductor-index sets + +```math +\mathcal{N} = \{1,\ldots,N\}, +\qquad +\mathcal{K} = \{1,\ldots,K\}. +``` + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer +$K$ | [-] | `K` | Number of conductors | Required, positive integer +$\mathbf{c}$ | [-] | `conductors` | Conductor phase-index list | $\mathbf{c} \in \mathcal{N}^K$ +$\Delta x$ | [m] | `dx` | Line segment length | Required, positive + +### Parameter Validation + +```math +\begin{aligned} +N &\in \mathbb{Z}_{>0} \\ +K &\in \mathbb{Z}_{>0} \\ +\mathbf{c} &\in \mathcal{N}^K \\ +\{c_k \mid k \in \mathcal{K}\} &= \mathcal{N} \\ +\Delta x &> 0 +\end{aligned} +``` + +### Derived Parameters + +```math +P_{\phi,nk} = +\begin{cases} +1, & n = c_k \\ +0, & n \ne c_k +\end{cases}, +\quad n \in \mathcal{N},\quad k \in \mathcal{K} +``` + +## Submodels + +Symbol | Description | Type | Order | JSON | Inputs | Outputs +------ | ----------- | ---- | ----- | ---- | ------ | ------- +$\mathbf{z}$ | Per-unit-length series impedance | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $KQ_{\mathbf{z}}$ | `Zp` | $\mathbb{R}^K$ | $\mathbb{R}^K$ +$\mathbf{y}_1$ | Per-unit-length shunt admittance at terminal 1 | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $KQ_{\mathbf{y}}$ | `Yp` | $\mathbb{R}^K$ | $\mathbb{R}^K$ +$\mathbf{y}_2$ | Per-unit-length shunt admittance at terminal 2 | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $KQ_{\mathbf{y}}$ | `Yp` | $\mathbb{R}^K$ | $\mathbb{R}^K$ + +`Yp` provides one coefficient set; the two terminal instances maintain +independent states. + +### Submodel Validation + +```math +\mathrm{rank}(\mathbf{E}^{\mathbf{z}}) = K +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}_{12}$ | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^K$ + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}_1^\mathrm{sh}$ | [A] | Shunt current at terminal 1 | $\mathbf{i}_1^\mathrm{sh} \in \mathbb{R}^K$ +$\mathbf{i}_2^\mathrm{sh}$ | [A] | Shunt current at terminal 2 | $\mathbf{i}_2^\mathrm{sh} \in \mathbb{R}^K$ + +### 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{v}_1$ | `v1` | Input | [V] | Terminal 1 bus voltage | $\mathbf{v}_1 \in \mathbb{R}^N$ +$\mathbf{v}_2$ | `v2` | Input | [V] | Terminal 2 bus voltage | $\mathbf{v}_2 \in \mathbb{R}^N$ +$\mathbf{i}_1$ | `i1` | Output | [A] | Current injection at terminal 1 | $\mathbf{i}_1 \in \mathbb{R}^N$ +$\mathbf{i}_2$ | `i2` | Output | [A] | Current injection at terminal 2 | $\mathbf{i}_2 \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +0 = \Delta x\,\mathbf{z}[\mathbf{i}_{12}] + + \mathbf{P}_\phi^\mathsf T(\mathbf{v}_2-\mathbf{v}_1) +``` + +### Algebraic Equations + +```math +\begin{aligned} +0 &= \Delta x\,\mathbf{y}_2[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2] + + 2\mathbf{i}_2^\mathrm{sh} \\ +0 &= \Delta x\,\mathbf{y}_1[\mathbf{P}_\phi^\mathsf T\mathbf{v}_1] + + 2\mathbf{i}_1^\mathrm{sh} +\end{aligned} +``` + +### Wiring + +```math +\begin{aligned} +\mathbf{i}_1 &\leftarrow + \mathbf{P}_\phi\left( + \mathbf{i}_1^\mathrm{sh} + - \mathbf{i}_{12} + \right) \\ +\mathbf{i}_2 &\leftarrow + \mathbf{P}_\phi\left( + \mathbf{i}_2^\mathrm{sh} + + \mathbf{i}_{12} + \right) +\end{aligned} +``` + +## Initialization + +None beyond the EMT initialization contract. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i12` | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^K$ +`i_sh1` | [A] | Shunt current at terminal 1 | $\mathbf{i}_1^\mathrm{sh} \in \mathbb{R}^K$ +`i_sh2` | [A] | Shunt current at terminal 2 | $\mathbf{i}_2^\mathrm{sh} \in \mathbb{R}^K$ + +## Development + +The initial three-phase formulation is a subset of the generalized formulation +above. + +### Derived Parameters + +```math +\begin{aligned} +\mathbf{R} &= \Delta x\,\mathbf{R}' \\ +\mathbf{L} &= \Delta x\,\mathbf{L}' \\ +\mathbf{G} &= \Delta x\,\mathbf{G}' \\ +\mathbf{C} &= \Delta x\,\mathbf{C}' +\end{aligned} +``` + +### Differential Equations + +```math +0 = \mathbf{R}\mathbf{i}_{12} + + \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}_{12}}{\mathrm{d}t} + + \mathbf{v}_2-\mathbf{v}_1 +``` + +### Algebraic Equations + +```math +\begin{aligned} +0 &= \mathbf{G}\mathbf{v}_2 + + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_2}{\mathrm{d}t} + + 2\mathbf{i}_2^\mathrm{sh} \\ +0 &= \mathbf{G}\mathbf{v}_1 + + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_1}{\mathrm{d}t} + + 2\mathbf{i}_1^\mathrm{sh} +\end{aligned} +``` diff --git a/GridKit/Model/EMT/Component/Line/README.md b/GridKit/Model/EMT/Component/Line/README.md new file mode 100644 index 000000000..16280155f --- /dev/null +++ b/GridKit/Model/EMT/Component/Line/README.md @@ -0,0 +1,9 @@ +# Line Models + +EMT line models represent $N$-phase network connections between buses in +instantaneous phase coordinates. + +## Models + +- [LineLumped](LineLumped/README.md) +- [LineDistributed](LineDistributed/README.md) diff --git a/GridKit/Model/EMT/Component/Load/LoadZ/README.md b/GridKit/Model/EMT/Component/Load/LoadZ/README.md new file mode 100644 index 000000000..14d46f0c6 --- /dev/null +++ b/GridKit/Model/EMT/Component/Load/LoadZ/README.md @@ -0,0 +1,120 @@ +# LoadZ Model + +`LoadZ` represents an $N$-phase impedance load. Current $\mathbf{i}$ is injected +from the load into the EMT bus. + +## Block Diagram + +![LoadZ model block diagram](../../../../../../docs/Figures/EMT/LoadZ/diagram.png) + +Figure 1: LoadZ model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer + +### Parameter Validation + +```math +N \in \mathbb{Z}_{>0} +``` + +### Derived Parameters + +None. + +## Submodels + +Symbol | Description | Type | Order | JSON | Inputs | Outputs +------ | ----------- | ---- | ----- | ---- | ------ | ------- +$\mathbf{z}$ | Impedance | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $NQ_{\mathbf{z}}$ | `Z` | $\mathbb{R}^N$ | $\mathbb{R}^N$ + +### Submodel Validation + +The current is differential for a nonsingular linear coefficient and algebraic +when the coefficient is zero. Partially singular coefficients are not +supported. + +```math +\mathbf{E}^{\mathbf{z}}=\mathbf{0} +\qquad \text{or} \qquad +\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N. +``` + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}$ | [A] | Current injection from load into EMT bus | $\mathbf{i} \in \mathbb{R}^N$, $\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N$ + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}$ | [A] | Current injection from load into EMT bus | $\mathbf{i} \in \mathbb{R}^N$, $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$ + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{v}$ | [V] | Bus voltage vector owned by EMT bus | $\mathbf{v} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{v}$ | `v` | Input | [V] | Bus voltage at load port | $\mathbf{v} \in \mathbb{R}^N$ +$\mathbf{i}$ | `i` | Output | [A] | Current injection at load port | $\mathbf{i} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +For $\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N$, + +```math +0 = \mathbf{z}[\mathbf{i}] + \mathbf{v} +``` + +### Algebraic Equations + +For $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$, the same residual is algebraic. + +### Wiring + +None. + +## Initialization + +None beyond the EMT initialization contract. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`i` | [A] | Load current injection | $\mathbf{i} \in \mathbb{R}^N$ + +## Development + +The initial three-phase formulation uses resistance and inductance matrices. + +### Differential Equations + +```math +0 = +\mathbf{R}\mathbf{i} ++ \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t} ++ \mathbf{v} +``` diff --git a/GridKit/Model/EMT/Component/Load/README.md b/GridKit/Model/EMT/Component/Load/README.md new file mode 100644 index 000000000..d5f1c8415 --- /dev/null +++ b/GridKit/Model/EMT/Component/Load/README.md @@ -0,0 +1,7 @@ +# Load Models + +Load models use EMT bus voltages to determine current injections. + +## Models + +- [LoadZ](LoadZ/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..b974e2aa8 100644 --- a/GridKit/Model/EMT/Component/README.md +++ b/GridKit/Model/EMT/Component/README.md @@ -1,18 +1,11 @@ # Component Models -This directory contains EMT component model notes for devices connected to EMT +This directory documents EMT component models for devices connected to EMT buses. -A component 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 -5. Initialization notes -6. Monitorable outputs +## Contents -## Types - -- `BranchLumpedConstant` (See [BranchLumpedConstant](Branch/BranchLumpedConstant/README.md)) -- `LoadRL` (See [LoadRL](LoadRL/README.md)) -- `VoltageSource` (See [VoltageSource](VoltageSource/README.md)) +- [Lines](Line/README.md) +- [Loads](Load/README.md) +- [Sources](Source/README.md) +- [Switch](Switch/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..d2dc74fee --- /dev/null +++ b/GridKit/Model/EMT/Component/Source/README.md @@ -0,0 +1,7 @@ +# Source Models + +Source models prescribe EMT waveforms and inject currents into EMT buses. + +## Models + +- [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..be3931777 --- /dev/null +++ b/GridKit/Model/EMT/Component/Source/VoltageSource/README.md @@ -0,0 +1,126 @@ +# VoltageSource Model + +`VoltageSource` represents an $N$-phase sinusoidal EMT voltage source connected +to the EMT bus through terminal admittance. + +## Block Diagram + +![VoltageSource model block diagram](../../../../../../docs/Figures/EMT/VoltageSource/diagram.png) + +Figure 1: VoltageSource model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer +$\mathbf{E}$ | [V] | `E` | Source voltage magnitudes | $\mathbf{E} \in \mathbb{R}_{\ge 0}^N$, RMS +$\boldsymbol{\phi}$ | [rad] | `phi` | Source phase offsets | $\boldsymbol{\phi} \in \mathbb{R}^N$ +$\omega$ | [rad/s] | `omega` | Source angular frequency | Required, positive + +### Parameter Validation + +```math +\begin{aligned} +N &\in \mathbb{Z}_{>0} \\ +\mathbf{E} &\in \mathbb{R}_{\ge 0}^N \\ +\boldsymbol{\phi} &\in \mathbb{R}^N \\ +\omega &> 0 +\end{aligned} +``` + +### Derived Parameters + +Define the phase-index set + +```math +\mathcal{N} = \{1,\ldots,N\}. +``` + +## Submodels + +Symbol | Description | Type | Order | JSON | Inputs | Outputs +------ | ----------- | ---- | ----- | ---- | ------ | ------- +$\mathbf{y}$ | Terminal admittance | [VectorFit](../../../Operators/Rational/VectorFit/README.md) | $NQ_{\mathbf{y}}$ | `Y` | $\mathbb{R}^N$ | $\mathbb{R}^N$ + +### Submodel Validation + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{e}$ | [V] | Source voltage vector | $\mathbf{e} \in \mathbb{R}^N$ + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{v}$ | [V] | Bus voltage vector owned by EMT bus | $\mathbf{v} \in \mathbb{R}^N$ + +#### Algebraic + +None. + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{v}$ | `v` | Input | [V] | Bus voltage at source port | $\mathbf{v} \in \mathbb{R}^N$ +$\mathbf{i}$ | `i` | Output | [A] | Current injection at source port | $\mathbf{i} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +0 = e_n - \sqrt{2}E_n\cos(\omega t + \phi_n), +\quad n \in \mathcal{N} +``` + +### Wiring + +```math +\mathbf{i} \leftarrow \mathbf{y}[\mathbf{e} - \mathbf{v}] +``` + +## Initialization + +None beyond the EMT initialization contract. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`e` | [V] | Source voltage | $\mathbf{e} \in \mathbb{R}^N$ +`i` | [A] | Source current injection | $\mathbf{i} \in \mathbb{R}^N$ + +## Development + +The initial three-phase formulation realizes the terminal admittance as a +series resistance and inductance, with $\mathbf{i}$ as a differential variable. + +### Differential Equations + +```math +0 = +\mathbf{R}_\mathrm{s}\mathbf{i} ++ \mathbf{L}_\mathrm{s}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t} ++ \mathbf{v} +- \mathbf{e} +``` diff --git a/GridKit/Model/EMT/Component/Switch/README.md b/GridKit/Model/EMT/Component/Switch/README.md new file mode 100644 index 000000000..901e2b8cd --- /dev/null +++ b/GridKit/Model/EMT/Component/Switch/README.md @@ -0,0 +1,110 @@ +# Switch Model + +`Switch` represents an ideal $N$-phase EMT switch between two buses. Series +current $\mathbf{i}_{12}$ is directed from terminal 1 to terminal 2. The +required Boolean input `open` operates all phases: `true` is open and +`false` is closed. The switch contains no energy storage; switching +transients arise from the connected EMT network. + +## Block Diagram + +![Switch model block diagram](../../../../../docs/Figures/EMT/Switch/diagram.png) + +Figure 1: Switch model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$N$ | [-] | `N` | Number of phases | Required, positive integer + +### Parameter Validation + +```math +N \in \mathbb{Z}_{>0} +``` + +### Derived Parameters + +None. + +## Submodels + +None. + +### Submodel Validation + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{i}_{12}$ | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^N$ + +### 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{v}_1$ | `v1` | Input | [V] | Terminal 1 bus voltage | $\mathbf{v}_1 \in \mathbb{R}^N$ +$\mathbf{v}_2$ | `v2` | Input | [V] | Terminal 2 bus voltage | $\mathbf{v}_2 \in \mathbb{R}^N$ +$\mathrm{open}$ | `open` | Input | [-] | Ganged switch command | Required Boolean; `true` open, `false` closed +$\mathbf{i}_1$ | `i1` | Output | [A] | Current injection at terminal 1 | $\mathbf{i}_1 \in \mathbb{R}^N$ +$\mathbf{i}_2$ | `i2` | Output | [A] | Current injection at terminal 2 | $\mathbf{i}_2 \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +```math +\begin{cases} +\mathbf{i}_{12} = \mathbf{0}, & \text{open}, \\ +\mathbf{v}_2-\mathbf{v}_1 = \mathbf{0}, & \text{closed}. +\end{cases} +``` + +### Wiring + +```math +\begin{aligned} +\mathbf{i}_1 &\leftarrow -\mathbf{i}_{12} \\ +\mathbf{i}_2 &\leftarrow \mathbf{i}_{12}. +\end{aligned} +``` + +## Initialization + +The `open` command is applied at $t_0$ before enforcing the algebraic +equations. The switch has no additional model-specific initialization. + +## Monitors + +Monitor | Units | Description | Note +------- | ----- | ----------- | ---- +`open` | [-] | Switch command | Boolean; `true` open, `false` closed +`i12` | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^N$ 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..e08ab60a1 --- /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. + +## Contents + +- [Rational operators](Rational/README.md) +- [Shift operators](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..6c2083af4 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/README.md @@ -0,0 +1,8 @@ +# Rational Operators + +Rational operators represent fitted transfer functions. + +## Models + +- [VectorFit](VectorFit/README.md) +- [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..78bcaf77f --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md @@ -0,0 +1,200 @@ +# StateSpace Model + +`StateSpace` represents a vector-fitted matrix rational approximation with +real or complex poles and factorized residue terms. For pole count $Q$, define +the pole-index set + +```math +\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\}. +``` + +Thus $\mathcal{Q}$ is empty when $Q=0$. + +Then + +```math +\mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} + + \mathbf{C}\dfrac{\mathbf{I}}{s\mathbf{I}-\mathbf{P}}\mathbf{B} +``` + +> [!NOTE] +> The consuming model classifies the input $\mathbf{u}$ as differential or +> algebraic. +> Algebraic input requires $\mathbf{E} = \mathbf{0}$. + +> [!NOTE] +> Each factorized term has residue +> $\mathbf{R}_q = \mathbf{C}_{:,q}\mathbf{B}_{q,:}$, so +> $\mathrm{rank}(\mathbf{R}_q) \le 1$. Terms with the same +> pole may be repeated. Their residues sum and can have higher rank. + +## Block Diagram + +![StateSpace rational-operator block diagram](../../../../../../docs/Figures/EMT/StateSpace/diagram.png) + +Figure 1: StateSpace model + +## Model Parameters + +For output dimension $N$, input dimension $K$, pole count $Q$, input units +$[u]$, and output units $[y]$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\mathbf{D}$ | $[y]/[u]$ | `D` | Constant coefficient | $\mathbf{D} \in \mathbb{R}^{N \times K}$ +$\mathbf{E}$ | $\mathrm{s}[y]/[u]$ | `E` | Linear coefficient | $\mathbf{E} \in \mathbb{R}^{N \times K}$ +$\mathbf{p}$ | $[\mathrm{s}^{-1}]$ | `poles` | Poles | $\mathbf{p} \in \mathbb{C}^Q$ +$\mathbf{C}$ | $[y]/[u]$ | `C` | Output matrix | $\mathbf{C} \in \mathbb{C}^{N \times Q}$ +$\mathbf{B}$ | $[\mathrm{s}^{-1}]$ | `B` | Input matrix | $\mathbf{B} \in \mathbb{C}^{Q \times K}$ + +### Parameter Validation + +The input and output dimensions are positive integers, and the pole count is a +nonnegative integer. Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain +the real-pole indices and +$\mathcal{Q}_\mathrm{c} \subseteq \mathcal{Q}$ the first indices of the +nonreal conjugate pairs. Define their partner-index set as + +```math +\mathcal{Q}_\mathrm{c}^{+} + = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\}. +``` + +The three sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and +$\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint and together contain every +pole index. Real poles have real factors, and each nonreal pole and its factors +are followed by their conjugates. + +```math +\begin{aligned} +N &\in \mathbb{Z}_{>0} \\ +K &\in \mathbb{Z}_{>0} \\ +Q &\in \mathbb{Z}_{\ge 0} \\ +\mathbf{E} &= \mathbf{0}, + \quad \text{for algebraic input} \\ +\mathcal{Q}_\mathrm{r} \cup \mathcal{Q}_\mathrm{c} + \cup \mathcal{Q}_\mathrm{c}^{+} + &= \mathcal{Q} \\ +p_q &\in \mathbb{R}, + \quad \mathbf{C}_{:,q} \in \mathbb{R}^N, + \quad \mathbf{B}_{q,:} \in \mathbb{R}^K, + \quad q \in \mathcal{Q}_\mathrm{r} \\ +p_{q+1} &= p_q^{\ast}, + \quad q \in \mathcal{Q}_\mathrm{c} \\ +\mathbf{C}_{:,q+1} &= \mathbf{C}_{:,q}^{\ast}, + \quad q \in \mathcal{Q}_\mathrm{c} \\ +\mathbf{B}_{q+1,:} &= \mathbf{B}_{q,:}^{\ast}, + \quad q \in \mathcal{Q}_\mathrm{c} +\end{aligned} +``` + +### Derived Parameters + +```math +\begin{aligned} +\mathbf{P} &= \mathrm{diag}(p_1,\ldots,p_Q) \\ +\mathbf{a} &= \mathrm{Re}(\mathbf{p}) \\ +\boldsymbol{\omega} &= \mathrm{Im}(\mathbf{p}) \\ +\mathbf{C}_{\mathrm{r}} &= \mathrm{Re}(\mathbf{C}) \\ +\mathbf{C}_{\mathrm{i}} &= \mathrm{Im}(\mathbf{C}) \\ +\mathbf{B}_{\mathrm{r}} &= \mathrm{Re}(\mathbf{B}) \\ +\mathbf{B}_{\mathrm{i}} &= \mathrm{Im}(\mathbf{B}) +\end{aligned} +``` + +## Submodels + +None. + +### Submodel Validation + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$w_q$ | $[u]$ | Real memory state | $w_q \in \mathbb{R}$, $q \in \mathcal{Q}_\mathrm{r} \cup \mathcal{Q}_\mathrm{c}$ +$v_q$ | $[u]$ | Imaginary memory state | $v_q \in \mathbb{R}$, $q \in \mathcal{Q}_\mathrm{c}$ + +The documented real realization has order $Q$. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{y}$ | $[y]$ | Output vector | $\mathbf{y} \in \mathbb{R}^N$ + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | Differential-input configuration, $\mathbf{u} \in \mathbb{R}^K$ + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | Algebraic-input configuration, $\mathbf{u} \in \mathbb{R}^K$ + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | $[u]$ | Input vector port | $\mathbf{u} \in \mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | $[y]$ | Output vector port | $\mathbf{y} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= -\dfrac{\mathrm{d}w_q}{\mathrm{d}t} + + a_qw_q+\mathbf{B}_{q,:}\mathbf{u}, + \quad q \in \mathcal{Q}_\mathrm{r} \\ +0 &= -\dfrac{\mathrm{d}w_q}{\mathrm{d}t} + + a_qw_q-\omega_qv_q + + (\mathbf{B}_{\mathrm{r}})_{q,:}\mathbf{u} \\ +0 &= -\dfrac{\mathrm{d}v_q}{\mathrm{d}t} + + \omega_qw_q+a_qv_q + + (\mathbf{B}_{\mathrm{i}})_{q,:}\mathbf{u}, + \quad q \in \mathcal{Q}_\mathrm{c} +\end{aligned} +``` + +### Algebraic Equations + +```math +\begin{aligned} +0 &= -\mathbf{y} + + \mathbf{D}\mathbf{u} + + \mathbf{E}\dfrac{\mathrm{d}\mathbf{u}}{\mathrm{d}t} + + \sum_{q \in \mathcal{Q}_\mathrm{r}} + \mathbf{C}_{:,q}w_q + + 2\sum_{q \in \mathcal{Q}_\mathrm{c}} + ((\mathbf{C}_{\mathrm{r}})_{:,q}w_q + -(\mathbf{C}_{\mathrm{i}})_{:,q}v_q) +\end{aligned} +``` + +For algebraic input, $\mathbf{E}=\mathbf{0}$ and the input-derivative term +vanishes. + +### Wiring + +None. + +## Initialization + +None beyond the EMT initialization contract. + +## 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..a4269eca3 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md @@ -0,0 +1,191 @@ +# VectorFit Model + +`VectorFit` represents a vector-fitted matrix rational approximation with real +or complex poles and general residue matrices. For pole count $Q$, define the +pole-index set + +```math +\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\}. +``` + +Thus $\mathcal{Q}$ is empty when $Q=0$. + +Then + +```math +\mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} + + \sum_{q \in \mathcal{Q}} \dfrac{\mathbf{R}_q}{s - p_q}. +``` + +`VectorFit` is a general rational operator; consuming models impose any +physical constraints. + +> [!NOTE] +> The consuming model classifies the input $\mathbf{u}$ as differential or +> algebraic. +> Algebraic input requires $\mathbf{E} = \mathbf{0}$. + +## Block Diagram + +![VectorFit rational-operator block diagram](../../../../../../docs/Figures/EMT/VectorFit/diagram.png) + +Figure 1: VectorFit model + +## Model Parameters + +For output dimension $N$, input dimension $K$, pole count $Q$, input units +$[u]$, and output units $[y]$: + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$\mathbf{D}$ | $[y]/[u]$ | `D` | Constant coefficient | $\mathbf{D} \in \mathbb{R}^{N \times K}$ +$\mathbf{E}$ | $\mathrm{s}[y]/[u]$ | `E` | Linear coefficient | $\mathbf{E} \in \mathbb{R}^{N \times K}$ +$\mathbf{p}$ | $[\mathrm{s}^{-1}]$ | `poles` | Poles | $\mathbf{p} \in \mathbb{C}^Q$ +$\mathbf{R}$ | $[y]/(\mathrm{s}[u])$ | `residues` | Residues | $\mathbf{R} \in \mathbb{C}^{N \times K \times Q}$ + +### Parameter Validation + +The input and output dimensions are positive integers, and the pole count is a +nonnegative integer. Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain +the real-pole indices and +$\mathcal{Q}_\mathrm{c} \subseteq \mathcal{Q}$ the first indices of the +nonreal conjugate pairs. Define their partner-index set as + +```math +\mathcal{Q}_\mathrm{c}^{+} + = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\}. +``` + +The three sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and +$\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint and together contain every +pole index. Real poles have real residues, and each nonreal pole and residue is +followed by its conjugate. + +```math +\begin{aligned} +N &\in \mathbb{Z}_{>0} \\ +K &\in \mathbb{Z}_{>0} \\ +Q &\in \mathbb{Z}_{\ge 0} \\ +\mathbf{E} &= \mathbf{0}, + \quad \text{for algebraic input} \\ +\mathcal{Q}_\mathrm{r} \cup \mathcal{Q}_\mathrm{c} + \cup \mathcal{Q}_\mathrm{c}^{+} + &= \mathcal{Q} \\ +p_q &\in \mathbb{R}, + \quad \mathbf{R}_q \in \mathbb{R}^{N \times K}, + \quad q \in \mathcal{Q}_\mathrm{r} \\ +p_{q+1} &= p_q^{\ast}, + \quad q \in \mathcal{Q}_\mathrm{c} \\ +\mathbf{R}_{q+1} &= \mathbf{R}_q^{\ast}, + \quad q \in \mathcal{Q}_\mathrm{c} +\end{aligned} +``` + +### Derived Parameters + +```math +\begin{aligned} +\mathbf{a} &= \mathrm{Re}(\mathbf{p}) \\ +\boldsymbol{\omega} &= \mathrm{Im}(\mathbf{p}) \\ +\mathbf{A} &= \mathrm{Re}(\mathbf{R}) \\ +\mathbf{B} &= \mathrm{Im}(\mathbf{R}) +\end{aligned} +``` + +## Submodels + +None. + +### Submodel Validation + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{w}_q$ | $\mathrm{s}[u]$ | Real memory states | $\mathbf{w}_q \in \mathbb{R}^K$, $q \in \mathcal{Q}_\mathrm{r} \cup \mathcal{Q}_\mathrm{c}$ +$\mathbf{v}_q$ | $\mathrm{s}[u]$ | Imaginary memory states | $\mathbf{v}_q \in \mathbb{R}^K$, $q \in \mathcal{Q}_\mathrm{c}$ + +The documented real realization has order $KQ$. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{y}$ | $[y]$ | Output vector | $\mathbf{y} \in \mathbb{R}^N$ + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | Differential-input configuration, $\mathbf{u} \in \mathbb{R}^K$ + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | Algebraic-input configuration, $\mathbf{u} \in \mathbb{R}^K$ + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | $[u]$ | Input vector port | $\mathbf{u} \in \mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | $[y]$ | Output vector port | $\mathbf{y} \in \mathbb{R}^N$ + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +0 &= -\dfrac{\mathrm{d}\mathbf{w}_q}{\mathrm{d}t} + + a_q\mathbf{w}_q + + \mathbf{u}, + \quad q \in \mathcal{Q}_\mathrm{r} \\ +0 &= -\dfrac{\mathrm{d}\mathbf{w}_q}{\mathrm{d}t} + + a_q\mathbf{w}_q + - \omega_q\mathbf{v}_q + + \mathbf{u} \\ +0 &= -\dfrac{\mathrm{d}\mathbf{v}_q}{\mathrm{d}t} + + \omega_q\mathbf{w}_q + + a_q\mathbf{v}_q, + \quad q \in \mathcal{Q}_\mathrm{c} +\end{aligned} +``` + +### Algebraic Equations + +```math +\begin{aligned} +0 &= -\mathbf{y} + + \mathbf{D}\mathbf{u} + + \mathbf{E}\dfrac{\mathrm{d}\mathbf{u}}{\mathrm{d}t} + + \sum_{q \in \mathcal{Q}_\mathrm{r}} + \mathbf{A}_q\mathbf{w}_q + + 2\sum_{q \in \mathcal{Q}_\mathrm{c}} + (\mathbf{A}_q\mathbf{w}_q-\mathbf{B}_q\mathbf{v}_q) +\end{aligned} +``` + +For algebraic input, $\mathbf{E}=\mathbf{0}$ and the input-derivative term +vanishes. + +### Wiring + +None. + +## Initialization + +None beyond the EMT initialization contract. + +## 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..2724b8ee4 --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/Delay/README.md @@ -0,0 +1,184 @@ +# Delay Model + +`Delay` applies a constant transport delay to each of $M$ input channels: + +```math +\mathbf{D}_{\boldsymbol{\tau}}(s) + = \mathrm{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right). +``` + +At runtime, accepted-step input samples are reconstructed with cubic Hermite +interpolation. `Delay` adds no DAE variables or residual rows. A scalar delay +is the $M=1$ case. + +## Block Diagram + +![Delay operator block diagram](../../../../../../docs/Figures/EMT/Delay/diagram.png) + +Figure 1: Delay model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$M$ | [-] | `M` | Channel count | Required, positive integer +$\boldsymbol{\tau}$ | [s] | `tau` | Channel delays | Required, each positive + +### Parameter Validation + +```math +\begin{aligned} +M &\in \mathbb{Z}_{>0} \\ +\tau_m &> 0 +\end{aligned} +``` + +### Derived Parameters + +```math +\tau_{\min} = \min(\boldsymbol{\tau}), +\qquad +\tau_{\max} = \max(\boldsymbol{\tau}) +``` + +## Submodels + +None. + +### Submodel Validation + +None. + +## Model Variables + +History samples are implementation data, not DAE variables or residual rows. + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | $\mathbf{u} \in \mathbb{R}^M$ + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | $[u]$ | Input vector port | $\mathbf{u} \in \mathbb{R}^M$ +$\mathbf{y}$ | `out` | Output | $[u]$ | Delayed output port | $\mathbf{y} \in \mathbb{R}^M$ + +The output provides both value and time derivative. + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +### Wiring + +```math +\mathbf{y} + \leftarrow \mathbf{u}(t-\boldsymbol{\tau}), +\qquad +\dfrac{\mathrm{d}\mathbf{y}}{\mathrm{d}t} + \leftarrow \dfrac{\mathrm{d}\mathbf{u}}{\mathrm{d}t}(t-\boldsymbol{\tau}) +``` + +Each channel satisfies $y_m(t)=u_m(t-\tau_m)$. Arguments at or before zero use +the prehistory defined under Initialization. + +## History Realization + +### History Record + +Accepted input history is stored as the knot sequence + +```math +(t_j,\ \mathbf{u}_j,\ \mathbf{u}'_j), +\qquad 0 = t_0 < t_1 < \cdots < t_n, +``` + +where $\mathbf{u}_j$ and $\mathbf{u}'_j$ are the input value and derivative at +$t_j$. The first knot holds the initialized values. Channels share knot times +and read the record at $t-\tau_m$ independently. + +![Delay history record and per-channel taps](../../../../../../docs/Figures/EMT/DelayHistory/diagram.png) + +Figure 2: Delay history record and channel taps + +> [!WARNING] +> Later knots are appended only at accepted steps, and the solver step size +> must not exceed $\tau_{\min}$. These constraints keep every lookup at or +> behind the accepted frontier; the realization must not extrapolate beyond +> it. + +### Interpolation + +Suppressing the channel index, a lookup at $\xi \le 0$ uses the analytic +prehistory. For $\xi \in (t_j,t_{j+1}]$, the bracketing knots define the cubic +Hermite interpolant + +```math +\begin{aligned} +h_j &= t_{j+1}-t_j, +\qquad +\theta = \dfrac{\xi-t_j}{h_j} \\ +u(\xi) + &= (1-\theta)^2(1+2\theta)\,u_j + + \theta(1-\theta)^2\,h_j\,u'_j \\ + &\quad + + \theta^2(3-2\theta)\,u_{j+1} + - \theta^2(1-\theta)\,h_j\,u'_{j+1}, +\end{aligned} +``` + +Its derivative comes from the same polynomial. For smooth input and exact +knot data, the interpolant is $C^1$ with nominal fourth-order value accuracy +and third-order derivative accuracy in the knot spacing. + +## Initialization + +A prehistory for $\mathbf{u}(t)$ and +$\mathrm{d}\mathbf{u}/\mathrm{d}t$ must be specified over + +```math +t \in [t_0-\tau_{\max},t_0]. +``` + +Its endpoint value and derivative must match the initialized input at $t_0$. +The delay does not synthesize prehistory. At $t_0$, + +```math +\begin{aligned} +\mathbf{y}(t_0) + &\leftarrow \mathbf{u}(t_0-\boldsymbol{\tau}) \\ +\left.\dfrac{\mathrm{d}\mathbf{y}}{\mathrm{d}t}\right|_{t_0} + &\leftarrow + \left.\dfrac{\mathrm{d}\mathbf{u}}{\mathrm{d}t} + \right|_{t_0-\boldsymbol{\tau}}. +\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..3e1ab53bb --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -0,0 +1,138 @@ +# Propagation Model + +For input units $[u]$, `Propagation` is the $K$-channel current-form propagation +operator used by `LineDistributed`. It applies a fitted input factor, one scalar +delay per mode, and a fitted output factor while preserving the input units. + +## Block Diagram + +![Propagation operator block diagram](../../../../../../docs/Figures/EMT/Propagation/diagram.png) + +Figure 1: Propagation model + +## Model Parameters + +Symbol | Units | JSON | Description | Note +------ | ----- | ---- | ----------- | ---- +$K$ | [-] | `K` | Signal dimension | Required, positive integer + +### Parameter Validation + +```math +K \in \mathbb{Z}_{>0} +``` + +### Derived Parameters + +The full modal basis has one mode per channel: + +```math +\begin{aligned} +M &= K \\ +\boldsymbol{\tau} &= [\tau_1,\ldots,\tau_M]^\mathsf T +\end{aligned} +``` + +The modal delays are produced by the offline propagation fitting and enter +through the delay bank's `delays` coefficient set. + +## Submodels + +Symbol | Description | Type | Order | JSON | Inputs | Outputs +------ | ----------- | ---- | ----- | ---- | ------ | ------- +$\mathbf{g}_\mathrm{in}$ | Input factor | [VectorFit](../../Rational/VectorFit/README.md) | $KQ_{\mathbf{g}_\mathrm{in}}$ | `input` | $\mathbb{R}^K$ | $\mathbb{R}^M$ +$\mathbf{d}$ | Modal delay bank | [Delay](../Delay/README.md) | History | `delays` | $\mathbb{R}^M$ | $\mathbb{R}^M$ +$\mathbf{g}_\mathrm{out}$ | Output factor | [VectorFit](../../Rational/VectorFit/README.md) | $KQ_{\mathbf{g}_\mathrm{out}}$ | `output` | $\mathbb{R}^M$ | $\mathbb{R}^K$ + +The offline fitting targets and propagation factorization are + +```math +\begin{aligned} +\mathbf{G}^\mathrm{in}(s) + &\approx \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\ +\mathbf{G}^\mathrm{out}(s) &\approx \mathbf{T}_i(s) \\ +\mathbf{H}^\mathrm{mps}(s) + &= \mathrm{diag}(h_1^\mathrm{mps}(s),\ldots,h_M^\mathrm{mps}(s)) \\ +\mathbf{D}_{\boldsymbol{\tau}}(s) + &= \mathrm{diag}(e^{-s\tau_1},\ldots,e^{-s\tau_M}) \\ +\mathbf{H}(s) + &= \mathbf{T}_i(s)\mathbf{D}_{\boldsymbol{\tau}}(s) + \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\ + &\approx \mathbf{G}^\mathrm{out}(s)\mathbf{D}_{\boldsymbol{\tau}}(s) + \mathbf{G}^\mathrm{in}(s) +\end{aligned} +``` + +$\mathbf{H}^\mathrm{mps}$ is the diagonal modal minimum-phase-shift propagation +function with the modal delays removed. The current modal transformation +$\mathbf{T}_i$ maps modal currents to phase coordinates, and +$\mathbf{T}_i^{-1}$ maps phase currents to modal coordinates. + +### Submodel Validation + +Both rational factors must have stable poles and no term linear in $s$. The +input factor has algebraic input; the output factor has differential input +from the modal delay bank. + +```math +\mathbf{E}^\mathrm{in}=\mathbf{E}^\mathrm{out}=\mathbf{0} +``` + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +------ | ----- | ----------- | ---- +$\mathbf{u}$ | $[u]$ | Input vector | $\mathbf{u} \in \mathbb{R}^K$ + +## Model Ports + +Symbol | Port | Type | Units | Description | Note +------ | ---- | ---- | ----- | ----------- | ---- +$\mathbf{u}$ | `input` | Input | $[u]$ | Input vector port | $\mathbf{u} \in \mathbb{R}^K$ +$\mathbf{y}$ | `out` | Output | $[u]$ | Output vector port | $\mathbf{y} \in \mathbb{R}^K$ + +## Model Equations + +### Differential Equations + +None. + +### Algebraic Equations + +None. + +### Wiring + +```math +\begin{aligned} +\mathbf{w} &\leftarrow \mathbf{g}_\mathrm{in}[\mathbf{u}] \\ +\mathbf{z} &\leftarrow \mathbf{d}[\mathbf{w}] \\ +\mathbf{y} &\leftarrow \mathbf{g}_\mathrm{out}[\mathbf{z}] +\end{aligned} +``` + +## Initialization + +TBD + +## 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..1434abb3b --- /dev/null +++ b/GridKit/Model/EMT/Operators/Shift/README.md @@ -0,0 +1,8 @@ +# Shift Operators + +Shift operators represent signal propagation in time. + +## Models + +- [Delay](Delay/README.md) +- [Propagation](Propagation/README.md) diff --git a/GridKit/Model/EMT/README.md b/GridKit/Model/EMT/README.md index abc526839..b3a10e478 100644 --- a/GridKit/Model/EMT/README.md +++ b/GridKit/Model/EMT/README.md @@ -1,29 +1,61 @@ # Electromagnetic Transients (EMT) -This directory contains design documentation for electromagnetic transient -(EMT) component models in instantaneous abc coordinates. +This directory documents electromagnetic transient (EMT) model specifications +and reusable operators in instantaneous phase coordinates. -## Conventions +> [!NOTE] +> The formulation supports $N$ phases; initial development targets three +> phases. -These conventions reflect the current EMT model draft and may change as the -EMT design and implementation develop. +## Conventions -- Phase order is $a$, $b$, $c$. +- $N$ denotes a phase or output dimension, $K$ a conductor or input dimension, + $M$ a mode count, and $Q$ a pole count. +- Corresponding calligraphic symbols denote index sets, such as + $\mathcal{M}$ for modal indices and $\mathcal{Q}$ for pole indices. - Equations use SI units unless a model states otherwise. +- Time derivatives are written explicitly as $\mathrm{d}(\cdot)/\mathrm{d}t$. - Current injection terms are written as positive into buses. - - -## Model Categories - -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 +- $\mathrm{j}$ denotes the imaginary unit and is not used as an index. +- The Model Variables section lists DAE variables owned directly by the model. + Each scalar internal variable corresponds to one local residual row; + external variables are owned elsewhere. Submodel-owned variables are not + repeated by the parent. +- Wiring introduces aliases or derived signals, not DAE variables or residual + rows. Ports and monitors may expose either without changing ownership. +- Equation headings follow the assembled DAE row classification; connected + models may add derivative terms to a residual that contains none locally. + +## Assembly + +Bus voltage is algebraic unless a connected model contributes a voltage +derivative to the bus current-balance. + +## Initialization + +EMT models are initialized using real-valued, instantaneous phase-coordinate +quantities in $\mathbb{R}^N$. RMS or phasor calculations, when used by an +upstream initialization workflow, are outside the EMT model specification. + +Initial differential states, algebraic variables, derivatives, and discrete +inputs must be consistent with the assembled EMT equations at $t_0$. Models +that require additional history document that requirement locally. + +## Contents + +- [Bus](Bus/README.md) +- [Components](Component/README.md) +- [Operators](Operators/README.md) + +## References + +- B. Gustavsen and A. Semlyen, [“Rational approximation of frequency domain + responses by vector fitting,”](https://doi.org/10.1109/61.772353) *IEEE + Transactions on Power Delivery*, 1999. +- A. Morched, B. Gustavsen, and M. Tartibi, [“A universal model for accurate + calculation of electromagnetic transients on overhead lines and underground + cables,”](https://doi.org/10.1109/61.772350) *IEEE Transactions on Power + Delivery*, 1999. +- B. Gustavsen and A. Semlyen, [“Enforcing passivity for admittance matrices + approximated by rational functions,”](https://doi.org/10.1109/59.910786) + *IEEE Transactions on Power Systems*, 2001. diff --git a/docs/Figures/EMT/Bus/diagram.png b/docs/Figures/EMT/Bus/diagram.png new file mode 100644 index 000000000..14bbaca82 Binary files /dev/null and b/docs/Figures/EMT/Bus/diagram.png differ diff --git a/docs/Figures/EMT/Bus/diagram.tex b/docs/Figures/EMT/Bus/diagram.tex new file mode 100644 index 000000000..e943f5ebe --- /dev/null +++ b/docs/Figures/EMT/Bus/diagram.tex @@ -0,0 +1,30 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Bus voltage node ================= +\draw[line] (0, -1.25) -- (0, 1.3); +\node[signal, label={[sig]above:$\mathbf{v}$}] at (0, 1.3) {}; + +% ================= Connected-device currents ================= +\coordinate (i1) at (-3.4, 0.8); +\coordinate (i2) at (-3.4, 0.2); +\coordinate (iE) at (-3.4, -0.9); + +\draw[->, line] (i1) -- (0, 0.8); +\draw[->, line] (i2) -- (0, 0.2); +\draw[->, line] (iE) -- (0, -0.9); + +\node[sig, anchor=east] at ($(i1)+(-0.2,0)$) {$\mathbf{i}_1$}; +\node[sig, anchor=east] at ($(i2)+(-0.2,0)$) {$\mathbf{i}_2$}; +\node[sig, anchor=east] at ($(iE)+(-0.2,0)$) + {$\mathbf{i}_{|\mathcal{E}|}$}; +\node at (-1.7, -0.35) {$\vdots$}; + +% ================= Model enclosure ================= +\draw[enclosure] (-0.8, -1.65) rectangle (0.8, 1.9); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Delay/diagram.png b/docs/Figures/EMT/Delay/diagram.png new file mode 100644 index 000000000..f59786148 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..525f6747b --- /dev/null +++ b/docs/Figures/EMT/Delay/diagram.tex @@ -0,0 +1,25 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +\node[block, minimum width=2.6cm] (delay) + {$\mathbf{D}_{\boldsymbol{\tau}}(s)$}; + +\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) + at ($(delay.west)+(-1.35,0)$) {}; +\draw[line] ($(uin)+(-0.8,0)$) -- (uin); +\draw[->, line] (uin) -- (delay.west); + +\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of delay] + (yout) {}; +\draw[line] (delay.east) -- (yout); +\draw[->, line] (yout) -- ++(1.35,0); + +\begin{scope}[on background layer] + \node[operator enclosure, fit=(delay)(yout)] {}; +\end{scope} + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/DelayHistory/diagram.png b/docs/Figures/EMT/DelayHistory/diagram.png new file mode 100644 index 000000000..194d7ffa6 Binary files /dev/null and b/docs/Figures/EMT/DelayHistory/diagram.png differ diff --git a/docs/Figures/EMT/DelayHistory/diagram.tex b/docs/Figures/EMT/DelayHistory/diagram.tex new file mode 100644 index 000000000..8e7482ea2 --- /dev/null +++ b/docs/Figures/EMT/DelayHistory/diagram.tex @@ -0,0 +1,83 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram, x=1.18cm, y=1.05cm] + +% Stored history and its shared knot times +\fill[black!4] (2.0,1.25) rectangle (6.6,4.65); +\foreach \x in {2.0,2.9,3.8,4.7,5.6} + \draw[black!18, thin] (\x,1.25) -- (\x,4.65); +\draw[dashed, semithick] (6.6,0) -- (6.6,4.65); + +% Time axis and region labels +\draw[->, line] (0.15,0) -- (9.15,0) node[right] {time}; +\node[below=3pt] at (2.0,0) {$0$}; +\node[below=3pt] at (6.6,0) {$t_n$}; +\draw[fill=white, semithick] (8.35,0) circle (1.8pt); +\node[below=3pt] at (8.35,0) {$t$}; +\node[font=\small] at (1.0,4.95) {prehistory}; +\node[font=\small] at (4.3,4.95) {stored history}; +\node[font=\small, anchor=west] at (6.72,4.58) {accepted frontier}; + +% Channel 1: the lookup lies in the analytic prehistory +\node[left] at (0.25,4.15) {$u_1$}; +\draw[densely dotted, semithick] + plot[smooth] coordinates { + (0.65,4.2) (1.25,4.32) (2.0,4.12) + }; +\draw[semithick] + plot[smooth] coordinates { + (2.0,4.12) (2.9,3.88) (3.8,4.3) (4.7,3.92) + (5.6,4.28) (6.6,4.04) + }; +\foreach \x/\y in {2.0/4.12,2.9/3.88,3.8/4.3,4.7/3.92,5.6/4.28,6.6/4.04} + \fill (\x,\y) circle (1.65pt); +\draw[dashed, thin] (1.25,0) -- (1.25,4.32); +\draw[fill=white, semithick] (1.25,4.32) circle (2pt) + node[above=3pt] {$t-\tau_1$}; + +% Channel 2: lookup within a Hermite segment +\node[left] at (0.25,2.95) {$u_2$}; +\draw[densely dotted, semithick] + plot[smooth] coordinates { + (0.65,2.82) (1.25,2.9) (2.0,3.08) + }; +\draw[semithick] + plot[smooth] coordinates { + (2.0,3.08) (2.9,3.28) (3.45,2.93) (3.8,2.72) + (4.7,3.12) (5.6,2.78) (6.6,3.06) + }; +\begin{scope} + \clip (2.9,2.55) rectangle (3.8,3.4); + \draw[very thick] + plot[smooth] coordinates { + (2.0,3.08) (2.9,3.28) (3.45,2.93) (3.8,2.72) (4.7,3.12) + }; +\end{scope} +\foreach \x/\y in {2.0/3.08,2.9/3.28,3.8/2.72,4.7/3.12,5.6/2.78,6.6/3.06} + \fill (\x,\y) circle (1.65pt); +\draw[dashed, thin] (3.45,0) -- (3.45,2.93); +\draw[fill=white, semithick] (3.45,2.93) circle (2pt) + node[above right=2pt] {$t-\tau_2$}; +\node[font=\scriptsize, anchor=north] at (3.35,2.5) {Hermite segment}; + +% Channel 3: the shallowest lookup remains behind the frontier +\node[left] at (0.25,1.75) {$u_3$}; +\draw[densely dotted, semithick] + plot[smooth] coordinates { + (0.65,1.88) (1.25,1.8) (2.0,1.58) + }; +\draw[semithick] + plot[smooth] coordinates { + (2.0,1.58) (2.9,1.88) (3.8,1.55) (4.7,1.84) + (5.6,1.6) (6.02,1.68) (6.6,1.82) + }; +\foreach \x/\y in {2.0/1.58,2.9/1.88,3.8/1.55,4.7/1.84,5.6/1.6,6.6/1.82} + \fill (\x,\y) circle (1.65pt); +\draw[dashed, thin] (6.02,0) -- (6.02,1.68); +\draw[fill=white, semithick] (6.02,1.68) circle (2pt) + node[above=3pt] {$t-\tau_3$}; + +\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..7351b88c3 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..df806e422 --- /dev/null +++ b/docs/Figures/EMT/LineDistributed/diagram.tex @@ -0,0 +1,74 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Terminal 1 (left column) ================= +\node[sum] (kcl1) at (-2.4, 2.4) {$\Sigma$}; +\node[vblock] (Yc1) at (-2.4, 0.0) {$\mathbf{Y}^{\mathrm{c}}_1(s)$}; +\node[sum] (wave1) at (-2.4, -2.4) {$\Sigma$}; + +\node[signal, label={[sig]left:$\mathbf{v}_1$}] (v1) at (-5.6, 0) {}; + +\draw[->, line] (Yc1.north) -- (kcl1); +\draw[->, line] (Yc1.south) -- (wave1); +\draw[->, line] (kcl1.west) -- (-4.0, 2.4) + -- (-4.0, -2.4) -- (wave1); +\coordinate (i1port) at (-5.6, 0.8); +\draw[->, line] (-4.0, 0.8) -- (i1port); +\node[sig, left=3pt of i1port] {$\mathbf{i}_1$}; + +% Voltage lead crosses over the continuous current path. +\draw[line] (v1) -- (-4.18, 0); +\draw[wire jump] (-4.18, 0) + arc[start angle=180, end angle=0, radius=0.18]; +\draw[->, line] (-3.82, 0) -- (Yc1.west); + +% ================= Terminal 2 (right column) ================= +\node[sum] (wave2) at (2.4, 2.4) {$\Sigma$}; +\node[vblock] (Yc2) at (2.4, 0.0) {$\mathbf{Y}^{\mathrm{c}}_2(s)$}; +\node[sum] (kcl2) at (2.4, -2.4) {$\Sigma$}; + +\node[signal, label={[sig]right:$\mathbf{v}_2$}] (v2) at (5.6, 0) {}; + +\draw[->, line] (Yc2.north) -- (wave2); +\draw[->, line] (Yc2.south) -- (kcl2); +\draw[->, line] (kcl2.east) -- (4.0, -2.4) + -- (4.0, 2.4) -- (wave2); +\coordinate (i2port) at (5.6, 0.8); +\draw[->, line] (4.0, 0.8) -- (i2port); +\node[sig, right=3pt of i2port] {$\mathbf{i}_2$}; + +% Voltage lead crosses over the continuous current path. +\draw[line] (v2) -- (4.18, 0); +\draw[wire jump] (4.18, 0) + arc[start angle=0, end angle=180, radius=0.18]; +\draw[->, line] (3.82, 0) -- (Yc2.east); + +% ================= Propagation channels (straight rows) ================= +% 1 -> 2 (lower row, left to right) +\node[hblock] (H12) at (0, -2.4) {$\mathbf{H}_{12}(s)$}; +\draw[->, line] (wave1.east) -- (H12.west); +\draw[->, line] (H12.east) -- (kcl2.west); + +% 2 -> 1 (upper row, right to left) +\node[hblock] (H21) at (0, 2.4) {$\mathbf{H}_{21}(s)$}; +\draw[->, line] (wave2.west) -- (H21.east); +\draw[->, line] (H21.west) -- (kcl1.east); + +% ================= Summation signs ================= +\node[pm] at ($(kcl1)+(-0.26,-0.50)$) {$-$}; % Yc1 v1 subtracts +\node[pm] at ($(kcl1)+( 0.45, 0.26)$) {$+$}; % incident current adds +\node[pm] at ($(wave1)+(0.26, 0.50)$) {$+$}; % Yc1 v1 +\node[pm] at ($(wave1)+(-0.45,-0.26)$) {$-$}; % i1 +\node[pm] at ($(kcl2)+( 0.26, 0.50)$) {$-$}; % Yc2 v2 subtracts +\node[pm] at ($(kcl2)+(-0.45,-0.26)$) {$+$}; % incident current adds +\node[pm] at ($(wave2)+(-0.26,-0.50)$) {$+$}; % Yc2 v2 +\node[pm] at ($(wave2)+( 0.45, 0.26)$) {$-$}; % i2 + +% ================= Model enclosure ================= +\draw[enclosure] (-4.8, -3.6) rectangle (4.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..108fd736b 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..6ab1f3777 --- /dev/null +++ b/docs/Figures/EMT/LineLumped/diagram.tex @@ -0,0 +1,47 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Series branch Z(s) ================= +\node[hblock] (Z) at (0, 2.1) {$\mathbf{Z}(s)$}; + +% ================= Shunt branches Y(s) ================= +\node[vblock] (Yk) at (-2.8, -0.2) {$\mathbf{Y}(s)$}; +\node[vblock] (Ym) at ( 2.8, -0.2) {$\mathbf{Y}(s)$}; + +% ================= Top rail + injection leads (current leaving) ================= +\draw[->, line] (Z.west) -- (-6.2, 2.1); +\draw[->, line] (Z.east) -- ( 6.2, 2.1); +\node[sig, anchor=east] at (-6.45, 2.1) {$\mathbf{i}_1$}; +\node[sig, anchor=west] at ( 6.45, 2.1) {$\mathbf{i}_2$}; + +% shunt taps (T-junctions on the rail) +\node[signal] (Tk) at (-2.8, 2.1) {}; +\node[signal] (Tm) at ( 2.8, 2.1) {}; + +% ================= Shunt wiring ================= +\draw[line] (Tk) -- (Yk.north); +\draw[line] (Tm) -- (Ym.north); +\draw[line] (Yk.south) -- (-2.8, -2.5); +\draw[line] (Ym.south) -- ( 2.8, -2.5); + +% ================= Ground symbols ================= +\draw[semithick] (-3.15,-2.50) -- (-2.45,-2.50); +\draw[semithick] (-3.02,-2.65) -- (-2.58,-2.65); +\draw[semithick] (-2.89,-2.80) -- (-2.71,-2.80); + +\draw[semithick] ( 2.45,-2.50) -- ( 3.15,-2.50); +\draw[semithick] ( 2.58,-2.65) -- ( 3.02,-2.65); +\draw[semithick] ( 2.71,-2.80) -- ( 2.89,-2.80); + +% ================= Terminals + labels ================= +\node[signal, label={[sig]above:$\mathbf{v}_1$}] at (-5.4, 2.1) {}; +\node[signal, label={[sig]above:$\mathbf{v}_2$}] at ( 5.4, 2.1) {}; + +% ================= Model enclosure ================= +\draw[enclosure] (-4.6, -3.6) rectangle (4.6, 3.6); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/LoadZ/diagram.png b/docs/Figures/EMT/LoadZ/diagram.png new file mode 100644 index 000000000..8f533d815 Binary files /dev/null and b/docs/Figures/EMT/LoadZ/diagram.png differ diff --git a/docs/Figures/EMT/LoadZ/diagram.tex b/docs/Figures/EMT/LoadZ/diagram.tex new file mode 100644 index 000000000..ce0fb8df5 --- /dev/null +++ b/docs/Figures/EMT/LoadZ/diagram.tex @@ -0,0 +1,27 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Impedance branch ================= +\node[vblock] (Z) at (0, -0.1) {$\mathbf{Z}(s)$}; +\coordinate (terminal) at (0, 1.4); +\draw[line] (terminal) -- (Z.north); + +% ================= Terminal voltage and current ================= +\node[signal, label={[sig]above:$\mathbf{v}$}] (vport) at (-2.25, 1.4) {}; +\draw[->, line] (terminal) -- (-3.4, 1.4); +\node[sig, anchor=east] at (-3.65, 1.4) {$\mathbf{i}$}; + +% ================= Ground reference ================= +\draw[line] (Z.south) -- (0, -1.7); +\draw[semithick] (-0.35, -1.70) -- (0.35, -1.70); +\draw[semithick] (-0.22, -1.85) -- (0.22, -1.85); +\draw[semithick] (-0.09, -2.00) -- (0.09, -2.00); + +% ================= Model enclosure ================= +\draw[enclosure] (-1.05, -2.4) rectangle (1.05, 2.0); + +\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..cca4160d1 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..983feb544 --- /dev/null +++ b/docs/Figures/EMT/Propagation/diagram.tex @@ -0,0 +1,48 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% Three-block current propagation: fitted input map -> modal delays -> fitted output map +\node[block, minimum width=2.1cm] (D2) {$e^{-s\tau_2}$}; +\node[block, minimum width=2.1cm, above=0.6cm of D2] (D1) {$e^{-s\tau_1}$}; +\node[block, minimum width=2.1cm, below=1.3cm of D2] (DN) {$e^{-s\tau_M}$}; +\node at ($(D2)!0.5!(DN)$) {$\vdots$}; + +\node[block, minimum width=2.6cm, left=1.5cm of D2] + (Gin) {$\mathbf{G}^{\mathrm{in}}(s)$}; +\node[block, minimum width=2.7cm, right=1.5cm of D2] + (Gout) {$\mathbf{G}^{\mathrm{out}}(s)$}; + +% Fan-out from a single internal point +\coordinate (split) at ($(Gin.east)!0.5!(D2.west)$); +\draw[line] (Gin.east) -- (split); +\draw[->, line] (split) -- (D2.west); +\foreach \b in {D1, DN} + \draw[->, line] (split) |- (\b.west); + +% Fan-in to the fitted output map +\coordinate (join) at ($(D2.east)!0.5!(Gout.west)$); +\draw[line] (D2.east) -- (join); +\foreach \b in {D1, DN} + \draw[line] (\b.east) -| (join); +\draw[->, line] (join) -- (Gout.west); + +% Output node (owned by this model) with port arrow out +\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of Gout] (yout) {}; +\draw[line] (Gout.east) -- (yout); +\draw[->, line] (yout) -- ++(1.55, 0); + +% Input node (owned externally) with port arrow into this model +\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) + at ($(Gin.west)+(-1.5, 0)$) {}; +\draw[->, line] ($(uin)+(-0.8, 0)$) -- (Gin.west); + +% Model enclosure: fixed padding around model-owned blocks and output variable +\begin{scope}[on background layer] + \node[operator enclosure, fit=(Gin)(D1)(D2)(DN)(Gout)(yout)] {}; +\end{scope} + +\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..842b187b4 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..e324886e9 --- /dev/null +++ b/docs/Figures/EMT/StateSpace/diagram.tex @@ -0,0 +1,50 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% State-space chain: input map -> resolvent state bank -> output map +\node[block, minimum width=2.9cm] (res) + {$\dfrac{\mathbf{I}}{s\mathbf{I} - \mathbf{P}}$}; +\node[block, minimum width=1.5cm, left=0.4cm of res] (B) {$\mathbf{B}$}; +\node[block, minimum width=1.5cm, right=0.4cm of res] (C) {$\mathbf{C}$}; + +% Feedthrough paths +\node[block, above=0.9cm of res] (D) {$\mathbf{D}$}; +\node[block, below=0.9cm of res] (E) {$s\mathbf{E}$}; + +% Fan-out from a single internal point +\coordinate (split) at ($(B.west)+(-1.25, 0)$); +\draw[->, line] (split) -- (B.west); +\draw[->, line] (split) |- (D.west); +\draw[->, line] (split) |- (E.west); + +% Chain series connections +\draw[->, line] (B.east) -- (res.west); +\draw[->, line] (res.east) -- (C.west); + +% Fan-in to summation +\node[sum, right=0.8cm of C] (S) {$\Sigma$}; +\draw[->, line] (C.east) -- (S); +\draw[->, line] (D.east) -| (S.north); +\draw[->, line] (E.east) -| (S.south); + +% Input node (owned externally) +\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) + at ($(split)+(-1.5, 0)$) {}; +\draw[line] ($(uin)+(-0.8, 0)$) -- (split); + +% Output node (owned by this model) with port arrow out +\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of S] + (yout) {}; +\draw[line] (S.east) -- (yout); +\draw[->, line] (yout) -- ++(1.55, 0); + +% Model enclosure: fixed padding around model-owned paths and output variable +\begin{scope}[on background layer] + \node[operator enclosure, fit=(split)(B)(res)(C)(D)(E)(S)(yout)] {}; +\end{scope} + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/Switch/diagram.png b/docs/Figures/EMT/Switch/diagram.png new file mode 100644 index 000000000..9af43eef7 Binary files /dev/null and b/docs/Figures/EMT/Switch/diagram.png differ diff --git a/docs/Figures/EMT/Switch/diagram.tex b/docs/Figures/EMT/Switch/diagram.tex new file mode 100644 index 000000000..9b73f9aa1 --- /dev/null +++ b/docs/Figures/EMT/Switch/diagram.tex @@ -0,0 +1,33 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Ideal switch contact ================= +\coordinate (left contact) at (-0.55, 0); +\coordinate (right contact) at (0.55, 0); +\draw[line] (left contact) -- (0.32, 0.55); +\node[signal] at (left contact) {}; +\node[signal] at (right contact) {}; +\node[sig] at (0, 1.0) {$\boldsymbol{\sigma}$}; + +% ================= Terminal rails and bus injections ================= +\draw[->, line] (left contact) -- (-4.4, 0); +\draw[->, line] (right contact) -- (4.4, 0); +\node[sig, anchor=east] at (-4.65, 0) {$\mathbf{i}_1$}; +\node[sig, anchor=west] at (4.65, 0) {$\mathbf{i}_2$}; + +% ================= Terminal voltages ================= +\node[signal, label={[sig]above:$\mathbf{v}_1$}] at (-3.2, 0) {}; +\node[signal, label={[sig]above:$\mathbf{v}_2$}] at (3.2, 0) {}; + +% ================= Branch-current direction ================= +\draw[->, line] (-1.5, 1.35) -- (1.5, 1.35); +\node[sig, anchor=south] at (0, 1.35) {$\mathbf{i}_{12}$}; + +% ================= Model enclosure ================= +\draw[enclosure] (-3.75, -1.0) rectangle (3.75, 2.05); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/VectorFit/diagram.png b/docs/Figures/EMT/VectorFit/diagram.png new file mode 100644 index 000000000..b2d7eef5b Binary files /dev/null and b/docs/Figures/EMT/VectorFit/diagram.png differ diff --git a/docs/Figures/EMT/VectorFit/diagram.tex b/docs/Figures/EMT/VectorFit/diagram.tex new file mode 100644 index 000000000..bfd9223ea --- /dev/null +++ b/docs/Figures/EMT/VectorFit/diagram.tex @@ -0,0 +1,44 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% Parallel branches +\node[block] (R1) {$\dfrac{\mathbf{R}_1}{s - p_1}$}; +\node[block, above=0.6cm of R1] (E) {$s\mathbf{E}$}; +\node[block, above=0.6cm of E] (D) {$\mathbf{D}$}; +\node[block, below=0.6cm of R1] (R2) {$\dfrac{\mathbf{R}_2}{s - p_2}$}; +\node[block, below=1.3cm of R2] (RQ) {$\dfrac{\mathbf{R}_Q}{s - p_Q}$}; +\node at ($(R2)!0.5!(RQ)$) {$\vdots$}; + +% Fan-out from a single internal point +\coordinate (split) at ($(R1.west)+(-1.05, 0)$); +\draw[->, line] (split) -- (R1.west); +\foreach \b in {D, E, R2, RQ} + \draw[->, line] (split) |- (\b.west); + +% Fan-in to summation +\node[sum, right=0.75cm of R1] (S) {$\Sigma$}; +\draw[->, line] (R1.east) -- (S); +\foreach \b/\a in {D/north, E/north, R2/south, RQ/south} + \draw[->, line] (\b.east) -| (S.\a); + +% Input node (owned externally) +\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) + at ($(split)+(-1.5, 0)$) {}; +\draw[line] ($(uin)+(-0.8, 0)$) -- (split); + +% Output node (owned by this model) with port arrow out +\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of S] + (yout) {}; +\draw[line] (S.east) -- (yout); +\draw[->, line] (yout) -- ++(1.55, 0); + +% Model enclosure: fixed padding around model-owned paths and output variable +\begin{scope}[on background layer] + \node[operator enclosure, fit=(split)(D)(E)(R1)(R2)(RQ)(S)(yout)] {}; +\end{scope} + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/VoltageSource/diagram.png b/docs/Figures/EMT/VoltageSource/diagram.png new file mode 100644 index 000000000..829de9b66 Binary files /dev/null and b/docs/Figures/EMT/VoltageSource/diagram.png differ diff --git a/docs/Figures/EMT/VoltageSource/diagram.tex b/docs/Figures/EMT/VoltageSource/diagram.tex new file mode 100644 index 000000000..b183d60e6 --- /dev/null +++ b/docs/Figures/EMT/VoltageSource/diagram.tex @@ -0,0 +1,37 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% ================= Terminal admittance branch ================= +\node[block, minimum width=2.1cm, minimum height=0.9cm] + (Y) at (0, 1.15) {$\mathbf{Y}(s)$}; + +% ================= Terminal voltage and current ================= +\node[signal, label={[sig]above:$\mathbf{v}$}] (vport) at (-2.3, 1.15) {}; +\draw[->, line] (Y.west) -- (-3.05, 1.15); +\node[sig, anchor=east] at (-3.3, 1.15) {$\mathbf{i}$}; + +% ================= Internal source voltage ================= +\node[signal, label={[sig]above:$\mathbf{e}$}] (enode) at (1.85, 1.15) {}; +\draw[line] (Y.east) -- (enode); + +% ================= Independent voltage source ================= +\node[draw, semithick, fill=white, circle, minimum size=1.0cm] + (source) at (1.85, -0.3) {}; +\draw[line] (enode) -- (source.north); +\node[pm] at ($(source.center)+(0,0.23)$) {$+$}; +\node[pm] at ($(source.center)+(0,-0.23)$) {$-$}; + +% ================= Ground reference ================= +\draw[line] (source.south) -- (1.85, -1.50); +\draw[semithick] (1.50, -1.50) -- (2.20, -1.50); +\draw[semithick] (1.63, -1.65) -- (2.07, -1.65); +\draw[semithick] (1.76, -1.80) -- (1.94, -1.80); + +% ================= Model enclosure ================= +\draw[enclosure] (-1.5, -2.2) rectangle (2.85, 2.05); + +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/EMT/diagram-style.tex b/docs/Figures/EMT/diagram-style.tex new file mode 100644 index 000000000..d4da54601 --- /dev/null +++ b/docs/Figures/EMT/diagram-style.tex @@ -0,0 +1,23 @@ +% Shared visual language for standalone EMT block diagrams. +\usepackage{amsmath} +\usetikzlibrary{arrows.meta,backgrounds,calc,fit,positioning} + +\tikzset{ + emt diagram/.style = {>={Stealth[length=2.4mm]}}, + line/.style = {semithick, rounded corners=6pt}, + block/.style = {draw, semithick, fill=white, + minimum height=1cm, minimum width=2.3cm}, + hblock/.style = {block, minimum width=2.24cm, minimum height=1.3cm}, + vblock/.style = {block, minimum width=1.3cm, minimum height=2.24cm}, + 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}, + wire jump/.style = {line, + preaction={draw=white, line width=3pt, + line cap=round}}, + enclosure/.style = {draw, dashed, semithick, rounded corners=4pt}, + operator enclosure/.style = {enclosure, inner xsep=7mm, inner ysep=6mm} +} 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/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/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..57440c5e4 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Line/README.md @@ -0,0 +1,15 @@ +# Line Models + +```{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/LoadZ/README.md b/docs/GridKit/Model/EMT/Component/Load/LoadZ/README.md new file mode 100644 index 000000000..02050f1fe --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Load/LoadZ/README.md @@ -0,0 +1,6 @@ +# LoadZ + +```{include} ../../../../../../../GridKit/Model/EMT/Component/Load/LoadZ/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..17cc7bab1 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Load/README.md @@ -0,0 +1,14 @@ +# Load Models + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +LoadZ +``` + +```{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..7f275b1b5 100644 --- a/docs/GridKit/Model/EMT/Component/README.md +++ b/docs/GridKit/Model/EMT/Component/README.md @@ -1,13 +1,14 @@ -# Component +# Component Models ```{toctree} :maxdepth: 4 :titlesonly: :hidden: -Branch -LoadRL -VoltageSource +Line +Load +Source +Switch ``` ```{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..7a26b6fa8 --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Source/README.md @@ -0,0 +1,14 @@ +# Source Models + +```{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/Switch/README.md b/docs/GridKit/Model/EMT/Component/Switch/README.md new file mode 100644 index 000000000..f9761017d --- /dev/null +++ b/docs/GridKit/Model/EMT/Component/Switch/README.md @@ -0,0 +1,6 @@ +# Switch + +```{include} ../../../../../../GridKit/Model/EMT/Component/Switch/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..70b0182b7 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/README.md @@ -0,0 +1,15 @@ +# Operator Models + +```{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..eaa39223c --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Rational/README.md @@ -0,0 +1,15 @@ +# Rational Operators + +```{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..e53b18fb2 --- /dev/null +++ b/docs/GridKit/Model/EMT/Operators/Shift/README.md @@ -0,0 +1,15 @@ +# Shift Operators + +```{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..f1c24672b 100644 --- a/docs/GridKit/Model/EMT/README.md +++ b/docs/GridKit/Model/EMT/README.md @@ -1,4 +1,4 @@ -# EMT +# Electromagnetic Transients (EMT) ```{toctree} :maxdepth: 4 @@ -7,6 +7,7 @@ Bus Component +Operators ``` ```{include} ../../../../GridKit/Model/EMT/README.md diff --git a/docs/examples/EMT/README.md b/docs/examples/EMT/README.md new file mode 100644 index 000000000..1b9ba8cea --- /dev/null +++ b/docs/examples/EMT/README.md @@ -0,0 +1,6 @@ +# Electromagnetic Transients (EMT) Examples + +```{include} ../../../examples/EMT/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/examples/README.md b/docs/examples/README.md index d06c6f640..2cd095d72 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -5,6 +5,7 @@ :titlesonly: :hidden: +EMT PhasorDynamics PowerElectronics PowerFlow diff --git a/examples/EMT/README.md b/examples/EMT/README.md new file mode 100644 index 000000000..a4214cabe --- /dev/null +++ b/examples/EMT/README.md @@ -0,0 +1,48 @@ +# Electromagnetic Transients (EMT) Examples + +This directory preserves the intended model composition for future EMT +examples. The trees describe ownership and nesting only. They do not define a +case-file schema. + +> [!NOTE] +> The formulations support $N$ phases; initial development targets three +> phases. + +## LineLumped + +```text +LineLumped + parameters: N, K, conductors, dx + initial state: i12 + submodels + Zp: VectorFit + Yp[1]: VectorFit + Yp[2]: VectorFit +``` + +Zp represents per-unit-length series impedance. The two Yp instances represent +terminal shunt admittances. Pole-free coefficients give the RLGC form, while +poles and residues give the frequency-dependent form. + +## LineDistributed + +```text +LineDistributed + parameters: N, K, conductors + submodels + Yc[1]: VectorFit + Yc[2]: VectorFit + H21: Propagation + input: VectorFit + delays[M]: Delay + output: VectorFit + H12: Propagation + input: VectorFit + delays[M]: Delay + output: VectorFit +``` + +Yc represents characteristic admittance. H21 and H12 represent directional +propagation. The rational factors have no term linear in $s$. Pole-free +factors give the Bergeron form, while fitted poles and residues give the +frequency-dependent form. diff --git a/examples/README.md b/examples/README.md index cd7ad11eb..5fdb0c374 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,6 +1,8 @@ # GridKit™ Usage Examples -GridKit™ usage examples are organized in following way: +GridKit™ usage examples are organized as follows: + +- [EMT](EMT/README.md) contains architecture skeletons for future EMT examples. - `Enzyme` directory contains Enzyme automatic differentiation examples. - `Experimental` directory contains examples of dynamic-constrained optimization. @@ -13,5 +15,5 @@ GridKit™. - `PowerFlow` contains examples of power flow steady-state simulations with GridKit™. -Examples are also used as integration tests for GridKit™ and are run on CI -pipeline. +Executable examples are also used as integration tests for GridKit™ and are +run on CI pipeline.