10. User-Defined Functions¶
User-Defined Functions (UDFs) are source files in the same directory as the project file that define code that is called by specific locations in the main MFiX code. UDFs are used to customize the behavior of MFiX. One common usage is for creating user-specific output files. In many cases, creating a personalized UDF is preferable to using postmfix.
Because MFiX is open source, users may modify any *.f
or *.inc
file
under the model directory.
To modify a file, first copy it from the model directory into the run directory. All
modifications should be made to the file in the run directory. For example, list
the contents of the adiabaticFlame
test case located in the legacy_tests
directory.
Legacy tests can be found by downloading the source tarball. They are meant to provide representative setups for older versions of MFiX (before the launch of the GUI), and are not guaranteed to run with the latest version of MFiX.
> cd tutorials/tfm/silane_pyrolysis_2d
> ls
SP2D.mfx usr0.f usr1.f usr_mod.f usr_rates.f
The SP2D.mfx
file is the project file, and the usr*.f
files are the UDFs used by this project.
simulation. After running build_mfixsolver
, a re-examination of the same folder reveals:
> build_mfixsolver
...long output...
> ls
Makefile build mfixsolver usr.mod usr0.f usr1.d usr1.o usr_mod.f usr_rates.d usr_rates.o
SP2D.mfx lib species.inc usr0.d usr0.o usr1.f usr_mod.d usr_mod.o usr_rates.f
Each UDF has a corresponding dependency (.d
) file and object (.o
) file.
If a project has a usr_rates.f
UDF, an additional species.inc
file is generated from
the project file during the reaction preprocessing step of the build.
The .d
and .o
files are intermediate dependency and object files that are
created and linked with the executable, mfix.
The following is a list of MFIX files that are usually modified to include user defined scalars, user defined drag models, and chemical reactions, physical properties, and source terms for the governing equations:
File Name: |
Usage Description |
|
Properties and source terms in scalar transport equations |
|
User-defined drag function |
|
Chemical reaction rates |
|
DES chemical reaction rates |
|
Physical properties (density, specific heat, etc.) |
|
Governing equation source terms |
The following routines are used for writing user-defined output:
File Name: |
Usage Description |
|
|
|
Called at intervals defined by USR_DT |
To activate the calls to the following routines, make sure the “Enable user-defined subroutines” checkbox is checked in the Model pane.
File Name: |
Usage Description |
---|---|
|
Subroutine that is called once every run, just before the time-loop begins. |
|
Subroutine that is called once every timestep. |
|
Subroutine that is called once every iteration. |
|
Subroutine that is called once every run, after the time-loop ends. |
|
List of user-defined keywords. These may be used to enter data through the input data file mfix.dat. |
|
Initialize user-defined keywords. |
|
User-defined module. Include |
|
Subroutine called before entering the DES time loop. [1] |
|
Subroutine called every DEM timestep after calculating DES source terms but before source terms are applied to the particles. |
|
Subroutine called every DES timestep after source terms are applied to the particles. |
|
Subroutine that is called after completing the DES time loop. |
The following figures illustrate the local call structure for UDFs, for typical TFM/PIC and DEM runs:
DES User-defined subroutines call structure:
Note that the USR_
keywords do not have any explicit behavior. They are only basic
input mechanisms to interact with user-defined functions. For example,
specifying USR_X_w
does not result in the associated I
index, USR_I_W
being calculated. It is upon the user to ensure that all user-hooks are fully
specified.