GeezerVison

GeezerVison is showing mflowcode.github.io — MFC: Getting Started

MFC

Exascale flow solver

Searching...

No Matches

Getting Started

Fetching MFC

You can either download MFC's latest release from GitHub or clone the repository:

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

cd MFC

Install via Homebrew (macOS)

On macOS, install prebuilt MFC via Homebrew:

brew install mflowcode/mfc/mfc

Run a quick example:

mkdir -p ~/mfc_quickstart && cd ~/mfc_quickstart

cp $(brew --prefix mfc)/examples/1D_sodshocktube/case.py .

# Use -n X to choose the number of MPI processes

mfc case.py -n 2

Notes:

The Homebrew package uses a simplified syntax: just mfc <case.py> to run cases.
Developer commands like build, test, clean are available when you clone the repo and use ./mfc.sh.
The package bundles a Python venv and prebuilt binaries; no additional setup is required.
Examples are installed at $(brew --prefix mfc)/examples/.

Build Environment

MFC can be built in multiple ways on various operating systems. Please select your desired configuration from the list below:

*nix

On supported clusters: Load environment modules

source ./mfc.sh load

Via Aptitude:

sudo apt update

sudo apt upgrade

sudo apt install tar wget make cmake gcc g++ \

python3 python3-dev python3-venv \

openmpi-bin libopenmpi-dev \

libhdf5-dev libfftw3-dev \

libblas-dev liblapack-dev

If you wish to build MFC using NVIDIA's NVHPC SDK, first follow the instructions here.

Windows

On Windows, you can either use Intel Compilers with the standard Microsoft toolchain, or the Windows Subsystem for Linux (WSL) for a Linux experience.

Windows + WSL (Recommended)

Install Windows Subsystem for Linux (WSL) on Windows 11: Either

Open a terminal with administrator privileges and run the following command:
wsl --install

Or

Open the Start menu, search for "Windows Features", and select "Turn Windows features on or off". Enable "Windows Subsystem for Linux" by checking the corresponding box.
Open the Microsoft Store, search for "Linux", and install your preferred distribution (e.g., Ubuntu)

Useful software to install for using WSL on Windows:

Windows Terminal
Visual Studio Code and the Remote - WSL extension

Once you have WSL installed, you can follow the instructions for *nix systems above (for Ubuntu, see Via Aptitude section).

Native Windows (Intel)

Install the latest version of:

Microsoft Visual Studio Community
Intel® oneAPI Base Toolkit
Intel® oneAPI HPC Toolkit
Strawberry Perl (Install and add C:\strawberry\perl\bin\perl.exe or your installation path to your PATH) Please note that Visual Studio must be installed first, and the oneAPI Toolkits need to be configured with the installed Visual Studio, even if you plan to use a different IDE.

Then, to initialize your development environment, run the following command (or your installation path) in the command prompt:

"C:\Program Files (x86)\Intel\oneAPI\setvars.bat"

Alternatively, you can run the following command in Powershell:

cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'

You could verify the initialization by typing where mpiexec in the command prompt terminal (does not work in Powershell), which should return the path to the Intel MPI executable. To continue following this guide, please stay in the initialized terminal window. Replace ./mfc.sh with .\mfc.bat for all commands.

If .\mfc.bat build produces errors, please run the command again. Repeating this process three times should resolve all errors (once each for pre_process, simulation, and post_process). If the same error persists after each attempt, please verify that you have installed all required software and properly initialized the development environment. If uncertain, you could try deleting the build directory and starting over.

You will also have access to the .sln Microsoft Visual Studio solution files for an IDE (Integrated Development Environment).

MacOS

Using Homebrew you can install the necessary dependencies before configuring your environment:

brew install coreutils python cmake fftw hdf5 gcc boost open-mpi lapack

echo -e "export BOOST_INCLUDE='$(brew --prefix --installed boost)/include'" | tee -a ~/.bash_profile ~/.zshrc

. ~/.bash_profile 2>/dev/null || . ~/.zshrc 2>/dev/null

! [ -z "${BOOST_INCLUDE+x}" ] && echo 'Environment is ready!' || echo 'Error: $BOOST_INCLUDE is unset. Please adjust the previous commands to fit with your environment.'

They will download the dependencies MFC requires to build itself.

Building MFC

MFC can be built with support for various (compile-time) features:

Feature	Enable	Disable	Default	Description
MPI	--mpi	--no-mpi	On	Allows MFC to run on multiple processors (and nodes).
GPU	--gpu	--no-gpu	Off	Enables GPU acceleration via OpenACC or OpenMP offload.
Debug	--debug	--no-debug	Off	Full debug mode: all runtime checks, minimal optimization.
RelDebug	--reldebug	--no-reldebug	Off	Lightweight debug: key runtime checks, -Og/-O1. Used by CI.
GCov	--gcov	--no-gcov	Off	Build MFC with coverage flags on.
Unified Memory	--unified	--no-unified	Off	Build MFC with unified CPU/GPU memory (GH200 superchip only)
Single	--single	--no-single	Off	Build MFC in single precision

⚠️ The --gpu option requires a supported compiler: NVHPC for NVIDIA GPUs (OpenACC or OpenMP), Cray for AMD GPUs (OpenACC or OpenMP), or AMD compilers for AMD GPUs (OpenMP only).

When these options are given to mfc.sh, they will be remembered when you issue future commands. You can enable and disable features anytime by passing any of the arguments above. For example, if you previously built MFC with MPI support and no longer wish to run using MPI, you can pass --no-mpi once, making the change permanent.

MFC comprises three codes, each being a separate target. By default, all targets (pre_process, simulation, and post_process) are selected. To only select a subset, use the -t (i.e., --targets) argument. For a detailed list of options, arguments, and features, please refer to ./mfc.sh build --help.

Most first-time users will want to build MFC using 8 threads (or more!) with MPI support:

./mfc.sh build -j 8

Some examples:

Build MFC using 8 threads with MPI and GPU acceleration: ./mfc.sh build --gpu -j 8.
Build MFC using a single thread without MPI, GPU, and Debug support: ./mfc.sh build --no-mpi.
Build MFC's simulation code in Debug mode with MPI and GPU support: ./mfc.sh build --debug --gpu -t simulation.

Using Containers

Instead of building MFC from scratch, you can use containers to quickly access a pre-built version of MFC and its dependencies. In brief, you can run the latest MFC container:

docker run -it --rm --entrypoint bash sbryngelson/mfc:latest-cpu

Please refer to the Docker document for more information.

Running the Test Suite

Run MFC's test suite with 8 threads:

./mfc.sh test -j 8

Please refer to the Testing document for more information.

Running an Example Case

MFC has example cases in the examples folder. You can run such a case interactively using 2 tasks by typing:

./mfc.sh run examples/2D_shockbubble/case.py -n 2

Please refer to the Running document for more information on case.py files and how to run them.

Units and Dimensions

MFC is unit-agnostic: the solver performs no internal unit conversions. Whatever units you provide for initial conditions, boundary conditions, and material properties, the same units appear in the output.

The only requirement is consistency — all inputs must use the same unit system. Note that some parameters use transformed stored forms rather than standard physical values (e.g., gamma expects $1/(\gamma-1)$, not $\gamma$ itself). See Stored Parameter Conventions for details.

Visualizing Results

After running post_process, visualize the output directly from the command line:

# List available variables

./mfc.sh viz examples/2D_shockbubble/ --list-vars --step 0

# Render a pressure snapshot

./mfc.sh viz examples/2D_shockbubble/ --var pres --step 1000

# Generate a video

./mfc.sh viz examples/2D_shockbubble/ --var pres --step all --mp4

Output images and videos are saved to the viz/ subdirectory of the case. For more options, see Flow Visualization or run ./mfc.sh viz -h.

Helpful Tools

Parameter Lookup

MFC has over 3,000 case parameters. Use the params command to search and explore them:

./mfc.sh params dt # Search for parameters matching "dt"

./mfc.sh params -d dt # Show parameter with description

./mfc.sh params patch # Find all patch-related parameters

./mfc.sh params --family # List all parameter families

Creating a New Case

Generate a case file template to get started quickly:

./mfc.sh new my_case.py # Create a new case file from template

Shell Completion

Enable tab-completion for ./mfc.sh commands:

Bash (add to ~/.bashrc):

source /path/to/MFC/toolchain/completions/mfc.bash

Zsh (add to ~/.zshrc):

fpath=(/path/to/MFC/toolchain/completions $fpath)

autoload -Uz compinit && compinit

After reloading your shell, press Tab to complete commands and options.

Page last updated: 2026-10-10