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.

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

Open

UCM creation interface

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

Open

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:

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

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.

The UCM_LOADFLOW_TYPE option has the following values:

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.

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.