Move branch folder into Component folder - tweak wording in docs [skip ci]

lukelowry · lukelowry · commit 12305170fc19 · 2026-05-16T14:22:25.000-05:00
diff --git a/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md b/GridKit/Model/EMT/Component/Branch/BranchLumpedConstant/README.md
@@ -2,13 +2,13 @@
 
 `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 terminal.
+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.
 
 <div align="center">
-   <img align="center" src="../../../../../docs/Figures/EMT/lumped_constant_diagram.svg">
+   <img align="center" src="../../../../../../docs/Figures/EMT/lumped_constant_diagram.svg">
 
   Figure 1: Lumped constant EMT branch model
 </div>
@@ -49,16 +49,16 @@ None.
 ### External Variables
 
 External variables enter component model equations but are owned by
-other components. The EMT bus at each terminal owns the voltage
+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]    | Terminal 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]    | Terminal 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$
+$\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
 
@@ -79,7 +79,7 @@ None.
 
 ### Bus Residual Contributions
 
-The lumped line contributes to the KCL residual at each terminal bus.
+The lumped line contributes to the KCL residual at each port bus.
 Each expression is accumulated into the owning bus residual.
 
 ``` math
@@ -119,5 +119,5 @@ DAE consistency:
 Candidate monitorable outputs include the series branch current components
 $i_a$, $i_b$, and $i_c$.
 
-Terminal current injection expressions are documented above as
+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
diff --git a/GridKit/Model/EMT/Component/LoadRL/README.md b/GridKit/Model/EMT/Component/LoadRL/README.md
@@ -41,15 +41,15 @@ None.
 ### External Variables
 
 External variables enter component model equations but are owned by
-other components. The EMT bus at the load terminal owns the voltage
+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]   | Terminal voltage vector, owned by EMT bus    | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
+$\mathbf{v}$     | [V]   | Port voltage vector, owned by EMT bus        | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
 
 #### Algebraic
 
@@ -69,7 +69,7 @@ None.
 
 ### Bus Residual Contributions
 
-The RL load contributes to the KCL residual at its terminal bus. The
+The RL load contributes to the KCL residual at its port bus. The
 expression is accumulated into the owning bus residual.
 
 ``` math
@@ -100,4 +100,5 @@ consistency:
 
 ## Model Outputs
 
-Candidate monitorable outputs include the load current components $i_a$, $i_b$, and $i_c$ (into the bus).
+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
@@ -13,5 +13,6 @@ A component README should include:
 
 ## Types
 
+- `BranchLumpedConstant` (See [BranchLumpedConstant](Branch/BranchLumpedConstant/README.md))
 - `LoadRL` (See [LoadRL](LoadRL/README.md))
 - `VoltageSource` (See [VoltageSource](VoltageSource/README.md))
diff --git a/GridKit/Model/EMT/Component/VoltageSource/README.md b/GridKit/Model/EMT/Component/VoltageSource/README.md
@@ -2,7 +2,7 @@
 
 `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 terminal is
+offset for each phase and is otherwise constant. Each source port is
 connected to the EMT bus through a phase resistance.
 
 ## Model Parameters
@@ -39,15 +39,15 @@ None.
 ### External Variables
 
 External variables enter component model equations but are owned by
-other components. The EMT bus at the source terminal owns the voltage
+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]   | Terminal voltage vector, owned by EMT bus    | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
+$\mathbf{v}$     | [V]   | Port voltage vector, owned by EMT bus        | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
 
 #### Algebraic
 
@@ -65,7 +65,7 @@ None.
 
 ### Bus Residual Contributions
 
-The source contributes current to the KCL residual at its terminal bus.
+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:
 
@@ -105,5 +105,5 @@ e_c(0) &= \sqrt{2}\,E_c\cos(\phi_c)
 Candidate monitorable outputs include the source waveform components
 $e_a(t)$, $e_b(t)$, and $e_c(t)$.
 
-The terminal current injection expression is documented above as
+The port current injection expression is documented above as
 $\mathbf{i}^\text{inj}$.
diff --git a/GridKit/Model/EMT/README.md b/GridKit/Model/EMT/README.md
@@ -13,13 +13,15 @@ EMT design and implementation develop.
 - Current injection terms are written as positive into buses.
 
 
-## Model Families
+## Model Categories
 
-The current EMT documentation is organized into one of three families:
+The current EMT documentation is organized into two categories:
 - `Bus`
-- `Branch`
 - `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
