Lecture 1:

Introduction
16.0 Release

User Defined Functions

in ANSYS Fluent
1 © 2015 ANSYS, Inc. June 7, 2015
 Why use User Defined Functions (UDFs)?

The Fluent solver is a general-purpose code. In order to customize the

Fluent solver, users can use their own C-codes called user-defined
functions (UDFs) to accomplish:
• Special boundary conditions
• Customized or solution dependent material properties
• New physical models
• Reaction rates
• Source terms
• Customized post-processing
• Solving user-supplied partial differential equations
• More ….

2 © 2015 ANSYS, Inc. June 7, 2015

 What are User Defined Functions?

Programs written in C
Similar mechanism used to develop models in Fluent
– Powerful and efficient
Extends the functionality of ANSYS Fluent
– Initial and boundary conditions
– Material properties
– Material and energy transfer through source terms
– Modify solution variables
– Adding extra flow equations
– And many more …
Typically compiled to DLLs/shared object libraries
– Loaded only when required

3 © 2015 ANSYS, Inc. June 7, 2015

 Sinusoidal Wall Temperature Variation

Adiabatic wall

inlet outlet

Heated wall T = T(x)

𝝅𝒙
T(x) = 𝟑𝟎𝟎 + 𝟏𝟎𝟎 𝐬𝐢𝐧 𝟎.𝟎𝟎𝟓

4 © 2015 ANSYS, Inc. June 7, 2015

 What Does It Take to Create a Model?

Ability to access and modify

– Interact with the user through a GUI/TUI
– Field variables
– Geometrical and mesh data
– Hooks to the solver at appropriate stages of the solution cycle
– Convenience macros
• Vector macros
• Looping macros
• Parallel programming

5 © 2015 ANSYS, Inc. June 7, 2015

 Basics of UDFs

16.0 Release

User Defined Functions

in ANSYS Fluent
6 © 2015 ANSYS, Inc. June 7, 2015
 C – The Foundation for UDFs
UDFs when compiled create C libraries that Fluent can use
Resources to learn C
– ANSYS Fluent Customization Manual (Appendix A. C Programming Basics)
– E.g. Practical C Programming, 3rd Edition by Steve Oualline
– Reference guide: C in a Nutshell, The Definitive Reference by Peter Prinz
and Tony Crawford

Programming practices
– Simplicity, Clarity and Generality
• Naming conventions
• Macros and comments
• Algorithms and data structures
• Design principles
• Testing
7 © 2015 ANSYS, Inc. June 7, 2015
 User Access to the Fluent Solver
SOLVERS
Segregated PBCS DBCS

User-
Initialize Begin Loop defined Solver? Solve U-Momentum Source terms
ADJUST
Solve Mass,
Solve V-Momentum
User Defined Solve Mass Momentum,
Source terms Source terms
INITIALIZE & Energy,
Solve W-Momentum
Repeat Momentum Species
Solve Mass Continuity;
Update Velocity
Exit Loop Check Convergence
Solve Energy
Update Properties
Solve Species Source
User-Defined Properties terms
Solve Turbulence Equation(s)
User-Defined BCs
Solve Other Transport Equations as required

8 © 2015 ANSYS, Inc. June 7, 2015

 Data Structures

Each type of UDF is passed different values and data structures

depending on its function.

Most UDFs will need solver data. This is stored in a hierarchy:

• Domains are collections of threads that make the whole mesh
• Threads (or zones) are collections of cells or faces
• Cells and faces are made of Nodes

9 © 2015 ANSYS, Inc. June 7, 2015

 Geometrical Entities

The parts of a mesh are:

Collection of cells and faces are stored in threads.

10 © 2015 ANSYS, Inc. June 7, 2015
 Data Structures

The terms ‘Thread’ and ‘Zone’ are interchangeable. The boundary

and cell zones defined in the User Interface are stored internally
as threads.
– Zones have an associated integer ID seen in the settings
panel
– In a UDF, the corresponding thread can be identified using
this ID
– Threads are an internal data type which stores information
about the mesh, models, properties, BCs all in one place
A cell has information about its bounding faces and a face has
access to its neighbouring cells.
11 © 2015 ANSYS, Inc. June 7, 2015
 Introduction to the
C Programming Language
16.0 Release

User Defined Functions

in ANSYS Fluent
12 © 2015 ANSYS, Inc. June 7, 2015
 C Programming – Basic Syntax Rules

– Each statement must be terminated with a semicolon ;

– Comments can be inserted anywhere between /* and */
– All variables must be explicitly declared (unlike in FORTRAN)
– Compound statements can be created by enclosing multiple
statements by braces: { }
– Function definitions have the following format:

return-value-type function-name(parameter-list)
{
function body
}

13 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – Data Types

Built-in data types: int, float, double, char, enum

int niter, a; /* Declare ‘niter’ and ‘a’ as integers */
float dx[10]; /* dx is an array of numbers indexed
from 0 to 9: dx[0],dx[1],…,dx[9] */
enum {X, Y, Z};/* X,Y,Z are enumeration constants = 0,1,2 */

Ansys Fluent: real, cxboolean

real a; /* real is a typedef that switches between
float for single-precision and
double for double-precision arithmetic */
cxboolean flag=TRUE; /* Pre-defined enumeration of
FALSE and TRUE*/
14 © 2015 ANSYS, Inc. June 7, 2015
 C Programming – Pointer
• A pointer is a special kind of variable that contains an address in memory, not
content, of another variable
• Pointers are declared using the * notation
int *ip; /* declares a pointer named ip that points to an
integer variable*/

• We can make a pointer point to the address of pre-defined variable as follows:

int a=1; Message Macro:
int *ip; /* (*ip) contains an integer */ • Defined in udf.h
• Similar to printf in C
• Recommended to use
ip = &a; /* &a returns the address of variable a */
Message(“ip is a pointer with value %p\n”,ip);
Message(“The integer ‘a’ pointed to by ip has value = %d\n”,*ip);

Output: ip is a pointer with value 0x40b2

The integer ‘a’ pointed to by ip has value = 1
15 © 2015 ANSYS, Inc. June 7, 2015
 C Programming – Pointers and Arrays
• Pointers and arrays are closely related:
int ar[10]; /* ar is an array of 10 integers */
int *ip; /* (*ip) contains an integer */

• The name of an array without an index can be used as a pointer to start

the array
ip = ar; /* ar is the address of its first integer
so this is equivalent to ip = &(ar[0]); */

• BUT: An array name cannot be set to a new value. It is fixed to the value
set when it is defined as an array.
ar = ip; /* This will cause a compilation error. */

16 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – Operators

• Arithmetic Operators
= (assignment)
+, -, *, /,
% (modulo reduction)
++ (increment) /* i++ is post-increment (i=i+1) */
-- (decrement) /* j–- is post-decrement (j=j-1) */

E.g.: x = 1;
y = x++; /* x is now 2, y is 1*/
• Logical Operators
<, >, >=, <= , ==, !=

• Assignments
E.g.: x += y; /* is equivalent
+=, *=, -=, /= to x = x + y */

17 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – Control Statements

if-else statement: for loop:

if ( logical-expression ) for (begin ; end ; increment)
{ statements } {statements}
else
{ statements }
while loop:
while ( logical-expression )
E.g.: {statements}
if ( x < 0 )
y = x/50; E.g.:
else for ( k=0; k < 10; k++)
{ {statements}
x = -x;
y = x/25; while ( x < 5 )
} { executed while the condition is true }

18 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – Conditional Operator

(logical-expression ? result1 : result2)

If the condition/logical-expression is true, result1 is returned

else result2 is returned.

E.g.:
real y = 2;
real x1 = (y < 0 ? 5 : 10);
real x2 = (y >= 0 ? 5 : 10);
Result: x1 = 10 and x2 = 5

19 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – User-defined Data Types (1)

Structures are collection of data that are of different type.

struct <structure_name> E.g.: struct car_struct
{ {
Element 1; char model_name[25];
… int number_of_wheels;
Element n; real top_speed;
}; };

Semicolon (;) at the end of structure declaration is needed!

Set and get values
struct car_struct alices_car, bobs_car;
alices_car.top_speed = 120.0;
if (bobs_car.top_speed > alices_car.top_speed)

20 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – User-defined Data Types (2)
To simplify a declaration
typedef <existing_type> <new_type_name> ;

If the example from previous slide is defined as follows

Combined example: Simplified:
typedef struct car_struct typedef struct
{ {
char model_name[25]; char model_name[25];
int number_of_wheels; int number_of_wheels;
real top_speed; real top_speed;
} car_model; } car_model;
then the variable can be declared as
car_model alices_car; instead of struct car_struct alices_car;

21 © 2015 ANSYS, Inc. June 7, 2015

 C Programming – Fluent Structures

The most common structure in Fluent is Thread.

typedef struct thread_struct E.g.:
{
… Thread *ct;
int id;
… Usually we use pointers to structures.
} Thread;

Pre-defined Marcos can be used to access structure elements.

#define THREAD_ID(t) ((t)->id)

Note -> operator: t->id is the same as (*t).id

22 © 2015 ANSYS, Inc. June 7, 2015

 Introduction to UDF
Implementation Using C
16.0 Release

User Defined Functions

in ANSYS Fluent
23 © 2015 ANSYS, Inc. June 7, 2015
 Why UDFs are written in the C Language
Fluent is written in C because it is a very powerful language. It provides access to high
level operations such as graphics and networking and low level capabilities such as
mathematical functions and memory operations.

It enables the linking of extra functionality using “shared objects” in Unix and Dynamic
Linked Libraries (DLLs) in windows systems.

This is a very convenient mechanism for linking in UDFs which allows a seamless
connection between the main program and the user functions

Users familiar with other “procedural” languages such as FORTRAN will be familiar with
most of the ideas and syntax used in C

24 © 2015 ANSYS, Inc. June 7, 2015

 Mesh Data Types (1)
• There are several Fluent-specific data types that are associated with mesh components.
• Some of the more commonly used ones are:
− Node – stores data associated with a grid point
− face_t – identifies a face within a face thread
− cell_t – identifies a cell within a cell thread
− Thread – stores data that is common to a collection of cells or faces
− Domain – stores data associated with a collection of face and cell threads in a mesh

• Each individual cell can be accessed by using a cell index of type cell_t and the cell thread
(the zone which contains the cell)
• Each individual face (boundary or internal) can be accessed by using a face index of type
face_t and the face thread (the zone which contains the face)
25 © 2015 ANSYS, Inc. June 7, 2015
 Mesh Data Types (2)
• Some mesh or solver data types have a capital letter. These are actually data
structures in the C language and are usually passed between functions as pointers to
these structures.
• Examples of how these data types are defined are shown below:

Type Example Declaration

Domain *d; d is a pointer to a Domain structure
Thread *t; t is a pointer to a Thread structure
cell_t c; c is cell index, a simple integer
face_t f; f is a face index, a simple integer
Node *node; node is pointer to a Node structure

26 © 2015 ANSYS, Inc. June 7, 2015

 Mesh Data Types (3)
Every Zone is associated to a single ID available in the BC panel or the TUI using:
/grid/modify-zones/list-zones
Given the ID, the thread associated with that zone
can be retrieved as:
int t_id = 7;
Thread *ft;
ft = Lookup_Thread(domain, t_id);

Once we have the thread we can access its associated data

Similarly, a thread’s ID can be retrieved using:
t_id = THREAD_ID(ft);
27 © 2015 ANSYS, Inc. June 7, 2015
 C macros and UDF Programming

• C has very powerful macro definition capabilities. These are

extensively used in Fluent in many ways. Notable examples include
definitions of:
– Data structure looping macro
– Geometry macros
– Field data macros
– Logic and status control macros
– Safe arithmetic and trigonometry functions
– Complete set of vector arithmetic operations
• The definition of each UDF also uses a specific DEFINE_ macro.

28 © 2015 ANSYS, Inc. June 7, 2015

 Looping Macros in a UDF

Fluent provides a set of pre-defined macros to accomplish looping tasks:

• thread_loop_c(t,d){…} Loop over cell threads in a domain d
• thread_loop_f(t,d){…} Loop over face threads in a domain d

• begin_c_loop(c,t) Loop over the cells in a given thread t

{…}
end_c_loop(c,t)

• begin_f_loop(f,t) Loop over the faces in a given thread t

{…}
end_f_loop(f,t)
29 © 2015 ANSYS, Inc. June 7, 2015
 Cell Field Variable Macros
C_R(c,t); Density C_DUDX(c,t); Velocity derivative
C_P(c,t); Pressure C_DUDY(c,t); Velocity derivative
C_U(c,t); U-velocity C_DUDZ(c,t); Velocity derivative
C_V(c,t); V-velocity C_DVDX(c,t); Velocity derivative
C_W(c,t); W-velocity C_DVDY(c,t); Velocity derivative
C_T(c,t); Temperature C_DVDZ(c,t); Velocity derivative
C_H(c,t); Enthalpy C_DWDX(c,t); Velocity derivative
C_K(c,t); Turbulent kinetic energy (k) C_DWDY(c,t); Velocity derivative
C_D(c,t); Turbulent dissipation rate (ε) C_DWDZ(c,t); Velocity derivative
C_YI(c,t,i); i-th Species mass fraction C_MU_L(c,t); Laminar viscosity
C_UDSI(c,t,i); i-th UDS scalars C_MU_T(c,t); Turbulent viscosity
C_UDMI(c,t,i); i-th UDM scalars C_MU_EFF(c,t); Effective viscosity
30 © 2015 ANSYS, Inc. June 7, 2015
 Geometry Macros A Hex cell
Faces

• C_CENTROID(pos,c,t) x, y, z coords of cell centroid

• F_CENTROID(pos,f,t) x, y, z coords of face centroid Nodes
• F_AREA(A,f,t) Area vector of a face;
• NV_MAG(A) Vector magnitude Location of cell variables
• C_VOLUME(c,t) Volume of a cell C_NNODES(c,t) = 8
• C_VOLUME_2D(c,t) Volume of a 2D cell C_NFACES(c,t) = 6
F_NNODES(f,t) = 4 each

pos and A are vectors which are discussed later.

Depth is 1m in 2D; 2 radians in axi-symmetric .

Node Coordinates:
• NODE_X(nn) Node x–coord; (with Node *nn;)
Many more
• NODE_Y(nn) Node y–coord; macros available,
• NODE_Z(nn) Node z–coord; see UDF Manual.

31 © 2015 ANSYS, Inc. June 7, 2015

 Cell-Face Connectivity (1)

• The cells on either side of a face (f,ft) can be accessed using the macros:

ct0 = THREAD_T0(ft); C0
ct1 = THREAD_T1(ft);
c0 = F_C0(f,ft); C1
c1 = F_C1(f,ft);
A face’s area vector
points from C0 to C1
• The macros THREAD_T0(ft) and THREAD_T1(ft)only need the
face thread, not the face index.
• Boundary zones such as inlets will connect to a cell zone on one side
with THREAD_T0(ft) but THREAD_T1(ft) will return NULL, a
special pointer which signifies there is no zone on the other side.

32 © 2015 ANSYS, Inc. June 7, 2015

 Cell-Face Connectivity (2)

• A face’s area can be obtained by C0

real A[3], area;
F_AREA(A,f,ft); C1
area = NV_MAG(A);

where F_AREA returns the face normal vector A and A face’s area vector
NV_MAG(A) the magnitude of the vector A. points from C0 to C1

• The faces that bound a cell can be accessed using this loop :

int nf;
for(nf = 0; nf < C_NFACES(c,ct); nf++)
{
f = C_FACE(c,ct,nf);
ft= C_FACE_THREAD(c,ct,nf);
}
33 © 2015 ANSYS, Inc. June 7, 2015
 Macros used for Control

• Data_Valid_P() if (!Data_Valid_P())
return;
TRUE if data is available, FALSE if not.
• FLUID_THREAD_P(t0)
TRUE if threat t0 is a fluid thread, FALSE if not.
• NULLP(ct)
TRUE if a pointer is NULL, FALSE if not.
• NNULLP(ct) if(NNULLP(THREAD_T1(ft)))
{ ... Do things on neighbouring
TRUE if a pointer is NOT NULL, FALSE if not. cell thread.
}

34 © 2015 ANSYS, Inc. June 7, 2015

 UDF Defining Macros

All UDFs that will be used must be defined using a specific

DEFINE_ macro
Common examples:
• Profiles : DEFINE_PROFILE
• Source Terms : DEFINE_SOURCE
• Properties : DEFINE_PROPERTY
• User-defined Scalars : DEFINE_UDS_UNSTEADY , DEFINE_UDS_FLUX
DEFINE_DIFFUSIVITY
• Initialization : DEFINE_INIT
• Global Functions : DEFINE_ADJUST For a complete list,
DEFINE_ON_DEMAND see UDF Manual.
DEFINE_RW_FILE
35 © 2015 ANSYS, Inc. June 7, 2015
 Additional Information

• Many additional macros are available to implement different physical

models including:
– Combustion models
– Particle-based models
– Turbulence models
– Radiation models
– etc.
• It is also possible to develop additional numerical methods, particularly
when using User-Defined Scalars (see Lecture 4). Access to low-level
operations is possible, such as
– Flux discretization
– Variable reconstruction and clipping

36 © 2015 ANSYS, Inc. June 7, 2015

 Overview of Fluent Macros

• UDF macros are defined in the udf.h file, for instance

#define DEFINE_PROFILE(name, t, i) void name(Thread *t, int i)
#define DEFINE_PROPERTY(name,c,t) real name(cell_t c, Thread *t)
…
• The udf.h is a Fluent header file in the

path\ANSYS Inc\v160\fluent\fluent16.0.0\src\udf
directory.
• At the beginning of every UDF source code file, the header file MUST be included.
#include “udf.h”

• There are many more header files stored in path\ANSYS Inc\v160\fluent\fluent16.0.0\src\*

which can be browsed by users but most are already included automatically within udf.h.

37 © 2015 ANSYS, Inc. June 7, 2015