> 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-definition-file.md).

# Build UCM with Definition File

This page explains the structure and content of the **UCM definition file**, which is used to describe a User Code Model (UCM) in HYPERSIM. It presents the organization of the file into its main sections, including model description, parameter definitions, preparation data, and simulation functions.

The definition file is **self-documenting**, with comment blocks (`%%`) guiding users on how to enter the required information in each section. Only specific editable areas should be modified, while the structure and comments must be preserved.

Each section includes an editable area where users can define or modify values for their model. These areas are organized in a tabular format, with each column representing a specific attribute (such as name, units, type, or description). The definition of each column is provided in the subsection preceding the editable area, which begins with `%% BEGIN`. To enter new values, fill in each field from left to right and repeat the process for each parameter.

{% hint style="info" %}
A few examples will be provided. They are taken from the two following UCM def files: ucm\_PV.def and ucm\_Static\_Generator.def.
{% endhint %}

The UCM General Structure is divided in 3 parts

1. Model description
2. Preparatory data preprocessing
3. Model simulation

## Model description <a href="#id-1.-model-description" id="id-1.-model-description"></a>

The **Model description** is made of the following sections:

### General information <a href="#general-information" id="general-information"></a>

This section contains general information about the UCM:

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

The **General information** section has the following parameters:

<table data-search="false"><thead><tr><th width="211.77783203125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>UCM_NAME</strong></td><td>Given name of UCM.</td></tr><tr><td><strong>UCM_TYPE</strong></td><td>Specify the type of UCM. Choose <code>Network</code> if it is a network component such as a resistor or voltage source and select <code>Command</code> if it is a command block.</td></tr><tr><td><strong>UCM_CATEGORY</strong></td><td>Specify the category of UCM. (It is optional)</td></tr><tr><td><strong>UCM_VERSION</strong></td><td>Specify the version of UCM. (It is optional)</td></tr><tr><td><strong>UCM_EXEC_TIME</strong></td><td>Specify the estimated execution time of UCM for real-time simulation. This value is used by the <strong>Task manager</strong> of HYPERSIM to better balance the computation loads across the simulator cores.</td></tr><tr><td><strong>UCM_DESCRIPTION</strong><br>(optional)</td><td>A description about the UCM.</td></tr><tr><td><strong>UCM_LOADFLOW_TYPE</strong><br>(optional)</td><td><p>Specify the load flow type for Network components. Allowed values are:<br><strong>Default (or unspecified)</strong>: The UCM does not participate in the power flow solution.</p><p><strong>Admittance</strong>: The UCM participates in power flow solution by being considered as a load.<br><strong>Generation:</strong> The UCM participates in the power flow solution as a generator. When selected, a new tab is added to the UCM block's mask after updating the UCM.<br><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0150c5c7256e8dfc9b62dbfb6e821ada77f6f711%2Fucm-file-load-flow.png?alt=media" alt=""></p></td></tr><tr><td><strong>UCM_ITERATION</strong><br>(optional)</td><td>Specifies whether the model supports iteration. See <a href="https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/use-iterations-in-ucm.md">Use Iterations in UCM</a> for more details.</td></tr></tbody></table>

### Model's documentation <a href="#tunable-parameters" id="tunable-parameters"></a>

In this section, users provide **textual documentation for the UCM**, which is displayed in the UCM interface and can be accessed by end users. All documentation must be entered within the block delimited by `%% BEGIN DOCUMENTATION` and `%% END DOCUMENTATION`.

This section is intended to describe:

* the purpose of the model
* its main features and behavior
* any relevant usage information

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

### Tunable parameters <a href="#tunable-parameters" id="tunable-parameters"></a>

In this section, users define the **tunable parameters** of the UCM, which are displayed in the UCM interface. All parameters must be added or modified within the block delimited by\
`%% BEGIN TUNABLE PARAMETERS` and `%% END TUNABLE PARAMETERS`, as shown in the figure below.

The example below illustrates the **Tunable Parameters** section for a Photovoltaic (PV) UCM.

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

Each tab (or column) represents a value, as described below:

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

The figure below shows the resulting UCM block mask for the PV model based on the defined tunable parameters.

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

### Control I/O <a href="#control-i-o" id="control-i-o"></a>

In this section, the input and output signals of the UCM are defined by the user. Below is an example of the Control I/O section for a Photovoltaic (PV) UCM.

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

### Network nodes <a href="#network-nodes" id="network-nodes"></a>

This section defines the nodes connected to the network.

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

When power nodes and control I/O signals are defined by the user, the UCM symbol will alter to reflect the chosen options. Below is an example of a Photovoltaic (PV) UCM symbol.

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

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

In HYPERSIM, all network components are modeled using the Norton Equivalent approach. This section allows the user to specify the equivalent current sources for the UCM by employing the Norton Equivalent method. An example of the Current Sources section for a Static Generator UCM is provided below.

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

### Historical currents <a href="#historical-currents" id="historical-currents"></a>

The equivalent historical current sources for the UCM are defined using the Norton Equivalent method. These historical current sources are calculated through a discretization method. In HYPERSIM, the Trapezoidal rule is employed to discretize derivative equations. Below is an example of the Historical Sources section for a Static Generator UCM.

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

## Preparatory data preprocessing <a href="#id-2.-preparatory-data-preprocessing" id="id-2.-preparatory-data-preprocessing"></a>

This **preparatory data preprocessing** section contains the initial codes that executes once before the beginning of the EMT simulation and is made of the following sections:

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

The user specifies the constant parameters to be utilized in the code in this section.

{% hint style="danger" %}
It is crucial to understand that while the tunable parameter can be adjusted by the user at the interface of component, the calculated parameters are determined only once at the start of the simulation, making them constant throughout.
{% endhint %}

Below is an example of the Calculated Parameters section for a Photovoltaic (PV) UCM.

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

### Global code <a href="#global-code" id="global-code"></a>

The code below will serve as the initial segment of the preparatory code file. User can append particular functions and incorporate necessary libraries within this preparatory code.

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

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

This section is crucial. It requires the user to write code that calculates the initial admittance matrix and determines the parameters that define the node's connection to the network.

Below is an example of a Photovoltaic (PV) UCM Function Code.

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

### Load flow admittance calculation <a href="#load-flow-admittance-calculation" id="load-flow-admittance-calculation"></a>

The Load Flow Admittance Calculation function enables the inclusion of the UCM in the load flow solution.

The code depicted in the figure below pertains to the Load Flow Admittance Calculation section for the UCM Static Generator. It is important to note that the real (ucmYlfReal) and imaginary (ucmYlfImag) components of the UCM should be distinctly defined within the nodal admittance matrix.

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

### Load flow historical values <a href="#load-flow-historical-values" id="load-flow-historical-values"></a>

The code added here is used to initialize the historical current and voltage with the values obtained from the load-flow calculation.

The code illustrated in the figure below represents the Load Flow Historical Values section for the Static Generator UCM .

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

### Load flow model parameters <a href="#load-flow-model-parameters" id="load-flow-model-parameters"></a>

The code added here is used to update the 'Calculate Parameters' with the values obtained from the load-flow analysis.

The code depicted in the figure below corresponds to the 'Load Flow Model Parameters' section for the UCM Static Generator.

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

### Variables definition <a href="#variables-definition" id="variables-definition"></a>

This section explains available variables to the users in the Preparatory data preprocessing sections. These are for **advanced users only**.

<table><thead><tr><th width="195.111083984375">Parameters</th><th>Description</th></tr></thead><tbody><tr><td><strong>ucmYini(i,j)</strong></td><td>Retrieves the equivalent impedance using the nodal method between nodes i and j, which is utilized for EMT simulation.</td></tr><tr><td><strong>ucmYfill(i,j)</strong></td><td>Retrieves a one if <strong>ucmYini(i,j)</strong> is non-zero; otherwise, it retrieves a zero. This variable is utilized in EMT simulation.</td></tr><tr><td><strong>ucmTimeStep</strong></td><td>Returns the timeStep of simulation.</td></tr><tr><td><strong>ucmYlfReal(i,j)</strong></td><td>Retrieves the real part of the equivalent impedance of the phasor method between nodes i and j. This variable is used for load flow calculation.</td></tr><tr><td><strong>ucmYlfImag(i,j)</strong></td><td>Retrieves the imaginary part of the equivalent impedance of the phasor method between nodes i and j. This variable is used for load flow calculation.</td></tr><tr><td><strong>ucmIlfHist(i)</strong></td><td>Returns current at one time-step before starting the simulation.</td></tr><tr><td><strong>ucmIlfActual(i)</strong></td><td>Returns current at starting the simulation.</td></tr><tr><td><strong>ucmVlfHist(i)</strong></td><td>Returns voltage at one time-step before starting the simulation.</td></tr><tr><td><strong>ucmVlfActual(i)</strong></td><td>Returns voltage at starting the simulation.</td></tr><tr><td><strong>ucmVintReal(i)</strong></td><td>Returns the real part of an internal source in the phasor domain from load flow calculation.</td></tr><tr><td><strong>ucmVintImag(i)</strong></td><td>Returns the imaginary part of an internal source in the phasor domain from load flow calculation.</td></tr></tbody></table>

## Model simulation <a href="#id-3.-model-simulation" id="id-3.-model-simulation"></a>

In this section, the user defines the code to simulate the model, which can be executed before or after calculating the node voltages.

### Historical values <a href="#historical-values" id="historical-values"></a>

In this section, the user defines the historical values to be used in the code.

{% hint style="info" %}
It's important to note that while the user can adjust the tunable parameter at the component interface, the calculated parameters are set only at the beginning of the simulation.

In contrast, historical values are computed at each time step and utilized in the subsequent time step of the simulation.
{% endhint %}

An example of the historical values section for a Static Generator UCM is provided below.

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

### Global code <a href="#global-code.1" id="global-code.1"></a>

The code below is an example of global code file. User can define particular functions and add necessary libraries within this simulation code.

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

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

The user must write code that is executed once before the simulation starts. Below is an example of a Static Generator UCM Initialization Code.

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

### Before nodes voltage calculation code <a href="#before-nodes-voltage-calculation-code" id="before-nodes-voltage-calculation-code"></a>

Code executed before "nodes voltages calculations".

Below is an example of a Photovoltaic (PV) UCM Before Voltage Calculation Code.

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

### Before nodes voltage calculation iteration code <a href="#before-nodes-voltage-calculation-iteration-code" id="before-nodes-voltage-calculation-iteration-code"></a>

Code executed before "nodes voltages calculations" **when iteration is activated**.

Below is an example of a Photovoltaic (PV) UCM Before Voltage Calculation Iteration code.

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

### After nodes voltage calculation iteration <a href="#after-nodes-voltage-calculation-iteration" id="after-nodes-voltage-calculation-iteration"></a>

The code is executed following the "nodes voltages calculations" **when iteration is enabled**. It returns an integer indicating whether iteration is necessary: return 0 for no iteration needed, return 1 for iteration required.

Below is an example of a Photovoltaic (PV) UCM After Voltage Calculation Iteration code.

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

### After nodes voltage calculation code <a href="#after-nodes-voltage-calculation-code" id="after-nodes-voltage-calculation-code"></a>

Code executed after "nodes voltages calculations". In this section, the user can enter the code to execute for calculating the output of the UCM.

Below is an example of a Photovoltaic (PV) UCM After Voltage Calculation Code.

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

### Variables definition <a href="#variables-definition.1" id="variables-definition.1"></a>

This table outlines the variables available to users in the Simulation sections. **These are for advanced users only.**

<table><thead><tr><th width="246.22216796875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>ucmNodePoste</strong></td><td>Retrieves the vector of index of nodes. The variable is the address of the first element in the vector.</td></tr><tr><td><strong>ucmVNode(noNode)</strong></td><td>Returns the tension of the node which the index is noNode.</td></tr><tr><td><strong>ucmIndSimPar</strong></td><td>Retrieves the vector of integer parameters. The variable is the address of the first element in the vector.</td></tr><tr><td><strong>ucmIndHist</strong></td><td>Retrieves the vector of changes (history of changes). The variable is the address of the first element in the vector.</td></tr><tr><td><strong>ucmYadd(i,j)</strong></td><td>Yadd between the nodes i and j.</td></tr><tr><td><strong>ucmTimeStep</strong></td><td>TimeStep of simulation.</td></tr><tr><td><strong>ucmId</strong></td><td>ID of SimData.</td></tr><tr><td><strong>ucmName</strong></td><td>Name of the model.</td></tr><tr><td><strong>ucmInitData</strong></td><td>Model init data.</td></tr><tr><td><strong>ucmNoSP</strong></td><td>Retrieves the index of the core where UCM is executed.</td></tr><tr><td><strong>ucmNodeChanged(noNode)</strong></td><td>Retrieves the node changes affected by non-linearity.</td></tr></tbody></table>


---

# 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-definition-file.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.
