Fluent Software Training

TRN-99-003

User Defined Functions

G1 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Introduction
 What is a User Defined Function?
 A UDF is a routine (programmed by the user) written in C which can be
dynamically linked with the solver.
 Standard C functions
 e.g., trigonometric, exponential, control blocks, do-loops, file i/o, etc.
 Pre-Defined Macros
 Allows access to field variable, material property, and cell geometry data.
 Why build UDF’s?
 Standard interface cannot be programmed to anticipate all needs.
 Customization of boundary conditions, source terms, reaction rates, material
properties, etc.
 Adjust functions (once per iteration)
 Execute on Demand functions
 Solution Initialization

G2 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

UDF Basics
 UDF’s assigns values (e.g., boundary data,
source terms) to individual cells and cell faces
in fluid and boundary zones.
 In a UDF, zones are referred to as threads.
 A looping macro is used to access individual
cells belonging to a thread.
 e.g., a face-loop macro visits 563 faces
on face zone 3 (velocity-inlet).
 Position of each face is available
to calculate and assign spatially
varying properties.
 Thread and variable references are
automatically passed to UDF when
assigned to boundary in GUI.
 Values returned to the solver by UDFs must be in SI units.

G3 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Using UDFs in the Solvers

 The basic steps for using UDFs in FLUENT are as follows:

STEP 1: Create a file containing the UDF source code

STEP 2: Start the solver and read in your case/data files
STEP 3: Interpret or Compile the UDF
STEP 4: Assign the UDF to the appropriate variable and zone in BC panel.
STEP 5: Set the UDF update frequency in the Iterate panel
STEP 6: Run the calculation

G4 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Non-Uniform Inlet Velocity

 A non-uniform inlet velocity is to be imposed on the 2D turbine vane
shown below. The x-velocity variation is to be specified as:

u(y) = 20 [ 1 - (y/0.0745)2]

y=0

G5 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Source Code

 The DEFINE_PROFILE macro allows #include "udf.h"
the function inlet_x_velocity to
DEFINE_PROFILE(inlet_x_velocity, thread, nv)
be defined. {
 All UDFs begin with a DEFINE_ float x[3]; /* this will hold the position
vector*/
macro.
 inlet_x_velocity will be float y;
face_t f;
identifiable in solver GUI.
 thread and nv are dynamic begin_f_loop(f, thread)
{
references, input to the UDF to F_CENTROID(x,f,thread);
identify the zone and variable y = x[1];
F_PROFILE(f, thread, nv) =
being defined, respectively. 20.*(1.- y*y/(.0745*.0745));
}
 The macro begin_f_loop loops end_f_loop(f, thread)
over all faces, f, on thread. }
 The F_CENTROID macro assigns cell position vector to x[].
 The F_PROFILE macro applies the velocity component to face f.

G6 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Interpreting the UDF

 The UDF is saved as velprof.c velocity_profile:
 Define User Defined Functions .local.pointer thread
(r0)
Interpreted…
.local.int position
(r1)
0 .local.end
0 save
.local.int f (r6)
8 push.int 0
10 save
.local.int.
.
.
.
.L1:
 Click Compile 132 restore
 The assembly language code will scroll 133 restore
past window. 134 ret.v

G7 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Activating the UDF

 Access the boundary condition
panel.
 Switch from constant to the UDF
function in the X-Velocity
dropdown list.

G8 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Run the Calculation

 Run the calculation as usual.
 You can change the UDF Profile
Update Interval in the Iterate panel
(here it is set to1).

G9 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Example: Numerical Solution

 The figure at right shows velocity
field throughout turbine blade
passage.
 The bottom figure shows the
velocity vectors at the inlet. Notice
the imposed parabolic profile.

G10 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Macros
 Macros are pre-defined (Fluent) functions:
 Allows definition of UDF functionality and function name ( DEFINE_ macro)
 Allows access to field variables, cell information, looping capabilities, etc.
 Macros are defined in header files.
 The udf.h header file must be included in your source code.
 #include “udf.h”
 The header files must be accessible in your path.
 Typically stored in Fluent.Inc/src/ directory.
 Other “.h” header files may need to be included.
 Depends upon relevant variables and macros needed in your UDF, e.g.,
 mem.h for field variable access
 metric.h for cell geometry data
 dpm.h for DPM variable access

G11 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

DEFINE Macros
 Any UDF you write must begin with a DEFINE macro:
 14 general purpose macros and 10 DPM-related macros (not listed):
DEFINE_ADJUST(name,domain); general purpose UDF called every iteration
DEFINE_INIT(name,domain); UDF used to initialize field variables
DEFINE_ON_DEMAND(name); defines an ‘execute-on-demand’ function
DEFINE_RW_FILE(name,face,thread,index); customize reads/writes to case/data files
DEFINE_PROFILE(name,thread,index); defines boundary profiles
DEFINE_SOURCE(name,cell,thread,dS,index); defines source terms
DEFINE_HEAT_FLUX(name,face,thread,c0,t0,cid,cir); defines heat flux
DEFINE_PROPERTY(name,cell,thread); defines material properties
DEFINE_DIFFUSIVITY(name,cell,thread,index); defines UDS and species diffusivities
DEFINE_UDS_FLUX(name,face,thread,index); defines UDS flux terms
DEFINE_UDS_UNSTEADY(name,face,thread,index); defines UDS transient terms
DEFINE_SR_RATE(name,face,thread,r,mw,yi,rr); defines surface reaction rates
DEFINE_VR_RATE(name,cell,thread,r,mw,yi,rr,rr_t); defines vol. reaction rates
DEFINE_SCAT_PHASE_FUNC(name,cell,face); defines scattering phase function for DOM

G12 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Looping Macros

cell_t c; defines a cell

face_t f; defines a face Specialized variable types
Thread *t; pointer to a thread used for referencing.
Domain *d; pointer to collection of all threads

thread_loop_c(t, d){} loop that steps through all cell threads in domain
thread_loop_f(t, d){} loop that steps through all face threads in domain
begin_c_loop(c, t){} end_c_loop(c, t) loop that steps through all cells in a thread
begin_f_loop(f, t){} end_f_loop(f, t) loop that steps through all faces in a thread

Code enclosed in {} is executed in loop.

G13 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Geometry and Time Macros

C_NNODES(c, t); returns nodes/cell
C_NFACES(c, t); returns faces/cell
F_NNODES(f, t); returns nodes/face
C_CENTROID(x, c, t); returns coordinates of cell centroid in array x[]
F_CENTROID(x, f, t); returns coordinates of face centroid in array x[]
F_AREA(A, f, t); returns area vector in array A[]
C_VOLUME(c, t); returns cell volume
C_VOLUME_2D(c, t); returns cell volume for axisymmetric domain

real flow_time() = RP_Get_Real(“flow-time”); returns actual time

int time_step; returns time step number
RP_Get_Real(“physical-time-step”); returns time step size

G14 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Cell Field Variable Macros

C_R(c,t); density C_DVDZ(c,t); velocity derivative
C_P(c,t); pressure C_DWDX(c,t); velocity derivative
C_U(c,t); u-velocity C_DWDY(c,t); velocity derivative
C_V(c,t); v-velocity C_DWDZ(c,t); velocity derivative
C_W(c,t); w-velocity
C_T(c,t); temperature C_MU_L(c,t); laminar viscosity
C_H(c,t); enthalpy C_MU_T(c,t); turbulent viscosity
C_K(c,t); turbulent KE C_MU_EFF(c,t); effective viscosity
C_D(c,t); tke dissipation C_K_L(c,t); laminar thermal conductivity
C_YI(c,t,i); species mass fraction C_K_T(c,t); turbulent thermal conductivity
C_UDSI(c,t,i); UDS scalars C_K_EFF(c,t); effective thermal conductivity
C_UDMI(c,t,i); UDM scalars C_CP(c,t); specific heat
C_RGAS(c,t); gas constant
C_DUDX(c,t); velocity derivative C_DIFF_L(c,t); laminar species diffusivity
C_DUDY(c,t); velocity derivative C_DIFF_EFF(c,t,i); effective species diffusivity
C_DUDZ(c,t); velocity derivative
C_DVDX(c,t); velocity derivative
C_DVDY(c,t); velocity derivative

G15 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Face Field Variable Macros

 Face field variables are only available when using the segregated
solver.
F_R(f,t); density
F_P(f,t); pressure
F_U(f,t); u-velocity
F_V(f,t); v-velocity
F_W(f,t); w-velocity
F_T(f,t); temperature
F_H(f,t); enthalpy
F_K(f,t); turbulent KE
F_D(f,t); tke dissipation
F_YI(f,t,i); species mass fraction
F_UDSI(f,t,i); UDS scalars
F_UDMI(f,t,i); UDM scalars

G16 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Other UDF Applications

 In addition to defining boundary values, source terms, and material properties,
UDFs can be used for:
 Initialization
 Executes once per initialization.
 Adjust
 Executes every iteration.
 Wall Heat Flux
 defines fluid-side diffusive and radiative wall
heat fluxes in terms of heat transfer coefficients
 applies to all walls
 User Defined Surface and Volumetric Reactions
 Read-Write to/from case and data files
 Read order and Write order must be same.
 Execute-on-Demand capability
 Not accessible during solve

G17 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

User Defined Memory

 User-allocated memory
Define  User-Defined  Memory...
 Up to 500 field variables can be defined.
 Can be accessed by UDFs:
 C_UDMI(cell,thread,index);
 F_UDMI(face,thread,index);
 Can be accessed for post-processing.
 Information is stored in data file.

G18 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

User Defined Scalars

 FLUENT can solve (up to 50) generic transport
equations for User Defined Scalars, k:
k    
  Fi k  k k   Sk k = 1, …, Nscalars
t xi  xi 
 User specifies:
DefineModelsUser-Defined Scalars…
 Number of User-Defined Scalars
 Flux Function, F
 DEFINE_UDS_FLUX(name,face,thread,index)
 DEFINE_UDS_UNSTEADY(name,cell,thread,index,apu,su)
 ‘case’ statement can be used to associate multiple flux and transient functions
with each UDS.
 Example
 Can be used to determine magnetic and/or electric field in a fluid zone.

G19 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

User Defined Scalars (2)

 User must also specify:
 Diffusivity, 
 case statement must be used to
define diffusivities for each UDS.
 Source terms, S
 Boundary Conditions for each UDS.
 Specified Flux or Specified Value.
 Define as constant or with UDF.

G20 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Interpreted vs. Compiled UDF’s

 Functions can either be read in and interpreted at run time (as in the
example) or compiled and grouped into a shared library that is linked
with the standard FLUENT executable.
 Interpreted vs. compiled code
 Interpreter -
 Interpreter is a large program that sits in the computer’s memory.
 Executes code on a “line by line” basis instantaneously
 Advantages - does not need a separate compiler
 Disadvantage - slow and takes up space in memory
 Compiler (refer to User’s Guide for instructions)-
 Code is translated “once” into machine language (object modules).
 Efficient way to run UDF’s. Uses Makefiles
 Creates “shared libraries” which are linked with the rest of the solver
 Overcomes interpreter limitations e.g. mixed mode arithmetic, structure
references etc.

G21 © Fluent Inc. 01/04/22

Fluent Software Training
TRN-99-003

Supporting UDF’s
 Because UDF’s can be very complicated, Fluent Inc. does not
assume responsibility for the accuracy or stability of solutions
obtained using UDFs that are user-generated.
 Support will be limited to guidance related to communication between a
UDF and the FLUENT solver.
 Other aspects of the UDF development process that include conceptual
function design, implementation (writing C code), compilation and
debugging of C source code, execution of the UDF, and function design
verification will remain the responsibility of the UDF author.
 Consulting option

G22 © Fluent Inc. 01/04/22