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.

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

• 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:

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.

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

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

Control IOs

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

Nodes definitions

This section defines the node connected to the network.

Calculated Parameters

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

Preparatory Code

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

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.

After voltage calculation

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

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 …

The code for the UCM device is generated, in the specified folder, with the following 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.