> 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-lines-in-ucm.md).

# Model Lines in UCM

## Phase-to-mode conversion

In a three‑phase transmission line, each phase is electrically coupled to the other two. Solving the line directly in phase coordinates is therefore more complex. To simplify the simulation, HYPERSIM transforms the coupled three‑phase line into three independent single‑phase equivalents, referred to as **modes**.

This modal decomposition allows the line equations to be solved more efficiently. Once the modal quantities have been computed, they are converted back to phase quantities and injected into the network at the line terminals.

## Modeling principle

In HYPERSIM, a transmission line is modeled using the following sequence:

1. Acquire the three‑phase node voltages at both terminals, **K** and **M**.
2. Convert the three‑phase voltages into modal voltages.

$$
\begin{bmatrix}
V\_0 \\
V\_1 \\
V\_2
\end{bmatrix}
=============

T\_v^{-1}
\begin{bmatrix}
V\_a \\
V\_b \\
V\_c
\end{bmatrix}
$$

3. Solve each mode independently using a single‑phase line equation.
4. Convert the resulting modal currents back into three‑phase currents.
5. Inject the phase currents at terminals **K** and **M**.

This approach applies to both balanced and unbalanced lines.

### Phase-to-mode transformation

The transformation from phase quantities to modal quantities decouples the three‑phase system into three independent propagation modes.

## Balanced line

For a balanced line, the phase‑to‑mode transformation is performed using a constant transformation matrix.

$$
T\_v = \frac{1}{\sqrt{3}}
\begin{bmatrix}
1 & \sqrt{2} & 0 \\
1 & -\frac{1}{\sqrt{2}} & \frac{\sqrt{3}}{\sqrt{2}} \\
1 & -\frac{1}{\sqrt{2}} & -\frac{\sqrt{3}}{\sqrt{2}}
\end{bmatrix}
$$

## Unbalanced line

For an unbalanced line, **T**<sub>**v**</sub> is the solution of the following equation:

$$
\[Λ]= T\_v^{-1} Z Y T\_v
$$

Where Λ is a diagonal matrix containing the eigenvalues of the matrix product ZY.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-42710b5a3e7c290241e560af4b3b35f0d6d6c374%2Fucm-unbalanced-lines.png?alt=media" alt=""><figcaption></figcaption></figure>

## Modal line representation

Each mode (0, 1, 2) is represented as an independent single‑phase transmission line.

For each mode, the terminal behavior is represented by an equivalent circuit composed of:

* a **current source**, and
* a **resistor in parallel**

The current source at each terminal depends only on past voltages and past currents at both ends of the line. As a result, the equivalent circuits at terminals **K** and **M** can be evaluated independently and in parallel.

$$
J\_{mK} =
\left( \frac{1 - h}{2} \right)
\left( \frac{V\_{mK}(t - \tau)}{R\_{eq}} + h I\_{mK}(t - \tau) \right)
\+
\left( \frac{1 + h}{2} \right)
\left( \frac{V\_{mM}(t - \tau)}{R\_{eq}} + h I\_{mM}(t - \tau) \right)
$$

$$
where\ R\_{eq} = Z\_c + \frac{R\_T}{4}
\and\\
h = \frac{Z\_c - \left(\frac{R\_T}{4}\right)}{Z\_c + \left(\frac{R\_T}{4}\right)}
$$

* m is the mode number (0, 1, 2)
* Z<sub>c</sub> is the line characteristic impedance
* tau is the transmission delay along the line and
* R<sub>T</sub> is the line loss.

A similar expression can also be derived for *J*<sub>*mM*</sub>, the current source at terminal *M*.

### Frequency-dependent lines

Frequency‑dependent line models follow the same general approach: the line is transformed into modal components and each mode is solved independently. However, the equivalent circuit used for each mode is more complex in order to represent the frequency dependence of the line parameters more accurately.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d7e469955095fcb17ce45795eb39c5af942e2b98%2Fucm-frequency-dependent-lines.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# 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-lines-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.
