Chapter 7.

Interpreting UDF Source Files

Once you have written your UDF using any text editor and have saved it with a .c extension in your working directory, you are now ready to interpret it. Follow the instructions in Section 7.2: Interpreting a UDF Source File Using the Interpreted UDFs Panel to interpret your UDF source le. Once interpreted, the UDF function name(s) will appear in drop-down lists in graphical panels in FLUENT, ready for you to hook to your CFD model. Alternatively, you can compile your UDF source le. See Chapter 8: Compiling UDF Source Files for details. Section 7.1: Introduction Section 7.2: Interpreting a UDF Source File Using the Interpreted UDFs Panel Section 7.3: Common Errors Made While Interpreting A Source File Section 7.4: Special Considerations for Parallel FLUENT

7.1

Introduction
An interpreted UDF is a function that is interpreted directly from a source le (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 le (e.g., udfexample.c) in a single step. Once a source le is interpreted, you can write the case le 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 le is subsequently read. Once interpreted (either manually through the Interpreted UDFs panel or automatically upon reading a case le), all of the interpreted UDFs that are contained within a source le 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 eortlessly between dierent architectures, operating systems, and FLUENT versions. If execution speed does become an issue, an interpreted UDF can always be run in compiled mode without modication.

c Fluent Inc. January 11, 2005

7-1

Interpreting UDF Source Files

7.1.1

Location of the udf.h File

UDFs are dened using DEFINE macros (see Chapter 4: Dening a UDF Using a DEFINE Macro) and the denitions for DEFINE macros are included in udf.h header le. Consequently, before you can interpret a UDF source le, udf.h will need to be accessible in your path, or saved locally within your working directory. The location of the udf.h le 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).

In general, you should not copy udf.h from the installation area. The compiler is designed to look for this le locally (in your current directory) rst. 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 le. You should not, under any circumstances, alter the udf.h le.

i
7.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

7-2

c Fluent Inc. January 11, 2005

7.2 Interpreting a UDF Source File Using the Interpreted UDFs Panel

7.2

Interpreting a UDF Source File Using the Interpreted UDFs Panel

This section presents the steps for interpreting a source le in FLUENT. Once interpreted, the names of UDFs contained within the source le will appear in drop-down lists in graphics panels in FLUENT. The general procedure for interpreting a source le is as follows: 1. Make sure that the UDF source le is in the same directory that contains your case and data les.

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 les 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 working 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 le. 4. Open the Interpreted UDFs panel (Figure 7.2.1). Dene User-Dened Functions Interpreted...

Figure 7.2.1: The Interpreted UDFs Panel

c Fluent Inc. January 11, 2005

7-3

Interpreting UDF Source Files

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

Figure 7.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/), and the desired le (e.g., udfexample.c) under Files. Once highlighted, the complete path to the source le will be displayed under Source File(s). Click OK The Select File panel will close and the complete path to the le you selected (e.g., udfexample.c) will appear under Source File Name in the Interpreted UDFs panel (Figure 7.2.1).

If you are running FLUENT on a network of Windows machines, you may need to type the les complete path in the Source File Name eld, 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

7-4

c Fluent Inc. January 11, 2005

7.2 Interpreting a UDF Source File Using the Interpreted UDFs Panel

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

7. 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 Contributed 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 overow. 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 language 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. 10. Click Interpret to interpret your UDF. The results of the interpretation will be displayed in the console window. You can also view the compilation history in the log le that is saved in your working directory. The console message for a successful interpretation of a UDF named inlet x velocity is shown below.

c Fluent Inc. January 11, 2005

7-5

Interpreting UDF Source Files

inlet 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

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.

11. Close the Interpreted UDFs panel when the interpreter has nished. 12. Write the case le 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 subsequently read. If the Display Assembly Listing option was chosen, then the assembly code will appear in the console window.

7-6

c Fluent Inc. January 11, 2005

7.3 Common Errors Made While Interpreting A Source File

7.3

Common Errors Made While Interpreting A Source File

If there are compilation errors when you interpret a UDF source le, they will appear in the console window. However, you may not see all the error messages if they scroll o the screen too quickly. For this reason, you may want to turn o the Display Assembly Listing option while debugging your UDF. You can view the compilation history in the log le 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 le in the editor window before trying to interpret again. One of the more common errors made when interpreting source les is trying to interpret code that contains elements of C that the interpreter does not accommodate. For example, 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

7.4

Special Considerations for Parallel FLUENT

If you are running the parallel version of FLUENT on a Windows network and you encounter errors when trying to interpret a source le, 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 dened locally instead, the following error message will be reported when you try to interpret a source le: Warning: unable to run cpp You will need to see your system administrator to reset the FLUENT INC environment variable.

c Fluent Inc. January 11, 2005

7-7

Interpreting UDF Source Files

7-8

c Fluent Inc. January 11, 2005