Working With User Functions

User functions are functions or subroutines that are written in a compiled language such as C, C++ or Fortran.

Each function can request arguments from Simcenter STAR-CCM+ and must return a result consistent with its type. The two principal categories of user functions are:

The most common use of user functions is the specification of profiles of values on regions or boundaries. Examples are initial conditions, boundary conditions, and source terms. User functions which are registered as scalar field functions or vector field functions can also be used in the same applications as field functions, such as visualization. The principal reason for choosing a user function instead of a field function is power: user functions can implement more complex functionality than field functions.

Simcenter STAR-CCM+ also allows specific user functions with fixed argument lists, such as user-coded reaction rates for stiff chemistry solvers.

In order for Simcenter STAR-CCM+ to know which arguments to pass to a user function and what type of result to expect, register the user function using a library registration function. Available user functions can then be viewed in the user library nodes in the User Code node under Tools in the object tree.



The display name for the user function, together with its Type, its Args, and their Sizes, is obtained from the library registration function.

What Are User-Coded Profiles?

A user-coded profile is a profile that is implemented through a user function. Either of the following are possibilities:

  • A boundary profile
  • A region profile

Once a user-coded profile has been compiled and its library is loaded, it is available for use in boundary and region definitions, which are shown in drop-down lists of user functions.

What Are User-Coded Field Functions?

A user-coded field function is a field function that is implemented through a user function. As with all field functions, a user-coded field function can be either of the following:

  • A scalar field function
  • A vector field function

Once a user-coded field function has been compiled and its library is loaded, it is available for use. This availability is the same as with any other field function that is shown in scalar or vector drop-down lists of field functions.

Using User Functions in Parallel Simulations

Every array which is passed into a user function is given a size which depends on the number of relevant entities of the region or boundary on that partition. Depending on the partitioning, some partitions can end up with 0 relevant entities.

Never assume that there is at least one relevant entity present on all partitions. For example, the following code causes a segmentation fault when used in a partition that does not contain any relevant entities:

// This will seg fault if the iter array is sized 0

int currentIteration = iter[0];

What is a Library Registration Function?

Each user library must contain a library registration function, uclib (for C), or uflib (for Fortran). Simcenter STAR-CCM+ calls this function when the user library is first attached. The purpose of calling this function is to:

  • Discover which user functions are contained in the library
  • Determine which arguments they need
  • What type of result they return

Ensure that the library registration functions follow the C template or Fortran template, either by coding in those languages or by replicating their bindings.

Creating a New User Function

Ensure that the user functions follow the C template or Fortran template, either by coding in those languages or by replicating their bindings. For each user function in a library, add code to the library registration function to register it. Simcenter STAR-CCM+ does not impose restrictions on how many user functions can be contained in a source file, nor on the names of the source files. Once a set of user function source files has been completed, together with a library registration function, the next stage is to create a user library from them.

Using User-Coded Reaction Rates

For the reacting species transport models which use non-stiff numerics to calculate species source from reactions (such as the Eddy Break-Up or Eddy Contact Micromixing models), you can use field functions or user-coded field functions to specify arbitrary reactions. However, for combustion models which use an ODE solver to handle numerical stiffness (in particular the Complex Chemistry and Surface Chemistry models), specific user-coded reaction rate functions must be used. These user functions are only for calculating reaction rates—the function signatures are fixed. See Reacting System Properties.