Composition of a UCM
Input parameters
Input parameters are those that will be in the parameter form. They can be modified once the UCM is inserted into the HYPERSIM® diagram.
Calculated parameters
These parameters are calculated by the Preparation function to be used in the Simulation functions. The purpose is to avoid repeating the same calculation at every time step, thus reducing the simulation execution time.
Power nodes
Power nodes can be external or internal. External nodes are graphically visible and will be connected to bus bars. Internal nodes are not visible. HYPERSIM® will include all UCM internal and external nodes into the substation’s node equation and calculate their voltages. HYPERSIM® provides the user with utilities to access UCM node voltages.
Control IOs
Control inputs allow the UCM to get information from other systems, while control outputs to send out information computed by the UCM. The control outputs can be connected to other systems or simply used for monitoring purpose.
Preparation function
The Preparation function prepares the parameters needed during the simulation. The objective is to reduced the calculation effort during the simulation.
Among the simulation parameters, there are:
- The fixed part of the admittance matrix Yini ,
- The sparsity indication matrix Yfill,
Other parameters derived from the input parameters. For example: if the input parameter is the frequency f, but during the simulation the period T=1/f is needed, then T is calculated during the preparation to avoid its calculation at every time steps. The Preparation function provided by user is compiled and linked with the HYPERSIM® GUI.
Simulation functions
The UCM Simulation function is compiled with the simulation code generated by HYPERSIM® to form the Simulation program. This simulation program runs either in real-time or non real-time and communicates with the HYPERSIM® GUI for simulation control purpose. The Simulation functions include: Initialization function executed only once at the beginning of the simulation, preVNode (calculations done before the solution of node voltages) and postVNode (calculation after the solution of node voltages) executed at every time step.
Initialization
This function is executed only once at the beginning of the simulation to perform various initializations needed by the UCM: set default parameters, initialize counters, etc.
Function preVNode
This function is called prior to the calculation of node voltages by HYPERSIM®. It performs the following tasks:
- Determine switch commands and switch states
- Calculate Yadd by taking into account the switch state and new non-linear operating point.
- Indicate nodes that are affected by changing in Yadd
- Calculate currents sources.
Note: Voltage sources must be converted to current sources using Norton equivalent.
Function postVNode
This function is called after the calculation of node voltages to:
- Calculate historics currents,
- Determine new operating point of non-linearities,
- Perform control functions and other calculations.
Building a UCM using an example: Functional description of the UCM in example
The example of a UCM, shown below, covers many aspects of the UCM coding. It has current sources, historic currents, non-linearity, internal and external nodes as well as control inputs-outputs.
UCM characteristics
- A UCM is a component located inside a substation. It is simulated with other components of the same substation. The UCM is composed of a power and a control part. The power part has external nodes (graphically visible) and internal nodes (invisible). This part is represented as an admittance matrix which will be added to the substation admittance matrix to solve the node equation. The UCM admittance matrix can be linear or non-linear.
- The control part performs user-defined control functions, using signals from the UCM control inputs and internal signals, then produces signals to send to the UCM control outputs or to be used internally.
- The UCM has its admittance matrix composed of a fixed part and a varying part :
Parameters
Input parameters
| Rs | Internal resistor of voltage source |
| Lvec, Vinc, Ldim | The non linear inductor depends on the rectified three-phase voltage across it. It is define as a table Lvec of Ldim inductance values picked at regular intervals of voltage Vinc. |
| freq | Frequency of the source. |
Calculated parameters and other parameters used during the simulation
| GaddVec | table of additional conductance values (to be added to the initial value to get actual value) corresponding to Lvec. It is calculated as follows: |
| Lo = Lvec[0] | first value in table Lvec. |
| GLo = T/(2 * Lo) | conductance equivalent to Lo. T is calculation time step. GaddVec[i] = T/(2 * Lvec[i]) - GLo |
| Lindex | indexes in the table GaddVec to be used to obtain current value of conductance for each phase. |
| Lchanged | Indication if inductor has changed it value. |
| omega | angular frequency =2 PI * freq. |
Connectors
Power nodes
| NE | three-phase external node. It is visible to allow the user to connect it to a three-phase bus bar. |
| NI | three-phase internal node. It is not graphically visible on the HYPERSIM® diagram, but HYPERSIM® calculates its voltages and makes them available to the user. |
Control Inputs Outputs
| A | control input that determines the amplitude of the voltage source. |
| IL | multiplex output port containing the three-phase currents IL_a, IL_b, IL_c of the inductance. |
| VLrec | control output giving the three-phase rectified value of the inductor’s voltages. |
Current sources
Current sources are named (by the user) Isrc_a, Isrc_b, Isrc_c. They are calculated by dividing the voltage source value by its internal resistor Rs.
For a multi-phase currents, names must be terminated by _a, _b, _c.
Historic currents
The non-linear inductor has historic currents. They are named (by the user) Ihist_a, Ihist_ b, Ihist_c and calculated according to the inductor EMTP model.
For a multi-phase historic currents, their name must also be terminated by _a, _b, _c.
UCM utilities available to the user
The following are the various utilities (under #define forms) to provide communication between HYPERSIM® and the UCM:
- double ucmVNode (int nodeNum):
- Obtain the node voltage calculated by HYPERSIM® for node number nodeNum which can be the node order number (0, 1, 2, ...) or its symbolic name (NE_a, NE_b, ...)
Ex: ucmVNode(0) or ucmVNode(NE_a)
- double ucmYini(int node1, int node2):
- Element of the matrix Yini of the UCM corresponding to row node1 and column node2. Yini is calculated by user but the space for this matrix is allocated by HYPERSIM®.
Ex: ucmYini (NI_a, NI_a) = (1.0/Rs) + (1.0/GL) or ucmYini(0, 0) = (1.0/Rs) + (1.0/GL)
- double ucmYadd(int node1, int node2):
- Element of the matrix Yadd of the UCM corresponding to row node1 and column node2. Yadd is calculated by user but the space for this matrix is allocated by HYPERSIM®.
Ex: ucmYadd(NI_a, NE_a) = -GaddVec[0]
- int ucmYfill(int node1, int node2):
- Element of the matrix Yfill of the UCM corresponding to row node1 and column node2. Yfill is determined by user but the space for this matrix is allocated by HYPERSIM®.
Ex: ucmYfill (1,2) = 0
- int ucmNodeChange(int node):
- nodeth element of vector NodeChange. this vector is also allocated by HYPERSIM®.
Ex: ucmNodeChange(NE_b) = 1
- double ucmTimeStep:
- Obtain the current simulation time step.
Ex: G = ucmTimeStep / (2.0 * L)