/
How to Build UCM Devices in HYPERSIM

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 page presents instructions useful to program and use a UCM device in HYPERSIM.

More details can be found in User-Coded Model (UCM)

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 provides guidance on creating and utilizing a UCM across various examples.

Completing the other exercises is recommended to gain a better understanding of how to utilize a UCM

UCM Exercise and UCM: Exercise #1 Inductor Description can help you get started

Creating a UCM

The steps below demonstrate how to begin creating a new UCM.

  • Create a new HYPERSIM model

  • In HYPERSIM, click UCM, and select New UCM or New UCM (UCM Builder).

UCM creation interface

  • Then a window similar to the figure below will appear. Specify a directory for the new UCM project. 

UCM information

  • In the UCM Name field, type the name of new component and then click “Ok” to begin its creation.

  • The toolbox creates a new UCM definition file named ucm_'UCM Name'.def. Subsequently, the toolbox automatically either launches the UCM Builder interface or opens the file with a text editor. A UCM definition (.def file) can later be used to add more instances of the same UCM. Each instance has its own set of parameter values and internal data.

  • The UCM definition features several sections that are automatically generated by default and described below.

  • User can now modify the definition using either a text editor or the UCM Builder tool installed alongside HYPERSIM. When editing the UCM with a text editor, it's crucial to change only the content within the comments (the text enclosed in quotation marks) and refrain from changing the comments themselves.

Modifying the UCM using a text editor

The UCM definition 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





Units

Type

Direction

Position

Group

Description

Repeat for each line of

parameters

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

Modifying the UCM using UCM Builder

The UCM block is represented by a toolbox called UCM Builder, which features multiple tabs. Each tab displays a section of the UCM that needs editing.

Updating the UCM after editing

Once the UCM code has been edited (either through a text editor or the UCM builder), the code in the UCM block itself needs to be updated from the modified definition.

To that end, right-click on the UCM and choose 'Update' within the HYPERSIM interface. If there are any errors in the code, the compiler will display a message.

Interface to Update a UCM block from a given definition

The files for the UCM device will be generated in the specified folder.

UCM General Structure

This section describes the content of a UCM .def file

A few examples will be provided. They are taken from the two following UCM def files: and .

The UCM General Structure is divided in 3 parts

  1. Model Description

  2. Preparatory data preprocessing

  3. Model simulation

1. Model Description

The Model Description is made of the following sections

  1. General informations or parameters

  2. Model's documentation

  3. Form parameters (tunables)

    1. General parameters table.

  4. Control IOs

  5. Network nodes

  6. Current sources

  7. Historical currents

General Information

This section contains general information about the UCM.

Below, the General section is displayed, as opened in a text editor or via the UCM builder:

Text editor

 

UCM builder

The General information section has the following parameters.

UCM_NAME

Given name of UCM.

UCM_TYPE

Specify the type of UCM. Choose Network if it is a network component such as a resistor or voltage source and select Command if it is a command block.

UCM_CATEGORY

Specify the category of UCM. (It is optional)

UCM_VERSION

Specify the version of UCM. (It is optional)

UCM_EXEC_TIME

Specify the estimated execution time of UCM for real-time simulation. This value is used by the task manager of HYPERSIM to better balance the computation loads across the simulator cores.

UCM_DESCRIPTION

A description about the UCM. (It is optional)

UCM_LOADFLOW_TYPE
(optional)

Specify the load flow type for Network components. Allowed values are “Admittance” or “Generation”. If the UCM_LOADFLOW_TYPE isn’t specified in the list of general information, the UCM is ignored during loadflow.

UCM_ITERATION
(optional)

Specify if the model supports iteration (Yes or No).


The UCM_LOADFLOW_TYPE option has the following values:

Default

The UCM does not participate in the power flow solution

Admittance

The UCM participates in power flow solution by being considered as a load

Generation

The UCM participates in the power flow solution as a generator

When selecting the Generation type for the load flow option, a new tab is added to the component's interface.

Load Flow tab added when Generation type is selected in a UCM

Please note that the tab will become visible after updating the UCM code. To update, right-click on the UCM and select the Update option from the UCM section.

In case the user selects the Use iteration button, an iteration option will be added to the UCM interface. To activate the iteration method, the user must set Enable Iteration to '1'. An iterative method is necessary for the non-linear components.

Iteration panel

Tunable Parameters

In this section, the user specifies the tunable parameters of the component, which will be displayed in the UCM interface. 

In case of using a text editor, any additions or changes must be made in the space between “%BEGIN TUNABLE PARAMETERS…” and “%% END TUNABLE PARAMETERS “, as shown in figure below.
Below is an example of the Tunable Parameters section for a Photovoltaic (PV) UCM.

Tunable parameters in text editor

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

Description of tunable parameters

Here is the section on Tunable Parameters using the UCM builder for the PV example.

Tunable parameters in UCM builder

Below is the mask of PV for the given tunable parameters.

PV mask for tunable parameters

Control I/O

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.

Control IOs in text editor

Here is the section on Tunable Parameters using the UCM builder for the PV example.

Control IOs in UCM builder

Network Nodes

This section defines the nodes connected to the network.

Power Nodes in text editor

Figure below shows the section on Power Nodes using the UCM builder for the PV example.

Power Nodes in UCM builder

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.

PV UCM symbol

Current Sources

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.

Current Source in text editor

Figure below shows the section on Current Sources using the UCM builder for the Static Generator example.

Current Source in UCM builder

Historical Currents

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.

Historical Sources in text editor

Figure below shows the section on Historical Current Sources using the UCM builder for the Static Generator example.

Historical Sources in UCM Builder

 

2. Preparatory data preprocessing

This section contains the initial codes that executes once before the beginning of the EMT simulation.

Calculated Parameters

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

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.

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

Calculated Parameters section in text editor

Figure below shows the section on Calculating Parameters using the UCM builder for the PV example.

Calculated Parameters section in UCM builder

Global Code

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.

Initial segment of preparatory code

Function Code

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.

PV UCM Function code

Load flow Admittance Calculation

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.

Load Flow Admittance Calculation of a Static Generator

Load flow Historical Values

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 .

Load Flow Historical Values section for the Static Generator UCM

Load flow Model Parameters

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.

Load Flow Model Parameters' section for the Static Generator UCM

Variables definition

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

ucmYini(i,j)

retrieves the equivalent impedance using the nodal method between nodes i and j, which is utilized for EMT simulation.

ucmYfill(i,j)

retrieves a one if ucmYini(i,j) is non-zero; otherwise, it retrieves a zero. This variable is utilized in EMT simulation.

ucmTimeStep

returns the timeStep of simulation.

ucmYlfReal(i,j)

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.

ucmYlfImag(i,j)

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.

ucmIlfHist(i)

returns current at one time-step before starting the simulation.

ucmIlfActual(i)

returns current at starting the simulation.

ucmVlfHist(i)

returns voltage at one time-step before starting the simulation.

ucmVlfActual(i)

returns voltage at starting the simulation.

ucmVintReal(i)

returns the real part of an internal source in the phasor domain from load flow calculation.

ucmVintImag(i)

returns the imaginary part of an internal source in the phasor domain from load flow calculation.

3. Model Simulation

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

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

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.

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

Hhistorical Values section for a Static Generator UCM

The figure below illustrates the section on Historical Values using the UCM builder for the Static Generator example.

historical values section for a Static Generator UCM in the UCM builder

Global Code

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

Global Code in text editor

Initialization Code

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

Static Generator UCM Initialization Code

Before Nodes Voltage Calculation Code

Code executed before "nodes voltages calculations".

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

Photovoltaic (PV) UCM Before Voltage Calculation Code

Before Nodes Voltage Calculation Iteration Code

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

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

Photovoltaic (PV) UCM Before Voltage Calculation Iteration code

After Nodes Voltage Calculation Iteration

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.

Photovoltaic (PV) UCM After Voltage Calculation Iteration code

After Nodes Voltage Calculation Code

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.

Photovoltaic (PV) UCM After Voltage Calculation Code

Variables definition

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

ucmNodePoste

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.

ucmIndSimPar

retrieves the vector of integer parameters. The variable is the address of the first element in the vector.

ucmIndHist

retrieves 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.

ucmTimeStep

timeStep of simulation.

ucmId

id of SimData.

ucmName

name of the model.

ucmInitData

model init data.

ucmNoSP

retrieves 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 | opal-rt.com | +1 514-935-2323
Follow OPAL-RT: LinkedIn | Facebook | YouTube | X/Twitter