> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/build-ucm-with-definition-file/ucm-definition-file-example.md).

# UCM Definition File Example

## Overview

The UCM definition file to be edited for the UCM Example is named `ucm_Exemple.def` and is shown below. The UCM Preparation and Simulation functions are coded according to standard C.

See the sample definition file below. The definition file is provided in code/preformatted text.

## UCM definition file structure

```
%% UCM Model Definition File -- Generated from:
%%
%% Model “Example” definition file -- Date: Tue Mar 22 16:16:10 EST 2005
%%-----------------------------------------------------------------------------
%%
%% Definition of a user's created HYPERSIM® model
%% ---------------------------------------------
%%
%% Comments used by the definition file are preceded by this string: "%%"
%%
%% ***************************
%% * DO NOT MODIFY COMMENTS! *
%% ***************************
%%
%% Only edit zones between comments.
%% Follow directives describing format of data.
%%
%% This file is divided en 3 major sections : “General description”,
%% “Preparatory data preprocessing” and “Model simulation”.
%%
%% Here is the file general structure :
%%
%% I- Model description.
%% 1- General informations or parameters.
%% 2- Model's documentation.
%% 3- Form parameters (tunables).
%% 3.1- General parameters table.
%% 3.2- (Load Flow parameters table. NOT IMPLEMENTED!!!)
%% 4- Control IOs.
%% 5- Network nodes.
%% 6- Current sources.
%% 7- Historical currents.
%%
%% II- Preparatory data preprocessing.
%% 8- Calculated values.
%% 8.1- Calculated parameters table.
%% 8.2- (Calculated Load Flow values. NOT IMPLEMENTED!!!)
%% 8.3- Preparation function code.
%% 8.3.1- Function's global code.
%% 8.3.2- Parameters & initial admittance matrix (Yini) calculation code.
%% 8.3.3- (Load Flow results calculation code. NOT IMPLEMENTED!!!)
%% 8.4- “Includes” paths list.
%% 8.5- Required libraries list.
%% 8.6- Required libraries paths list.
%%
%% III- Model simulation.
%% 9- Simulation code.
%% 9.1- Historical values table.
%% 9.2- Test points table.
%% 9.3- Simulation functions global code.
%% 9.4- Simulation initialization function.
%% 9.5- Before “nodes voltage calculation” function code.
%% 9.5.1- Sources calculation.
%% 9.5.2- Command selection.
%% 9.5.3- Admittances matrix calculation (YMadd).
%% 9.6- After “nodes voltage calculation” function code.
%% 9.6.1- Historical values calculation.
%% 9.6.2- Commands outputs calculation.
%% 9.6.3- Determine nodes to recalculate.
%% 9.7- “Includes” paths list.
%% 9.8- Required libraries list.
%% 9.9- Required libraries paths list.
%%
%%-----------------------------------------------------------------------------
%% Beginning of model definition:
%%-----------------------------------------------------------------------------
%%
%% I- Model description.
%%
%% 1- General informations or parameters.
%% -----------------------------------
%%
%% UCM_NAME: Model Unique Name, already assigned
%% UCM_TYPE: Model type (Choice of NetworkElement or CommandBlock)
%% Default: NetworkElement.
%% UCM_CATEGORY: Model category (Breaker, Transformer, etc.)
%% UCM_VERSION: User's model version number (in a string)
%% UCM_EXEC_TIME: Estimated model's average simulation step time.
%% Default: 5.0e-6 s.
%% UCM_DESCRIPTION: Short description of model (one phrase).
%%
%%vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
%% BEGIN GENERAL INFORMATION -- Enter or modify general information
```

## Example of UCM definition file

```

%% BEGIN GENERAL INFORMATION
UCM_NAME          = Example
UCM_TYPE          = NetworkElement
UCM_CATEGORY      = User
UCM_VERSION       = "1.0"
UCM_EXEC_TIME     = 5.0e-6
UCM_DESCRIPTION   = "Voltage source with non-linear inductor"
%% END GENERAL INFORMATION

%% BEGIN DOCUMENTATION
Three-phase sine-wave voltage source with:
Programmable amplitude of sine waves
Voltage sources have resistor in series with non-linear inductors at the output
Inductor voltages are rectified and sent out for display
%% END DOCUMENTATION

%% BEGIN TUNABLE PARAMETERS
Rs    "Rs"    Ohm  double 1 0.01 0.0 1.0e12 - "Series resistance"
Lvec  "Lvec"  H    double 9 [1.0 0.60 0.36 0.22 0.13 0.08 0.04 0.03 0.01] 0.0 10.0 - "Inductance values"
Vinc  "Vinc"  V    double 1 500 0.0 1000 - "Voltage increment for inductance index"
Ldim  "Ldim"  -    int    1 9 1 10 - "Number of entries in Lvec"
freq  "freq"  Hz   double 1 60.0 30.0 90.0 - "Source frequency"
%% END TUNABLE PARAMETERS

%% BEGIN CONTROL IOS
A      V  double in  auto - "Voltage amplitude"
IL_a   A  double out auto I "Inductor current, phase a"
IL_b   A  double out auto I "Inductor current, phase b"
IL_c   A  double out auto I "Inductor current, phase c"
VLrec  V  double out auto - "Rectified inductor voltage"
Ind    -  int    out auto - "Current index in Lvec"
%% END CONTROL IOS

%% BEGIN NODES DEFINITIONS
NE 3 extern top yes "Network connection"
NI 3 intern -   yes "Internal node"
%% END NODES DEFINITIONS

%% BEGIN CURRENT SOURCES
Isrc_a NI_a ground
Isrc_b NI_b ground
Isrc_c NI_c ground
%% END CURRENT SOURCES

%% BEGIN HISTORICAL CURRENT
Ihist_a NE_a NI_a
Ihist_b NE_b NI_b
Ihist_c NE_c NI_c
%% END HISTORICAL CURRENTS

%% BEGIN CALCULATED PARAMETERS
GaddVec  -  double 9 "Additional conductance values"
Lchanged -  int    1 "Inductance index changed flag"
Lindex   -  int    1 "Current inductance index"
omega    -  double 1 "Angular frequency"
period   -  double 1 "Signal period"
%% END CALCULATED PARAMETERS

%% BEGIN PREPARATORY GLOBAL CODE
#include <stdio.h>
%% END PREPARATORY GLOBAL CODE

%% BEGIN PREPARATION FUNCTION CODE
int i, j;
double GLo, Lo, Gs;
printf("********** ucm_Exemple_prep: Rs = %f *******************\n", Rs);
/* Initialize Yini and Yfill to 0 */
for (i = 0; i < 6; i++)
{
    for (j = 0; j < 6; j++)
    {
        ucmYini(i,j) = 0.0;
        ucmYfill(i,j) = 0;
    }
}
/* Compute Yini and Yfill */
Lo = Lvec[0];
GLo = ucmTimeStep / (2.0 * Lo);
Gs = 1.0 / Rs;
/* Diagonal terms for internal node NI */
ucmYini(NI_a, NI_a) = Gs + GLo;
ucmYini(NI_b, NI_b) = Gs + GLo;
ucmYini(NI_c, NI_c) = Gs + GLo;
ucmYfill(NI_a, NI_a) = 1;
ucmYfill(NI_b, NI_b) = 1;
ucmYfill(NI_c, NI_c) = 1;
/* Coupling between NI and NE */
ucmYini(NI_a, NE_a) = -GLo;
ucmYini(NE_a, NI_a) = -GLo;
ucmYini(NI_b, NE_b) = -GLo;
ucmYini(NE_b, NI_b) = -GLo;
ucmYini(NI_c, NE_c) = -GLo;
ucmYini(NE_c, NI_c) = -GLo;
ucmYfill(NI_a, NE_a) = 1;
ucmYfill(NE_a, NI_a) = 1;
ucmYfill(NI_b, NE_b) = 1;
ucmYfill(NE_b, NI_b) = 1;
ucmYfill(NI_c, NE_c) = 1;
ucmYfill(NE_c, NI_c) = 1;
/* Diagonal terms for external node NE */
ucmYini(NE_a, NE_a) = GLo;
ucmYini(NE_b, NE_b) = GLo;
ucmYini(NE_c, NE_c) = GLo;
ucmYfill(NE_a, NE_a) = 1;
ucmYfill(NE_b, NE_b) = 1;
ucmYfill(NE_c, NE_c) = 1;
/* Compute GaddVec */
for (i = 0; i < Ldim; i++)
{
    GaddVec[i] = (ucmTimeStep / (2.0 * Lvec[i])) - GLo;
}
/* Compute other parameters */
omega = 2.0 * 3.141593 * freq;
period = 1.0 / freq;
%% END PREPARATION FUNCTION CODE

%% BEGIN PREPARATORY INCLUDES PATHS LIST
UCM_PREP_INCLUDES_PATHS =
%% END PREPARATORY INCLUDES PATHS LIST

%% BEGIN PREPARATORY DEPENDANT LIBRARIES LIST
UCM_PREP_DEP_LIBS_PATHNAMES =
%% END PREPARATORY DEPENDANT LIBRARIES LIST

%% BEGIN PREPARATORY LIBRARIES LIST
UCM_PREP_LIBRARIES =
%% END PREPARATORY LIBRARIES LIST

%% BEGIN HISTORICAL VALUES
time double 1 0.0 "Simulation time"
%% END HISTORICAL VALUES


%% BEGIN SIMULATION GLOBAL CODE
#include <math.h>
%% END SIMULATION GLOBAL CODE

%% BEGIN SIMULATION INITIALIZATION FUNCTION CODE
time = 0.0;
Lindex = 0;
Lchanged = 0;
%% END SIMULATION INITIALIZATION FUNCTION CODE

%% BEGIN BEFORE VOLTAGE CALCULATION CODE
int i;
double Vsrc_a, Vsrc_b, Vsrc_c;
double TwoPiOver3 = 2.094395333; /* 2*pi/3 */
/* Calculate source currents */
Vsrc_a = A * sin(omega * time);
Vsrc_b = A * sin(omega * time - TwoPiOver3);
Vsrc_c = A * sin(omega * time + TwoPiOver3);
Isrc_a = Vsrc_a / Rs;
Isrc_b = Vsrc_b / Rs;
Isrc_c = Vsrc_c / Rs;
/* Reset node changed flags */
for (i = 0; i < 6; i++)
{
    ucmNodeChanged(i) = 0;
}

/* Update Yadd if the nonlinear inductance operating point changed */
if (Lchanged)
{
    ucmYadd(NI_a, NI_a) =  GaddVec[Lindex];
    ucmYadd(NI_a, NE_a) = -GaddVec[Lindex];
    ucmYadd(NE_a, NI_a) = -GaddVec[Lindex];
    ucmYadd(NE_a, NE_a) =  GaddVec[Lindex];
    ucmYadd(NI_b, NI_b) =  GaddVec[Lindex];
    ucmYadd(NI_b, NE_b) = -GaddVec[Lindex];
    ucmYadd(NE_b, NI_b) = -GaddVec[Lindex];
    ucmYadd(NE_b, NE_b) =  GaddVec[Lindex];
    ucmYadd(NI_c, NI_c) =  GaddVec[Lindex];
    ucmYadd(NI_c, NE_c) = -GaddVec[Lindex];
    ucmYadd(NE_c, NI_c) = -GaddVec[Lindex];
    ucmYadd(NE_c, NE_c) =  GaddVec[Lindex];
    /* Indicate affected nodes */
    ucmNodeChanged(NI_a) = 1;
    ucmNodeChanged(NE_a) = 1;
    ucmNodeChanged(NI_b) = 1;
    ucmNodeChanged(NE_b) = 1;
    ucmNodeChanged(NI_c) = 1;
    ucmNodeChanged(NE_c) = 1;
}
%% END BEFORE VOLTAGE CALCULATION CODE

%% BEGIN AFTER VOLTAGE CALCULATION CODE
double Lo, GLo, GL;
double VL_a, VL_b, VL_c;
int index;
/* Calculate historic currents */
Lo = Lvec[0];
GLo = ucmTimeStep / (2.0 * Lo);
GL = GLo + GaddVec[Lindex];
VL_a = ucmVNode(NI_a) - ucmVNode(NE_a);
IL_a = VL_a * GL + Ihist_a;
Ihist_a = IL_a + VL_a * GL;
VL_b = ucmVNode(NI_b) - ucmVNode(NE_b);
IL_b = VL_b * GL + Ihist_b;
Ihist_b = IL_b + VL_b * GL;
VL_c = ucmVNode(NI_c) - ucmVNode(NE_c);
IL_c = VL_c * GL + Ihist_c;
Ihist_c = IL_c + VL_c * GL;
/* Compute rectified three-phase inductor voltage */
VLrec = fabs(VL_a);
if (VLrec < fabs(VL_b))
{
    VLrec = fabs(VL_b);
}
if (VLrec < fabs(VL_c))
{
    VLrec = fabs(VL_c);
}
/* Determine new operating point */
Lchanged = 0;
index = (int)(VLrec / Vinc);
if (index > Ldim - 1)
{
    index = Ldim - 1;
}
if (index < 0)
{
    index = 0;
}
if (index != Lindex)
{
    Lindex = index;
    Lchanged = 1;
}
Ind = Lindex;
/* Advance time */
time += ucmTimeStep;
if (time >= period)
{
    time -= period;
}
%% END AFTER VOLTAGE CALCULATION CODE

%% BEGIN SIMULATION INCLUDES PATHS LIST
UCM_SIMULATION_INCLUDES_PATHS =
%% END SIMULATION INCLUDES PATHS LIST

%% BEGIN SIMULATION DEP LIBS LIST
UCM_SIMULATION_DEP_LIBS_PATHNAMES =
%% END SIMULATION DEP LIBS LIST

%% BEGIN SIMULATION LIBRARIES LIST
UCM_SIMULATION_LIBRARIES =
%% END SIMULATION LIBRARIES LIST
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/import-models-from-external-software-or-code/create-user-coded-models-ucm/build-ucm-with-definition-file/ucm-definition-file-example.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
