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

# Understand UCM Composition

This page explains the structure and execution model of a **User Code Model (UCM)** in HYPERSIM. It describes the different elements that compose a UCM, including input and calculated parameters, power nodes, control I/Os, and the separation between preparation and simulation functions.

The page also details how a UCM interacts with the network solution, including its contribution to the substation admittance matrix and the role of the **preVNode** and **postVNode** functions within each simulation time step. Together, these components define how the UCM integrates electrical behavior and control logic within the HYPERSIM simulation environment.

## Input parameters <a href="#input-parameters" id="input-parameters"></a>

Input parameters are those that will be in the parameter form. They can be modified once the UCM is inserted into the HYPERSIM® diagram.

### Calculated parameters <a href="#calculated-parameters" id="calculated-parameters"></a>

These parameters are calculated by the Preparation function to be used in the Simulation functions. The purpose is to avoid repeating the same calculation at every time step, thus reducing the simulation execution time.

### Power nodes <a href="#power-nodes" id="power-nodes"></a>

Power nodes can be external or internal. External nodes are graphically visible and will be connected to bus bars. Internal nodes are not visible. HYPERSIM® will include all UCM internal and external nodes into the substation’s node equation and calculate their voltages. HYPERSIM® provides the user with utilities to access UCM node voltages.

### Control IOs <a href="#control-ios" id="control-ios"></a>

Control inputs allow the UCM to get information from other systems, while control outputs to send out information computed by the UCM. The control outputs can be connected to other systems or simply used for monitoring purpose.

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

The Preparation function prepares the parameters needed during the simulation. The objective is to reduced the calculation effort during the simulation.

**Among the simulation parameters, there are:**

* The fixed part of the admittance matrix **Y**<sub>**ini**</sub> ,
* The sparsity indication matrix **Y**<sub>**fill**</sub>,

Other parameters derived from the input parameters. For example: if the input parameter is the frequency f, but during the simulation the period T=1/f is needed, then T is calculated during the preparation to avoid its calculation at every time steps. The Preparation function provided by user is compiled and linked with the HYPERSIM® GUI.

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

The UCM Simulation function is compiled with the simulation code generated by HYPERSIM® to form the Simulation program. This simulation program runs either in real-time or non real-time and communicates with the HYPERSIM® GUI for simulation control purpose. The Simulation functions include: Initialization function executed only once at the beginning of the simulation, preVNode (calculations done before the solution of node voltages) and postVNode (calculation after the solution of node voltages) executed at every time step.

### Initialization <a href="#initialization" id="initialization"></a>

This function is executed only once at the beginning of the simulation to perform various initializations needed by the UCM: set default parameters, initialize counters, etc.

### Function preVNode <a href="#function-prevnode" id="function-prevnode"></a>

This function is called prior to the calculation of node voltages by HYPERSIM®. It performs the following tasks:

* Determine switch commands and switch states
* Calculate **Y**<sub>**add**</sub> by taking into account the switch state and new non-linear operating point.
* Indicate nodes that are affected by changing in **Y**<sub>**add**</sub>
* Calculate currents sources.

{% hint style="info" %}
Voltage sources must be converted to current sources using Norton equivalent.
{% endhint %}

### Function postVNode <a href="#function-postvnode" id="function-postvnode"></a>

This function is called after the calculation of node voltages to:

* Calculate historics currents,
* Determine new operating point of non-linearities,
* Perform control functions and other calculations.

## Example <a href="#building-a-ucm-using-an-example-functional-description-of-the-ucm-in-example" id="building-a-ucm-using-an-example-functional-description-of-the-ucm-in-example"></a>

The example of a UCM, shown below, covers many aspects of the UCM coding. It has current sources, historic currents, non-linearity, internal and external nodes as well as control inputs-outputs.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-4535b1fca564ae79b273c2bafd9124388b52ada0%2Fucm-composition.png?alt=media" alt=""><figcaption><p>Example of a UCM with its Functional Content</p></figcaption></figure>

### UCM characteristics <a href="#ucm-characteristics" id="ucm-characteristics"></a>

* A UCM is a component located inside a substation. It is simulated with other components of the same substation. The UCM is composed of a power and a control part. The power part has external nodes (graphically visible) and internal nodes (invisible). This part is represented as an admittance matrix which will be added to the substation admittance matrix to solve the node equation. The UCM admittance matrix can be linear or non-linear.
* The control part performs user-defined control functions, using signals from the UCM control inputs and internal signals, then produces signals to send to the UCM control outputs or to be used internally.
* The UCM has its admittance matrix composed of a fixed part and a varying part :

### Parameters <a href="#parameters" id="parameters"></a>

## Input parameters <a href="#input-parameters.1" id="input-parameters.1"></a>

<table data-header-hidden><thead><tr><th width="170.66668701171875"></th><th></th></tr></thead><tbody><tr><td><strong>Rs</strong></td><td>Internal resistor of voltage source</td></tr><tr><td><strong>Lvec, Vinc, Ldim</strong></td><td>The non linear inductor depends on the rectified three-phase voltage across it. It is define as a table Lvec of Ldim inductance values picked at regular intervals of voltage Vinc.</td></tr><tr><td><strong>freq</strong></td><td>Frequency of the source.</td></tr></tbody></table>

## Calculated parameters and other parameters used during the simulation <a href="#calculated-parameters-and-other-parameters-used-during-the-simulation" id="calculated-parameters-and-other-parameters-used-during-the-simulation"></a>

<table data-header-hidden><thead><tr><th width="162.888916015625"></th><th></th></tr></thead><tbody><tr><td><strong>GaddVec</strong></td><td><p>table of additional conductance values (to be added to the initial value to get actual value) corresponding to Lvec.</p><p><strong>It is calculated as follows:</strong></p></td></tr><tr><td><strong>Lo = Lvec[0]</strong></td><td>first value in table Lvec.</td></tr><tr><td><strong>GLo = T/(2 * Lo)</strong></td><td>conductance equivalent to Lo. T is calculation time step. GaddVec[i] = T/(2 * Lvec[i]) - GLo</td></tr><tr><td><strong>Lindex</strong></td><td>indexes in the table GaddVec to be used to obtain current value of conductance for each phase.</td></tr><tr><td><strong>Lchanged</strong></td><td>Indication if inductor has changed it value.</td></tr><tr><td><strong>omega</strong></td><td>angular frequency =2 PI * freq.</td></tr></tbody></table>

### Connectors <a href="#connectors" id="connectors"></a>

## Power nodes <a href="#power-nodes.1" id="power-nodes.1"></a>

<table data-header-hidden><thead><tr><th width="94"></th><th></th></tr></thead><tbody><tr><td><strong>NE</strong></td><td>three-phase external node. It is visible to allow the user to connect it to a three-phase bus bar.</td></tr><tr><td><strong>NI</strong></td><td>three-phase internal node. It is not graphically visible on the HYPERSIM® diagram, but HYPERSIM® calculates its voltages and makes them available to the user.</td></tr></tbody></table>

## Control inputs outputs <a href="#control-inputs-outputs" id="control-inputs-outputs"></a>

<table data-header-hidden><thead><tr><th width="109.55560302734375"></th><th></th></tr></thead><tbody><tr><td><strong>A</strong></td><td>control input that determines the amplitude of the voltage source.</td></tr><tr><td><strong>IL</strong></td><td>multiplex output port containing the three-phase currents IL_a, IL_b, IL_c of the inductance.</td></tr><tr><td><strong>VLrec</strong></td><td>control output giving the three-phase rectified value of the inductor’s voltages.</td></tr></tbody></table>

## Current sources <a href="#current-sources" id="current-sources"></a>

Current sources are named (by the user) Isrc\_a, Isrc\_b, Isrc\_c. They are calculated by dividing the voltage source value by its internal resistor Rs.\
For a multi-phase currents, names must be terminated by \_a, \_b, \_c.

## Historic currents <a href="#historic-currents" id="historic-currents"></a>

The non-linear inductor has historic currents. They are named (by the user) Ihist\_a, Ihist\_ b, Ihist\_c and calculated according to the inductor EMTP model.\
For a multi-phase historic currents, their name must also be terminated by \_a, \_b, \_c.

## UCM utilities available to the user <a href="#ucm-utilities-available-to-the-user" id="ucm-utilities-available-to-the-user"></a>

The following are the various utilities (under #define forms) to provide communication between HYPERSIM® and the UCM:

* double ucmVNode (int nodeNum):
* Obtain the node voltage calculated by HYPERSIM® for node number nodeNum which can be the node order number (0, 1, 2, ...) or its symbolic name (NE\_a, NE\_b, ...)

`Ex: ucmVNode(0) or ucmVNode(NE_a)`

* double ucmYini(int node1, int node2):
* Element of the matrix **Y**<sub>**ini**</sub> of the UCM corresponding to row node1 and column node2. **Y**<sub>**ini**</sub> is calculated by user but the space for this matrix is allocated by HYPERSIM®.

`Ex: ucmYini (NI_a, NI_a) = (1.0/Rs) + (1.0/GL) or ucmYini(0, 0) = (1.0/Rs) + (1.0/GL)`

* double ucmYadd(int node1, int node2):
* Element of the matrix **Y**<sub>**add**</sub> of the UCM corresponding to row node1 and column node2. **Y**<sub>**add**</sub> is calculated by user but the space for this matrix is allocated by HYPERSIM®.

`Ex: ucmYadd(NI_a, NE_a) = -GaddVec[0]`

* int ucmYfill(int node1, int node2):
* Element of the matrix **Y**<sub>**fill**</sub> of the UCM corresponding to row node1 and column node2. **Y**<sub>**fill**</sub> is determined by user but the space for this matrix is allocated by HYPERSIM®.

`Ex: ucmYfill (1,2) = 0`

* int ucmNodeChange(int node):
* node<sup>th</sup> element of vector NodeChange. this vector is also allocated by HYPERSIM®.

`Ex: ucmNodeChange(NE_b) = 1`

* double ucmTimeStep:
* Obtain the current simulation time step.

`Ex: G = ucmTimeStep / (2.0 * L)`


---

# 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-ucm-composition.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.
