> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/model-switches-in-ucm.md).

# Model Switches in UCM

This page explains how **switches and power elements are represented and solved** in HYPERSIM. It describes how switching devices are modeled as variable resistances, and how all power elements, linear or nonlinear, are expressed in a unified form using **equivalent conductance matrices and current sources**.

## Overview <a href="#switches" id="switches"></a>

Switches such as circuit-breakers and power electronic switches are simulated as resistors with two values: one small value (milliohms) for closing state and one large value (megohms) for opening state. To know which resistor value to use, HYPERSIM® needs to know the state of switch prior to the calculation of Y matrix.

## Generalized power element <a href="#generalized-power-element" id="generalized-power-element"></a>

Each branch element is connected between nodes kk and mm of the substation and is equivalent to a conductance:

$$
Yeq=\frac{1}{R\_{eq}}
$$

In parallel with a current source:

$$
I\_{hist}
$$

A **generalized power element** can be seen as a *black box* connected to nodes k, m, n, etc, represented by a **conductance matrix** and a **vector of historic currents.**

The dimensions of these quantities correspond to the number of nodes of the element.

## Conductance matrix interpretation

In the conductance matrix ***Y***<sub>***eq***</sub>​:

* ***Y***<sub>***eq,kk***</sub> represents the **self‑conductance at node&#x20;*****k***
* ***Y***<sub>***eq,km***</sub>​ represents the **mutual conductance between nodes&#x20;*****k*****&#x20;and&#x20;*****m***

## Nonlinear elements

For a nonlinear element, the equivalent conductance is expressed as:

$$
Yeq=Yini+Yadd
$$

where:

* ***Y***<sub>***ini***</sub>​: fixed part used as the **initial condition**
* ***Y***<sub>***add***</sub>***​***: variable part used to **update the conductance based on the operating point**

### Relation to branch elements

Therefore, all branches are also generalized elements connected to two nodes in the substation. Linear branches have ***Y***<sub>***add***</sub> = 0 and ***Y***<sub>***ini***</sub> = ***Y***<sub>***eq***</sub>

All power elements, fixed or non-linear, are equivalent to resistors in parallel with historic currents. In the node equation

$$
YV=I,Y
$$

therefore becomes a pure conductance matrix, I is the algebraic sum of currents, including source currents and historic currents, injected into nodes; currents entering a node have a + sign, currents leaving have a - sign.

### Solution of substation's node equation <a href="#solution-of-substations-node-equation" id="solution-of-substations-node-equation"></a>

$$
\begin{aligned}
Y\_{ii} &= \sum (\text{all self conductances connected to node } i) \\
\\
Y\_{ij} &= \sum (\text{all mutual conductances connected between nodes } i \text{ and } j) \\
\\
I\_i &= \sum (\text{source & historic currents entering node } i)
\- \sum (\text{source & historic currents leaving node } i)
\end{aligned}
$$

***Y*** has dimension ***n*** x ***m*** where ***n*** is the number of nodes in the substation (excluding the ground node), ***V*** and ***I*** are vectors of dimension ***n***. A three-phase bus bar corresponds to 3 nodes.

As with each individual element, HYPERSIM splits Y into a fixed part and a varying part:

$$
Y=Y\_{INI}+Y\_{ADD}Y\_{INI}
$$

is formed by the fixed parts ***Y***<sub>***ini***</sub> of all elements and ***Y***<sub>***ADD***</sub> is formed by varying parts ***Y***<sub>***add***</sub> of all elements.

The simulation of all power elements in a substation required to solve the node equation ***YV=I*** where ***Y*** and ***I*** are known quantities, and ***V*** is the vector of node voltages to be determined.

HYPERSIM solves the node equation using the LDU conversion: ***Y=LDU*** where ***L*** is a lower triangular matrix with all values in the upper triangular matrix equal to 0 and all elements on the diagonal equal to 1, ***D*** is a diagonal matrix, ***U*** is an upper triangular matrix with all values in the lower triangle equal to 0 and all elements on the diagonal equal to 1.

For example, if the matrix ***Y*** has a dimension 3 times 3, the LDU conversion will have the following form:

$$
\begin{bmatrix}
Y\_{11} & Y\_{12} & Y\_{13} \\
Y\_{21} & Y\_{22} & Y\_{23} \\
Y\_{31} & Y\_{32} & Y\_{33}
\end{bmatrix}
=============

\begin{bmatrix}
1 & 0 & 0 \\
L\_{21} & 1 & 0 \\
L\_{31} & L\_{32} & 1
\end{bmatrix}
\begin{bmatrix}
D\_{11} & 0 & 0 \\
0 & D\_{21} & 0 \\
0 & 0 & D\_{33}
\end{bmatrix}
\begin{bmatrix}
1 & U\_{12} & U\_{13} \\
0 & 1 & U\_{23} \\
0 & 0 & 1
\end{bmatrix}
$$

The LDU conversion is chosen instead of the LU conversion because when Y is symmetrical (which is the case for most of the substation's node equation), U=L<sup>T</sup>. HYPERSIM will use this advantage if it exists to save the time needed to compute U.

The node equation ***YV=I*** now becomes ***LDUV=I***.

This system is solved in two sequential steps:

**Step 1 — Forward substitution:**

Define an intermediate vector ***J=DUV*** then solve ***LJ=I***. Since ***L*** is a **lower triangular matrix**, this step is performed using **forward substitution**.

**Step 2 — Backward substitution:**

Once ***J*** is known, solve ***DUV=J***. Since the product ***DU*** is an **upper triangular matrix**, this step is performed using **backward substitution** to obtain the node voltage vector ***V***.

### LDU decomposition

The LDU decomposition is performed using a **pivoting technique**, in which matrix elements are progressively eliminated to transform the original matrix into a product of lower triangular, diagonal, and upper triangular matrices.

The final formulas are:

$$
\begin{aligned}
D\_{ii} &= Y\_{ii} - \sum\_{k=0}^{i-1} D\_{kk} , L\_{ik} , U\_{ki} \\\[6pt]

L\_{ii} &= U\_{ii} = 1 \\\[10pt]

L\_{ij} &= \frac{1}{D\_{jj}} \left(
Y\_{ij} - \sum\_{k=1}^{j-1} D\_{kk} , L\_{ik} , U\_{kj}
\right), \quad i > j \\\[10pt]

U\_{ij} &= \frac{1}{D\_{ij}} \left(
Y\_{ij} - \sum\_{k=0}^{i-1} D\_{kk} , L\_{ik} , U\_{kj}
\right)
\end{aligned}
$$

For ***i*** < ***j***.

At any time step, if ***Y*** does not change from the previous step, the LDU decomposition does not need to be redone.

If ***Y*** changes due to either switching or a change of behavior of some non-linear elements, then the LDU decomposition must be recalculated.

In HYPERSIM, for saving space, matrices ***L***, ***D***, and ***U*** are stored on a single ***Y***<sub>***LDU***</sub> matrix, as shown, for an example of 3 modes. Elements of ***D*** are on the diagonal, and elements of ***L*** and ***U*** (except their diagonal) are respectively in the lower left and upper right triangular.

$$
\begin{bmatrix}
D\_{11} & U\_{12} & U\_{13} \\
L\_{21} & D\_{22} & U\_{23} \\
L\_{31} & L\_{32} & D\_{33}
\end{bmatrix}
$$

Example of a ***Y***<sub>***LDU***</sub> matrix and a part of it which needs to be recalculated if a resistor connected to node 2 changes.

All equivalent resistors of power elements contributing to Y are connected either between a node k and the ground node or between two nodes k and m. According to previous equations, if a resistor connected to node k changes its value, this changes at least the value of ***Y***<sub>***kk***</sub>.

Therefore, ***D***<sub>***ii***</sub>, ***L***<sub>***ij***</sub> and ***U***<sub>***ij***</sub>, for all ***i*** and ***j*** bigger or equal to ***k*** have to be re-evaluated. In the ***Y***<sub>***LDU***</sub> matrix shown here, this corresponds to elements in the square block below and on the right starting from ***D***<sub>***kk***</sub> when k=2 in this example.

For the purpose of saving computation time, HYPERSIM orders the ***Y*** and ***Y***<sub>***LDU***</sub> matrices such as nodes connected to varying elements, groups them together and corresponds to the lower right part of these matrices.

## Sparseness of Y Matrix <a href="#sparseness-of-y-matrix" id="sparseness-of-y-matrix"></a>

The $Y$ matrix is normally sparse, meaning that many elements are zero. To avoid calculations with zero elements, HYPERSIM keeps a matrix $YF$ indicating the state of each element of ***Y***:

$$
YF\_{ij} =
\begin{cases}
1 & \text{if } Y\_{ij} \ne 0 \\
0 & \text{if } Y\_{ij} = 0
\end{cases}
$$


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/model-switches-in-ucm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
