Editing the UCM

To start editing a UCM from scratch:
• Launch HYPERSIM® using its shortcut
• Create a new model or open an existing one
• Click the HYPERSIM tab to display the HYPERSIM ribbon
• In the Import section, click UCM/New UCM

New UCM menu

Choose a directory to save your new UCM and type a name and click OK. This will import a new UCM block in your diagram and open your default text editor to edit the UCM definition file (.def).

When the user has finished editing the UCM definition file, they must save it and exit the editor. To update the UCM block, right-click on the block in the diagram and click UCM/Update…

This updates the component code and its symbol.

Naming conventions

• Many utilities provided by HYPERSIM® start with three letters ucm. Therefore DO NOT use variable or function name starting with ucm (for example, ucmFreqency) to avoid duplication error.
• Although power nodes are entered as multiphase, all calculations must be done on a per-phase basis.
• Single-phase node is specified either by nodeName_phase (for example NI_a) or by its ordering number. As with our example above, nodes are numbered and named as follows (if NE is defined before NI):

NE_a

NE_b

NE_c

NI_a

NI_b

NI_c

Names of multi-phase current sources and historic currents must be terminated with _a, _b, _c, etc. to indicate the phase to which they belong. Ex: Isrc_a, Ihist_b.

Users must declare variables and functions used, except for certain variables that are mandatory for UCM. Those are allocated by HYPERSIM and users can access them through UCM utilities described above.

The mandatory variables already allocated by HYPERSIM are:

This is the fixed part of the UCM admittance matrix

This is the variable part of the UCM admittance matrix

This is the matrix indicating the sparsity of the UCM admittance matrix

NodeChange: vector indicating which node has been affected by non-linearity.

NodeChange[i]=1 if node i has been affected

NodeChange[i]=0 if node i has not been affected

Input parameters, Calculated parameters, and Control I/Os are named according to C conventions (but names starting with the three letters ucm are avoided). They are defined in their appropriate section in the UCM file and must not be re-declared in the functions section.