On Windows (See WIN Prefix, below)

• Users may wish to conceal IP when working in the UCM on a Windows target, More and more users build models in the Windows version of HYPERSIM and would like to verify the result offline first.
• In this case, knowing how to create a library on a Windows target becomes necessary. 
• Note that the variable {HYPERSIM_DIR} is in this case the installation directory of HYPERSIM. By default, it should be something like: C:\OPAL-RT\HYPERSIM\hypersim_R6.0.XX.oYYY
• Note that the variable {TOOLS_MINGW} is in this case the installation directory of HYPERSIM. By default, it should be something like C:\OPAL-RT\HYPERSIM\tools\MinGW\X.X.X
• Note that the library paths are absolute. Each time the library file path is changed (it is moved or the simulation is used on another computer), the paths in the .def file must be updated.

On LINUX (See LINUX Prefix, below)

• The UCM feature in HYPERSIM allows users to create customized blocks from their own code. Sometimes the code may involve intellectual property, so they may want to hide the code in a library, and then the UCM template does not expose it.
• This procedure shows a way to use either a dynamic or static library to hide the code in UCM. 
• When developers deliver the HYPERSIM model with the Library in UCM to the client, the path specifying the library file in the developer's computer doesn't exist in the client computer.
• You may modify the configuration file to change the library file path setting, but a more convenient way is to create a symbolic link in the client's computer. This symbolic link emulates the library file path in the developer's computer. 

Using a Dynamic or Static Library to Hide Intellectual Property in the User-Coded Model (Windows Target)

WIN Generating a .dll Library

• Open a command-line window and go to the directory where your C code is located
• Generate the .o file by replacing 'test' below with your filename

{TOOLS_MINGW}/bin/gcc -c test.c -o test.o

• Generate the dll file using the following command.
• By convention, the DLL file should be lib{name of your lib}.dll.
• In this case the library name is test. The .lib file name is

{TOOLS_MINGW}/bin/gcc -shared -o libtest.dll test.o

• Add the path of the library to the UCM
• 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

• 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

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

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

• 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, click User variable Path (you can also edit system variables if you are the administrator of your computer). Then click Edit

• Add the path of your library in the Variable value, by adding a ; (semi-colon) before

WIN Generating a .lib

• Open a command-line window and go to the directory where your C code resides
• Generate the .o file by replacing test with your filename

{TOOLS_MINGW}\bin\gcc -c test.c -o test.o

• Generate the lib file using the following, replacing libtest and test as required

{TOOLS_MINGW}\bin\ar -rcs libtest.lib test.o

• Add the path of the library to the UCM.
• 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.lib:

UCM_SIMULATION_LIBRARIES_WINDOWS = C:/Users/user_name/test_code/libtest.lib

• 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

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

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

LINUX Target: Using a Dynamic/Static Library to Hide IP in the User-Coded Model

• 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

Head file

LINUX Generate an Objective File, Dynamic Library, and Static Library File

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

• Change the path to the directory where the C and Head file exist

• Type command: gcc -c xxx.c (xxx is the C file name). The objective file xxx.o is created

• If you want to use a dynamic library, type command gcc -shared -o xxx.so xxx.o (xxx.so is the name of the dynamic library file, and xxx.o is the objective file you just created)
• The dynamic library xxx.so is created

• If you want to use a static library, type command ar rcs xxx.a xxx.o (xxx.a is the name of the static library file, and xxx.o is the objective file you just created)
• The static library xxx.a is created

LINUX Create and Complete in the UCM template

Type ucm any_name at the Linux command line to create a template.

Complete 3.1 General parameters table

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

Complete 4 Control IOs

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

Complete 9.3.1 User includes

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

Complete 9.6 After nodes voltage calculation function

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.

Complete 9.7 Includes paths

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

File 9.9 Libraries required by the simulation

• If we want to use a dynamic library, we need to put the path of the dynamic file as below.

• If we want to use a static library, we need to put the path of the static file as below.

• Then save and quit the template. You should see a message indicating that the UCM def file is successfully compiled

Run HYPERSIM simulation

• Remove the C code from the directory since we want to hide it
• Open HYPERSIM, and get a UCM block and browse to the UCM we just generated

• Get two inputs and run the simulation
• In this case, put 1 for both of the inputs, and a sensor is added at Y.

• Check the result.

Since Y = add2user(X1+M[0],X2+M[1]); M[0] and [1] are 0, X1 = X2 =1, so Y should be 2.

Creating a Relative Link with a Symbolic Link

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/

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

This model is to be delivered to the client, so I will transfer the whole folder to

/home/hypusr01/client_path/

And remove the <add_function> from the developer path, since it doesn’t exist on the client’s computer.

Now create a symbolic link between the client 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