The Fluent preCICE adapter operates using Fluent's User-Defined Function (UDF) feature. UDFs are functions written in the C programming language that are dynamically loaded with the Fluent solver and can be used to enhance and generalize its standard features. For example, UDFs can be used to:
- Customize boundary conditions, material property definitions, or source functions.
- Customize different numerical/physics models being employed: multiphase mixture models, discrete phase models, radiation models, chemical reaction models, diffusivity models, etc.
- Execute code at different stages of a solution: at solution initialization, at every iteration, upon reaching convergence, etc.
- Many other things, as long as one can code it in C.
Details about UDFs can be found in the UDF Manual provided by Ansys Fluent. A summary of the major requirements follows.
UDFs are identified by a *.c file extension (for example fsi_udf.c). UDFs must be defined using DEFINE macros supplied by Fluent. These macros are pre-defined functions that access the Fluent solver and perform other tasks. The *.c file containing the UDFs (fsi_udf.c) must contain an include statement for a udf header file (#include "udf.h"). The udf header file is provided with the Fluent application and will be found upon UDF execution. It contains the DEFINE macros, among other things.
Beyond this, the use of UDFs can be very general. For example, this preCICE adapter uses a very simple UDF file (fsi_udf.c) to handle fluid structure interaction coupling. The file contains only 4 DEFINE macros, each containing a single function that is sourced from the header file fsi.h and are written in fsi.c.
The user-written source code for the UDFs can either be compiled or interpreted in Ansys Fluent through the Fluent GUI. We are using external functions from the preCICE source code, so we have to compile our UDFs. There appears to be no way to inform Fluent of the existance of external libraries when compiling through the GUI. We need some preCICE functions in our UDFs, so we are going to have to compile these UDFs outside of the Fluent GUI. When one uses the GUI to compile Fluent UDFs, though, it dynamically writes files based on user inputs: a Makefile, a text file called user.udf, and a C-file called udf_names.c. Fluent also requires a certain directory structure wherein specific files must be placed. If this directory structure isn't strictly followed the UDFs (even if compiled correctly) will not be loaded into the simulation at run time.
The end result of compiling the UDF(s) for use in a Fluent simulation is a UDF shared library called libudf.so. This library and the compiled code and source code used to build it must exist in a specific directory structure. The same directory that contains the *.cas file should contain a directory in it called libudf/. Within this directory, a sub-directory called lnamd64/ must exist. The name lnamd64/ actually depends on your system architecture, but because we are building this on a Linux system, we'll stick with lnamd64/. If the Fluent run is to be executed in serial, the compiled library (libudf.so) should exist within a sub-directory of lnamd64/. The name of the sub-directory is dependent on whether the simulation is 2D or 3D and whether it is run in single precision or double precision. The following list contains the names for the different simulations that can be run:
2d: Two dimensional, single precision simulation.3d: Three dimensional, single precision simulation.2ddp: Two dimensional, double precision simulation.3ddp: Three dimensional, double precision simulation.
If the simulation is to be run in parallel, two sub-directories of lnamd64/ need to exist, one with a _host suffix, and one with a _node suffix. A copy of the library libudf.so needs to exist in each sub-directory.
To summarize, the following directory structure needs to exist for a 2D, single precision FSI simulation run in serial:
fluent.cas
libudf
└── lnamd64
└── 2d
├── fsi_udf.c
├── fsi.c
├── fsi.h
├── user.udf
├── udf_names.c
├── makefile
├── fsi_udf.o
├── fsi.o
├── udf_names.o
├── libudf.soThe files are:
fsi_udf.c: user-written UDF file containing Fleunt'sDEFINEMacrosfsi.c: user-written UDF file containing custom C-functions that employ preCICE codefsi.h: user-written header file forfsi.cuser.udf: text file used to define file names to be compiled (fsi_udf.c,fsi.c, andfsi.h); sourced by makefile to user-written header file forfsi.c; user may have to edit this fileudf_names.c: will be auto-generated by Fluent GUI; do not edit this file!makefile: instructions to create proper compile commands; may have to be edited by user to include proper directoriesfsi_udf.o: compiled object file fromfsi_udf.cfsi.o: compiled object file fromfsi.cudf_names.o: compiled object file fromudf_names.clibudf.so: shared library file that Fluent uses
The following directory structure needs to exist for a 2D, double precision simulation run in parallel:
fluent.cas
libudf
└── lnamd64
└── 2ddp_host
| ├── fsi_udf.c
| ├── fsi.c
| ├── fsi.h
| ├── user.udf
| ├── udf_names.c
| ├── makefile
| ├── fsi_udf.o
| ├── fsi.o
| ├── udf_names.o
| ├── libudf.so
└── 2ddp_node
├── fsi_udf.c
├── fsi.c
├── fsi.h
├── user.udf
├── udf_names.c
├── makefile
├── fsi_udf.o
├── fsi.o
├── udf_names.o
├── libudf.so Please note that the _node directory and _host directory are copies of one another. Also, the makefile, source files, and intermediary object files (*.o) are not necessarily required to be in this directory structure. They are kept here just for convenience. The libudf.so file is the only thing required to be read by Fluent.
It is recommended to follow the instructions from the Fluent documentation to build a UDF with or without the GUI.
Alternatively, you may use the following instructions (for ANSYS 2025 R1).
Directory structure:
- Adapt
lnamd64/2ddp_host/user.udf- change
CSOURCES=...to include a space-separated list of*.csource files to be compiled; for the FSI case we're building this should befsi_udf.candfsi.c - change
HSOURCES=...to include a space-separated list of*.hsource header files to be compiled; for the FSI case we're building this should befsi.h - change
FLUENT_INC=...to point to the Fluent install directory. Usewhich fluentto determine the path of yourfluentexecutable. Usually the executable is located at$FLUENT_INC/bin/fluent. Example: Ifwhich fluentreturns/some/path/ansys/v251/fluent/bin/fluent, useFLUENT_INT=/some/path/ansys/v251/fluent
- change
- Adapt
lnamd64/2ddp_host/makefile- In order to get the makefile please follow the instruction from Ansys
- change
USER_OBJECTSvariable (line 20) to be a space separated list of the absolute path tolibprecice.soand the Python library shipped with Fluent:- You can use
pkg-config --libs-only-L libpreciceto determine the location oflibprecice.so. Ifpkg-config --libs-only-L libprecicereturns-L/some/path/precice/libplease use/some/path/precice/lib/libprecice.so. - The Python library can be found in the Fluent installation files. Use
which fluentto determine the path/some/path/ansys/v251/fluent/bin/fluent. The Python library is located at/some/path/ansys/v251/commonfiles/CPython/3_10/linx64/Release/python/lib/libpython3.so(you might have to replace3_10with a different number).
- You can use
- change
RELEASEvariable to be the Ansys release version; for example,RELEASE=25.1.0
- Open a terminal in the directory
fluent-adapter/lnamd64/2ddp_host - To build
libudf.soexecutemake "FLUENT_ARCH=lnamd64" - Clean the build using
make clean - Copy ALL of the contents of
lnamd64/2ddp_host/tolnamd64/2ddp_node/
Instructions for ANSYS 2025 R1
Given that you already have a license, generating a makefile is quite straight forward.
- Open Fluent by running
fluent 2ddp - Open the tab "User-Defined" > "Functions" > "Compiled". This will open the window "Compiled UDFs".
- Add under "Source Files" the
.cfilesfluent-adapter/src/fsi_udf.candfluent-adapter/src/fsi.c. Note that thelibudffolder (we will need this later) will be generated in the folder where these files are located, i.e., influent-adapter/src/. - Add under "Header Files" the
.hfilefluent-adapter/src/fsi.h. - Ensure that under "Library Name" you use the name
libudf, then press "Build". This will create the folderfluent-adapter/src/libudf. - You can find the
makefilewe need for compiling our UDFs underfluent-adapter/src/libudf/lnamd64/2ddp_host/makefile.
Ubuntu 20.04 is not officially supported by Ansys and hence only the Fluent package works on this distribution. All other packages (Ansys Workbench, etc.) do not work and hence the case setup needs to be done on a different compatible operating system. Current compatible distributions for Ansys version 2019 R3 are: Ubuntu 16.04, CentOS 7.x, Linux Mint 18.x, Debian 9 (tested with 2019 R3, unknown for 2020 R2). Generally it is recommended to only install the required packages, since the installation process might break (tested with 2019 R3). Make sure to test your installation by starting fluent (see below). If Fluent crashes, see the troubleshooting hints.
- Before running the installation, you should install some libraries to allow the Ansys GUI to run smoothly:
sudo apt update
sudo apt install libxcb-xinerama0 libxcb-util1 libx11-xcb1 libxcb-render0 libxcb-shape0 libxcb-shm0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0- Run:
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/- Right click on each of the disk images and select
Open With Disk Image Mounter - Go to the first Disk and run
sudo ./INSTALLthis will allow the installer to write files and not run into permission denied error - Enter the corresponding Port and Hostname for the License.
- During installation you will be asked to enter the 2nd and 3rd Disk, just go to the mounter disks and copy paste the address to the corresponding disk.
- To make sure that the installation finished with no errors, go to installation directory for example
/usr/ansys_incand there should be not install.log.err - After installation you might need to run
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH://ansys_inc/v232/tp/qt/5.9.6/linx64/libif you run into a problem related to Ans.QT.dll while launching the workbench.
- Run
./INSTALLfrom the Ansys directory and follow steps of installation as seen in the GUI - The installation hangs between 80-90%. Close partially completed installation.
- Run
./INSTALLfrom the Ansys directory and follow steps of installation as seen in the GUI - The installation completes successfully.
- All packages of Ansys Version 2019 R3 work on Ubuntu 16.04 and this forum post describes the installation process.
- Ansys 2024 is not completely supported on Ubuntu yet, there are some dependency problems between the OS and the software and even if the installation is successfull you might run into problems while trying to work with the workbench, and according to this forum certain issues are never resolved. So reverting to Ansys 2023 is highly advised. Ansys 24 platform support describes which systems are supported for each version of Ansys
- If you try to start fluent via
fluent 2ddpand the program exits with the errorBad substitution, the following forum post provides a solution. Short:sudo dpkg-reconfigure dash, answer No to the questions "Use dash as the default system shell (/bin/sh)?". - If the error:
undefined symbol: FT_Done_MM_Varis encountered on starting Fluent, the following forum post has the solution.
In accordance with the preCICE documentation preCICE, PETSc (if used), and all solvers should run the same MPI implementation and version. So, we need to make sure that the version of preCICE we are running and Fluent use the same MPI. Unfortunately, we don't really know what implementation (Intel, OpenMPI, etc.) or version of MPI Fluent uses. However, Fluent can be made to run with any version and implementation of an MPI, within reason. Fluent does this using environment variables. To run with a version of OpenMPI set the environment variable OPENMPI_ROOT, and to run with a version of IntelMPI set the environment variable INTELMPI_ROOT. Upon execution, Fluent will append /bin/mpirun to this environment variable, so we should set whichever one we use to the corresponding path. For example, setting:
export OPENMPI_ROOT=/opt/Software/openmpi/3.1.4/mpirunor
export INTELMPI_ROOT=/opt/Software/intel_parallel_studio/2018u4/impi/2018.4.274/intel64will force Fluent to use a system MPI rather than the MPI it's packaged with. A note to the effect will be reflected in Fluent's output when the simulation is run.
NOTE:One attempt was made to run Fluent with openmpi/4.0.0, and this failed. This is presumably because Fluent is calling some older MPI commands that are since deprecated. Do not attempt to define both the OPENMPI_ROOT and INTELMPI_ROOT environment variables. This will just confuse things.
With this environment variable in place, we can now run fluent with or without the GUI, making sure to define the -mpi= argument such that it aligns with our environment variable definition.
All Ansys packages are installed in a folder ansys_inc/ at the location defined by the user during installation. The Fluent executable is located at /ansys_inc/vXXX/fluent/bin.
- serial:
fluent 2ddp -g < steer-fluent.txt - parallel:
fluent 2ddp -g -t4 -mpi=openmpi < steer-fluent.txt(-t4sets 4 processes for computations,steer-fluent.txtis a driver file for Fluent and is only written for convenience)
UDFs can be difficult to debug because they are interpreted within Fluent. Sometimes this leads to misleading statements and tracebacks upon crashing. Some instructions on how to use gdb to step through UDF code line-by-line are found here.
The initial version of this adapter was developed by Bernhard Gatzhammer as part of his doctoral dissertation [1].
Richard Hertrich [2] and Ishaan Desai worked on the adapter in the scope of their work under supervision of Benjamin Rodenberg.
Mike Tree contributed a considerable update of the adapter.
Khalil Hkiri updated the adapter to preCICE v3.
[1] Gatzhammer, Bernhard. Efficient and Flexible Partitioned Simulation of Fluid-Structure Interactions. PhD Thesis, Department of Informatics, Technical University of Munich, 2014. [2] Hertrich, Richard. MSE-Forschungspraktikum: Aktualisierung des preCICE-Fluent Adapters. Studienarbeit, Munich School of Engineering, Technical University of Munich, 2018.
This offering is not approved or endorsed by Ansys, Inc., producer and distributor of Ansys Fluent.