Documentation Home Page HYPERSIM Home Page
Pour la documentation en FRANÇAIS, utilisez l'outil de traduction de votre navigateur Chrome, Edge ou Safari. Voir un exemple.

How to Build UCM Devices in HYPERSIM

This document presents instructions necessary to program parameters for and use a UCM device in HYPERSIM.

What is a UCM?

UCM (User Code Model) is a HYPERSIM utility that allows users to build custom models that they cannot build using existing models. As its name suggests, a UCM is coded by users, using C language, according to certain specific HYPERSIM rules. This document shows how to use the UCM device to implement a simple resistance in the HYPERSIM library.

Generating a UCM

  • Create a new model
  • In your model directory, create a subfolder named MyUCM.
  • In HYPERSIM, click UCM, and select New UCM.

Create a UCM

  • Then click the button next to the UCM Directory text field and browse to the MyUCM folder.

UCM information window

  • In the UCM Name field, type Resistor and then click “Ok”.
  • The “ucm_Resistor.def ” file will automatically open with Notepad. Now, you can see the different section of a UCM code device that was created by default.
  • The user can now edit the UCM (in Notepad) with their own code in different sections. It is important to edit only the sections between the comments (text included between quotation marks). Do not modify the comments!

Using Notepad to edit the UCM

The UCM block is presented in text format and divided into sections. This document depicts only the sections required to edit the UCM.

Entering custom specifications

Each section has an area where users can create or modify values for their model. Each of these areas is in a tabular (column) form. The descriptions for each of these tab values are provided in the subsection immediately before the editable area (the section starts with %% BEGIN…).

The procedure for entering new values is:

On the first line, at the start of the line

type the Name

Press tab and specify the


Repeat for each line of


Each section may contain different column headings, but the procedure is the same.

General Information

This section is not editable. It displays information about the UCM.

UCM in Notepad, General information section

Tunable Parameters

This section enters or modifies tunable parameters. Any additions or changes must be made in the space between “%BEGIN TUNABLE PARAMETERS…” and “%% END TUNABLE PARAMETERS “, as shown in Figure 4.
In our example (Figure 4), we only wanted a simple resistor, so “R” is the only parameter added. But there are many other options: s, rad, W, V.s, V, T, Hz, H, F, A and ohm

Tunable parameters section

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

Tunable parameters description section

Control IOs

Control IOs are visible on network schematics as input and output connectors.

Control IOS section

Nodes definitions

This section defines the node connected to the network.

Nodes definition section

Calculated Parameters

The values that were calculated before starting the simulation. Simulation tasks use the results of these calculations.

Calculated parameters section

Preparatory Code

The following code is at the beginning of the preparatory code file.

Preparatory global code section

Preparation function code

This section is very important: in it, the user must write the code to calculate the initial admittance matrix and the calculated parameters to define the node connection to the network.

Preparation function code

After voltage calculation

In this section, the user enters the code to execute for calculating the output of the UCM.

After voltage calculation section

You have finished the coding of your resistor in the UCM template.

Next, you must generate the code written in the UCM file: In the HYPERSIM interface, right-click the UCM and select Update …

Generating the UCM code device in HYPERSIM

The code for the UCM device is generated, in the specified folder, with the following files:

UCM folder with associated files

You are ready to use your UCM in any model. We recommend that you complete the next exercise to ensure are ready to use the device in a model.

Defined variables

This section explains available variables to the user. These are for advanced users only.


retrieves the vector of index of nodes. The variable is the address of the first element in the vector.

ucmVNode(noNode)returns the tension of the node which the index is noNode.
ucmIndSimParretrieves the vector of integer parameters. The variable is the address of the first element in the vector.
ucmIndHistretrieves the vector of changes (history of changes). The variable is the address of the first element in the vector.
ucmYadd(i,j)Yadd between the nodes i and j.
ucmTimeSteptimeStep of simulation.
ucmIdid of SimData.
ucmNamename of the model.
ucmInitDatamodel init data.
ucmNoSPretrieves the index of the core where UCM is executed.
ucmNodeChanged(noNode)retrieves the node changes affected by non-linearity.

OPAL-RT TECHNOLOGIES, Inc. | 1751, rue Richardson, bureau 1060 | Montréal, Québec Canada H3K 1G6 | | +1 514-935-2323