8.4. Frequently Asked Questions

This document explains how to perform common tasks with MFiX.

8.4.1. How do I ask question, or send feedback?

Please send specific questions and feedback regarding the GUI to the support forum. Please include your version info in all communications (Menu –> About and press the “Copy Version Info” button). Other technical questions regarding MFiX can be sent to the support forum.

8.4.2. How do I change the look & feel of the GUI?

Go to the Settings pane and change the style from the pull down menu.

8.4.3. MFiX (VTK) crashes on RHEL/CentOS 7 with the following error message:

ERROR: In ../Rendering/OpenGL2/vtkShaderProgram.cxx, line 431
vtkShaderProgram (0x55555dda47a0):

This error message means that the OpenGL driver in RHEL 7.5 does not support the version needed by VTK.

Try using an earlier version of OpenGL:


If this solves the issue for your system, you can add export MESA_GL_VERSION_OVERRIDE=3.2 to your shell profile.

8.4.4. How do I build the C++ solver on RHEL/CentOS 7?

If you get linking errors when building with --cppmfix on Linux, try installing Boost from source with your system compiler. The Spack package manager is a convenient way of installing software (such as Boost) built from source as an ordinary user without root access (common in HPC cluster environments).

Since Spack installs packages from source, a system compiler and other build dependencies are required. The following command will install Spack build dependencies (given root access):

> yum install git gcc make    # CentOS 7

Spack installs software under the Github repo it is cloned from, and uses Environment Modules to load installed software packages.

> cd $HOME   # or whichever directory you prefer
> git clone https://github.com/spack/spack.git
> ./spack/bin/spack bootstrap
> source ./spack/share/spack/setup-env.sh
> spack install boost
> spack load boost

Now that boost module is loaded, try building the custom solver with using the C++ implementation again:

> build_mfixsolver --cppmfix

There may be a warning message if the spack boost version is newer than your cmake version, but you can ignore that (or update CMake if you prefer)

This has been tested on CentOS 7, but may be applicable for using recent Boost versions on older Linux distributions.

8.4.5. How do I build the custom solver in parallel?

The custom solver can be built in parallel from the GUI by checking the “Build solver in parallel” check box. This will pass the -j option to the make command and significantly decrease the time to build the solver.

8.4.6. Play/Pause/Reinit

While the simulation is running, it can be paused by pressing the Pause button button. A few settings can be modified, such as the stop time. Settings that cannot be changed (for example, the grid spacing) will be disabled while the simulation is paused. To resume the simulation, save the new settings by pressing the Save button button and press the Start button button.

8.4.7. Restart a simulation from current time

Once a simulation has run to completion, it can be restarted from the current simulation time. Increase the stop time in the “Run” pane, press the Save button button, and press the Start button button. In the “Run solver” dialog box, check the “Restart” check box and select “Resume”. Then press the “Run” button.

8.4.8. Restart a simulation from the beginning

Once a simulation has run to completion, or if you pressed the Stop button button, the simulation can be restarted from the beginning. This is typically needed if the simulation settings need to be changed and the current results are not needed anymore. First press the Reset button to delete the current results. Next change the simulation settings as needed (if any). Press the Save button button, and press the Start button button.

8.4.9. What system of units does MFiX use?

Simulations can be setup using the International System of Units (SI). The centimeter-gram-second system (CGS) is no longer supported.


MFiX SI unit

length, position

meter \((m)\)


kilogram \((kg)\)


second \((s)\)

thermal temperature

Kelvin \((K)\)


Joule \((J)\)

amount of substance‡

kilomole \((kmol)\)


Newton (\(N = kg·m·s^{-2}\))


Pascal (\(Pa = N·m^{-2}\))

dynamic viscosity


kinematic viscosity


gas constant




specific heat


thermal conductivity


† The SI unit for energy is the Joule. This is reflected in MFiX through the gas constant. However, entries in the Burcat database are always specified in terms of calories regardless of the simulation units. MFiX converts the entries to joules after reading the database when SI units are used.

‡ The SI unit for the amount of a substance is the mole (mol). MFiX uses the kilomole (kmole). These units are needed when specifying reaction rates:

  • amount per time per volume for Eulerian model reactions (kmole.s^{-1}.m^3)

  • amount per time for Lagrangian model reactions (kmole.s^{-1})

8.4.10. What do I do if a run does not converge?

Initial non-convergence:

Ensure that the initial conditions are physically realistic. If in the initial time step, the run displays NaN (Not-a-Number) for any residual, reduce the initial time step. If time step reductions do not help, recheck the problem setup.

Holding the time step constant (DT_FAC=1) and ignoring the stalling of iterations (DETECT_STALL=.FALSE.) may help in overcoming initial nonconvergence. Often a better initial condition will aid convergence. For example, using a hydrostatic rather than a uniform pressure distribution as the initial condition will aid convergence in fluidized bed simulations.

If there are computational regions where the solids tend to compact (i.e., solids volume fraction less than EP_star), convergence may be improved by reducing UR_FAC(2) below the default value of 0.5.

Convergence is often difficult with higher order discretization methods. First order upwinding may be used to overcome initial transients and then the higher order method may be turned on. Also, higher-order methods such as van Leer and minmod give faster convergence than methods such as superbee and ULTRA-QUICK.

Non-convergence due to bad cut-cell mesh:

When using cut-cells, non-convergence can arise due to a few bad cut cells, typically small cells (in volume) or bad cut cells coming from poorly resolved geometry in a coarse mesh with geometrical details in the order of one to two cells.

Convergence may be improved by lowering the number of small cut cells. This can be done either by removing small cut cells or by snapping intersection points to cell corners. The settings are available in the Mesh> Mesher pane in the GUI, or through keywords in the .mfx file.

To completely remove a small cut cell, increase the “small cell tolerance” (default value is 0.01), or modify the TOL_SMALL_CELL keyword when editing the .mfx file.

To snap intersection points to a cell corner, increase the “snap tolerance” (default value is 0.00), or modify the TOL_SNAP keyword when editing the .mfx file.

Increasing the “small area tolerance” (TOL_SMALL_AREA keyword) or Normal distance tolerance (TOL_DELH keyword) may also help.

Small cell removal

Fig. 8.3 Removing small cut-cells

8.4.11. How to provide initial particle positions in particle_input.dat file?

It is possible to provide initial particles position and velocity rather than using the automatic particle generation mechanism with Initial Conditions regions. The file particle_input.dat is a text file that stores each particle position, radius, density, and velocity. For 2D geometries, it contains 6 columns: x , y, radius, density, u, v. In 3D, it contains 8 columns: x , y, z, radius, density, u, v, w. The number of lines correspond to the number of particles read, and should match the “Data file particle count” defined in the Solids > DEM tab. The check box “Enable automatic particle generation” must be left unchecked.

Below is an example of a 2D particle_input.dat (only 4 particles shown):

0.2000D-03  0.2000D-03  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00
0.6000D-03  0.2000D-03  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00
0.1000D-02  0.2000D-03  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00
0.1400D-02  0.2000D-03  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00

Below is an example of a 3D particle_input.dat (only 4 particles shown):

0.2000D-03  0.2000D-03  0.1000D-01  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00  0.0000D+00
0.6000D-03  0.2000D-03  0.1000D-01  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00  0.0000D+00
0.1000D-02  0.2000D-03  0.1000D-01  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00  0.0000D+00
0.1400D-02  0.2000D-03  0.1000D-01  0.5000D-04  0.1800D+04  0.0000D+00  0.0000D+00  0.0000D+00

Currently, the particle_input.dat file must be edited outside of the GUI and saved in the project directory. Please see the dem/fluid_bed_3d tutorial for an example.

8.4.12. How to verify/flip STL file facet normals?

When using an STL file to define the geometry, a normal vector is associated with each facet (triangle). The direction in which the normal vector points indicates the fluid region. It is important to verify the normal vectors points in the desired direction before running the simulation.

To show the normal vectors in the Model view, expand the geometry view settings on the right and check “Show Normals”. It may be necessary to adjust the scale to get a better view. The figure below shows an example of a cylinder with vectors pointing towards the interior region of the cylinder. This will correspond with an internal flow simulation where the fluid region is located inside the cylinder and the outside region is not part of the simulation.

STL normals, Internal flow

Fig. 8.4 Displaying STL normals, internal flow

If the normal vectors are not pointing in the correct direction, the normals can be flipped by checking the “Flip normal” box for any selected stl file. To model an external flow using the same geometry as above, flip the normals and the change will be reflected in the Model view (see figure below). Now the normals points towards the outside of the cylinder, and the region inside the cylinder will not be part of the computation.

STL normals, External flow

Fig. 8.5 Flipping STL normals to model an external flow

8.4.13. How to manually specify a grid partition for DMP runs?

When running a simulation in parallel (DMP) mode, the parallel decomposition is by default uniform in each direction and the number of partitions is set by NODESI, NODESJ, and NODESK in the x,y and z directions, respectively. The default partition may not always be the most efficient. For example, a DEM simulation of a fluidized bed where most particles are at the bottom of the bed may run faster if smaller partitions are set at the bottom, where many particles are located and a large partition is used in the freeboard. This will better distribute particles among processors, and provide a better load balance.

Let’s assume the mesh contains 20x100x20 cells (IMAX=20, JMAX=100, KMAX=20) and we use 16 cores with a 2x4x2 partition (NODESI=2, NODESJ=4, NODESK=2). Assume particles are roughly located within the bottom half of the bed throughout the simulation. With the default (uniform) decomposition, each vertical partition will contain JMAX/NODESJ=25 cells (Figure 8.6). This means 8 cores will remain mostly idle with respect to particle tracking and collision.

Instead, we can distribute cells in the y-direction so that the vertical partitions have roughly the same number of particles. This can be achieved with 10, 10, 10, and 70 cells from bottom to top. (Figure 8.7).

Due to the symmetry of the problem in x and z directions, no adjustment is needed in these directions, and a uniform distribution is adequate.

Note that the custom partition will provide better load balance for particles but will make the fluid calculation slower since fluid cells will be unbalanced. However, since a large majority of the time is spent in the DEM loop, it should be beneficial to customize the partition.

To specify this decomposition, the following gridmap.dat needs to be saved in the project directory:

The first line specifies the values of NODESI, NODESJ, NODESK.

2        4          2    ! NODESI, NODESJ, NODESK

The next two lines (NODESI=2) specify the partition sizes in the x-direction. Here each partition contains 10 cells:

0        10
1        10

The next four lines (NODESJ=4) specify the partition sizes in the y-direction. Here three partitions at the bottom contains 10 cells each, and the last partition contains 70 cells:

0        10
1        10
2        10
3        70

The last two lines (NODESK=2) specify the partition sizes in the z-direction. Here each partition contains 10 cells:

0        10
1        10

Below is the entire gridmap.dat file:

2        4          2    ! NODESI, NODESJ, NODESK
0        10
1        10
0        10
1        10
2        10
3        70
0        10
1        10
Small cell removal

Fig. 8.6 Default partition (uniform distribution)

Small cell removal

Fig. 8.7 Adjusted partition in vertical direction (specified with gridmap.dat)