> 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/understand-hypersim-execution-workflow.md).

# Understand HYPERSIM Execution Workflow

This page explains how HYPERSIM prepares and simulates power system networks at the substation level. It describes the sequence of operations performed during the **preparation phase**, where model parameters and the initial admittance matrix are computed, and during the **simulation phase**, where the node equation is solved at each time step.

The page also details how the admittance matrix is updated to account for switching events and nonlinear behavior, and how element currents and control functions are evaluated throughout the simulation. Finally, it introduces the concept of **parallel task execution**, which enables efficient simulation of large networks by distributing computations across multiple processors.

## Preparation <a href="#preparation" id="preparation"></a>

To calculate parameters for all power elements and the substation’s node equation, **the preparation operations are:**

* Read each element’s parameters from the parameter form
* **Define node signals:** voltages and currents
* **Define element’s signals:** voltages (except node voltages), currents (source, historic), control signals
* Calculate the fixed part *Y*<sub>*ini*</sub> as initial admittance of all elements, as well as other element’s parameters needed during the simulation
* Calculate the fixed part ***Y***<sub>***INI***</sub> and initialize the substation admittance matrix **Y** to this value
* Reorder **Y** so that varying elements will affect only the lower right part of **Y**
* Download ***Y***<sub>***INI***</sub>: *Y*<sub>*ini*</sub>, and other simulation parameters needed by the simulation program

## Simulation <a href="#simulation" id="simulation"></a>

At each simulation step, the following operations are required to simulate power elements and solve the node equation of a substation:

* Determine the switch commands (used to turn them on or off)
* Determine states of switches
* If needed (some switches have changed their state or some non-linear elements have changed their operation point), determine the area of matrix **Y** that needs to be re-evaluated due to elements that have changed their operating point.

Re-calculate this part of **Y**.

* If needed (as above), perform the LDU decomposition of the lower-right bloc of the **Y**<sub>**LDU**</sub> matrix
* Calculate source’s currents (voltage sources and current sources)
* Add source’s currents to node currents **I**.
* Solve **YV = I** to calculate node voltages **V**.
* Determine if a non-linear element changes its operating point. If it is the case, calculate its new **Y**<sub>**add**</sub> and update **Y**<sub>**eq**</sub>**=Y**<sub>***ini***</sub>**+Y**<sub>***add***</sub> for that element.
* Calculate element’s historic current **I**<sub>***hist***</sub> as well as all other signals it needs.
* Re-initialize node currents **I** to \[0] for the next step
* Add element’s historic currents **I**<sub>***hist***</sub> to node current **I**.
* Calculate control functions

## Parallel tasks in HYPERSIM® <a href="#parallel-tasks-in-hypersim-r" id="parallel-tasks-in-hypersim-r"></a>

As mentioned in the line modeling section, lines are equivalent to current sources in parallel to resistors at each line end. Current sources at each end depend only on the past value of line voltages and currents of both ends. Variations at one end will therefore affect the other end at one transmission delay later. The transmission speed is about light speed, which is 300 000 km/s. A 30km line has a transmission delay of 100 µs.\
Due to the transmission delay, in a network composed of lines and substation (as shown), the following tasks can be performed in parallel:

* Substation tasks solving substation node equations, which also include line-end equivalents (current sources in parallel with resistors) and simple control systems,
* Line tasks calculating line equivalents at each line end.

Certain complex substations can have complex control systems, such as an AC-DC conversion station, generation station with machine models. These substations are simulated with many tasks: one for solving the node equation and others for control systems.

In non-real-time mode running in a single processor, all tasks are given to the same processor. With a parallel computer, tasks are distributed among parallel processors using a task mapping algorithm based on following criteria: execution time of each task, available time of processor, communications needed and communication link available, I/O needed and I/O availability, etc.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ebfd96e42ac3f77482b4f33c8251e3166f7bce09%2Fucm-prep.png?alt=media" alt=""><figcaption><p>A Network Structure and the Corresponding Parallel Tasks</p></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/understand-hypersim-execution-workflow.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.
