@@ -10,6 +10,11 @@ Notes:
1010- $G$ and $B$ are total branch shunt values split equally between terminals.
1111- The branch has no solver-owned variables; it contributes current residuals
1212 directly to the connected buses.
13+ - ` closed=false ` is static case-import status. It removes the branch admittance
14+ contribution but does not insert fake admittance; islanded or underconstrained
15+ topology can still make the system singular.
16+ - Sparse automatic differentiation may materialize zero-valued structural
17+ entries for an open branch; the mathematical Jacobian contribution is zero.
1318
1419## Circuit Diagram
1520
@@ -23,14 +28,15 @@ Figure 1: Branch equivalent circuit
2328
2429## Model Parameters
2530
26- Symbol | Units | Description | Typical Value | Note
27- ------------|---------|--------------------------------------------------|---------------|------
28- $R$ | [ p.u.] | Branch series resistance | |
29- $X$ | [ p.u.] | Branch series reactance | |
30- $G$ | [ p.u.] | Total branch shunt conductance | 0 |
31- $B$ | [ p.u.] | Total branch shunt susceptance | 0 |
32- $\tau$ | [ p.u.] | Off-nominal tap magnitude on bus-1 side | 1 | Parameter name: ` tap `
33- $\theta$ | [ rad] | Phase-shift angle | 0 | Parameter name: ` phase `
31+ Symbol | Units | JSON | Description | Typical Value | Note
32+ -----------------------|--------|----------|-----------------------------------------|---------------|------
33+ $R$ | [ p.u.] | ` R ` | Branch series resistance | |
34+ $X$ | [ p.u.] | ` X ` | Branch series reactance | |
35+ $G$ | [ p.u.] | ` G ` | Total branch shunt conductance | 0 |
36+ $B$ | [ p.u.] | ` B ` | Total branch shunt susceptance | 0 |
37+ $\tau$ | [ p.u.] | ` tap ` | Off-nominal tap magnitude on bus-1 side | 1 |
38+ $\theta$ | [ rad] | ` phase ` | Phase-shift angle | 0 |
39+ $c_ {\mathrm{br}}$ | [ -] | ` closed ` | Static branch closed status | ` true ` | JSON boolean
3440
3541### Parameter Validation
3642
@@ -39,17 +45,23 @@ Invalid Branch parameter sets are rejected by the following checks:
3945``` math
4046\begin{aligned}
4147 &R, X, G, B, \tau, \theta \in \mathbb{R}\ \text{and finite} \\
48+ &c_{\mathrm{br}} \in \{\mathrm{true}, \mathrm{false}\} \\
4249 &R^2 + X^2 > 0 \\
4350 &\tau > 0
4451\end{aligned}
4552```
4653
4754### Model Derived Parameters
4855
49- The series and shunt admittances are:
56+ The closed-status factor and branch admittances are:
5057
5158``` math
5259\begin{aligned}
60+ s_{\mathrm{br}} &=
61+ \begin{cases}
62+ 1, & c_{\mathrm{br}} = \mathrm{true} \\
63+ 0, & c_{\mathrm{br}} = \mathrm{false}
64+ \end{cases} \\
5365 Y_{\mathrm{br}} &= \dfrac{1}{R + jX} \\
5466 Y_{\mathrm{sh}} &= G + jB
5567\end{aligned}
@@ -86,11 +98,47 @@ The off-nominal transformer transformation uses bus 1 as the tap side:
8698 \tau^{-1} & 0 \\
8799 0 & e^{j\theta}
88100 \end{bmatrix} \\
89- \mathbf{Y} &= \mathbf{M}^{\dagger}\mathbf{Y}_0\mathbf{M}
101+ \mathbf{Y} &= s_{\mathrm{br}} \mathbf{M}^{\dagger}\mathbf{Y}_0\mathbf{M}
90102\end{aligned}
91103```
92104
93- For the equations below, write each entry as $Y_ {mn}=G_ {mn}+jB_ {mn}$.
105+ For each entry $Y_ {mn}=G_ {mn}+jB_ {mn}$, the real-valued contribution from
106+ terminal $n$ to current at terminal $m$ is:
107+
108+ ``` math
109+ \begin{aligned}
110+ \begin{bmatrix}
111+ I_{rm} \\
112+ I_{im}
113+ \end{bmatrix}_{n}
114+ =
115+ \begin{bmatrix}
116+ G_{mn} & -B_{mn} \\
117+ B_{mn} & G_{mn}
118+ \end{bmatrix}
119+ \begin{bmatrix}
120+ V_{rn} \\
121+ V_{in}
122+ \end{bmatrix}
123+ \end{aligned}
124+ ```
125+
126+ The voltage derivative for the same block is:
127+
128+ ``` math
129+ \begin{aligned}
130+ \frac{\partial [I_{rm}, I_{im}]^T}
131+ {\partial [V_{rn}, V_{in}]}
132+ =
133+ \begin{bmatrix}
134+ G_{mn} & -B_{mn} \\
135+ B_{mn} & G_{mn}
136+ \end{bmatrix}
137+ \end{aligned}
138+ ```
139+
140+ When ` closed=false ` , $s_ {\mathrm{br}}=0$, so $\mathbf{Y}=0$ and every current
141+ block and voltage derivative block is zero.
94142
95143## Model Variables
96144
@@ -127,24 +175,19 @@ None.
127175
128176### Algebraic Equations
129177
130- The branch current relation is $0 = -\mathbf{I} + \mathbf{Y}\mathbf{V}$.
131-
132178``` math
133179\begin{aligned}
134- I_{r1} &= G_{11} V_{r1} - B_{11} V_{i1}
180+ 0 &= - I_{r1} + G_{11} V_{r1} - B_{11} V_{i1}
135181 + G_{12} V_{r2} - B_{12} V_{i2} \\
136- I_{i1} &= B_{11} V_{r1} + G_{11} V_{i1}
182+ 0 &= - I_{i1} + B_{11} V_{r1} + G_{11} V_{i1}
137183 + B_{12} V_{r2} + G_{12} V_{i2} \\
138- I_{r2} &= G_{21} V_{r1} - B_{21} V_{i1}
184+ 0 &= - I_{r2} + G_{21} V_{r1} - B_{21} V_{i1}
139185 + G_{22} V_{r2} - B_{22} V_{i2} \\
140- I_{i2} &= B_{21} V_{r1} + G_{21} V_{i1}
186+ 0 &= - I_{i2} + B_{21} V_{r1} + G_{21} V_{i1}
141187 + B_{22} V_{r2} + G_{22} V_{i2}
142188\end{aligned}
143189```
144190
145- These current contributions are added to the connected bus residuals with
146- positive sign because branch current is oriented entering the bus.
147-
148191## Initialization
149192
150193The Branch model has no internal state to initialize. During construction or
0 commit comments