Chapter 3.

A Step-by-Step UDF Example

This chapter contains an example that utilizes a 7-step process to code a UDF and use
it eectively in your FLUENT model.
3.1 Process Overview
1. Dene your problem. (Section 3.1.1: Step 1: Dene Your Problem)
2. Create a C source code le. (Section 3.1.2: Step 2: Create a C Source File)
3. Start FLUENT and read in (or set up) the case le. (Section 3.1.3: Step 3: Start
FLUENT and Read (or Set Up) the Case File)
4. Interpret or compile the source le. (Section 3.1.4: Step 4: Interpret or Compile
the Source File)
5. Hook the UDF to FLUENT. (Section 3.1.5: Step 5: Hook Your UDF to FLUENT)
6. Run the calculation. (Section 3.1.6: Step 6: Run the Calculation)
7. Analyze the numerical solution and compare it to expected results. (Section 3.1.7: Step
7: Analyze the Numerical Solution and Compare to Expected Results)
To begin the process, youll need to dene the problem you wish to solve using a UDF
(Step 1). For example, suppose you want to use a UDF to dene a custom boundary
prole for your model. You will rst need to dene the set of mathematical equations
that describes the prole.
Next you will need to translate the mathematical equation (conceptual design) into a
function written in the C programming language (Step 2). You can do this using any
text editor. Save the le with a .c sux (e.g., udfexample.c) in your working directory.
Once you have written the C function, you are ready to start FLUENT and read in (or set
up) your case le (Step 3). You will then need to interpret or compile the source code,
debug it (Step 4), and then hook the function to FLUENT (Step 5). Finally youll run
the calculation (Step 6), analyze the results from your simulation, and compare them
to expected results (Step 7). You may loop through this entire process more than once,
depending on the results of your analysis. Follow the step-by-step process in the sections
below to see how this is done.
c Fluent Inc. January 11, 2005 3-1
A Step-by-Step UDF Example
3.1.1 Step 1: Dene Your Problem
The rst step in creating a UDF and using it in your FLUENT model involves dening
your model equation(s).
Consider the turbine vane illustrated in Figure 3.1.1. An unstructured grid is used to
model the ow eld surrounding the vane. The domain extends from a periodic boundary
on the bottom to an identical one on the top, a velocity inlet on the left, and a pressure
outlet on the right.
Grid
Turbine Vane (1551 cells, 2405 faces, 893 nodes)
Figure 3.1.1: The Grid for the Turbine Vane Example
A ow eld in which a constant x velocity is applied at the inlet will be compared with
one where a parabolic x velocity prole is applied. The results of a constant-velocity
applied eld (of 20 m/s) at the inlet are shown in Figures 3.1.2 and 3.1.3. The initial
constant-velocity eld is distorted as the ow moves around the turbine vane.
Now suppose that you want to impose a non-uniform x velocity to the turbine vane inlet,
which is described by the prole
v
x
= 20 20

y
0.0745

2
(3.1-1)
where the variable y is 0.0 at the center of the inlet, and extends to values of 0.0745 m
at the top and bottom. Thus the x velocity will be 20 m/s at the center of the inlet, and
0 at the edges.
3-2 c Fluent Inc. January 11, 2005
3.1 Process Overview
Contours of Velocity Magnitude (m/s)
Turbine Vane (1551 cells, 2405 faces, 893 nodes)
5.98e+01
5.42e+01
4.86e+01
4.30e+01
3.74e+01
3.19e+01
2.63e+01
2.07e+01
1.51e+01
9.54e+00
3.96e+00
Figure 3.1.2: Velocity Magnitude Contours for a Constant Inlet x Velocity
Velocity Vectors Colored By Velocity Magnitude (m/s)
Turbine Vane (1551 cells, 2405 faces, 893 nodes)
6.11e+01
5.52e+01
4.93e+01
4.34e+01
3.75e+01
3.16e+01
2.57e+01
1.98e+01
1.39e+01
7.96e+00
2.05e+00
Figure 3.1.3: Velocity Vectors for a Constant Inlet x Velocity
c Fluent Inc. January 11, 2005 3-3
A Step-by-Step UDF Example
To solve this type of problem, you can write a custom prole UDF and apply it to your
FLUENT model.
3.1.2 Step 2: Create a C Source File
Now that you have determined the equation that denes the UDF (Equation 3.1-1), you
can use any text editor to create a le containing C code that implements the function.
Save the source code le with a .c extension (e.g., udfexample.c) in your working
directory. The following UDF source code listing contains a single function, only. Your
source le can contain multiple concatenated functions.
Below is an example of how the equation derived in Step 1 (Equation 3.1-1) can be
implemented in a UDF. The functionality of the UDF is designated by the leading DEFINE
macro. Here, the DEFINE PROFILE macro is used to indicate to the solver that the code
proceeding it will provide prole information at boundaries. Other DEFINE macros will
be discussed later in this manual.
/**********************************************************************
udfexample.c
UDF for specifying a steady-state velocity profile boundary condition
**********************************************************************/
#include "udf.h" /* must be at the beginning of every UDF you write */
DEFINE_PROFILE(x_velocity,thread,index)
{
real x[ND_ND]; /* this will hold the position vector */
real y;
face_t f;
begin_f_loop(f,thread) /* loops over all faces in the thread passed
in the DEFINE macro argument */
{
F_CENTROID(x,f,thread);
y = x[1];
F_PROFILE(f,thread,index) = 20. - y*y/(.0745*.0745)*20.;
}
end_f_loop(f,thread)
}
The rst argument of the DEFINE PROFILE macro, x velocity, is the name of the UDF
that you supply. The name will appear in the boundary condition panel once the func-
tion is interpreted or compiled. Note that the UDF name you supply cannot contain
3-4 c Fluent Inc. January 11, 2005
3.1 Process Overview
a number as the rst character. The equation that is dened by the function will be
applied to all cell faces (identied by f in the face loop) on a given boundary zone
(identied by thread). The thread is dened automatically when you hook the UDF
to a particular boundary in the FLUENT graphical user-interface. The index is dened
automatically through the begin f loop utility. In this UDF, the begin f loop macro
(Section 6.2: Looping Macros) is used to loop through all cell faces in the boundary
zone. For each face, the coordinates of the face centroid are accessed by F CENTROID
(Section 5.2.4: Connectivity Variables). The y coordinate y is used in the parabolic
prole equation and the returned velocity is assigned to the face through F PROFILE.
begin f loop and F PROFILE (Section 6.4: Setting Face Variables Using F PROFILE) are
Fluent-supplied macros.
3.1.3 Step 3: Start FLUENT and Read (or Set Up) the Case File
Once you have created the source code for your UDF, you are ready to begin the problem
setup in FLUENT.
1. Start FLUENT from your working directory.
2. Read (or set up) your case le.
3.1.4 Step 4: Interpret or Compile the Source File
You are now ready to interpret or compile the prole UDF named x velocity) that you
created in Step 2 and is contained within the source le named udfexample.c. In general,
you must compile your function as a compiled UDF if the source code contains structured
reference calls or other elements of C that are not handled by the FLUENT interpreter.
To determine whether you should compile or interpret your UDF, see Section 1.6.1: Dif-
ferences Between Interpreted and Compiled UDFs.
c Fluent Inc. January 11, 2005 3-5
A Step-by-Step UDF Example
Interpret the Source File
Follow the procedure below to interpret your source le in FLUENT. For more information
on interpreting UDFs, see Chapter 7: Interpreting UDF Source Files.
i
Note that this step does not apply to Windows parallel networks. See
Section 7.2: Interpreting a UDF Source File Using the Interpreted UDFs
Panel for details.
1. Open the Interpreted UDFs panel.
Dene User-Dened Functions Interpreted...
Figure 3.1.4: The Interpreted UDFs Panel
3-6 c Fluent Inc. January 11, 2005
3.1 Process Overview
2. In the Interpreted UDFs panel, select the UDF source le by either typing the
complete path in the Source File Name eld or click Browse... to use the browser.
This will open the Select File panel (Figure 3.1.5).
Figure 3.1.5: The Select File Panel
3. In the Select File panel, highlight the directory path under
Directories (e.g., /nfs/homeserver/home/clb/mywork/), and the desired le
(e.g., udfexample.c) under Files, and click OK. This will close the Select File panel
and display the path to the selected source le in the Interpreted UDFs panel.
4. In the Interpreted UDFs panel, specify the C preprocessor to be used in the CPP
Command Name eld. You can keep the default cpp or you can select Use Con-
tributed CPP to use the preprocessor supplied by Fluent Inc.
If you installed the /contrib component from the PrePost CD, then by default,
the cpp preprocessor will appear in the panel. For Windows NT users, the standard
Windows NT installation of the FLUENT product includes the cpp preprocessor.
For Windows NT systems, if you are using the Microsoft compiler, then use the
command cl -E.
c Fluent Inc. January 11, 2005 3-7
A Step-by-Step UDF Example
i
Note that the default CPP Command Name is dierent for 2d and 3d cases.
The default preprocessor is cpp and cc -E for a 2d and 3d case, respec-
tively.
5. Keep the default Stack Size setting of 10000, unless the number of local variables
in your function will cause the stack to overow. In this case, set the Stack Size to
a number that is greater than the number of local variables used.
6. Keep the Display Assembly Listing option on if you want a listing of assembly lan-
guage code to appear in your console window when the function interprets. This
option will be saved in your case le, so that when you read the case in a subsequent
FLUENT session, the assembly code will be automatically displayed.
7. Click Interpret to interpret your UDF. If the Display Assembly Listing option was
chosen, then the assembly code will appear in the console window when the UDF
is interpreted, as shown below.
x_velocity:
.local.pointer thread (r0)
.local.int nv (r1)
0 .local.end
0 save
.local.int f (r3)
1 push.int 0
.local.pointer x (r4)
3 begin.data 8 bytes, 0 bytes initialized:
7 save
. .
. .
. .
156 pre.inc.int f (r3)
158 pop.int
159 b .L3 (22)
.L2:
161 restore
162 restore
163 ret.v
i
Note that if your compilation is unsuccessful, then FLUENT will report an
error and you will need to debug your program. See Section 7.3: Common
Errors Made While Interpreting A Source File for details.
8. Click Close when the interpreter has nished.
3-8 c Fluent Inc. January 11, 2005
3.1 Process Overview
9. Write the case le. The interpreted UDF, named x velocity, will be saved with
the case le so that the function will be automatically interpreted whenever the
case is subsequently read.
Compile the Source File
You can compile your UDF using the text user interface (TUI) or the graphical user
interface (GUI) in FLUENT. The GUI option for compiling a source le on a UNIX system
is discussed below. For details about compiling on other platforms (e.g., Windows) using
the TUI to compile your function, or for general questions about compiling UDFs in
FLUENT see Chapter 8: Compiling UDF Source Files.
1. Make sure that the UDF source le (e.g., udfexample.c) is in the same directory
that contains your case and data le.
2. Start FLUENT from your working directory.
3. Read (or set up) your case le.
4. Open the Compiled UDFs panel (Figure 3.1.6).
Dene User-Dened Functions Compiled...
Figure 3.1.6: The Compiled UDFs Panel
5. Click Add... under Source Files in the Compiled UDFs panel. This will open the
Select File panel (Figure 3.1.7).
c Fluent Inc. January 11, 2005 3-9
A Step-by-Step UDF Example
Figure 3.1.7: The Select File Panel
6. In the Select File panel under Directories, choose the directory path that contains
the C source le, and then under Files select the desired le (e.g., udfexample.c)
you want to compile. (Once selected, the complete path to the source le will
be displayed under Source File(s).) Click OK. The Select File panel will close and
the le you added will appear in the Source Files list in the Compiled UDFs panel.
Repeat the previous step to select the Header Files that need to be included in the
compilation.
7. In the Compiled UDFs panel, select the le that is listed under Source Files and type
the name of the shared library in the Library Name eld (or leave the default name
libudf). Click Build. This process will compile the code and will build a shared
library in your working directory for the architecture you are running on.
3-10 c Fluent Inc. January 11, 2005
3.1 Process Overview
As the compile/build process begins, a Warning dialog box will appear, reminding
you that the UDF source le must be in the directory that contains your case and
data les (i.e., your working directory). If you have an existing library directory
(e.g., libudf) then you will need to remove it prior to the build, to ensure that the
latest les are used. Click OK to close the dialog box and resume the compile/build
process. The results of the build will be displayed on the console window. You can
view the compilation history in the log le that is saved in your working directory.
i
If the compile/build is unsuccessful, then FLUENT will report an error
and you will need to debug your program before continuing. See Sec-
tion 8.6: Common Errors When Building and Loading a Shared Library
for a list of common errors.
8. Click Load to load the shared library into FLUENT. The console will report that
the library has been opened and the function (e.g., x velocity) loaded.
Opening library "libudf"...
Library "libudf/lnx86/2d/libudf.so" opened
x_velocity
Done.
See Chapter 8: Compiling UDF Source Files for more information on the com-
pile/build process.
c Fluent Inc. January 11, 2005 3-11
A Step-by-Step UDF Example
3.1.5 Step 5: Hook Your UDF to FLUENT
Now that you have interpreted or compiled your UDF following the methods outlined in
Step 4, you are ready to hook the function to FLUENT using a graphical user interface
panel. The name you supplied in the DEFINE macro argument (e.g., x velocity) will
appear in graphics panels in FLUENT. You will hook the prole UDF in this sample
problem to the Velocity Inlet boundary condition panel.
1. Open the Velocity Inlet panel.
Dene Boundary Conditions...
Figure 3.1.8: The Velocity Inlet Panel
2. In the drop-down list for X-Velocity, choose udf x velocity, the name that was given
to the function in our sample problem. Once selected, the UDF will be used in the
calculation, and the default value will be grayed-out in the X-Velocity eld. Click
OK to accept the new boundary condition and close the panel.
3.1.6 Step 6: Run the Calculation
Run the calculation as usual.
Solve Iterate...
3-12 c Fluent Inc. January 11, 2005
3.1 Process Overview
3.1.7 Step 7: Analyze the Numerical Solution and Compare to Expected
Results
Once the solution is run to convergence, obtain a revised velocity eld. The velocity
magnitude contours for the parabolic inlet x velocity are shown in Figure 3.1.9, and
can be compared to the results of a constant-velocity eld of 20 m/sec (Figure 3.1.2).
For the constant velocity condition, the ow eld is distorted as the ow moves around
the turbine vane. The velocity eld for the imposed parabolic prole, however, shows a
maximum at the center of the inlet, which drops to zero at the edges.
Contours of Velocity Magnitude (m/s)
Turbine Vane (1551 cells, 2405 faces, 893 nodes)
4.46e+01
4.05e+01
3.64e+01
3.23e+01
2.83e+01
2.42e+01
2.01e+01
1.60e+01
1.19e+01
7.78e+00
3.68e+00
Figure 3.1.9: Velocity Magnitude Contours for a Parabolic Inlet x Velocity
c Fluent Inc. January 11, 2005 3-13
A Step-by-Step UDF Example
3-14 c Fluent Inc. January 11, 2005