Chapter 8

User-Defined Functions

Introductory FLUENT
Training

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-1 Inventory #002600
User-Defined Functions
Outline Training Manual

• A brief introduction to FLUENT user-defined functions

• Overview of FLUENT Data Structure and Macros

• Two Examples

• Where to get more information and help

• UDF Support

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-2 Inventory #002600
User-Defined Functions
Introduction Training Manual

• What is a User Defined Function?

– A UDF is a function (programmed by the user) written in C which can be
dynamically linked with the FLUENT solver.
• Standard C functions
– Trigonometric, exponential, control blocks, do-loops, file i/o, etc.
• Pre-Defined Macros
– Allows access to field variable, material property, and cell geometry data and many
utilities

• Why program UDFs?

– Standard interface cannot be programmed to anticipate all needs:
• Customization of boundary conditions, source terms, reaction rates, material
properties, etc.
• Customization of physical models
• User-supplied model equations
• Adjust functions (once per iteration)
• Execute on Demand functions
• Solution Initialization

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-3 Inventory #002600
User-Defined Functions
User Access to the FLUENT Solver Training Manual

Segregated PBCS DBCS

User-
Initialize Begin Loop defined Solver? Solve U-Momentum Source terms
ADJUST
Solve Mass,
Source terms Solve V-Momentum Momentum,
User Defined Solve Mass Source terms
& Momentum Energy,
INITIALIZE Species
Solve W-Momentum

Repeat
Solve Mass Continuity;
Update Velocity

Exit Loop Check Convergence

Solve Energy

Update Properties Solve Species Source

terms
User-Defined Properties
Solve Turbulence Equation(s)
User-Defined BCs

Solve Other Transport Equations as required

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-4 Inventory #002600
User-Defined Functions
Fluent UDF Data Structure (1) Training Manual

 The cell zones and face zones of a model (in the finite-volume
scheme) are accessed in UDFs as Thread data types
 Thread is a FLUENT-defined data type

Domain
Domain

Cell
Cell face
face
Thread Thread
Thread
Boundary (face thread or zone) Fluid (cell
thread or
zone)
Cells Faces

 In order to access data in a thread (zone),

we need to provide the correct thread pointer, and use FLUENT
provided loop macro to access each member (cell or face) in that
thread.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-5 Inventory #002600
User-Defined Functions
Fluent UDF Data Structure (2) Training Manual

• cell_t declares an integer data type used to identify cells

• face_t declares an integer data type used to identify faces

Type Variable Meaning of the declaration

Domain *d; d is a pointer to domain thread
Thread *t; t is a pointer to thread
cell_t c; c is cell thread variable
face_t f; f is a face thread variable
Node *node; node is a pointer to a node.

Fluid cell-thread Boundary face-thread

(control-volume ensemble) (boundary-face ensemble)

Nodes Internal face-thread

(internal-face ensemble)
associated with cell-threads

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-6 Inventory #002600
User-Defined Functions
Loop Macros in UDF Training Manual

• Several frequently used loop macros:

– Loop over all cell threads in domain d:
thread_loop_c(ct,d) { }

– Loop over face threads in domain d:

thread_loop_f(ft,d) { }
d: a domain pointer
ct, t: a cell thread pointer
– Loop over all cells in a cell thread t: ft,f_thread: a face thread
begin_c_loop(c, t) pointer
{…} c: a cell thread variable
end_c_loop (c,t) f: a face thread variable

– Loop over faces in a face thread f_thread:

begin_f_loop(f, f_thread)
{ … }
end_f_loop(f, f_thread)

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-7 Inventory #002600
User-Defined Functions
Example – Parabolic Inlet Velocity Profile Training Manual

• We would like to impose a parabolic inlet velocity to the 2D elbow

shown.

• The x velocity is to be specified as

• We need to know the centroids of the

inlet faces via a macro, and another
macro to perform the boundary
condition assignment.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-8 Inventory #002600
User-Defined Functions
Step 1 – Prepare the Source Code Training Manual

• The DEFINE_PROFILE macro allows the Header file “udf.h” must be included at the top
function x_velocity to of the program by the #include command
be defined. #include "udf.h"
– All UDFs begin with a DEFINE_ DEFINE_PROFILE(x_velocity,thread,nv)
macro {
– x_velocity will appear in the float x[3]; /* an array for the
solver GUI coordinates */
– thread and nv are arguments of float y;
the DEFINE_PROFILE macro, face_t f; /* f is a face
which are used to identify the
zone and variable being defined, thread index */
respectively
– The macro begin_f_loop loops begin_f_loop(f, thread)
over all faces f, pointed by thread {
F_CENTROID(x,f,thread);
• The F_CENTROID macro assigns
y = x[1];
cell position vector to x[] F_PROFILE(f, thread, nv)
• The F_PROFILE macro applies the = 20.*(1.-
velocity component to face f y*y/(.0745*.0745));
• The code is store as a text file }
inlet_bc.c end_f_loop(f, thread)
}

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-9 Inventory #002600
User-Defined Functions
Step 2 – Interpret or Compile the UDF Training Manual

• Compiled UDF • Interpreted UDF

Define User-Defined Functions Compiled Define User-Defined Functions Interpreted

• Add the UDF source code to the Source • Add the UDF source code to the Source
Files list File Name list.
• Click Build to compile and link the code • Click Interpret
• If no errors, click Load to load the library • The assembly language code will display
• You can also unload a library if needed. in the FLUENT console
/define/user-defined/functions/manage • Click Close if there is no error

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-10 Inventory #002600
User-Defined Functions
Interpreted vs. Compiled UDFs Training Manual

• Functions can either be read and interpreted at run time or compiled

and grouped into a shared library that is linked with the standard
FLUENT executable.
• Interpreted code vs. compiled code
– Interpreted
• Interpreter is a large program that sits in the computer’s memory.
• Executes code on a “line by line” basis instantaneously.
• Advantage – Does not require a third-party compiler.
• Disadvantage – Interpreter is slow and takes up memory.
– Compiled (refer to the FLUENT User’s Guide for instructions)
• UDF code is translated once into machine language (object modules).
• Efficient way to run UDFs.
• Creates shared libraries which are linked with the rest of the solver.
• Overcomes many interpreter limitations such as mixed mode arithmetic,
structure references, etc.
• Interpretation of your code should only be considered before the
C/C++ compiler is installed on your system.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-11 Inventory #002600
User-Defined Functions
Step 3 – Hook the UDF in FLUENT GUI Training Manual

• Open the boundary condition panel for the surface to which you
would like to apply the UDF

• Switch from Constant to udf x_velocity in the drop-down list.

• The macro name is the first argument of DEFINE_PROFILE in the UDF

code

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-12 Inventory #002600
User-Defined Functions
Step 4 – Run the Calculations Training Manual

• You can change the Profile Update Interval in the Run Calculation
panel (default value is 1).
– This setting controls how often (either iterations or time steps if
unsteady) the UDF profile is updated.

• Run the calculation

as usual.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-13 Inventory #002600
User-Defined Functions
Numerical Solution of the Example Training Manual

• The figure on the left shows the velocity field through the 2D elbow.

• The figure on the right shows the velocity vectors at the inlet. Notice
the imposed parabolic velocity profile.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-14 Inventory #002600
User-Defined Functions
Other UDF Hooks Training Manual

• In addition to defining boundary values, source terms, and material

properties, UDFs can be used for:
– Initialization Define User-Defined Function Hooks
• Executes once per initialization.
– Solution adjustment
• 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
• Does not participate in the solver iterations
• They are hooked into the solver using the
User-Defined Function Hooks panel.
ANSYS, Inc. Proprietary April 28, 2009
© 2009 ANSYS, Inc. All rights reserved. 8-15 Inventory #002600
User-Defined Functions
Example 2 – Custom Initialization Training Manual

• Initialize a temperature of 600 K #include "udf.h“

inside a sphere, with its center DEFINE_INIT(my_init_function, domain)
at (0.5, 0.5, 0.5), radius of 0.25, {
cell_t c;
and 300 K throughout the rest Thread *ct;
of the domain. real xc[ND_ND];
thread_loop_c(ct,domain)
• The domain pointer is passed {
begin_c_loop (c,ct)
to this UDF through the {
argument C_CENTROID(xc,c,ct);
if (sqrt(ND_SUM(pow(xc[0]-0.5,2.),
pow(xc[1] - 0.5,2.),
• thread_loop_c macro is used pow(xc[2] - 0.5,2.))) < 0.25)
to access all cell threads C_T(c,ct) = 600.;
else
(zones), and begin_c_loop C_T(c,ct) = 300.;
macro is used to access cells }
end_c_loop (c,ct)
within each cell thread }
}
• Deploy this UDF as a user
defined function hook.
ANSYS, Inc. Proprietary April 28, 2009
© 2009 ANSYS, Inc. All rights reserved. 8-16 Inventory #002600
User-Defined Functions
DEFINE Macros Training Manual

• Examples of top-level DEFINE macros

DEFINE_ADJUST(name,domain); general purpose UDF called every iteration
DEFINE_INIT(name,domain); UDF used to initialize field variables
DEFINE_ON_DEMAND(name); an ‘execute-on-demand’ function
DEFINE_RW_FILE(name,fp); customize reads/writes to case/data files
DEFINE_PROFILE(name,thread,index); boundary profiles
DEFINE_SOURCE(name,cell,thread,dS,index); equation source terms
DEFINE_HEAT_FLUX(name,face,thread,c0,t0,cid,cir); heat flux
DEFINE_PROPERTY(name,cell,thread); material properties
DEFINE_DIFFUSIVITY(name,cell,thread,index); UDS and species diffusivities
DEFINE_UDS_FLUX(name,face,thread,index); defines UDS flux terms
DEFINE_UDS_UNSTEADY(name,cell,thread,index,apu,su); UDS transient terms
DEFINE_SR_RATE(name,face,thread,r,mw,yi,rr); surface reaction rates
DEFINE_VR_RATE(name,cell,thread,r,mw,yi,rr,rr_t); volumetric reaction rates
DEFINE_SCAT_PHASE_FUNC(name,cell,face); scattering phase function for DOM
DEFINE_DELTAT(name,domain); variable time step size for unsteady problems
DEFINE_TURBULENT_VISCOSITY(name,cell,thread); calculates turbulent viscosity
DEFINE_TURB_PREMIX_SOURCE(name,cell,thread,turbflamespeed,source);
turbulent flame speed
DEFINE_NOX_RATE(name,cell,thread,nox); NOx production and destruction rates

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-17 Inventory #002600
User-Defined Functions
Geometry and Time Macros Training Manual

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 (axisymmetric domain)

real flow_time(); Returns actual time

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

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-18 Inventory #002600
User-Defined Functions
Cell Field Variable Macros Training Manual

C_R(c,t); Density C_DVDX(c,t); Velocity derivative

C_P(c,t); Pressure C_DVDY(c,t); Velocity derivative
C_U(c,t); U-velocity C_DVDZ(c,t); Velocity derivative
C_V(c,t); V-velocity C_DWDX(c,t); Velocity derivative
C_W(c,t); W-velocity C_DWDY(c,t); Velocity derivative
C_T(c,t); Temperature C_DWDZ(c,t); Velocity derivative
C_H(c,t); Enthalpy
C_K(c,t); Turbulent kinetic energy (k) C_MU_L(c,t); Laminar viscosity
C_D(c,t); Turbulent dissipation rate (ε) C_MU_T(c,t); Turbulent viscosity
C_O(c,t); Specific dissipation of k (ω) C_MU_EFF(c,t); Effective viscosity
C_YI(c,t,i); Species mass fraction C_K_L(c,t); Laminar thermal
C_UDSI(c,t,i); UDS scalars conductivity
C_UDMI(c,t,i); UDM scalars C_K_T(c,t); Turbulent thermal
conductivity
C_K_EFF(c,t); Effective thermal
C_DUDX(c,t); Velocity derivative conductivity
C_DUDY(c,t); Velocity derivative C_CP(c,t); Specific heat
C_DUDZ(c,t); Velocity derivative C_RGAS(c,t); Gas constant

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-19 Inventory #002600
User-Defined Functions
Cell Field Variable Macros Training Manual

C_R(c,t); Density C_DVDX(c,t); Velocity derivative

C_P(c,t); Pressure C_DVDY(c,t); Velocity derivative
C_U(c,t); U-velocity C_DVDZ(c,t); Velocity derivative
C_V(c,t); V-velocity C_DWDX(c,t); Velocity derivative
C_W(c,t); W-velocity C_DWDY(c,t); Velocity derivative
C_T(c,t); Temperature C_DWDZ(c,t); Velocity derivative
C_H(c,t); Enthalpy
C_K(c,t); Turbulent kinetic energy (k) C_MU_L(c,t); Laminar viscosity
C_D(c,t); Turbulent dissipation rate (ε) C_MU_T(c,t); Turbulent viscosity
C_O(c,t); Specific dissipation of k (ω) C_MU_EFF(c,t); Effective viscosity
C_YI(c,t,i); Species mass fraction C_K_L(c,t); Laminar thermal
C_UDSI(c,t,i); UDS scalars conductivity
C_UDMI(c,t,i); UDM scalars C_K_T(c,t); Turbulent thermal
conductivity
C_K_EFF(c,t); Effective thermal
C_DUDX(c,t); Velocity derivative conductivity
C_DUDY(c,t); Velocity derivative C_CP(c,t); Specific heat
C_DUDZ(c,t); Velocity derivative C_RGAS(c,t); Gas constant
C_DIFF_L(c,t); Laminar species
diffusivity
C_DIFF_EFF(c,t,i); Effective species
diffusivity

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-20 Inventory #002600
User-Defined Functions
User Defined Memory Training Manual

• User-allocated memory for each cell 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 any purposes,
including user’s own numerical
algorithms and postprocessing
– Information is stored in the FLUENT
data file.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-21 Inventory #002600
User-Defined Functions
User Defined Scalars Training Manual

• FLUENT can solve up to 50 generic Define User-Defined Scalars

transport equations for user-defined
scalars

– Number of UDS variables

– In which zones the UDS is solved

– Flux Function
• DEFINE_UDS_FLUX(name,face,thread,index)
– Unsteady function
• DEFINE_UDS_UNSTEADY(name,cell,thread,index,apu,su)
• If statements are required in order to associate multiple flux and transient
functions with each UDS
• Example
– Can be used to solve the electromagnetic field equations.
ANSYS, Inc. Proprietary April 28, 2009
© 2009 ANSYS, Inc. All rights reserved. 8-22 Inventory #002600
User-Defined Functions
Additional Macros Training Manual

• Still many more macros are available in the following categories and
are documented in UDF Manual:
– Turbulence Models
– Multiphase models
– Reacting flows
– Dynamic mesh
– Input/Output

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-23 Inventory #002600
User-Defined Functions
Where to Get More Information and Help Training Manual

• UDF User Guide

– A very readable document which should serve as the main source of information.
– Contains macro definitions, numerous code examples and code fragments.
– New users of UDFs should quickly go through the UDF manual as a pre-requisite
for UDF programming

• FLUENT’s UDF Archive accessible through www.fluentusers.com

• Start your own UDF program by modifying an existing UDF program which is
close to what you want to do, then step by step add your own code to the
program.

• Attend the Advanced UDF Programming course

• Submit your help requests through the ANSYS technical support

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-24 Inventory #002600
User-Defined Functions
UDF Technical Support Training Manual

• Because UDFs can be very complicated, ANSYS does not assume

responsibility for the accuracy or stability of solutions obtained
using user-generated UDFs.

• Support will be generally be limited to guidance related to

communication between UDFs and the FLUENT solver.

• A consulting project provided by the ANSYS technical services

engineers is an option to jumpstart your project.

ANSYS, Inc. Proprietary April 28, 2009

© 2009 ANSYS, Inc. All rights reserved. 8-25 Inventory #002600