You are on page 1of 22

Fluent Software Training

TRN-99-003

User Defined Functions

G1 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Introduction
u What is a User Defined Function?
l A UDF is a routine (programmed by the user) written in C which can be
dynamically linked with the solver.
n Standard C functions
s e.g., trigonometric, exponential, control blocks, do-loops, file i/o, etc.

n Pre-Defined Macros
s Allows access to field variable, material property, and cell geometry data.

u Why build UDF’s?


l Standard interface cannot be programmed to anticipate all needs.
n Customization of boundary conditions, source terms, reaction rates, material
properties, etc.
n Adjust functions (once per iteration)
n Execute on Demand functions
n Solution Initialization

G2 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

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

G3 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Using UDFs in the Solvers


u 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. 2/20/01


Fluent Software Training
TRN-99-003

Example: Non-Uniform Inlet Velocity


u 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. 2/20/01


Fluent Software Training
TRN-99-003

Example: Source Code


u The DEFINE_PROFILE macro allows #include "udf.h"
the function inlet_x_velocity to
DEFINE_PROFILE(inlet_x_velocity, thread, nv)
be defined. {
l All UDFs begin with a DEFINE_ float x[3]; /* this will hold the position
vector*/
macro. float y;
l inlet_x_velocity will be face_t f;

identifiable in solver GUI. begin_f_loop(f, thread)


{
u thread and nv are dynamic F_CENTROID(x,f,thread);
references, input to the UDF to y = x[1];
F_PROFILE(f, thread, nv) =
identify the zone and variable 20.*(1.- y*y/(.0745*.0745));
being defined, respectively. }
end_f_loop(f, thread)
u The macro begin_f_loop loops }
over all faces, f, on thread.
u The F_CENTROID macro assigns cell position vector to x[].
u The F_PROFILE macro applies the velocity component to face f.

G6 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Example: Interpreting the UDF


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

G7 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Example: Activating the UDF


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

G8 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Example: Run the Calculation


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

G9 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Example: Numerical Solution


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

G10 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

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

G11 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

DEFINE Macros
u Any UDF you write must begin with a DEFINE macro:
l 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. 2/20/01


Fluent Software Training
TRN-99-003

Looping and Thread 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

Thread *tf = Lookup_Thread(domain, ID); return thread pointer of integer ID of zone


THREAD_ID(tf); returns zone integer ID of thread pointer

Code enclosed in {} is executed in loop.

G13 © Fluent Inc. 2/20/01


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
NV_MAG(x); returns magnitude of vector x[]

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. 2/20/01


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. 2/20/01


Fluent Software Training
TRN-99-003

Face Field Variable Macros

u Face field variables are only available when using the segregated
solver and generally, only at exterior boundaries.
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. 2/20/01


Fluent Software Training
TRN-99-003

Other UDF Applications


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

G17 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

User Defined Memory


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

G18 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

User Defined Scalars


u FLUENT can solve (up to 50) generic transport
equations for User Defined Scalars, fk:
∂φ k ∂  ∂φ k 
+ 
 Fiφk − Γk  = Sφk k = 1, …, Nscalars
∂t ∂xi  ∂xi 
u User specifies:
DefineÕModelsÕUser-Defined Scalars…
l Number of User-Defined Scalars
l Flux Function, F
n DEFINE_UDS_FLUX(name,face,thread,index)
n DEFINE_UDS_UNSTEADY(name,cell,thread,index,apu,su)
n ‘case’ statement can be used to associate multiple flux and transient functions
with each UDS.
u Example
l Can be used to determine magnetic and/or electric field in a fluid zone.
G19 © Fluent Inc. 2/20/01
Fluent Software Training
TRN-99-003

User Defined Scalars (2)


u User must also specify:
l Source terms, Sf
l Diffusivity, Gf
n case statement needed to define
UDF diffusivities for each UDS.
l Boundary Conditions for each UDS.
n Specified Flux or Specified Value.
u Define as constant or with UDF.

G20 © Fluent Inc. 2/20/01


Fluent Software Training
TRN-99-003

Interpreted vs. Compiled UDF’s


u 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.
u Interpreted vs. compiled code
l Interpreter -
n Interpreter is a large program that sits in the computer’s memory.
n Executes code on a “line by line” basis instantaneously
n Advantages - does not need a separate compiler
n Disadvantage - slow and takes up space in memory
l Compiler (refer to User’s Guide for instructions)-
n Code is translated “once” into machine language (object modules).
n Efficient way to run UDF’s. Uses Makefiles
n Creates “shared libraries” which are linked with the rest of the solver
n Overcomes interpreter limitations e.g. mixed mode arithmetic, structure
references etc.
G21 © Fluent Inc. 2/20/01
Fluent Software Training
TRN-99-003

Supporting UDF’s
u 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.
l Support will be limited to guidance related to communication between a
UDF and the FLUENT solver.
l 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.
n Consulting option

G22 © Fluent Inc. 2/20/01

You might also like