Lecture 1:

Introduction
15.0 Release

User Defined Functions

in ANSYS Fluent
1

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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 .

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Sinusoidal Wall Temperature Variation

Adiabatic wall
inlet

outlet
Heated wall T = T(x)

T(x) = +

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Basics of UDFs
15.0 Release

User Defined Functions

in ANSYS Fluent
6

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

C The Foundation for UDFs

UDFs when compiled create C libraries that Fluent can use
Resources to learn C
ANSYS Fluent UDF Manual (Appendix A. C Programming Basics)
E.g. The C-Programming Language, B. Kernighan & D. Ritchie

Programming practices
Simplicity, Clarity and Generality
Naming conventions
Macros and comments
Algorithms and data structures
Design principles
Testing
7

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

User Access to the Fluent Solver

Segregated

Initialize

Begin Loop

Userdefined
ADJUST

Solver?

SOLVERS

Solve U-Momentum
Solve V-Momentum

User Defined
INITIALIZE

Source terms

Repeat

Solve W-Momentum

PBCS

DBCS

Source terms
Solve Mass
&
Momentum

Solve Mass,
Momentum,
Energy,
Species

Source terms

Solve Mass Continuity;

Update Velocity
Exit Loop

Check Convergence
Solve Energy
Update Properties

User-Defined Properties

Solve Species

Solve Turbulence Equation(s)

Source
terms

User-Defined BCs
Solve Other Transport Equations as required
8

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Geometrical Entities
The parts of a mesh are:

Collection of cells and faces are stored in threads.

10

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Introduction to the
C Programming Language
15.0 Release

User Defined Functions

in ANSYS Fluent
12

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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;
int *ip; /* (*ip) contains an integer */

Message Macro:
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:
15

2013 ANSYS, Inc.

ip is a pointer with value 0x40b2

The integer a pointed to by ip has value = 1

June 4, 2014

Release 15.0

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;
16

2013 ANSYS, Inc.

/* This will cause a compilation error. */

June 4, 2014

Release 15.0

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
+=, *=, -=, /=
17

2013 ANSYS, Inc.

June 4, 2014

E.g.: x += y; /* is equivalent

to x = x + y */
Release 15.0

C Programming Control Statements

if-else statement:

for loop:

if ( logical-expression )
{ statements }
else
{ statements }

if ( x < 0 )
y = x/50;
else
{
x = -x;
y = x/25;
}
2013 ANSYS, Inc.

while loop:
while ( logical-expression )
{statements}

E.g.:

18

for (begin ; end ; increment)

{statements}

June 4, 2014

E.g.:
for ( k=0; k < 10; k++)
{statements}
while ( x < 5 )
{ executed while the condition is true }
Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

C Programming User-defined Data Types (1)

Structures are collection of data that are of different type.
struct <structure_name>
{
Element 1;

Element n;
};

E.g.: struct car_struct

{

char model_name[25];
int
number_of_wheels;
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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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:
typedef struct car_struct
{
char model_name[25];
int
number_of_wheels;
real top_speed;
} car_model;

Simplified:
typedef struct
{
char model_name[25];
int
number_of_wheels;
real top_speed;
} car_model;

then the variable can be declared as

car_model alices_car;
21

2013 ANSYS, Inc.

June 4, 2014

instead of struct car_struct alices_car;

Release 15.0

C Programming Fluent Structures

The most common structure in Fluent is Thread.
typedef struct thread_struct
{

int id;

} Thread;

E.g.:
Thread *ct;

Usually we use pointers to structures.

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

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

Note ->

22

2013 ANSYS, Inc.

operator: t->id

June 4, 2014

is the same as (*t).id

Release 15.0

Introduction to UDF
Implementation Using C
15.0 Release

User Defined Functions

in ANSYS Fluent
23

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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
Domain
Thread
cell_t
face_t
Node

26

2013 ANSYS, Inc.

Example
*d;
*t;
c;
f;
*node;

June 4, 2014

Declaration
d is a pointer to a Domain structure
t is a pointer to a Thread structure
c is cell index, a simple integer
f is a face index, a simple integer
node is pointer to a Node structure

Release 15.0

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 threads ID can be retrieved using:
t_id = THREAD_ID(ft);
27

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

C macros and UDF Programming

C has very powerful macro definition capabilities. These are
extensively used in Fluent in many ways. Notable example 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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Looping Macros in a UDF

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

thread_loop_c(t,d){}
thread_loop_f(t,d){}

Loop over cell threads in a domain 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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Geometry Macros

C_CENTROID(pos,c,t)
F_CENTROID(pos,f,t)
F_AREA(A,f,t)
NV_MAG(A)
C_VOLUME(c,t)
C_VOLUME_2D(c,t)

x, y, z coords of cell centroid

x, y, z coords of face centroid
Area vector of a face;
Vector magnitude
Volume of a cell
Volume of a 2D cell

A Hex cell
Faces

Nodes

Location of cell variables

C_NNODES(c,t) = 8
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_Y(nn)
NODE_Z(nn)
31

2013 ANSYS, Inc.

Node xcoord; (with Node *nn;)

Node ycoord;
Node zcoord;
June 4, 2014

Many more
macros available,
see UDF Manual.
Release 15.0

Cell-Face Connectivity (1)

The cells on either side of a face (f,ft) can be accessed using the macros:
ct0 = THREAD_T0(ft);
ct1 = THREAD_T1(ft);
c0 = F_C0(f,ft);
c1 = F_C1(f,ft);

C0
C1
A faces 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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

Cell-Face Connectivity (2)

A faces area can be obtained by
real A[3], area;
F_AREA(A,f,ft);
area = NV_MAG(A);

where F_AREA returns the face normal vector A and

NV_MAG(A) the magnitude of the vector A.

C0
C1
A faces area vector
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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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)
TRUE if a pointer is NOT NULL, FALSE if not.

34

2013 ANSYS, Inc.

June 4, 2014

if(NNULLP(THREAD_T1(ft)))
{ ... Do things on neighbouring
cell thread.
}
Release 15.0

UDF Defining Macros

All UDFs that will be used must be defined using a specific
DEFINE_ macro
Common examples:

35

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
DEFINE_ON_DEMAND
DEFINE_RW_FILE

2013 ANSYS, Inc.

June 4, 2014

For a complete list,

see UDF Manual.
Release 15.0

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

2013 ANSYS, Inc.

June 4, 2014

Release 15.0

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\v150\fluent\fluent15.0.0\src
directory.

At the beginning of every UDF source code file, the header file MUST be included.

#include udf.h

37

There are many more header files stored in the same directory which can be
browsed by users but most are already included automatically within udf.h.

2013 ANSYS, Inc.

June 4, 2014

Release 15.0