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

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

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

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

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:

 

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.

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.

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.

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

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

Below is the mask of PV for the given 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.

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

Network Nodes

This section defines the nodes connected to the network.

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

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.

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.

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

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.

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

 

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.

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

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

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.

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.

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

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.

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

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

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.

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.

Before Nodes Voltage Calculation Code

Code executed before "nodes voltages calculations".

Below is an example of a 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.

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.

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.

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