lukelowry · Oct 10, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git 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
@@ -0,0 +1,210 @@
+# BranchBreakers
+
+A two-terminal phasor-domain $\pi$ branch with independently controlled circuit
+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.
+
+## 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} \\
+  Y_\mathrm{br} &= \dfrac{1}{R + jX} \\
+  Y_\mathrm{mag} &= G_\mathrm{mag} + jB_\mathrm{mag} \\
+  Y_\mathrm{sh} &= G + jB \\
+  \mathbf{Y}_0 &=
+    \begin{bmatrix}
+      -Y_\mathrm{br} & Y_\mathrm{br} \\
+      Y_\mathrm{br} & -Y_\mathrm{br}
+    \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
+`close1` | Input  | Known | Bus-1 breaker close command
+`trip2`  | Input  | Known | Bus-2 breaker trip 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 close
+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`
+$c_1$    | [-]    | Bus-1 breaker close command                  | `close1`
+$s_2$    | [-]    | Bus-2 breaker trip command                   | `trip2`
+$c_2$    | [-]    | Bus-2 breaker close command                  | `close2`
+
+## Model Equations
+
+Smooth functions: [`above`](../../../../CommonMath.md#above),
+[`below`](../../../../CommonMath.md#below),
+[`latch`](../../../../CommonMath.md#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, c_1, s_1) \\
+  0 &= -\dot{z}_2 + \dfrac{1}{T_\mathrm{latch}}\text{latch}(z_2, c_2, s_2)
+\end{aligned}
+```
+
+A close command drives the latch toward closed; a full trip command overrides it.
+
+#### 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}$
diff --git a/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md b/GridKit/Model/PhasorDynamics/Relay/DefiniteTimeRelay/README.md
@@ -0,0 +1,140 @@
+# DefiniteTimeRelay
+
+A definite-time relay with optional lockout. Each relay models one
+[element](../README.md#elements).
+
+## 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 relay commits to trip once $x$ passes $1/2$, so it may
+  measure the current it interrupts.
+
+## 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`](../../../../CommonMath.md#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$