Introduction to UDF and FLUENT Data Structure

C Programming (1)
Basic syntax rules:
each statement must be terminated with a semicolon ;
comments can be inserted anywhere between /* and */
variables must be explicitly declared (unlike in FORTRAN)
compound statements must be enclosed by braces { }
Chapter 1
functions have the following format:
return-value-type function-name (parameter-list)
Introduction and { function body }
FLUENT Data Structure Macros are defined in the header files, they can be used just like functions
Built-in data types: int, float, double, enum, boolean:
int niter, a; /* declaring ‘niter’ and ‘a’ as integers */
Advanced FLUENT float dx[10]; /* ‘dx’ is a real array with 10 members, the
User-Defined Functions array index always starts from dx[0] */

enum {X, Y, Z}; /* X, Y, Z are enumeration constants 0, 1, 2 */

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009
© 2006 ANSYS,
ANSYS, Inc.AllAll
Inc. rightsreserved.
rights reserved. 1-1 © Fluent Inc. 11/16/2010
Inventory
ANSYS, #002686
Inc. Proprietary © 2009 ANSYS, Inc. All rights reserved. 1-4 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Introduction C Programming (2)

• pointer is a special kind of variable that contains the

• The FLUENT solver is a general-purpose code. In order to customize address, not content, of another variable
the FLUENT solver, users can use their own C-codes called user-
defined functions (UDFs) to accomplish: • Pointers are declared using the * notation:
Special boundary conditions int *ip; /* ip is declared as a pointer to integer */
Customized or solution dependent material properties • We can make a pointer point to the address of predefined variable as
New physical models follows:
int a=1;
Reaction rates int *ip;
Source terms ip = &a; /* &a returns the address of variable a */
printf(“content of address pointed to by ip = %d\n”, *ip);
Customized post-processing
Solving user-supplied partial differential equations
• Pointers are also used to point to the beginning of an array
Thus pointers are used to address arrays in C
More ….
• Array variables can be defined using the notation name[size]
where name is the variable name and size is an integer which defines
the number of elements in the array (from 0 to size-1)

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-2 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-5 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

User Access to the FLUENT Solver C Programming (3)

Segregated PBCS DBCS Operators
= (assignment)
User-
Initialize Begin Loop defined Solver? Solve U-Momentum Source terms +, -, *, /, % (modulus)
ADJUST
Solve Mass, <, >, >=, <= , ==, !=
Source terms Solve V-Momentum Momentum,
Solve Mass Source terms
User Defined
& Momentum Energy, ++ increment; i++ is “post-increment”: use the current value of i
INITIALIZE Species
Solve W-Momentum in the expression, then increment i by 1 (i=i+1)
Repeat
Solve Mass Continuity;
Update Velocity
-- decrement: j-- post-decrement, use the current value of j,
Exit Loop Check Convergence
then decrement j by 1 (j=j-1)
Solve Energy

Update Properties Solve Species Source += addition assignment:

terms
User-Defined Properties Solve Turbulence Equation(s)
agg += single; /* it means agg=agg+single; */
User-Defined BCs
*= multiplication assignment, -= subtraction assignment,
Solve Other Transport Equations as required
/= division assignment

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-3 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-6 Inventory #002686
Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

C Programming (4) The Domain

Basic control structures For Loops: • Domain is the set of connectivity and hierarchy info for the entire
for ( k=0; k < NUM; k++ ) data structure in a given problem for single phase flows. It includes:
if ( … ) <statement>; all fluid zones (‘fluid threads’)
all solid zones (‘solid threads’)
<statement>; all boundary zones (‘boundary threads’)
While Loops:
• Cell: Cell is the computational unit, conservation equations are
if ( …) while ( … ) solved over each cell
<statement>; <statement>; • Face: direction is in the outward normal
else • Threads: represent the collection of cells or faces; a Thread
represents a fluid or solid or boundary zone
<statement>;
Conditional Operator (? : ) • multiphase simulations (singlephase simulations use single domain
( condition ? operand a : operand b ) only)
if ( …) Each phase has its own “Domain-structure”
<statement>; false Geometric and common property information are shared among ‘sub-
example: domains’
else if ( … ) real At = (rp_axi ? At*2*M_PI : At ); Multiphase UDF will be discussed later
<statement>;
true
ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-7 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-10 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

CFD Programming in FLUENT The Threads

• We (as CFD programmers in FLUENT) want to know how FLUENT • A Thread is a sub-set of the Domain structure
organizes data so that we know: • Individual ‘fluid’, ‘solid’ and each ‘boundary’ zones are
How to access mesh information for a particular cell zone or a face zone identified as ‘zones’ and their datatype is Thread
Cell centroids, cell volumes, the neighbors, etc.
Face centroids, face areas, face normal directions (vectors), etc.
• ‘Zone’ and ‘Thread’ terms are often used interchangeably
How to access field data for cells (and faces): pressure, velocity, density, etc. • Some further details about Zone/Thread ID and Thread-
How to efficiently loop through these cells or faces in the codes datatype:
• How to supply customized source terms, boundary conditions, and fluid Zones are identified at mesh level with an integer ID in the
properties, etc., to the solver Define/Boundary Condition panel
• How to modify the behaviors or specific model parameters for various Threads, a Fluent-specific datatype, store structured information
physical models as in turbulence, reactions kinetics, multiphase, and about the mesh, connectivity, models, property, etc. all in one place
dynamic mesh, etc. Users identify zones through the ID’s

• How to implement user’s own governing equations in the finite-volume Zone/Thread-ID and Threads are correlated through UDF
macro’s
framework of FLUENT solver

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-8 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-11 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Data Structure Overview Cell and Face Datatypes

• Control volumes of fluid and solid zones are also called ‘cells’ in
face FLUENT
Domain The data structure for the cell zones is typed as ‘cell_t’ (the cell
cell cell thread index)
The data structure for the cell faces is typed as ‘face_t’ (the face
Domain Thread thread index)
• A fluid or solid zone is called a cell zone, which can be accessed by
using cell threads
Cell Cell
• Boundary or internal faces can be accessed by using face threads

Boundary (face thread or zone) Fluid (cell thread or zone)

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-9 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-12 Inventory #002686
Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Some additional info on Faces Geometry Macros

• C_NNODES(c, t) Number of in a
• Each Control volume has a finite number of faces • C_NFACES(c, t) No. of in a
A Hex cell
• F_NNODES(f, t) No. of in a
Faces on the boundary are also typed ‘face_t’; their • C_CENTROID(x, c, t) x, y, z-coords of centroid
Faces

ensemble are listed as boundary face-threads with the • F_CENTROID(x, f, t) x, y, z-coords of centroid
Nodes
fluid & solid cell-threads under Define- • F_AREA(A, f, t) vector of a
• NV_MAG(A) Area-magnitude
Boundary_Condition panel Location of cell variables
• C_VOLUME(c, t) Volume of a C_CENTROID(X,c,t); X: X[3]
Those faces which are inside the flow-domain and do not • C_VOLUME_2D(c, t) Volume of a 2D C_NNODES(c,t) = 8
share any external boundary are not accessible from GUI (Depth is 1m in 2D; 2*π m in axi-symmetric solver )C_NFACES(c,t) = 6
F_NNODES(f,t) = 4 each
• NODE_X(nn) x-coord; nn is a node pointer
(because you do not need them)
• NODE_Y(nn) x-coord;
They can still be accessed from User-Defined-Functions • NODE_Z(nn) x-coord;
Many more are available. See the FLUENT UDF Manual

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-13 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-16 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Fluent UDF Data Structure Summary Macros for Cell Variables

The data structure for accessing a cell zone is typed as ‘cell_t’

(the cell thread index); the data structure for faces is typed as • C_R(c,t) Density
‘face_t’ (the face thread index) • C_P(c,t) Pressure
• C_U(c,t)
Boundary face-thread • C_V(c,t) Velocity components
Fluid cell-thread the boundary-face ensemble
the Control-volume
• C_W(c,t)
ensemble Internal face-thread • C_T(c,t) Temperature
the Internal-face ensemble • C_H(c,t) Enthalpy
associated to cell-threads
Nodes • C_K(c,t) Turbulent kinetic energy
• C_D(c,t) Turbulent energy dissipation
• C_YI(c,t,i) Species mass fraction
Type Example Declaration
Domain *d d is a pointer to domain thread • C_UDSI(c,t,i) User defined scalar
Thread *t t is a pointer to thread t is a cell-thread pointer, c is a cell thread index, i is an integer
cell_t c c is cell thread index
face_t f f is a face thread index for indexing
Node *node node is pointer to a node

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-14 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-17 Inventory #002686

Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Fluent UDF Data Structure Summary (2) Macros for Cell Variables (2)
• More cell variables
• Each thread (zone) has a unique integer ID
available in the boundary condition panel (or can • C_DUDX(c,t)
be listed by the list-zone TUI command: • C_DUDY(c,t)
/grid/modify-zones/list-zones) • C_DUDZ(c,t)
• C_DVDX(c,t)
• Given a correct ID, the Lookup_Thread macro
• C_DVDY(c,t) Velocity derivatives
can retrieve the thread pointer • C_DVDZ(c,t)
int ID=7; • C_DWDX(c,t)
Thread *tf=Lookup_Thread(domain, ID); • C_DWDY(c,t)
• Conversely, given a thread pointer tf, the zone ID • C_DWDZ(c,t)
can be retrieved • C_MU_L(c,t) Laminar viscosity
• C_MU_T(c,t) Turbulent viscosity
ID=THREAD_ID(tf);
• C_MU_EFF(c,t)
• Once we have the correct pointer (for a specific • C_DP(c,t)[i] Pressure derivatives
zone), we can access the members belonging to • C_D_DENSITY(c,t)[i] Density derivatives
the zone without any problem. Thread pointer
provides the leading address of the thread (zone)

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-15 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-18 Inventory #002686
Introduction to UDF and FLUENT Data Structure Introduction to UDF and FLUENT Data Structure

Loop Macros in UDF The Header Files

The udf-macros are defined in the ‘udf.h’ file
udf.h is a fluent header file in the {Fluent installed
thread_loop_c(ct,d) { } for loop over cell threads in domain d directory}/Fluent12.y/src/ directory
thread_loop_f(ft,d) { } for loop over face threads in domain d udf.h must be included at the top in each and every udf file
A file may contain more than one UDF
(Note: ct, ft and d are pointers to Thread) User can use multiple files for UDF
Any UDF you might write must use one of the ‘DEFINE_…’ macros from
begin_c_loop(c, t) this udf.h file
{…} There are many more header files stored in the same directory can be
browsed by users
end_c_loop (c,t) for loop over cells in a given cell thread t
#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)
begin_f_loop(f, f_thread) #define DEFINE_SOURCE(name, c, t, dS, i) \
real name(cell_t c, Thread *t, real dS[], int i)
{…}
#define DEFINE_INIT(name, domain) void name(Domain *domain)
end_f_loop(f, f_thread) for loop over all faces in a given #define DEFINE_ADJUST(name, domain) void name(Domain *domain)
face thread f_thread #define DEFINE_DIFFUSIVITY(name, c, t, i) \
real name(cell_t c, Thread *t, int i)

ANSYS, Inc. Proprietary April 30, 2009 ANSYS, Inc. Proprietary April 30, 2009
© 2009 ANSYS, Inc. All rights reserved. 1-19 Inventory #002686 © 2009 ANSYS, Inc. All rights reserved. 1-22 Inventory #002686

Introduction to UDF and FLUENT Data Structure

Macros for Accessing Cells/Faces

• For any given face, the cell from which the
face normal vector points away is called the C0
cell; and the cell which the face normal vector
points at is called the C1 cell. The following
program fragment calculate the total cell
volume next to a given face zone with zone ID
on the C0 side:
C0
Thread *tf, *t0;
face_t f;
cell_t c0; C1
real totalV=0.;
tf = Lookup_Thread(domain, ID);
t0 = THREAD_T0(tf); a face normal
begin_f_loop(f, tf) vector for the C0 cell
{ c0=F_C0(f, tf); /*get the c0 thread */
totalV += C_VOLUME(c0, t0);
}
end_f_loop(f, tf)

ANSYS, Inc. Proprietary April 30, 2009

© 2009 ANSYS, Inc. All rights reserved. 1-20 Inventory #002686

Introduction to UDF and FLUENT Data Structure

Top-Level UDF Macros

• User’s own codes must use the top-level UDF macros in order to
communicate with the FLUENT solver
Profiles DEFINE_PROFILE
Source terms DEFINE_SOURCE
Properties DEFINE_PROPERTY
User-defined Scalars DEFINE_UNSTEADY
DEFINE_FLUX
DEFINE_DIFFUSIVITY
Initialization DEFINE_INIT
Global Functions DEFINE_ADJUST
DEFINE_ON_DEMAND
DEFINE_RW_FILE
Wall-heat-flux DEFINE_HEAT_FLUX
Model-Specific Functions DEFINE_DPM_…
DEFINE_SR_RATE
DEFINE_VR_RATE
…
Refer to the UDF Manual for a complete list

ANSYS, Inc. Proprietary April 30, 2009

© 2009 ANSYS, Inc. All rights reserved. 1-21 Inventory #002686