Function Library¶

Introduction¶

The Function Library is where users define new reusable functions that behave like custom built-in functions for Local UDFs. These functions accept input arguments and perform arbitrary calculations. They typically return output values, but can also be defined as void functions that operate on input values passed by reference. Once defined, a custom function can be invoked within any local UDF. This makes the function library the preferred way to package bespoke correlations, transformations, or proprietary models that need to be reused in multiple places across a simulation. Within a single function library, functions can reference other functions.

The function library is commonly used to (i) encode empirical or semi-empirical correlations that are not available among built-in functions or (ii) capture domain-specific models (for example, a reaction-rate expression, a transport-property correction, or a vendor-specific energy-efficiency factor).

By consolidating these reusable relationships into named functions, the function library keeps models cleaner, more maintainable, and easier to audit, especially when the same correlation appears in many places across a model.

Note

Functions defined in the Function Library are not accessible from System UDFs or Global Scripts.

Property Grid¶

Function Library

The function library is where users define new reusable functions that behave like custom built-in functions for Local UDFs. Launch the Function Library Editor to define the function.

In the example below, we pre-define a custom function that adds random forces to particles to mimic the effects of stochastic Brownian motion. The forcing subroutine defined within the function library is applied across multiple particle sets. The single location for this model reduces duplication errors if modifications to the kernel are made. The purpose of this simulation is to assess the effects of Brownian motion on particle diffusion, as compared to scalar fields and particles with no additional Brownian motion.

Download Sample File: Function Library

Function Library Editor¶

The Function Library Editor is launched by pressing the green edit button () in the property grid.

Components¶

The components of the Function Library Editor are presented below.

Title Bar: This title indicates the window is the Function Library Editor.
Toolbar: These action buttons are used to close the editor and perform a syntax/output check on the UDF. OK saves the code script and closes the form. Cancel closes the form without saving the code script. Check Code performs a syntax check on the UDF script. The result of this syntax check are viewed in the Reporting Log.
Script Editor: This field is where the UDF script is entered. System variable expressions are written in the C-programing language.
Reporting Log: This panel reports the results of the syntax check (Check Code). If syntax error is detected, the error type and location will be listed. These errors must be corrected for the UDF to execute.
Status Bar: This panel identifies the cursor location within the Function Library Editor.
Search Bar: This field is to search for a built-in function. Press enter to execute the search.
Built-in Functions: These are the built-in functions that can be evoked when writing the function.

Function Format¶

Within the Function Library Editor, a notional function is defined as:

float calcAlpha(float tau, float dt){

return dt/tau;

}

float exponentialAveragef(float Current, float Past,
          float timeConstant, float dt){

float alpha = calcAlpha(timeConstant, dt);

float Calc = alpha * Current + (1.0f - alpha) * Past;

return Calc;
}

where the input variables are defined in the function signature and the return variable is the function output. Intermediate variables and calls to built-in math functions are also permitted. Once saved, myFunction (x, y) can be called just like a native built-in function anywhere in the model.

Variable Types¶

The fundamental variable types are float, int, and bool. It is necessary to understand the difference between these variable types to avoid improper rounding or truncation.

A float variable represents continuous physical quantities like velocity and pressure, providing the necessary decimal precision for accurate property representations. This type defines a single precision floating point variable. The values range from \(±10^{−38}\) to \(±10^{38}\), with approximately 7 decimal digits of precision.

An int variable manages discrete aspects, such as mesh indices, iteration counts, and zone IDs. Values range from -2,147,483,648 to 2,147,483,647.

A bool (Boolean) variable implements a conditional logic (true/false), enabling checks and control flow within the UDF—ending the simulation when a specific condition is achieved, for example. Additionally, Boolean operations (e.g., <, >, ==, !=) are used within if statements to compare values and determine the execution path, making these comparisons essential for conditional logic.

UDFs can also contain double precision floating-point variables, which store 14 decimal digits of precision. These double-precision variables should only be used when the code is operating in double precision mode.

Tip

Be careful with how integers and floating-point values interact. Integer division (int/int) always truncates, so if you want a real quotient, you must promote at least one operand to a floating type.
Floating-point numbers cannot represent many decimal values exactly, so avoid testing equality directly. Instead, compare within a small tolerance.

Built-in Functions¶

The built-in functions available for use within the function library are the same as those available for Local UDFs, are based on the C++ Math library. Within a single function library, functions can reference other functions. Functions cannot call or access functions in other function libraries. Lookup tables cannot be evoked within the function library.

Function Library Toolbar¶

Context-Specific Toolbar Options	Description
Help	The Help command launches the M-Star reference documentation in your web browser.

For a full description of each selection on the Context-Specific Toolbar, see Toolbar Selections.