Chapter 4.

Interpreting UDFs

Once you have written your UDF using any text editor and have saved the source code file
it with a .c extension in your working directory, you are ready to interpret the source file.
Follow the instructions below in Section 4.2: Interpreting a UDF Source File Using the
Interpreted UDFs Panel. Once interpreted, the UDF function name(s) that you supplied
in the DEFINE macro(s) will appear in drop-down lists in graphical panels in FLUENT,
ready for you to hook to your CFD model. Alternatively, if you wish to compile your
UDF source file, see Chapter 5: Compiling UDFs for details.

• Section 4.1: Introduction

• Section 4.2: Interpreting a UDF Source File Using the Interpreted UDFs Panel

• Section 4.3: Common Errors Made While Interpreting A Source File

• Section 4.4: Special Considerations for Parallel FLUENT

4.1 Introduction
An interpreted UDF is a function that is interpreted directly from a source file (e.g.,
udfexample.c) at runtime. The process involves a visit to the Interpreted UDFs panel
where you can interpret all of the functions in a source file (e.g., udfexample.c) in a
single step. Once a source file is interpreted, you can write the case file and the names
and contents of the interpreted function(s) will be stored in the case. In this way, the
function(s) will be automatically interpreted whenever the case file is subsequently read.
Once interpreted (either manually through the Interpreted UDFs panel or automatically
upon reading a case file), all of the interpreted UDFs that are contained within a source
file will become visible and selectable in graphical user interface panel(s) in FLUENT.
Inside FLUENT, the source code is compiled into an intermediate, architecture-independent
machine code using a C preprocessor. This machine code then executes on an internal
emulator, or interpreter, when the UDF is invoked. This extra layer of code incurs a
performance penalty, but allows an interpreted UDF to be shared effortlessly between
different architectures, operating systems, and FLUENT versions. If execution speed
does become an issue, an interpreted UDF can always be run in compiled mode without
modification.

c Fluent Inc. September 11, 2006 4-1
Interpreting UDFs

4.1.1 Location of the udf.h File

UDFs are defined using DEFINE macros (see Chapter 2: DEFINE Macros) and the defi-
nitions for DEFINE macros are included in udf.h header file. Consequently, before you
can interpret a UDF source file, udf.h will need to be accessible in your path, or saved
locally within your working directory.
The location of the udf.h file is:
⇓
path/Fluent.Inc/fluent6.x/src/udf.h

where path is the directory in which you have installed the release directory, Fluent.Inc,
and x is replaced by the appropriate number for the release you have (e.g., 2 for
fluent6.2).

i In general, you should not copy udf.h from the installation area. The
compiler is designed to look for this file locally (in your current directory)
first. If it is not found in your current directory, the compiler will look
in the /src directory automatically. In the event that you upgrade your
release area, but do not remove an old copy of udf.h from your working
directory, you will not be accessing the most recent version of this file.

i You should not, under any circumstances, alter the udf.h file.

4.1.2 Limitations
Due to limitations in the interpreter used to compile interpreted UDF source code in
FLUENT, interpreted UDFs are limited in their use of the C programming language. In
particular, the following elements of C cannot be used in interpreted UDFs:

• goto statements
• non ANSI-C prototypes for syntax
• direct data structure references
• declarations of local structures
• unions
• pointers to functions
• arrays of functions
• multi-dimensional arrays

4-2
c Fluent Inc. September 11, 2006
 4.2 Interpreting a UDF Source File Using the Interpreted UDFs Panel

4.2 Interpreting a UDF Source File Using the Interpreted UDFs Panel
This section presents the steps for interpreting a source file in FLUENT. Once interpreted,
the names of UDFs contained within the source file will appear in drop-down lists in
graphics panels in FLUENT.
The general procedure for interpreting a source file is as follows:

1. Make sure that the UDF source file is in the same directory that contains your case
and data files.

i If you are running the parallel version of FLUENT on a network of Windows

machines, you must ‘share’ the working directory that contains your UDF
source, case, and data files so that all of the compute nodes in the cluster
can see it. To do this:
(a) Open the Windows Explorer application, right click on the folder for the work-
ing directory (e.g., mywork), select the Sharing... option, and specify a Share
Name (e.g., mywork).
2. Start FLUENT from your working directory.
3. Read (or set up) your case file.
4. Open the Interpreted UDFs panel (Figure 4.2.1).
Define −→ User-Defined −→ Functions −→ Interpreted...

Figure 4.2.1: The Interpreted UDFs Panel

5. In the Interpreted UDFs panel, select the UDF source file you want to interpret by
either typing the complete path in the Source File Name field or click Browse....
This will open the Select File panel (Figure 4.2.2).

c Fluent Inc. September 11, 2006 4-3
Interpreting UDFs

Figure 4.2.2: The Select File Panel

6. In the Select File panel, highlight the directory path under Directories
(e.g., /nfs/homeserver/home/clb/mywork/ when running Linux), and the desired
file (e.g., udfexample.c) under Files. Once highlighted, the complete path to the
source file will be displayed under Source File(s). Click OK.
The Select File panel will close and the complete path to the file you selected (e.g.,
udfexample.c) will appear under Source File Name in the Interpreted UDFs panel
(Figure 4.2.1).

i If you are running FLUENT on a network of Windows machines, you may

need to type the file’s complete path in the Source File Name field, instead
of using the browser option. For example, to interpret udfexample.c that
is located in a shared working directory named mywork, you would enter
the following:

\\<fileserver>\mywork\udfexample.c

i This text goes into the Source File Name field in the
Interpreted UDFs panel, replacing <fileserver> with the name of
the computer on which your working directory (mywork) and source file
(udfexample.c) are located.

4-4
c Fluent Inc. September 11, 2006
 4.2 Interpreting a UDF Source File Using the Interpreted UDFs Panel

7. In the Interpreted UDFs panel, specify the C preprocessor to be used in the CPP
Command Name field. 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.

8. Keep the default Stack Size setting of 10000, unless the number of local variables
in your function will cause the stack to overflow. In this case, set the Stack Size to
a number that is greater than the number of local variables used.

9. 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 file, so that when you read the case in a subsequent
FLUENT session, the assembly code will be automatically displayed.

10. Click Interpret to interpret your UDF.

If the compilation is successful and you choose to Display Assembly Listing then
the assembler code is printed on the console window. If you chose not to display
the listing and the compilation is successful then the CPP Command Name that
was executed will appear on the console. If the compilation is unsuccessful, then
FLUENT will report an error and you will need to debug your program. See Sec-
tion 4.3: Common Errors Made While Interpreting A Source File. You can also
view the compilation history in the ‘log’ file that is saved in your working directory.

11. Close the Interpreted UDFs panel when the interpreter has finished.

12. Write the case file if you want the interpreted function(s) (e.g., inlet x velocity)
to be saved with the case, and automatically interpreted when the case is subse-
quently read. If the Display Assembly Listing option was chosen, then the assembly
code will appear in the console window.

c Fluent Inc. September 11, 2006 4-5
Interpreting UDFs

4.3 Common Errors Made While Interpreting A Source File

If there are compilation errors when you interpret a UDF source file, they will appear in
the console window. However, you may not see all the error messages if they scroll off
the screen too quickly. For this reason, you may want to turn off the Display Assembly
Listing option while debugging your UDF. You can view the compilation history in the
’log’ file that is saved in your working directory.
If you keep the Interpreted UDFs panel open while you are in the process of debugging
your UDF, the Interpret button can be used repeatedly since you can make changes with
an editor in a separate window. Then, you can continue to debug and interpret until
no errors are reported. Remember to save changes to the source code file in the editor
window before trying to interpret again.
One of the more common errors made when interpreting source files is trying to interpret
code that contains elements of C that the interpreter does not accommodate. For exam-
ple, if you have code that contains a structured reference call (which is not supported by
the C preprocessor), the interpretation will fail and you will get an error message similar
to the following:

Error: /nfs/clblnx/home/clb/fluent/udfexample.c:
line 15: structure reference

4-6
c Fluent Inc. September 11, 2006
 4.4 Special Considerations for Parallel FLUENT

4.4 Special Considerations for Parallel FLUENT

If you are running the parallel version of FLUENT on a Windows network and you en-
counter errors when trying to interpret a source file, it could be the result of an improper
installation of cpp. Proper installation of parallel FLUENT for Windows ensures that
the FLUENT INC environment variable is set to the shared directory where FLUENT is
installed. If the variable is defined locally instead, the following error message will be
reported when you try to interpret a source file:

Warning: unable to run cpp

You will need to see your system administrator to reset the FLUENT INC environment
variable.

c Fluent Inc. September 11, 2006 4-7
Interpreting UDFs

4-8
c Fluent Inc. September 11, 2006