> 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/build-ucm-with-ucm-builder.md).

# Build UCM with UCM Builder

## Introduction

**UCM Builder** is an interface that simplifies the creation and editon of **User Code Models (UCMs)**.

It builds on the original UCM definition format (`.def`), which is organized into sections, but uses an **XML-based format** to support new features and improved integration. For parameter details, refer to the [Definition File](https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/build-ucm-with-definition-file.md) documentation.

The UCM Builder is organized into seven main areas, including:

1. **Menu bar**: Divided into **File** and **Help**. All UCM file management actions are available under **File**.
2. **Toolbar:** Provides quick access to actions for **opening**, **saving**, and **saving a UCM under a new name (Save As)**.
3. **Model identification**: Contains the name and the description of the UCM.
4. **Edition manager**: Allows users to **select and navigate between the different sections** of the UCM to be edited.
5. **Edition zone**: Contains all the parameters of the model. The displayed parameters depend on the section selected in the **Edition manager**.
6. **Console**: Displays relevant information regarding UcmBuilder actions.
7. **Status bar**: Allows to see the state of UcmBuilder. It is also synchronized with the number of section defined in the `.def` to help the user to understand where the section is in the `.def` file.

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

## Build the UCM with UCM Builder

To edit a UCM, right‑click the model block, then select **UCM > Edit (UcmBuilder)**.

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

### General

Click **General** in the **Edition manager** and complete the general information.

### Tunable parameters

Navigate to **Tunable Parameters** and click the \[**+**] button to add a parameter. When finished, press **Enter**.

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

{% hint style="danger" %}
vectors must be in square brackets \[val1 val2 val3 ... valN] and separated by a space.
{% endhint %}

### Control I/O

Navigate to **Control I/O** and to add model's inputs or outputs.

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

### Power nodes

Navigate to **Power Nodes** to add network connectors.

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

### Calculated parameters

Navigate to **Calculated Parameter** to add calculated parameters.

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

### Preparatory <a href="#preparatory" id="preparatory"></a>

The **Preparatory** section includes the following subsections:

* **Global Code**: Make sure to include the `stdio.h` file.

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

* **Function Code**: Use this section to initialize parameters (e.g. the admittance matrix and the calculated parameters).

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

Here is the code for the example shown above:

```
int i = 0;
int j = 0;
G[0] = 1.0 / R[0];
G[1] = 1.0 / R[1];
G[2] = 1.0 / R[2];
/* Initialization of Yini and Yfill */
for (i = 0; i < 3; i++)
{
	{
		ucmYini(i, j) = 0.0;
		ucmYfill(i, j) = 0;
	}
}
/* Calculate Yini and define Yfill */
ucmYini(T_a, T_a) = 1.0 * G[0];
ucmYini(T_b, T_b) = 1.0 * G[1];
ucmYini(T_c, T_c) = 1.0 * G[2];
ucmYfill(T_a, T_a) = 1;
ucmYfill(T_b, T_b) = 1;
ucmYfill(T_c, T_c) = 1;
```

* **Loadflow Admittance Calculation**
* **Loadflow Historical Values**
* **Loadflow Model Parameters**
* **Build Information**

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

The **Simulation** section includes the following subsections:

* **Historical Values**: Make sure to include the `stdio.h` file.
* **Global Code**: Make sure to include the `stdio.h` file
* **Initialisation Code**: Make sure to include the `stdio.h` file
* **Before Voltage Calculation Code**: Make sure to include the `stdio.h` file
* **Before Voltage Calculation Iteration**: Make sure to include the `stdio.h` file
* **After Voltage Calculation Iteration**: Make sure to include the `stdio.h` file
* **After Voltage Calculation Code**: In this section, add the code to calculate the output currents.

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

## Save the UCM

Once editing is completed, click **Save** in the toolbar to save the UCM. UCM Builder provides two definition files for the model:

* `ucm_%model_name%.def` which is a simplified version of the model definition
* and `%model_name%.xml` which is more evolved.

## Update the UCM <a href="#design" id="design"></a>

The UCM is present in the design, but no pins are displayed yet. The UCM must be updated to reflect the defined parameters and expose the corresponding pins.

To update the UCM, right‑click the model block, then select **UCM > Update...**.

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

HYPERSIM detects and displays the changes and requests approval to update the model accordingly.

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

Hypersim associates a generic view according to the UCM information and another generic view to select sensors.

## Review the UCM

Once updated, HYPERSIM automatically generates a generic graphical view based on the UCM definition, along with a default interface for selecting sensors.

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

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

The UCM block is now ready to be connected to other blocks and used in simulation.


---

# 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/build-ucm-with-ucm-builder.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.
