Welcome to MFC! MFC is an exascale-ready fully-documented parallel simulation code for multi-component, multi-phase, high-speed, and bubbly flows.

Authors | Publications | Installing | Running | Testing | User's Guide | Documentation

Authors

MFC was first developed by the Colonius research group at Caltech. Now it is developed and maintained by the groups of Professors Spencer Bryngelson, Tim Colonius, and Mauro Rodriguez (alphabetical). We try to maintain a list of current and past developers in the AUTHORS file!

Publications

Primary Paper

The paper that describes MFC's capabilities:

• S. H. Bryngelson, K. Schmidmayer, V. Coralic, K. Maeda, J. Meng, T. Colonius (2021) Computer Physics Communications 4655, 107396

Related publications

Several publications have used MFC in various stages of its development. A partial list is included here.

Journal papers:

• S. H. Bryngelson, R. O. Fox, T. Colonius (2021) arXiv: 2112.14172.
• S. H. Bryngelson and T. Colonius (2020) Journal of the Acoustical Society of America, Vol. 147, pp. 1126-1135
• K. Schmidmayer, S. H. Bryngelson, T. Colonius (2020) Journal of Computational Physics, Vol. 402, 109080
• S. H. Bryngelson, K. Schmidmayer, T. Colonius (2019) International Journal of Multiphase Flow, Vol. 115, pp. 137-143
• K. Maeda and T. Colonius (2019) Journal of Fluid Mechanics, Vol. 862, pp. 1105-1134
• K. Maeda and T. Colonius (2018) Journal of Computational Physics, Vol. 371, pp. 994-1017
• J. C. Meng and T. Colonius (2018) Journal of Fluid Mechanics, Vol. 835, pp. 1108-1135
• K. Maeda and T. Colonius (2017) Wave Motion, Vol. 75, pp. 36-49
• J. C. Meng and T. Colonius (2015) Shock Waves, Vol. 25(4), pp. 399-414
• V. Coralic and T. Colonius (2014) Journal of Computational Physics, Vol. 274, pp. 95-121

Ph.D. Disserations:

• J.-C. Veilleux (2019) Ph.D. thesis, California Institute of Technology
• K. Maeda (2018) Ph.D. thesis, California Institute of Technology
• J. Meng (2016) Ph.D. thesis, California Institute of Technology
• V. Coralic (2014) Ph.D. thesis, California Institute of Technology

Installing MFC

To fetch, build, and run MFC and its dependencies on a UNIX-like system, you must have installed common utilities such as GNU's Make, Python3, its developement headers and libraries, a C/C++ compiler (GCC, NVHPC, etc., but *not Clang*), and an MPI wrapper (like Open MPI). Below are some commands for popular operating systems and package managers.

*nix

• Via Aptitude:

sudo apt install tar wget make cmake gcc g++ python3 "openmpi-*" python python-dev python3-dev python3-venv libopenmpi-dev

MacOS (including x86 and M1/Apple Silicon)

• Via Homebrew:

You can modify the assignment on the first line to have the GCC major version you wish to have installed and use.

USE_GCC_VERSION=11
brew install wget make python make cmake gcc@$USE_GCC_VERSION
HOMEBREW_CC=gcc-$USE_GCC_VERSION; HOMEBREW_CXX=g++-$USE_GCC_VERSION; brew install open-mpi

Further reading on open-mpi incompatibility with clang-based gcc on macOS: here. We do not support clang due to conflicts with our Silo dependency.

Fetch and build MFC

The following commands fetch and build MFC and its required dependencies. The dependencies are built to the build/ directory within your MFC installation. This should have no impact on your local installation(s) of these packages.

• Fetch MFC:

git clone https://github.com/MFlowCode/MFC
cd MFC

• (Optional) Configure MFC defaults in mfc.user.yaml:

If you wish, you can override MFC's default build parameters in mfc.user.yaml, a file intended for user customisation. This can greatly reduce the number of command-line arguments you have to pass to mfc.sh` in the following sections. You can do this at any time.

• Build MFC and its dependencies with 8 threads in release-cpu mode:

Argument	Flag	Default Value (from mfc.user.yaml)	Possible values
Threads	-j	1	From 1 to the maximum logical thread count of your processor.
Target(s)	-t	MFC	MFC / pre_process / simulation / post_process / FFTW3 / HDF5 / SILO
Configuration	-cc	release-cpu	release-cpu / release-gpu / debug-cpu / debug-gpu

chmod +x ./mfc.sh
./mfc.sh --build -j 8 -cc release-cpu

• Run MFC's tests to make sure it was correctly built and your environment is adequate

./mfc.sh --test

Please refer to the Testing section of this document for more information.

User Configuration (mfc.user.yaml)

The mfc.sh script used in the previous section is configured through the file named mfc.user.yaml.

Running MFC

MFC can be run by changing into a case directory and executing the appropriate Python input file. Example Python input files can be found in the example_cases directories, and they are called input.py. Their contents, and a guide to filling them out, are documented in the user manual. A commented, tutorial script can also be found in example_cases/3d_sphbubcollapse/ MFC can be executed as

./input.py pre_process

which will generate the restart and grid files that will be read by the simulation code. Then

./input.py simulation

will execute the flow solver. The last (optional) step is to post treat the data files and output HDF5 databases for the flow variables via

./input.py post_process

Testing MFC

To run MFC's test suite, simply run ./mfc.sh --test. It will generate and run test cases, to compare their output to that of previous runs from versions of MFC considered to be accurate. golden files, stored in the tests/ directory contain this data, by aggregating .dat files generated when running MFC. A test is considered passing within a very small margin of error, to maintain a high level of stability and accuracy across versions of MFC.

Adding a new test case is as simple as modifying bootstrap/internal/test.py, and selecting which parameters you want to vary from the base case. Then run ./mfc.sh --test -g|--generate to generate new golden files. Please make sure that these files are generated with accurate data.

If you want to only run certain tests, you can pass the argument -o (--only) along with the associated test ID or hash:

• Test ID: It is the execution order of a test. The first test is #1, the next one is #2, and so on. If a test is added or removed, it could modify the test IDs of all tests executed after it.
• Hash: It is a hash of the parameters given to MFC by a certain test. They look like 5340bc2a. They are used to refer to a specific test, as they don't change if tests are added or removed, since they are not based on execution order, but rather on test content. However, if a test's parameters change, its hash also changes (ignoring collisions).

An example of running targeted tests:

./mfc.sh --test -o 7 5b486221

Development

Fypp

MFC uses Fypp, a Python-based Fortran preprocessor to reduce code duplication. .fpp files are converted into regular .f90 files as part of the build process. Documentation for Fypp can be found here.

You can inspect the generated .f90 files located in build/___current___/src/<name of target>/src.

License

Copyright 2022. MFC is under the MIT license (see LICENSE file for full text).

Acknowledgements

The development of MFC was supported in part by multiple current and past grants from the US Office of Naval Research (ONR), the US National Institute of Health (NIH), and the US National Science Foundation (NSF). MFC computations utilize the Extreme Science and Engineering Discovery Environment (XSEDE), under allocations TG-CTS120005 (PI Colonius) and TG-PHY210084 (PI Bryngelson) and ORNL Summit under allocation CFD154 (PI Bryngelson).