Local UDF¶
Introduction¶
A local UDF is calculated on a voxel-by-voxel and/or particle-by-particle basis across the entire simulation domain. This type of UDF is evaluated at each voxel or particle during every simulation time step (or at specific intervals) and produces outputs or actions that influence localized properties or behaviors within the system.
Examples of Local UDFs include:
Custom fluid rheology dependent on local fluid strain
Aqueous reactions governed by local species concentrations
Custom mass transfer relationships based on local fluid/particle concentration
Local UDFs are also used to define custom variables for particles, fluids, and solid bodies. Beyond these examples, local UDFs offer extensive flexibility to model highly specific, localized phenomena and implement advanced physics tailored to the problem at hand.
Input Variables¶
The Input Variables Panel within the Local UDF Editor lists the variables available for use in each Local UDF. These variables depend on the specific context and application of the UDF. All Local UDFs can utilize global variables, global constants, lookup tables, and the current time as expression inputs.
A voxel-based Local UDF operates on properties of individual fluid voxels within the computational domain. It can access voxel-specific fluid properties (e.g., local velocity, pressure, strain, viscosity, species concentrations, and temperature). Additionally, voxel-based Local UDFs can be functions of voxel position within the lattice and its proximity to solid surfaces.
A particle-based Local UDF is applied to individual particles within a particle set rather than to specific voxels. As a result, its input variables include particle-specific properties, such as position, velocity, diameter, species concentrations, and temperature. Particle-based UDFs can also dynamically retrieve and evoke the fluid properties immediately surrounding the particle (e.g., velocity, pressure, strain, viscosity, species concentrations, and temperature). The particle UDF determines the relevant fluid properties at runtime, based on the particle’s position within the domain. This means that when a particle UDF invokes a local fluid property, it is accessing the fluid conditions directly around the particle at that moment. Particle UDFs can account for proximity to solid surfaces and event-driven properties, such as the time since the last particle-particle breakup, collision, or coalescence event (when relevant).
Output Variables¶
The Output Variables Panel in the Local UDF Editor lists the variables expected to be assigned within the Local UDF. The user defines the logic that determines how these pre-defined output variables are assigned values during execution. This panel specifies the variable name, data type, expected units, and usage. In most cases, the output variable name reflects the underlying physics of the Local UDF. In several cases, the name of the output variable is related to the dynamic name of the object within the model tree. In the index below, the dynamic output variable names are identified by curly brackets {}.
Note
The output variable name for Local UDFs associated with particles are always appended by a _p, implying that the UDF is evaluated on a per particle basis.
Input and Output Variable Types¶
Declaring and understanding the basic variable types in the System UDF is necessary. The fundamental variable types are float, int, and bool. 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 \(+/- 1.18 \times 10^{-38}\) to \(+/-3.4 \times 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; for instance, ending the simulation when a specific condition is achieved. 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 double precision mode.
Local UDF Expression Index¶
The following System UDF variables are available. The table lists the name of the UDF and the location. The location refers to the path of selections which start in the model tree and continue through the property grid to arrive at the desired UDF.
Built-in Functions¶
The following is a list of the built-in functions available for Local Variable UDFs.
float powf(float x, float y) |
Evaluate power of x raised to the y power |
float acosf (float x) |
Calculate the arc cosine of the input argument. |
float acoshf (float x) |
Calculate the nonnegative arc hyperbolic cosine of the input argument. |
float asinf (float x) |
Calculate the arc sine of the input argument. |
float asinhf (float x) |
Calculate the arc hyperbolic sine of the input argument. |
float atan2f (float y, float x) |
Calculate the arc tangent of the ratio of first and second input arguments. |
float atanf (float x) |
Calculate the arc tangent of the input argument. |
float atanhf (float x) |
Calculate the arc hyperbolic tangent of the input argument. |
float cbrtf (float x) |
Calculate the cube root of the input argument. |
float ceilf (float x) |
Calculate ceiling of the input argument. |
float copysignf (float x, float y) |
Create value with given magnitude, copying sign of second value. |
float cosf (float x) |
Calculate the cosine of the input argument. |
float coshf (float x) |
Calculate the hyperbolic cosine of the input argument. |
float cospif (float x) |
Calculate the cosine of the input argument x pi. |
float cyl_bessel_i0f (float x) |
Calculate the value of the regular modified cylindrical Bessel function of order 0 for the input argument. |
float cyl_bessel_i1f (float x) |
Calculate the value of the regular modified cylindrical Bessel function of order 1 for the input argument. |
float erfcf (float x) |
Calculate the complementary error function of the input argument. |
float erfcinvf (float y) |
Calculate the inverse complementary error function of the input argument. |
float erfcxf (float x) |
Calculate the scaled complementary error function of the input argument. |
float erff (float x) |
Calculate the error function of the input argument. |
float erfinvf (float y) |
Calculate the inverse error function of the input argument. |
float exp10f (float x) |
Calculate the base 10 exponential of the input argument. |
float exp2f (float x) |
Calculate the base 2 exponential of the input argument. |
float expf (float x) |
Calculate the base e exponential of the input argument. |
float expm1f (float x) |
Calculate the base e exponential of the input argument, minus 1. |
float fabsf (float x) |
Calculate the absolute value of its argument. |
float fdimf (float x, float y) |
Compute the positive difference between x and y. |
float fdividef (float x, float y) |
Divide two ing-point values. |
float floorf (float x ) |
Calculate the largest integer less than or equal to x. |
float fmaf (float x, float y, float z) |
Compute x × y + z as a single operation. |
float fmaxf (float x, float y) |
Determine the maximum numeric value of the arguments. |
float fminf (float x, float y) |
Determine the minimum numeric value of the arguments. |
float fmodf (float x, float y) |
Calculate the ing-point remainder of x / y. |
float frexpf (float x, int* nptr ) |
Extract mantissa and exponent of a ing-point value. |
float hypotf (float x, float y) |
Calculate the square root of the sum of squares of two arguments. |
float ntilogbf (float x ) |
Compute the unbiased integer exponent of the argument. |
bool isfinite (float a) |
Determine whether argument is finite. |
bool isinf (float a) |
Determine whether argument is infinite. |
bool isnan (float a) |
Determine whether argument is a NaN. |
float j0f (float x ) |
Calculate the value of the Bessel function of the first kind of order 0 for the input argument. |
float j1f (float x ) |
Calculate the value of the Bessel function of the first kind of order 1 for the input argument. |
float jnf (int n, float x) |
Calculate the value of the Bessel function of the first kind of order n for the input argument. |
float ldexpf (float x, int exp) |
Multiplies a floating point value arg by the number 2 raised to the exp power. |
float lgammaf (float x) |
Calculate the natural logarithm of the absolute value of the gamma function of the input argument. |
float llrintf (float x) |
Round input to nearest integer value. |
float llroundf (float x) |
Round to nearest integer value. |
float log10f (float x) |
Calculate the base 10 logarithm of the input argument. |
float log1pf (float x) |
Calculate the value of l o g e ( 1 + x ). |
float log2f (float x) |
Calculate the base 2 logarithm of the input argument. |
float logbf (float x) |
Calculate the ing-point representation of the exponent of the input argument. |
float logf (float x) |
Calculate the natural logarithm of the input argument. |
float lrintf (float x) |
Round input to nearest integer value. |
float lroundf (float x) |
Round to nearest integer value. |
float modff (float x, * iptr) |
Break down the input argument into fractional and integral parts. |
float nanf ( const char* tagp) |
Returns nan value. |
float nearbyintf (float x ) |
Round the input argument to the nearest integer. |
float nextafterf (float x, float y) |
Return next representable single-precision ing-point value after argument. |
float norm3df (float a, float b, float c) |
Calculate the square root of the sum of squares of three coordinates of the argument. |
float norm4df (float a, float b, float c, float d) |
Calculate the square root of the sum of squares of four coordinates of the argument. |
float normcdff (float y) |
Calculate the standard normal cumulative distribution function. |
float normcdfinvf (float y) |
Calculate the inverse of the standard normal cumulative distribution function. |
float normf (int dim, const * a) |
Calculate the square root of the sum of squares of any number of coordinates. |
float powf (float x, float y) |
Calculate the value of first argument to the power of second argument. |
float rcbrtf (float x ) |
Calculate reciprocal cube root function. |
float regincbetaf (float a, float b, float x) |
Calculate the cumulative beta probability density function at value x per the shape parameters a and b. |
float remainderf (float x, float y) |
Compute single-precision ing-point remainder. |
float remquof (float x, float y, int* quo) |
Compute single-precision ing-point remainder and part of quotient. |
float rhypotf (float x, float y) |
Calculate one over the square root of the sum of squares of two arguments. |
float rintf (float x ) |
Round input to nearest integer value in ing-point. |
float rnorm3df (float a, float b, float c) |
Calculate one over the square root of the sum of squares of three coordinates of the argument. |
float rnorm4df (float a, float b, float c, float d) |
Calculate one over the square root of the sum of squares of four coordinates of the argument. |
float rnormf (int dim, const* a) |
Calculate the reciprocal of square root of the sum of squares of any number of coordinates. |
float roundf (float x) |
Round to nearest integer value in ing-point. |
float rsqrtf (float x) |
Calculate the reciprocal of the square root of the input argument. |
float scalblnf (float x, long int n) |
Scale ing-point input by integer power of two. |
float scalbnf (float x, int n) |
Scale ing-point input by integer power of two. |
float signbit (float a) |
Return the sign bit of the input. |
float sincosf (float x, * sptr, * cptr) |
Calculate the sine and cosine of the first input argument. |
float sincospif (float x, * sptr, * cptr) |
Calculate the sine and cosine of the first input argument x pi. |
float sinf (float x) |
Calculate the sine of the input argument. |
float sinhf (float x) |
Calculate the hyperbolic sine of the input argument. |
float sinpif (float x) |
Calculate the sine of the input argument x pi. |
float sqrtf (float x) |
Calculate the square root of the input argument. |
float tanf (float x) |
Calculate the tangent of the input argument. |
float tanhf (float x) |
Calculate the hyperbolic tangent of the input argument. |
float tgammaf (float x) |
Calculate the gamma function of the input argument. |
float truncf (float x) |
Truncate input argument to the integral part. |
float y0f (float x) |
Calculate the value of the Bessel function of the second kind of order 0 for the input argument. |
float y1f (float x) |
Calculate the value of the Bessel function of the second kind of order 1 for the input argument. |
float ynf ( int n, float x) |
Calculate the value of the Bessel function of the second kind of order n for the input argument. |
float printf(const char* format, …) |
Prints formatted output from a kernel to a host-side output stream. |