From d2745e67465912186a3be14148ea25c9efa67753 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Sat, 10 Oct 2026 18:34:42 -0500 Subject: [PATCH 1/5] Specification for branch with breakers --- .../Branch/BranchBreakers/README.md | 221 ++++++++++++++++++ .../PhasorDynamics/BranchBreakers/diagram.png | Bin 0 -> 26118 bytes .../PhasorDynamics/BranchBreakers/diagram.tex | 54 +++++ .../Branch/BranchBreakers/README.md | 6 + .../Model/PhasorDynamics/Branch/README.md | 8 + 5 files changed, 289 insertions(+) create mode 100644 GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md create mode 100644 docs/Figures/PhasorDynamics/BranchBreakers/diagram.png create mode 100644 docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex create mode 100644 docs/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md diff --git a/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md new file mode 100644 index 0000000000..20ea9acf1d --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md @@ -0,0 +1,221 @@ +# BranchBreakers + +A two-terminal phasor-domain $\pi$ branch with independently controlled circuit +breakers at both terminals. + +## Notes + +- Terminal-current outputs publish values without Jacobian coupling to the bus + voltages or breaker states. + +## Block Diagram + +![BranchBreakers model block diagram](../../../../../docs/Figures/PhasorDynamics/BranchBreakers/diagram.png) + +Figure 1: BranchBreakers model. + +## Model Parameters + +Symbol | Units | JSON | Description | Typical Value | Note +-----------------|--------|---------|----------------------------------------|---------------|---------------------------- +$R$ | [p.u.] | `R` | Branch series resistance | | +$X$ | [p.u.] | `X` | Branch series reactance | | +$G$ | [p.u.] | `G` | Total line shunt conductance | 0.0 | +$B$ | [p.u.] | `B` | Total line shunt susceptance | 0.0 | +$G_\mathrm{mag}$ | [p.u.] | `Gmag` | Magnetizing shunt conductance at bus 1 | 0.0 | +$B_\mathrm{mag}$ | [p.u.] | `Bmag` | Magnetizing shunt susceptance at bus 1 | 0.0 | +$\tau$ | [p.u.] | `tap` | Off-nominal tap magnitude at bus 1 | 1.0 | +$\theta$ | [rad] | `phase` | Phase-shift angle | 0.0 | +$T_\mathrm{brk}$ | [s] | `Tbrk` | Breaker operating time | 0.05 | Time to $z_k = 1/2$ for a unit step command + +### Parameter Validation + +```math +\begin{aligned} + R^2 + X^2 &> 0 \\ + \tau &> 0 \\ + T_\mathrm{brk} &\ge 0 \\ + Y_{11}, Y_{22} &\ne 0 +\end{aligned} +``` + +All parameters must be finite real values. + +### Model Derived Parameters + +$Y_{mn}$ are entries of the closed-branch admittance matrix $\mathbf{Y}$. +$Y_k^\mathrm{o}$ is the admittance seen at terminal $k$ with the opposite breaker open. + +```math +\begin{aligned} + \epsilon_T &= 10^{-3}\ \mathrm{s} \\ + T_\mathrm{brk} &\leftarrow \max(T_\mathrm{brk}, \epsilon_T) \\ + T_\mathrm{latch} &= \dfrac{T_\mathrm{brk}}{\ln 2} \\ + Z &= R + jX \\ + Y_\mathrm{mag} &= G_\mathrm{mag} + jB_\mathrm{mag} \\ + Y_\mathrm{sh} &= G + jB \\ + \mathbf{Y}_0 &= \dfrac{1}{Z} + \begin{bmatrix} + -1 & 1 \\ + 1 & -1 + \end{bmatrix} \\ + \mathbf{Y}_\mathrm{mag} &= + \begin{bmatrix} + -Y_\mathrm{mag} & 0 \\ + 0 & 0 + \end{bmatrix} \\ + \mathbf{Y}_\mathrm{sh} &= \dfrac{1}{2} + \begin{bmatrix} + -Y_\mathrm{sh} & 0 \\ + 0 & -Y_\mathrm{sh} + \end{bmatrix} \\ + \mathbf{M} &= + \begin{bmatrix} + \tau^{-1} & 0 \\ + 0 & \exp(j\theta) + \end{bmatrix} \\ + \mathbf{Y} &= \mathbf{M}^{\dagger}\mathbf{Y}_0\mathbf{M} + + \mathbf{Y}_\mathrm{mag} + \mathbf{Y}_\mathrm{sh} \\ + Y_1^\mathrm{o} &= Y_{11} - \dfrac{Y_{12}Y_{21}}{Y_{22}} \\ + Y_2^\mathrm{o} &= Y_{22} - \dfrac{Y_{21}Y_{12}}{Y_{11}} +\end{aligned} +``` + +## Model Ports + +Name | Port | Init | Description +---------|--------|-------|-------------------------------------------- +`bus1` | Bus | Known | Required bus-1 terminal; the tapped side +`bus2` | Bus | Known | Required bus-2 terminal +`trip1` | Input | Known | Bus-1 breaker trip command +`reset1` | Input | Known | Bus-1 breaker reset command +`trip2` | Input | Known | Bus-2 breaker trip command +`reset2` | Input | Known | Bus-2 breaker reset command +`ir1` | Output | Known | Bus-1 terminal current, real component +`ii1` | Output | Known | Bus-1 terminal current, imaginary component +`ir2` | Output | Known | Bus-2 terminal current, real component +`ii2` | Output | Known | Bus-2 terminal current, imaginary component + +Signal ports are optional. Attached inputs must be linked. Trip and reset +commands lie in $[0,1]$; unattached inputs default to zero. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +-------|-------|----------------------------------|----- +$z_1$ | [-] | Bus-1 breaker closed-state latch | +$z_2$ | [-] | Bus-2 breaker closed-state latch | + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +---------|--------|----------------------------------------------|-------------------- +$V_{r1}$ | [p.u.] | Terminal voltage, real component, bus 1 | Owned by bus object +$V_{i1}$ | [p.u.] | Terminal voltage, imaginary component, bus 1 | Owned by bus object +$V_{r2}$ | [p.u.] | Terminal voltage, real component, bus 2 | Owned by bus object +$V_{i2}$ | [p.u.] | Terminal voltage, imaginary component, bus 2 | Owned by bus object +$s_1$ | [-] | Bus-1 breaker trip command | `trip1` +$r_1$ | [-] | Bus-1 breaker reset command | `reset1` +$s_2$ | [-] | Bus-2 breaker trip command | `trip2` +$r_2$ | [-] | Bus-2 breaker reset command | `reset2` + +## Model Equations + +Smooth functions: [`above`](../../../../CommonMath.md#above), +[`below`](../../../../CommonMath.md#below), [`latch`](#appendix-a-latch). + +For readability, define: + +```math +\begin{aligned} + u_1 &= \text{above}(z_1; 1/2) \\ + u_2 &= \text{above}(z_2; 1/2) \\ + \bar{u}_1 &= \text{below}(z_1; 1/2) \\ + \bar{u}_2 &= \text{below}(z_2; 1/2) +\end{aligned} +``` + +### Internal Equations + +#### Differential + +```math +\begin{aligned} + 0 &= -\dot{z}_1 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_1, r_1, s_1) \\ + 0 &= -\dot{z}_2 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_2, r_2, s_2) +\end{aligned} +``` + +Reset drives the latch toward closed; a full trip command overrides reset. + +#### Algebraic + +None. + +### External Equations + +```math +\begin{aligned} + I_1 &= u_1\left[u_2(Y_{11} V_1 + Y_{12} V_2) + + \bar{u}_2 Y_1^\mathrm{o} V_1\right] \\ + I_2 &= u_2\left[u_1(Y_{21} V_1 + Y_{22} V_2) + + \bar{u}_1 Y_2^\mathrm{o} V_2\right] +\end{aligned} +``` + +The real and imaginary parts are added to the bus residuals, positive entering +the buses. + +## Initialization + +```math +\begin{aligned} + z_1 &\leftarrow 1 \\ + z_2 &\leftarrow 1 +\end{aligned} +``` + +All internal derivatives initialize to zero. + +## Monitors + +Monitor | Units | Description | Note +--------|--------|----------------------------------------------|-------------------------------- +`ir1` | [p.u.] | Terminal current, real component, bus 1 | $I_{r1}$ +`ii1` | [p.u.] | Terminal current, imaginary component, bus 1 | $I_{i1}$ +`im1` | [p.u.] | Terminal current magnitude, bus 1 | $\sqrt{I_{r1}^2 + I_{i1}^2}$ +`p1` | [p.u.] | Active power entering bus 1 | $V_{r1} I_{r1} + V_{i1} I_{i1}$ +`q1` | [p.u.] | Reactive power entering bus 1 | $V_{i1} I_{r1} - V_{r1} I_{i1}$ +`ir2` | [p.u.] | Terminal current, real component, bus 2 | $I_{r2}$ +`ii2` | [p.u.] | Terminal current, imaginary component, bus 2 | $I_{i2}$ +`im2` | [p.u.] | Terminal current magnitude, bus 2 | $\sqrt{I_{r2}^2 + I_{i2}^2}$ +`p2` | [p.u.] | Active power entering bus 2 | $V_{r2} I_{r2} + V_{i2} I_{i2}$ +`q2` | [p.u.] | Reactive power entering bus 2 | $V_{i2} I_{r2} - V_{r2} I_{i2}$ + +## Appendix A: `latch` + +For $x,a,b \in [0,1]$: + +```math +\text{latch}(x, a, b) + = (1 - b)\left[a + (1 - a)\sigma(x - 1/2)\right] - x +``` + +where $\sigma$ is GridKit's smooth +[`sigmoid`](../../../../CommonMath.md#logistic-function), with $\mu > 4$. +Here $x$ is the state, $a$ the set drive, and $b$ the reset drive. Full reset has +priority. With both drives zero, $x = 1/2$ separates the stable low and high states. diff --git a/docs/Figures/PhasorDynamics/BranchBreakers/diagram.png b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..933a2af2c283fce6aa32b85114b2aa717205e41c GIT binary patch literal 26118 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 literal 0 HcmV?d00001 diff --git a/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex new file mode 100644 index 0000000000..a73dc3f832 --- /dev/null +++ b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex @@ -0,0 +1,54 @@ +\documentclass[tikz,border=12pt]{standalone} +\input{../../EMT/diagram-style.tex} + +\begin{document} +\begin{tikzpicture}[emt diagram] + +% Branch network: shunts remain outside the bus-1 tap transformation. +\node[hblock] (series) at (1.8, 0) {$Z$}; +\node[vblock] (mag) at (-4.8, -1.6) {$Y_\mathrm{mag}$}; +\node[vblock] (shunt1) at (-3.0, -1.6) {$\dfrac{Y_\mathrm{sh}}{2}$}; +\node[vblock] (shunt2) at (4.8, -1.6) {$\dfrac{Y_\mathrm{sh}}{2}$}; + +% Single-line transformer symbol, with the tap on the bus-1 side. +\draw[semithick] (-1.35, 0) circle (0.45); +\draw[semithick] (-0.75, 0) circle (0.45); +\node[sig, anchor=south] at (-1.05, 0.6) {$\tau:1$}; +\node[sig, anchor=north] at (-1.05, -0.6) {$\theta$}; + +% Single-line circuit breakers (device 52). +\foreach \k/\x in {1/-6.5,2/6.5} { + \node[draw, semithick, fill=white, minimum size=0.85cm, + inner sep=0pt] (breaker\k) at (\x, 0) {52}; + \draw[->, line] (\x-0.22, 2.1) -- ($(breaker\k.north)+(-0.22, 0)$); + \draw[->, line] (\x+0.22, 2.1) -- ($(breaker\k.north)+( 0.22, 0)$); + \node[sig, anchor=south] at (\x-0.22, 2.2) {$s_\k$}; + \node[sig, anchor=south] at (\x+0.22, 2.2) {$r_\k$}; +} + +\draw[line] (breaker1.east) -- (-1.8, 0); +\draw[line] (-0.3, 0) -- (series.west); +\draw[line] (series.east) -- (breaker2.west); + +\foreach \shunt/\x in {mag/-4.8,shunt1/-3.0,shunt2/4.8} { + \node[signal] at (\x, 0) {}; + \draw[line] (\x, 0) -- (\shunt.north); + \draw[line] (\shunt.south) -- (\x, -3.2); + \draw[semithick] (\x-0.35, -3.20) -- (\x+0.35, -3.20); + \draw[semithick] (\x-0.22, -3.35) -- (\x+0.22, -3.35); + \draw[semithick] (\x-0.09, -3.50) -- (\x+0.09, -3.50); +} + +% Terminal voltages are bus-owned; current arrows point into the buses. +\draw[->, line] (breaker1.west) -- (-9.0, 0); +\draw[->, line] (breaker2.east) -- (9.0, 0); +\node[signal, label={[sig]above:$V_1$}] at (-8.2, 0) {}; +\node[signal, label={[sig]above:$V_2$}] at (8.2, 0) {}; +\node[sig, anchor=east] at (-9.2, 0) {$I_1$}; +\node[sig, anchor=west] at (9.2, 0) {$I_2$}; + +% Model enclosure. +\draw[enclosure] (-7.5, -4.0) rectangle (7.5, 1.5); + +\end{tikzpicture} +\end{document} diff --git a/docs/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md b/docs/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md new file mode 100644 index 0000000000..20453c276b --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md @@ -0,0 +1,6 @@ +# BranchBreakers + +```{include} ../../../../../../GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/PhasorDynamics/Branch/README.md b/docs/GridKit/Model/PhasorDynamics/Branch/README.md index f1adc4f9d0..2b3580ce62 100644 --- a/docs/GridKit/Model/PhasorDynamics/Branch/README.md +++ b/docs/GridKit/Model/PhasorDynamics/Branch/README.md @@ -1,5 +1,13 @@ # Branch +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +BranchBreakers +``` + ```{include} ../../../../../GridKit/Model/PhasorDynamics/Branch/README.md :start-line: 1 :relative-images: From ad1564b2d4fac56aa425ef9264322e58654dcc91 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Wed, 21 Oct 2026 08:15:02 -0500 Subject: [PATCH 2/5] generalize relay for deinfintee time relay --- .../Relay/DefiniteTimeRelay/README.md | 154 ++++++++++++++++++ GridKit/Model/PhasorDynamics/Relay/README.md | 7 + 2 files changed, 161 insertions(+) create mode 100644 GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md create mode 100644 GridKit/Model/PhasorDynamics/Relay/README.md diff --git a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md new file mode 100644 index 0000000000..6daabdc5ab --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md @@ -0,0 +1,154 @@ +# DefiniteTimeRelay + +A definite-time relay with optional lockout. Each relay models one of the +elements below. + +ID[^device-numbers] | Short Name | Long Name +--------------------|------------|--------------- +50 | OC | Overcurrent +27 | UV | Undervoltage +59 | OV | Overvoltage +81U | UF | Underfrequency +81O | OF | Overfrequency + +## Notes + +- The element operates above $M_\mathrm{pickup}$ if + $M_\mathrm{pickup} > M_\mathrm{ref}$ and below it otherwise. +- With lockout, the latch commits at $x = 1/2$. A committed relay holds the + trip after the measured quantity recovers; an uncommitted relay resets. +- With lockout, the trip rises at $x = 3/4$, after the latch commits, so the + relay may measure the current it interrupts, such as a + [BranchBreakers](../../Branch/BranchBreakers/README.md) terminal current. +- Without lockout, the relay resets on recovery. +- Inverse-time overcurrent characteristics[^inverse-time] are not modeled. + +## Model Parameters + +Symbol | Units | JSON | Description | Typical Value | Note +--------------------|-----------|-----------|------------------|---------------|----------------------------------------------------- +$M_\mathrm{pickup}$ | [p.u.] | `Mpickup` | Pickup level | | Required +$M_\mathrm{ref}$ | [p.u.] | `Mref` | Reference level | | Required; 0 for current, 1 for voltage and frequency +$T_\mathrm{trip}$ | [s] | `Ttrip` | Trip time | | Required; time to $x = 3/4$ for $p = 1$ +$s_\mathrm{lock}$ | [boolean] | `Lockout` | Lockout selector | `true` | `true` = lockout, `false` = self-reset + +### Parameter Validation + +```math +\begin{aligned} + M_\mathrm{pickup} &> 0 \\ + M_\mathrm{ref} &\ge 0 \\ + M_\mathrm{pickup} &\ne M_\mathrm{ref} \\ + T_\mathrm{trip} &\ge 0 +\end{aligned} +``` + +All real parameters must be finite. + +### Model Derived Parameters + +```math +\begin{aligned} + \epsilon_T &= 10^{-3}\ \mathrm{s} \\ + T_\mathrm{trip} &\leftarrow \max(T_\mathrm{trip}, \epsilon_T) \\ + T_\mathrm{latch} &= \dfrac{T_\mathrm{trip}}{\ln 4} +\end{aligned} +``` + +## Model Ports + +Name | Port | Init | Description +-------|--------|-------|------------------------------------------- +`mr` | Input | Known | Required measured quantity, real component +`mi` | Input | Known | Measured quantity, imaginary component +`trip` | Output | Known | Required trip command + +Unattached `mi` defaults to zero, so absolute frequency uses `mr` alone. + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +-------|-------|-------------|----- +$x$ | [-] | Relay latch | + +#### Algebraic + +Symbol | Units | Description | Note +-------|-------|--------------|------- +$s$ | [-] | Trip command | `trip` + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------|--------|----------------------------------------|----- +$m_r$ | [p.u.] | Measured quantity, real component | `mr` +$m_i$ | [p.u.] | Measured quantity, imaginary component | `mi` + +## Model Equations + +Smooth functions: [`above`](../../../../CommonMath.md#above), +[`latch`](../../Branch/BranchBreakers/README.md#appendix-a-latch), +[`logistic`](../../../../CommonMath.md#logistic-function) ($\sigma$). + +For readability, define: + +```math +\begin{aligned} + p &= \text{logistic}\left(\dfrac{m_r^2 + m_i^2 - M_\mathrm{pickup}^2}{M_\mathrm{pickup}^2 - M_\mathrm{ref}^2}\right) +\end{aligned} +``` + +### Internal Equations + +#### Differential + +```math +\begin{aligned} + 0 &= -\dot{x} + \dfrac{1}{T_\mathrm{latch}}\text{latch}(x, p, (1 - s_\mathrm{lock})(1 - p)) +\end{aligned} +``` + +#### Algebraic + +```math +\begin{aligned} + 0 &= -s + \text{above}(x; 3/4) +\end{aligned} +``` + +### External Equations + +None. + +## Initialization + +```math +\begin{aligned} + x &\leftarrow 0 \\ + s &\leftarrow \text{above}(x; 3/4) +\end{aligned} +``` + +All internal derivatives initialize to zero. + +## Monitors + +Monitor | Units | Description | Note +--------|--------|-----------------------------|----------------------- +`m` | [p.u.] | Measured quantity magnitude | $\sqrt{m_r^2 + m_i^2}$ +`x` | [-] | Relay latch | $x$ +`trip` | [-] | Trip command | $s$ + +[^device-numbers]: [IEEE Std C37.2-2022, *IEEE Standard for Electrical Power System Device Function Numbers, Acronyms, and Contact Designations*](https://standards.ieee.org/ieee/C37.2/6043/). + +[^inverse-time]: [IEEE Std C37.112-2018, *IEEE Standard for Inverse-Time Characteristics Equations for Overcurrent Relays*](https://standards.ieee.org/ieee/C37.112/7036/). diff --git a/GridKit/Model/PhasorDynamics/Relay/README.md b/GridKit/Model/PhasorDynamics/Relay/README.md new file mode 100644 index 0000000000..0be51589ee --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Relay/README.md @@ -0,0 +1,7 @@ +# Relay Models + +Relays measure network quantities and issue breaker commands. + +## Types + +- [DefiniteTimeRelay](DefiniteTimeRelay/README.md): Definite-time relay with optional lockout From f4564c910404ef000ffa835f1fabbc9449c8eb1c Mon Sep 17 00:00:00 2001 From: lukelowry Date: Wed, 21 Oct 2026 08:32:01 -0500 Subject: [PATCH 3/5] InverseTimeRelay --- .../Relay/DefiniteTimeRelay/README.md | 17 +- .../Relay/InverseTimeRelay/README.md | 160 ++++++++++++++++++ GridKit/Model/PhasorDynamics/Relay/README.md | 14 ++ docs/GridKit/Model/PhasorDynamics/README.md | 1 + .../Relay/DefiniteTimeRelay/README.md | 6 + .../Relay/InverseTimeRelay/README.md | 6 + .../Model/PhasorDynamics/Relay/README.md | 15 ++ 7 files changed, 204 insertions(+), 15 deletions(-) create mode 100644 GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md create mode 100644 docs/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md create mode 100644 docs/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md create mode 100644 docs/GridKit/Model/PhasorDynamics/Relay/README.md diff --git a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md index 6daabdc5ab..07bb59a3dd 100644 --- a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md @@ -1,15 +1,7 @@ # DefiniteTimeRelay -A definite-time relay with optional lockout. Each relay models one of the -elements below. - -ID[^device-numbers] | Short Name | Long Name ---------------------|------------|--------------- -50 | OC | Overcurrent -27 | UV | Undervoltage -59 | OV | Overvoltage -81U | UF | Underfrequency -81O | OF | Overfrequency +A definite-time relay with optional lockout. Each relay models one +[element](../README.md#elements). ## Notes @@ -21,7 +13,6 @@ ID[^device-numbers] | Short Name | Long Name relay may measure the current it interrupts, such as a [BranchBreakers](../../Branch/BranchBreakers/README.md) terminal current. - Without lockout, the relay resets on recovery. -- Inverse-time overcurrent characteristics[^inverse-time] are not modeled. ## Model Parameters @@ -148,7 +139,3 @@ Monitor | Units | Description | Note `m` | [p.u.] | Measured quantity magnitude | $\sqrt{m_r^2 + m_i^2}$ `x` | [-] | Relay latch | $x$ `trip` | [-] | Trip command | $s$ - -[^device-numbers]: [IEEE Std C37.2-2022, *IEEE Standard for Electrical Power System Device Function Numbers, Acronyms, and Contact Designations*](https://standards.ieee.org/ieee/C37.2/6043/). - -[^inverse-time]: [IEEE Std C37.112-2018, *IEEE Standard for Inverse-Time Characteristics Equations for Overcurrent Relays*](https://standards.ieee.org/ieee/C37.112/7036/). diff --git a/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md new file mode 100644 index 0000000000..b60e1f8120 --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md @@ -0,0 +1,160 @@ +# InverseTimeRelay + +An inverse-time overcurrent relay with optional lockout. + +## Notes + +- Above pickup, the trip rises at $x = 3/4$ once + $\int t_\mathrm{op}^{-1}\,dt = 1$, the operate criterion of IEEE + C37.112[^inverse-time]. +- With lockout, the latch commits at $x = 1/2$. A committed relay holds the + trip after the current falls; an uncommitted relay resets. +- With lockout, the trip rises at $x = 3/4$, after the latch commits, so the + relay may measure the current it interrupts, such as a + [BranchBreakers](../../Branch/BranchBreakers/README.md) terminal current. +- Without lockout, the relay resets after the current falls. + +## Model Parameters + +Symbol | Units | JSON | Description | Typical Value | Note +--------------------|-----------|-----------|-------------------|---------------|--------------------------------------- +$I_\mathrm{pickup}$ | [p.u.] | `Ipickup` | Pickup current | | Required +$D$ | [-] | `TD` | Time dial | | Required +$A$ | [s] | `A` | Curve coefficient | | Required +$B$ | [s] | `B` | Curve offset | | Required +$\alpha$ | [-] | `alpha` | Curve exponent | | Required +$t_r$ | [s] | `tr` | Reset constant | 0.0 | 0 for instantaneous reset +$s_\mathrm{lock}$ | [boolean] | `Lockout` | Lockout selector | `true` | `true` = lockout, `false` = self-reset + +IEEE C37.112 curves: + +Curve | `A` | `B` | `alpha` | `tr` +-------------------|--------|--------|---------|----- +Moderately inverse | 0.0515 | 0.1140 | 0.02 | 4.85 +Very inverse | 19.61 | 0.491 | 2.0 | 21.6 +Extremely inverse | 28.2 | 0.1217 | 2.0 | 29.1 + +### Parameter Validation + +```math +\begin{aligned} + I_\mathrm{pickup} &> 0 \\ + D &> 0 \\ + A &> 0 \\ + B &\ge 0 \\ + \alpha &> 0 \\ + t_r &\ge 0 +\end{aligned} +``` + +All real parameters must be finite. + +### Model Derived Parameters + +```math +\begin{aligned} + \epsilon_T &= 10^{-3}\ \mathrm{s} \\ + T_\mathrm{reset} &= \max(D t_r, \epsilon_T) +\end{aligned} +``` + +## Model Ports + +Name | Port | Init | Description +-------|--------|-------|----------------------------------------------- +`ir` | Input | Known | Required measured current, real component +`ii` | Input | Known | Required measured current, imaginary component +`trip` | Output | Known | Required trip command + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +-------|-------|-------------|----- +$x$ | [-] | Relay latch | + +#### Algebraic + +Symbol | Units | Description | Note +-------|-------|--------------|------- +$s$ | [-] | Trip command | `trip` + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------|--------|---------------------------------------|----- +$I_r$ | [p.u.] | Measured current, real component | `ir` +$I_i$ | [p.u.] | Measured current, imaginary component | `ii` + +## Model Equations + +Smooth functions: [`above`](../../../../CommonMath.md#above), +[`latch`](../../Branch/BranchBreakers/README.md#appendix-a-latch), +[`logistic`](../../../../CommonMath.md#logistic-function) ($\sigma$), +[`max`](../../../../CommonMath.md#maximum), +[`min`](../../../../CommonMath.md#minimum). + +For readability, define: + +```math +\begin{aligned} + M^2 &= \dfrac{I_r^2 + I_i^2}{I_\mathrm{pickup}^2} \\ + p &= \text{logistic}(M^2 - 1) \\ + K &= \text{max}(M^2, 1)^{\alpha/2} - 1 \\ + \dfrac{1}{t_\mathrm{op}} &= \dfrac{K}{D(A + B K)} \\ + \dfrac{1}{t_\mathrm{rs}} &= \dfrac{1 - \text{min}(M^2, 1)}{T_\mathrm{reset}} \\ + \dfrac{1}{T_\mathrm{latch}} &= \ln 4\left(\dfrac{p}{t_\mathrm{op}} + \dfrac{1 - p}{t_\mathrm{rs}}\right) +\end{aligned} +``` + +### Internal Equations + +#### Differential + +```math +\begin{aligned} + 0 &= -\dot{x} + \dfrac{1}{T_\mathrm{latch}}\text{latch}(x, p, (1 - s_\mathrm{lock})(1 - p)) +\end{aligned} +``` + +#### Algebraic + +```math +\begin{aligned} + 0 &= -s + \text{above}(x; 3/4) +\end{aligned} +``` + +### External Equations + +None. + +## Initialization + +```math +\begin{aligned} + x &\leftarrow 0 \\ + s &\leftarrow \text{above}(x; 3/4) +\end{aligned} +``` + +All internal derivatives initialize to zero. + +## Monitors + +Monitor | Units | Description | Note +--------|--------|----------------------------|----------------------- +`im` | [p.u.] | Measured current magnitude | $\sqrt{I_r^2 + I_i^2}$ +`x` | [-] | Relay latch | $x$ +`trip` | [-] | Trip command | $s$ + +[^inverse-time]: [IEEE Std C37.112-2018, *IEEE Standard for Inverse-Time Characteristics Equations for Overcurrent Relays*](https://standards.ieee.org/ieee/C37.112/7036/). diff --git a/GridKit/Model/PhasorDynamics/Relay/README.md b/GridKit/Model/PhasorDynamics/Relay/README.md index 0be51589ee..a158b14ee3 100644 --- a/GridKit/Model/PhasorDynamics/Relay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/README.md @@ -5,3 +5,17 @@ Relays measure network quantities and issue breaker commands. ## Types - [DefiniteTimeRelay](DefiniteTimeRelay/README.md): Definite-time relay with optional lockout +- [InverseTimeRelay](InverseTimeRelay/README.md): Inverse-time overcurrent relay with optional lockout + +## Elements + +ID[^device-numbers] | Short Name | Long Name | Model +--------------------|------------|--------------------------|------------------ +27 | UV | Undervoltage | DefiniteTimeRelay +50 | OC | Overcurrent | DefiniteTimeRelay +51 | TOC | Inverse-time overcurrent | InverseTimeRelay +59 | OV | Overvoltage | DefiniteTimeRelay +81O | OF | Overfrequency | DefiniteTimeRelay +81U | UF | Underfrequency | DefiniteTimeRelay + +[^device-numbers]: [IEEE Std C37.2-2022, *IEEE Standard for Electrical Power System Device Function Numbers, Acronyms, and Contact Designations*](https://standards.ieee.org/ieee/C37.2/6043/). diff --git a/docs/GridKit/Model/PhasorDynamics/README.md b/docs/GridKit/Model/PhasorDynamics/README.md index cef6df173d..dc5f10aa48 100644 --- a/docs/GridKit/Model/PhasorDynamics/README.md +++ b/docs/GridKit/Model/PhasorDynamics/README.md @@ -13,6 +13,7 @@ Converter Exciter Governor Load +Relay SignalNode SignalSource Stabilizer diff --git a/docs/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/docs/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md new file mode 100644 index 0000000000..b322101c15 --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md @@ -0,0 +1,6 @@ +# DefiniteTimeRelay + +```{include} ../../../../../../GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md b/docs/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md new file mode 100644 index 0000000000..563aef879f --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md @@ -0,0 +1,6 @@ +# InverseTimeRelay + +```{include} ../../../../../../GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/PhasorDynamics/Relay/README.md b/docs/GridKit/Model/PhasorDynamics/Relay/README.md new file mode 100644 index 0000000000..f3fe92dd93 --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/Relay/README.md @@ -0,0 +1,15 @@ +# Relay + +```{toctree} +:maxdepth: 4 +:titlesonly: +:hidden: + +DefiniteTimeRelay +InverseTimeRelay +``` + +```{include} ../../../../../GridKit/Model/PhasorDynamics/Relay/README.md +:start-line: 1 +:relative-images: +``` From e3e34164b834e3ea7649ee345c9fd8389001918a Mon Sep 17 00:00:00 2001 From: lukelowry Date: Wed, 21 Oct 2026 09:12:16 -0500 Subject: [PATCH 4/5] extract latch into CommonMaht --- GridKit/CommonMath.md | 19 + .../Branch/BranchBreakers/README.md | 41 +- .../Relay/DefiniteTimeRelay/README.md | 2 +- .../Relay/InverseTimeRelay/README.md | 2 +- docs/Figures/CommonMath/latch.svg | 1193 +++++++++++++++++ docs/Figures/CommonMath/latch.tex | 27 + .../PhasorDynamics/BranchBreakers/diagram.png | Bin 26118 -> 93673 bytes .../PhasorDynamics/BranchBreakers/diagram.tex | 27 +- 8 files changed, 1270 insertions(+), 41 deletions(-) create mode 100644 docs/Figures/CommonMath/latch.svg create mode 100644 docs/Figures/CommonMath/latch.tex diff --git a/GridKit/CommonMath.md b/GridKit/CommonMath.md index 65102e1d95..853ce34fb4 100644 --- a/GridKit/CommonMath.md +++ b/GridKit/CommonMath.md @@ -144,6 +144,7 @@ We implement an approximation to $\text{ReQU}$ using the logistic function. | Inside | `inside` | Interior pulse indicator | | Outside | `outside` | Outside-band indicator | | Antiwindup | `antiwindup` | Anti-windup limited derivative | +| Latch | `latch` | Set-reset memory rate | ### Maximum @@ -364,3 +365,21 @@ The limits satisfy $\ell\le u$. &\approx \phi(x,f)\,f \end{aligned} ``` + +### Latch + +The drives satisfy $a,b\in[0,1]$, and the scale satisfies $\mu\gt 4$. + +```math +\begin{aligned} + \text{latch}(x,a,b) + &= (1-b)\left[a+(1-a)H(x-1/2)\right]-x \\[0pt] + &\approx (1-b)\left[a+(1-a)\sigma(x-1/2)\right]-x +\end{aligned} +``` + +![](../docs/Figures/CommonMath/latch.svg) + +Here $x$ is the stored state, $a$ the set drive, and $b$ the reset drive. +Full reset has priority. With both drives zero, as plotted, the stable states +lie on either side of $1/2$ and approach zero and one as $\mu$ increases. diff --git a/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md index 20ea9acf1d..4a174adf63 100644 --- a/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md @@ -51,13 +51,13 @@ $Y_k^\mathrm{o}$ is the admittance seen at terminal $k$ with the opposite breake \epsilon_T &= 10^{-3}\ \mathrm{s} \\ T_\mathrm{brk} &\leftarrow \max(T_\mathrm{brk}, \epsilon_T) \\ T_\mathrm{latch} &= \dfrac{T_\mathrm{brk}}{\ln 2} \\ - Z &= R + jX \\ + Y_\mathrm{br} &= \dfrac{1}{R + jX} \\ Y_\mathrm{mag} &= G_\mathrm{mag} + jB_\mathrm{mag} \\ Y_\mathrm{sh} &= G + jB \\ - \mathbf{Y}_0 &= \dfrac{1}{Z} + \mathbf{Y}_0 &= \begin{bmatrix} - -1 & 1 \\ - 1 & -1 + -Y_\mathrm{br} & Y_\mathrm{br} \\ + Y_\mathrm{br} & -Y_\mathrm{br} \end{bmatrix} \\ \mathbf{Y}_\mathrm{mag} &= \begin{bmatrix} @@ -88,15 +88,15 @@ Name | Port | Init | Description `bus1` | Bus | Known | Required bus-1 terminal; the tapped side `bus2` | Bus | Known | Required bus-2 terminal `trip1` | Input | Known | Bus-1 breaker trip command -`reset1` | Input | Known | Bus-1 breaker reset command +`close1` | Input | Known | Bus-1 breaker close command `trip2` | Input | Known | Bus-2 breaker trip command -`reset2` | Input | Known | Bus-2 breaker reset command +`close2` | Input | Known | Bus-2 breaker close command `ir1` | Output | Known | Bus-1 terminal current, real component `ii1` | Output | Known | Bus-1 terminal current, imaginary component `ir2` | Output | Known | Bus-2 terminal current, real component `ii2` | Output | Known | Bus-2 terminal current, imaginary component -Signal ports are optional. Attached inputs must be linked. Trip and reset +Signal ports are optional. Attached inputs must be linked. Trip and close commands lie in $[0,1]$; unattached inputs default to zero. ## Model Variables @@ -129,14 +129,15 @@ $V_{i1}$ | [p.u.] | Terminal voltage, imaginary component, bus 1 | Owned by bus $V_{r2}$ | [p.u.] | Terminal voltage, real component, bus 2 | Owned by bus object $V_{i2}$ | [p.u.] | Terminal voltage, imaginary component, bus 2 | Owned by bus object $s_1$ | [-] | Bus-1 breaker trip command | `trip1` -$r_1$ | [-] | Bus-1 breaker reset command | `reset1` +$c_1$ | [-] | Bus-1 breaker close command | `close1` $s_2$ | [-] | Bus-2 breaker trip command | `trip2` -$r_2$ | [-] | Bus-2 breaker reset command | `reset2` +$c_2$ | [-] | Bus-2 breaker close command | `close2` ## Model Equations Smooth functions: [`above`](../../../../CommonMath.md#above), -[`below`](../../../../CommonMath.md#below), [`latch`](#appendix-a-latch). +[`below`](../../../../CommonMath.md#below), +[`latch`](../../../../CommonMath.md#latch). For readability, define: @@ -155,12 +156,12 @@ For readability, define: ```math \begin{aligned} - 0 &= -\dot{z}_1 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_1, r_1, s_1) \\ - 0 &= -\dot{z}_2 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_2, r_2, s_2) + 0 &= -\dot{z}_1 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_1, c_1, s_1) \\ + 0 &= -\dot{z}_2 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_2, c_2, s_2) \end{aligned} ``` -Reset drives the latch toward closed; a full trip command overrides reset. +A close command drives the latch toward closed; a full trip command overrides it. #### Algebraic @@ -205,17 +206,3 @@ Monitor | Units | Description | Note `im2` | [p.u.] | Terminal current magnitude, bus 2 | $\sqrt{I_{r2}^2 + I_{i2}^2}$ `p2` | [p.u.] | Active power entering bus 2 | $V_{r2} I_{r2} + V_{i2} I_{i2}$ `q2` | [p.u.] | Reactive power entering bus 2 | $V_{i2} I_{r2} - V_{r2} I_{i2}$ - -## Appendix A: `latch` - -For $x,a,b \in [0,1]$: - -```math -\text{latch}(x, a, b) - = (1 - b)\left[a + (1 - a)\sigma(x - 1/2)\right] - x -``` - -where $\sigma$ is GridKit's smooth -[`sigmoid`](../../../../CommonMath.md#logistic-function), with $\mu > 4$. -Here $x$ is the state, $a$ the set drive, and $b$ the reset drive. Full reset has -priority. With both drives zero, $x = 1/2$ separates the stable low and high states. diff --git a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md index 07bb59a3dd..d05be36da3 100644 --- a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md @@ -88,7 +88,7 @@ $m_i$ | [p.u.] | Measured quantity, imaginary component | `mi` ## Model Equations Smooth functions: [`above`](../../../../CommonMath.md#above), -[`latch`](../../Branch/BranchBreakers/README.md#appendix-a-latch), +[`latch`](../../../../CommonMath.md#latch), [`logistic`](../../../../CommonMath.md#logistic-function) ($\sigma$). For readability, define: diff --git a/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md index b60e1f8120..2fb9390668 100644 --- a/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md @@ -98,7 +98,7 @@ $I_i$ | [p.u.] | Measured current, imaginary component | `ii` ## Model Equations Smooth functions: [`above`](../../../../CommonMath.md#above), -[`latch`](../../Branch/BranchBreakers/README.md#appendix-a-latch), +[`latch`](../../../../CommonMath.md#latch), [`logistic`](../../../../CommonMath.md#logistic-function) ($\sigma$), [`max`](../../../../CommonMath.md#maximum), [`min`](../../../../CommonMath.md#minimum). diff --git a/docs/Figures/CommonMath/latch.svg b/docs/Figures/CommonMath/latch.svg new file mode 100644 index 0000000000..17415beb0b --- /dev/null +++ b/docs/Figures/CommonMath/latch.svg @@ -0,0 +1,1193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/Figures/CommonMath/latch.tex b/docs/Figures/CommonMath/latch.tex new file mode 100644 index 0000000000..617aaa5cca --- /dev/null +++ b/docs/Figures/CommonMath/latch.tex @@ -0,0 +1,27 @@ +\documentclass[tikz,border=4pt]{standalone} +\usepackage{commonmath} + +\begin{document} +\begin{tikzpicture} +\begin{groupplot}[ + cmbase, + x=3.2cm, y=2.2cm, + xmin=-0.12, xmax=1.22, ymin=-0.7, ymax=0.7, + xtick={0.5,1}, xticklabels={,}, + ytick={-0.5,0.5}, yticklabels={$-1/2$,$1/2$}, + domain=0:1, +] +\exactpanel + \addplot[domain=0:0.5] {-x}; + \addplot[domain=0.5:1] {1-x}; + \cmclosedpoints{(0.5,-0.5)} + \cmopenpoints{(0.5,0.5)} + \node[font=\scriptsize, anchor=south east, yshift=1.5pt] at (axis cs:0.5,0) {$1/2$}; + \node[font=\scriptsize, anchor=south, yshift=1.5pt] at (axis cs:1,0) {$1$}; + +\smoothpanel{sigmaS(x-0.5,\cmu) - x} + \node[font=\scriptsize, anchor=south east, yshift=1.5pt] at (axis cs:0.5,0) {$1/2$}; + \node[font=\scriptsize, anchor=south, yshift=1.5pt] at (axis cs:1,0) {$1$}; +\end{groupplot} +\end{tikzpicture} +\end{document} diff --git a/docs/Figures/PhasorDynamics/BranchBreakers/diagram.png b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.png index 933a2af2c283fce6aa32b85114b2aa717205e41c..e1c5202a82d1f2f57a9c7a8f909d5f7008f332ef 100644 GIT binary patch literal 93673 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�Ewz5XO1q@QR}K4eHuJg|N(7_oRbx^A>*DUcFki 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 literal 26118 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 diff --git a/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex index a73dc3f832..849b11ed42 100644 --- a/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex +++ b/docs/Figures/PhasorDynamics/BranchBreakers/diagram.tex @@ -5,7 +5,7 @@ \begin{tikzpicture}[emt diagram] % Branch network: shunts remain outside the bus-1 tap transformation. -\node[hblock] (series) at (1.8, 0) {$Z$}; +\node[hblock] (series) at (1.8, 0) {$Y_\mathrm{br}$}; \node[vblock] (mag) at (-4.8, -1.6) {$Y_\mathrm{mag}$}; \node[vblock] (shunt1) at (-3.0, -1.6) {$\dfrac{Y_\mathrm{sh}}{2}$}; \node[vblock] (shunt2) at (4.8, -1.6) {$\dfrac{Y_\mathrm{sh}}{2}$}; @@ -16,19 +16,22 @@ \node[sig, anchor=south] at (-1.05, 0.6) {$\tau:1$}; \node[sig, anchor=north] at (-1.05, -0.6) {$\theta$}; -% Single-line circuit breakers (device 52). -\foreach \k/\x in {1/-6.5,2/6.5} { - \node[draw, semithick, fill=white, minimum size=0.85cm, - inner sep=0pt] (breaker\k) at (\x, 0) {52}; - \draw[->, line] (\x-0.22, 2.1) -- ($(breaker\k.north)+(-0.22, 0)$); - \draw[->, line] (\x+0.22, 2.1) -- ($(breaker\k.north)+( 0.22, 0)$); +% Single-line circuit breakers: switch contact with a cross at the fixed contact. +\foreach \k/\x/\d in {1/-6.5/-1,2/6.5/1} { + \coordinate (pivot\k) at ({\x-\d*0.45}, 0); + \coordinate (contact\k) at ({\x+\d*0.45}, 0); + \draw[line] (pivot\k) -- ({\x+\d*0.32}, 0.55); + \draw[semithick] ($(contact\k)+(-0.12,-0.12)$) -- ($(contact\k)+(0.12,0.12)$); + \draw[semithick] ($(contact\k)+(-0.12,0.12)$) -- ($(contact\k)+(0.12,-0.12)$); + \draw[->, line] (\x-0.22, 2.1) -- (\x-0.22, 0.75); + \draw[->, line] (\x+0.22, 2.1) -- (\x+0.22, 0.75); \node[sig, anchor=south] at (\x-0.22, 2.2) {$s_\k$}; - \node[sig, anchor=south] at (\x+0.22, 2.2) {$r_\k$}; + \node[sig, anchor=south] at (\x+0.22, 2.2) {$c_\k$}; } -\draw[line] (breaker1.east) -- (-1.8, 0); +\draw[line] (pivot1) -- (-1.8, 0); \draw[line] (-0.3, 0) -- (series.west); -\draw[line] (series.east) -- (breaker2.west); +\draw[line] (series.east) -- (pivot2); \foreach \shunt/\x in {mag/-4.8,shunt1/-3.0,shunt2/4.8} { \node[signal] at (\x, 0) {}; @@ -40,8 +43,8 @@ } % Terminal voltages are bus-owned; current arrows point into the buses. -\draw[->, line] (breaker1.west) -- (-9.0, 0); -\draw[->, line] (breaker2.east) -- (9.0, 0); +\draw[->, line] (contact1) -- (-9.0, 0); +\draw[->, line] (contact2) -- (9.0, 0); \node[signal, label={[sig]above:$V_1$}] at (-8.2, 0) {}; \node[signal, label={[sig]above:$V_2$}] at (8.2, 0) {}; \node[sig, anchor=east] at (-9.2, 0) {$I_1$}; From 581d41fe7f7f7bc6837da834ac214673f5e6b716 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Wed, 21 Oct 2026 09:33:06 -0500 Subject: [PATCH 5/5] notes for new models --- .../Branch/BranchBreakers/README.md | 2 ++ .../Relay/DefiniteTimeRelay/README.md | 11 +++++------ .../Relay/InverseTimeRelay/README.md | 15 ++++++--------- 3 files changed, 13 insertions(+), 15 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md index 4a174adf63..8cfdf64c0c 100644 --- a/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/BranchBreakers/README.md @@ -5,6 +5,8 @@ breakers at both terminals. ## Notes +- Designed for [relay](../../Relay/README.md) protection: relay `trip` outputs + drive `trip1` and `trip2`, and relays measure the terminal-current outputs. - Terminal-current outputs publish values without Jacobian coupling to the bus voltages or breaker states. diff --git a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md index d05be36da3..8e07be1264 100644 --- a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md @@ -5,14 +5,13 @@ A definite-time relay with optional lockout. Each relay models one ## Notes +- Designed to measure a [BranchBreakers](../../Branch/BranchBreakers/README.md) + terminal current, a bus voltage, or a frequency, and to drive a BranchBreakers + `trip1` or `trip2` input. - The element operates above $M_\mathrm{pickup}$ if $M_\mathrm{pickup} > M_\mathrm{ref}$ and below it otherwise. -- With lockout, the latch commits at $x = 1/2$. A committed relay holds the - trip after the measured quantity recovers; an uncommitted relay resets. -- With lockout, the trip rises at $x = 3/4$, after the latch commits, so the - relay may measure the current it interrupts, such as a - [BranchBreakers](../../Branch/BranchBreakers/README.md) terminal current. -- Without lockout, the relay resets on recovery. +- With lockout, the relay commits to trip once $x$ passes $1/2$, so it may + measure the current it interrupts. ## Model Parameters diff --git a/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md index 2fb9390668..cdb48128b1 100644 --- a/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md +++ b/GridKit/Model/PhasorDynamics/Relay/InverseTimeRelay/README.md @@ -4,15 +4,12 @@ An inverse-time overcurrent relay with optional lockout. ## Notes -- Above pickup, the trip rises at $x = 3/4$ once - $\int t_\mathrm{op}^{-1}\,dt = 1$, the operate criterion of IEEE - C37.112[^inverse-time]. -- With lockout, the latch commits at $x = 1/2$. A committed relay holds the - trip after the current falls; an uncommitted relay resets. -- With lockout, the trip rises at $x = 3/4$, after the latch commits, so the - relay may measure the current it interrupts, such as a - [BranchBreakers](../../Branch/BranchBreakers/README.md) terminal current. -- Without lockout, the relay resets after the current falls. +- Designed to measure a [BranchBreakers](../../Branch/BranchBreakers/README.md) + terminal current and to drive a BranchBreakers `trip1` or `trip2` input. +- Above pickup, the trip rises once $\int t_\mathrm{op}^{-1}\,dt = 1$, the IEEE + C37.112[^inverse-time] operate criterion. +- With lockout, the relay commits to trip once $x$ passes $1/2$, so it may + measure the current it interrupts. ## Model Parameters