How to write a thermal plugin in Simcenter 3D

What is a thermal plugin?

A thermal plugin is a collection of functions compiled into a DLL file, executed during the simulation run to modify how the thermal solver computes results. These functions may include heat transfer correlations, windage correlations, and other utilities relevant to your design space.

For example, consider a function that returns the heat transfer coefficient based on mass flow, flow area, and length, such as HTC (M, A, L). With such a function, you could access parameters like fluid temperature and density during the simulation to calculate values useful for your correlations used by the thermal solver at run-time.

To begin the process of programming and using a plugin function in Simcenter 3D:

Define the variables in your correlation using the solver predefined API methods.
Translate the correlation into a function written in the C++ programming language, using any text editor and save the source code file with a .cpp extension in your working folder.
Compile the source code for your plugin function using the scripts to generate a DLL file for Windows or an SO file for Linux.
Load the plugin function in Simcenter 3D. Functions defined in a plugin are used directly as expressions.
Specify a plugin function in the boundary condition.
Run the simulation. The thermal solver evaluates the plugin functions for each boundary condition element or node at run-time and applies the resulting value to the specified property.

Advantages of a thermal plugin

A thermal plugin allows you to:

Develop your own boundary condition correlations.
Use the material properties to define the correlations.
Include complex custom expressions and access solver variables.
Keep your correlations confidential.
Simplify your model inputs and minimize the complexity of expressions.
Reduce the risk of user input errors.

Writing a plugin function

To write a plugin function you use predefined API methods that are supported by Simcenter 3D and the thermal solver which allow you to access:

Unit system of the solution, element areas, radius, thickness, and coordinates of element centroid.
Elemental and boundary conditions data during the solve, such as element rotational speed, upstream mass flow rate and fluid temperature, generic entity data.
Material properties such as density, enthalpy, thermal conductivity, specific heat, dynamic viscosity, Young's modulus, Poisson ratio, and thermal expansion coefficient.
Current iteration count or time step of a transient solution.

For the list of API methods, see Simcenter 3D method definitions and Thermal solver method definitions in the Thermal solver API guide.

To get familiar with the structure and syntax, open and inspect the ExpressionsPlugin.cpp source file in the <Simcenter 3D or NX path>\nxcae_extras\tmg\plugin_examples\thermal_solver\ExpressionsVS2019\ExpressionsPlugin folder.

The following are detailed steps to write a plugin:

Include the header file directive in your source code file that contains declarations for the API methods. This allows the compiler to recognize the types, function signatures, and class structures your code interacts with, ensuring it compiles correctly.
```
#include <CaeUtils_Exp_IMaterial.hxx>
#include <CaeUtils_Exp_IContext.hxx>
#include <CaeUtils_Exp_IScalarValue.hxx>
#include <CaeUtils_Exp_ITableValue.hxx>
#include <CaeUtils_Exp_IFieldValue.hxx>
#include <CaeUtils_Exp_IReturnValue.hxx>
#include <CaeUtils_Exp_IFunctionDefinition.hxx>
#include <CaeUtils_Exp_IRegistrar.hxx>
#include <CaeUtils_Exp_PluginVersion.hxx>
```
The context and material properties
```
#include <CaeUtils_Exp_IMaterial.hxx>
#include <CaeUtils_Exp_IContext.hxx>
```
are key concepts of user-defined plugin functions that are in <Simcenter 3D or NX path>\ugstructures\evalplugin\src\.
The thermal solver receives the following data from context:
- Unit system used in the simulation.
- Current time and elemental IDs.
- Elemental properties during the solution time:
  - X, Y, Z coordinates of the element center
  - Normals to the element
  - Rotational speed
  - Radius
  - Temperature
  - Material
Material refers to the solid and fluid material used in the context.

Initialize your plugin function. To load a plugin function:

The thermal solver calls the Initialize function:

extern "C" __declspec(dllexport) void Initialize(UGS::CaeUtils::Exp::IRegistrar* pReg)
{
    AddFunctions(pReg);
}

Simcenter 3D calls the Initialize_Versioned function:

extern "C" __declspec(dllexport) void
Initialize_Versioned(UGS::CaeUtils::Exp::IRegistrar* pReg, int nVersionNumber)
{
    AddFunctions(pReg);
}

Define a plugin function using the API methods supported by Simcenter 3D. You can:
- Access the context objects, such as material fluid or solid temperature.
```
const IMaterial* pMaterial = pContext->GetFluidMaterial();
bool boolResult = pContext->GetFluidTemp(&fluidTemperature);
```
- Access the material properties from context object, such as fluid viscosity, density, and conductivity.
```
 double fluidConductivity = pMaterial->GetThermalConductivity(fluidTemperature,
                                    fluidPressure);
```
- Write the mathematical function, using context and material inputs.
```
double prandtlNumber = fluidViscosity * fluidSpecificHeat / fluidConductivity;
        result = prandtlNumber * fluidConductivity / (time + 1e-6);
```
Register a plugin function using the AddFunction method.
```
void AddHTCCustom(IRegistrar* pReg)
{
        Measure meas;
        meas.Set(1, 0, -3, 0, 0, 0, -1, 0, 0);
        IFunctionDefinition* pFunc = pReg>AddFunction("HTCCustom",
            "Return heat transfer coefficient from a free disc with turbulent flow",
            meas,
            TYP_DBL,
            "Heat transfer coefficient",
            &HTCCustom);
}
```
This method is used to register a function pointer with the expression. It returns an IFunctionDefinition interface that allows you to define any arguments this function requires. When you add your plugin function, you must specify the unit dimensions,
```
Measure meas;
        meas.Set(1, 0, -3, 0, 0, 0, -1, 0, 0)
```
of the physical quantity
```
"Heat transfer coefficient"
```
that is returned by your function, and for any arguments used by your function. Notice that "HTCCustom" is a name of the function that is used in Simcenter 3D.
Add your plugin function to the structure of the source code using the following function:
```
void AddFunctions(IRegistrar* pReg)
    {
        AddHTCCustom(pReg);
    }
```

The source code is ready for compilation.

Compiling a thermal plugin

You can compile a thermal plugin using Visual Studio in Windows or using a command line in Windows or Linux with the appropriate compiler. For the list of supported compilers of the latest version, see Supported compilers in the Thermal solver API guide.

Using Visual Studio in Windows

The advantage of using Visual Studio is that it provides access to all your files within a single interface, eliminating the need to manually open individual text files from a folder.

To compile a thermal plugin in Visual Studio:

Set UGII_BASE_DIR environment variable to point to the installation directory of Simcenter 3D.
Browse to your installation directory and locate the following folder: <Simcenter 3D or NX path>\nxcae_extras\tmg\plugin_examples\thermal_solver\ExpressionsVS2019
Copy the entire folder to a location where you have write access.
In Visual Studio, open the Expressions.sln file in the first level directory.
Compile the code using Build > Build Solution. This will generate the DLL file that you can reference in Simcenter 3D.

Using a command line in Windows or Linux

This approach is the same, whether you are working in Windows or in Linux. Only the build file used is different:

For Windows, use build_windows.cmd.
For Linux, use build_linux.com.

To compile a thermal plugin with a build script:

Set the UGII_BASE_DIR environment variable to point to the installation directory of Simcenter 3D.
Browse to your installation directory and locate the following folder: <Simcenter 3D or NX path>\nxcae_extras\tmg\plugin_examples\thermal_solver\ExpressionsShell
Copy the entire folder to a location where you have write access.
Execute the build file. This will generate the DLL file for Windows and the SO file for Linux that you can then reference in Simcenter 3D.

Referencing a thermal plugin

On Windows in Simcenter 3D

Choose File > Utilities > Customer Defaults.
Choose Simulation > Pre/Post > Expressions.
On the Plugin tab, select the Use Custom Plugin check box and define your full path to the DLL file.
Restart your Simcenter 3D session.
Open the simulation file from <Simcenter 3D or NX path>\nxcae_extras\tmg\plugin_examples\thermal_solver\Model\model.sim to test your plugin in it.
Inspect the Thermal Stream (1) boundary condition that references the HTCCustom() function.
Run the model and verify that your plugin is working.

On Linux in the xml file

Edit the xml file in a text editor.

Locate the <CustomerDefaultList>, and set the following:

<CustomerDefaultList>
    <Property name="Custom Plugin Files">
      <Value>path to the SO file</Value>
    </Property>
  </CustomerDefaultList>

Run the xml file.

How do you obtain quantities from the thermal solver?

For example, suppose you want to access the swirl velocity in your plugin or retrieve a material property like thermal conductivity. The following files provide the necessary syntax and function names to obtain various quantities:

AdditionalFunctions.h—various thermal solver quantities such as fluid material name, temperature value from the enthalpy. The file is in the <Simcenter 3D or NX path>\nxcae_extras\tmg\include\maya\expeval_utils directory.
CaeUtils_Exp_Icontext.hxx—NX quantities such as spatial coordinates, time, element and node IDs. The file is in the <Simcenter 3D or NX path>\ugstructures\evalplugin\src directory.
CaeUtils_Exp_Imaterial.hxx—NX material properties such as thermal conductivity. The file is in the <Simcenter 3D or NX path>\ugstructures\evalplugin\src directory.