> 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/protect-code-and-ip-in-ucm.md).

# Protect Code & IP in UCM

## Introduction

This page explains how to **protect intellectual property (IP) in User Code Models (UCM)** by encapsulating model implementations into external libraries on both **Windows and Linux platforms**.

As more users develop and validate models in the Windows version of HYPERSIM, there is an increasing need to **build libraries on Windows targets** in order to verify models offline while keeping the source code hidden. In this context, it is important to understand how to generate and reference libraries using the HYPERSIM toolchain.

On **Windows**:

* The variable **`{HYPERSIM_DIR}`** refers to the HYPERSIM installation directory (for example:\
  `C:\OPAL-RT\HYPERSIM\hypersim_R6.0.XX.oYYY`)
* The variable **`{TOOLS_MINGW}`** refers to the MinGW toolchain directory (for example:\
  `C:\OPAL-RT\HYPERSIM\tools\MinGW\X.X.X`)
* Library paths are **absolute**, meaning that if a library is moved or the model is used on another machine, the paths in the `.def` file must be updated accordingly
* While paths can be manually updated in configuration files, a more convenient approach is to create a **symbolic link** on the workstation
* This symbolic link reproduces the original library path, allowing the model to function without modifying the `.def` file

On **Linux**:

* UCM models can also use **static or dynamic libraries** to hide proprietary code
* When a model is delivered to another user, the original library path from the developer’s system may not exist on the simulator
*

Overall, this page provides guidance on how to **package UCM implementations into reusable libraries across platforms**, ensuring that models can be shared and executed while protecting proprietary code.

## Hide IP for Windows targets <a href="#using-a-dynamic-or-static-library-to-hide-intellectual-property-in-the-user-coded-model-windows-targ" id="using-a-dynamic-or-static-library-to-hide-intellectual-property-in-the-user-coded-model-windows-targ"></a>

### Generating a .dll dynamic library for Windows <a href="#win-generating-a-.dll-library" id="win-generating-a-.dll-library"></a>

1. Open a command-line window and go to the directory where your C code is located
2. Generate the `.o` file by replacing 'test' with your filename: `{TOOLS_MINGW}/bin/gcc -c test.c -o test.o`
3. Generate the `.dll` file using the following command.
4. **By convention, the `DLL` file should be `lib{name of your lib}.dll`**.
5. In this case the library name is test. The `.lib` file name is `{TOOLS_MINGW}/bin/gcc -shared -o libtest.dll test.o`
6. Add the path of the library to the UCM
7. Open the def file and complete the following line: `UCM_SIMULATION_LIBRARIES_WINDOWS = -L{Path to your lib} –l{name of your lib} *without extension*`

**NOTE: the path is entered using / instead of \\**

Example where {Path to your lib} = `C:/Users/user_name/test_code/ and {name of your lib}`

```
=libtest.dll:
UCM_SIMULATION_LIBRARIES_WINDOWS = -LC:/Users/user_name/test_code/ -llibtest
```

{% hint style="danger" %}
Paths provided here must not contain any white space characters.
{% endhint %}

8. Then in the **Definitions** section, add the function you want to import. In this case, the function is myFunc

```
/* 9.3.2 -- Definitions * #ifdef  cplusplus extern "C" {
#endif
int myFunc(int); #ifdef cplusplus
}
#endif
```

9. Now you can use your functions in the UCM. Example :

```
%% BEGIN AFTER VOLTAGE CALCULATION -- Enter code ->...
out12 = myFunc(in12);
```

10. The last step is to make sure your `.dll` library is in Windows paths. There are two options:
    * The **first option** is to add the `.dll` to HYPERSIM’s library path `{HYPERSIM_DIR}\Windows\bin`.
    * The **second option** is by adding the `.dll` directory to the Windows. Open **Environment Variables**, in **User variables**, click **Path** (you can also edit system variables if you are the administrator of your computer). Click **Edit** then add the path of your library in the **Variable value**:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-69750c02e37bcde87c6f304602413b18b13fe836%2Fucm-user-variables.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-99faab43e892bb134a19799149cf6cafb93e8eb7%2Fucm-path-variable-value.png?alt=media" alt=""><figcaption></figcaption></figure>

### Generating a .lib static library for Windows <a href="#win-generating-a-.lib" id="win-generating-a-.lib"></a>

1. Open a command-line window and go to the directory where your C code resides
2. Generate the `.o` file by replacing test with your filename: `{TOOLS_MINGW}\bin\gcc -c test.c -o test.o`
3. Generate the lib file using the following, replacing libtest and test as required `{TOOLS_MINGW}\bin\ar -rcs libtest.lib test.o`
4. Add the path of the library to the UCM.
5. Open the def file and complete the following line: `UCM_SIMULATION_LIBRARIES_WINDOWS = {Path to your lib}/{name of your lib}.lib`

**NOTE: the path is entered using / instead of \\**

Example where {Path to your lib} = `C:/Users/user_name/test_code/ and {name of your lib}`

```
=libtest.dll:
UCM_SIMULATION_LIBRARIES_WINDOWS = -LC:/Users/user_name/test_code/ -llibtest
```

{% hint style="danger" %}
Paths provided here must not contain any white space characters.
{% endhint %}

6. Then in the **Definitions** section, add the function you want to import. In this case the function is myFunc :

```
/* 9.3.2 -- Definitions * #ifdef  cplusplus extern "C" {
#endif
int myFunc(int); #ifdef cplusplus
}
#endif
```

7. Now you can use your functions in the UCM. Example :

```
%% BEGIN AFTER VOLTAGE CALCULATION -- Enter code ->...
out12 = myFunc(in12);
```

## Hide IP for Linux targets <a href="#linux-target-using-a-dynamic-static-library-to-hide-ip-addresses-in-the-user-coded-model" id="linux-target-using-a-dynamic-static-library-to-hide-ip-addresses-in-the-user-coded-model"></a>

Get the C and head file ready. The C file contains the intellectual property, and the head file calls the function in the C file. For example, the C code below contains an add function which we want to hide.

**C file**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b4a8d9239ee0821042676d2c63ec767e805e0293%2Fucm-c-file.png?alt=media" alt=""><figcaption></figcaption></figure>

**Head file**

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-5398cc041ec9ffd7398082ae24accc2d2988b704%2Fucm-head-file.png?alt=media" alt=""><figcaption></figcaption></figure>

### Generate the objective, dynamic library, and static library files <a href="#linux-generate-an-objective-file-dynamic-library-and-static-library-file" id="linux-generate-an-objective-file-dynamic-library-and-static-library-file"></a>

1. Create a folder in your Linux workspace, and drag the C and Head file into it via MobaXterm

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-04fbbc69642a57d1b5da1350daf9a4eaed57500f%2Fucm-create-folder.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Change the path to the directory where the C and Head file exist

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-4abd6e75e31891f6b18e0bfc0b0f1a7a95e73efe%2Fucm-change-path.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Type command: `gcc -c %file_name%.c` (replace `%file_name%` by the C file name) to get the `.o` objective file:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-994d4f3fb715278ee736ffe1a70e578edccaffaf%2Fucm-command-objective-file.png?alt=media" alt=""><figcaption></figcaption></figure>

* To get a dynamic library, type command `gcc -shared -o %dynamic_library_file%.so %objective_file_name%.o` (replace `%dynamic_library_file%` by the name of the dynamic library file and `%objective_file_name%` by the name of the objective file just created)

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c69c7f25bfa809c8648adfb170423f9adf8cd67e%2Fucm-command-dynamic-library.png?alt=media" alt=""><figcaption></figcaption></figure>

* To get a static library, type command `ar rcs %static_library_file%.a %objective_file_name%.o` (replace `%static_library_file%` by the name of the static library file and `%objective_file_name%` by the name of the objective file just created)

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a58f6d4e36b02efd0b1de81333986d7e02c3f281%2Fucm-command-static-library.png?alt=media" alt=""><figcaption></figcaption></figure>

### Create and complete in the UCM template <a href="#linux-create-and-complete-in-the-ucm-template" id="linux-create-and-complete-in-the-ucm-template"></a>

Type ucm any\_name at the Linux command line to create a template.

## Complete 3.1 General parameters table <a href="#complete-3.1-general-parameters-table" id="complete-3.1-general-parameters-table"></a>

* In this case, choose double data type, 2 parameters whose default values are 0.0, minimal value is 0.0 and maximal value is 1.0e-12.
* A detailed explanation can be found on the template.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0391aa1adee8767d5039dd57cccaa9e5267f472a%2Fucm-command-3.png?alt=media" alt=""><figcaption></figcaption></figure>

## Complete 4 Control IOs <a href="#complete-4-control-ios" id="complete-4-control-ios"></a>

* In this case, choose to have two inputs "X1" and "X2" on the left side to receive double format data, and one output "Y" on the right side to send double format data.
* A detailed explanation can be found on the template.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-e75ec97c034458bd51670cdb0b9baf814b274dfa%2Fucm-command-4.png?alt=media" alt=""><figcaption></figcaption></figure>

## Complete 9.3.1 User includes <a href="#complete-9.3.1-user-includes" id="complete-9.3.1-user-includes"></a>

This is to ensure the head file can be correctly called and interpreted by various compilers.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0fe0a419ee93ff96fa892b40f56a56090dcbd269%2Fucm-command-9.png?alt=media" alt=""><figcaption></figcaption></figure>

## Complete 9.6 After nodes voltage calculation function <a href="#complete-9.6-after-nodes-voltage-calculation-function" id="complete-9.6-after-nodes-voltage-calculation-function"></a>

This is to call the add2user function from the head file. The X1 and X2 are two inputs we defined in step 3c, and M\[0] and M\[1] are two parameters we defined.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7513788fa5449bcb0ae381c3b4b4d09237310e50%2Fucm-command-9-6.png?alt=media" alt=""><figcaption></figcaption></figure>

## Complete 9.7 Includes paths <a href="#complete-9.7-includes-paths" id="complete-9.7-includes-paths"></a>

`/home/hypusr01/HyWorkspace/Fei_workspace/UCM_handson/` is where the head file and library files locate.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-abc28ca5d706c180305225f6f94390f193985e61%2Fucm-command-9-7.png?alt=media" alt=""><figcaption></figcaption></figure>

## File 9.9 Libraries required by the simulation <a href="#file-9.9-libraries-required-by-the-simulation" id="file-9.9-libraries-required-by-the-simulation"></a>

* To use a dynamic library, we need to put the path of the dynamic file as below:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-731d6015d1955d7ca430af470baef0736c598f18%2Fucm-command-9-9.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Paths provided here must not contain any white space characters.
{% endhint %}

* To use a static library, we need to put the path of the static file as below:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-741453bee42043aa81080ad1b7ac32c8828c49fc%2Fucm-command-9-9-static.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
Paths provided here must not contain any white space characters.
{% endhint %}

Save and quit the template. You should see a message indicating that the UCM def file is successfully compiled:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-beb2e3279bc280c822288c800da6cf8672dbab30%2Fusm-command-save.png?alt=media" alt=""><figcaption></figcaption></figure>

### Run HYPERSIM simulation <a href="#run-hypersim-simulation" id="run-hypersim-simulation"></a>

1. Remove the C code from the directory since we want to hide it
2. Open HYPERSIM, and get a UCM block and browse to the UCM we just generated
3. Get two inputs and run the simulation
4. In this case, put 1 for both of the inputs, and a sensor is added at Y.
5. Check the result.

### Create a relative link with a symbolic link <a href="#creating-a-relative-link-with-a-symbolic-link" id="creating-a-relative-link-with-a-symbolic-link"></a>

Create a UCM with head and library file to hide the C code. Make sure this model is running well. I am taking the add function with dynamic library example we did

This is the developer’s path, so put it on `/home/hypusr01/developer_path/`

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-38ee4c255d5a63837429447a51334cc8ca635ab7%2Fucm-devceloper-path.png?alt=media" alt=""><figcaption></figcaption></figure>

The UCM points to this folder to get the head and library file.

To share the model, transfer the whole folder to `/home/hypusr01/client_path/`

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7dbf49daceb4040a2853193567b7613ca0a751c4%2Fucm-client-path.png?alt=media" alt=""><figcaption></figcaption></figure>

And remove the \<add\_function> from the developer path, since it doesn’t exist on the client computer.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-cbf652fa73f826c468a550373cf01b950fba210d%2Fucm-remove-add-function.png?alt=media" alt=""><figcaption></figcaption></figure>

Now create a symbolic link between the recipient path and the developer path. The symbolic path doesn’t necessarily exist when creating this link.

`ln –s /home/hypuser01/client_path/add_function/ /home/hypusr01/developer_path/add_function/`

Please note the symbolic path only allows one level of fake directory.

* In this case, `/home/hypusr01/developer_path/` exists, but `/home/hypusr01/developer_path/add_function/` doesn’t exist, so `.../add_function/` directory is the one-level fake directory here, so it is ok.
* If you link client path to `/home/hypusr01/developer_path/add_function/another_diretory`, it won’t work, since `.../add_fuction/another_directory/` gives a two level fake directory, which is not allowed in symbolic link.

Now open the model from the client path

Even though this UCM still locates to the developer\_path, but since we link the developer\_path to the client path, it will be able to find the library and head file.

As a result, you can run the simulation correctly without having the developer path.

Symbolic link description can be found at <https://en.wikipedia.org/wiki/Symbolic_link>


---

# 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/protect-code-and-ip-in-ucm.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.
