MFC
Exascale flow solver
Loading...
Searching...
No Matches
CLI Reference

CLI Reference

Auto-generated from toolchain/mfc/cli/commands.py

Regenerate with: ./mfc.sh generate

Overview

Welcome to the MFC master script. This tool automates and manages building, testing, running, and cleaning of MFC in various configurations on all supported platforms. The README documents this tool and its various commands in more detail. To get started, run ./mfc.sh build -h.

Quick Reference

Command Alias Description
build b Build MFC and its dependencies.
run r Run a case with MFC.
test t Run MFC's test suite.
clean c Clean build artifacts.
validate v Validate a case file without running.
new - Create a new case from a template.
viz - Visualize post-processed MFC output.
params - Search and explore MFC case parameters.
packer - Packer utility (pack/unpack/compare).
completion - Install shell tab-completion.
help - Show help on a topic.
generate - Regenerate completion scripts from CLI schema.
load - Loads the MFC environment with source.
lint - Lints and tests all toolchain code.
format - Formats all code after editing.
spelling - Runs the spell checker after editing.
precheck - Run CI lint checks locally before committing.
interactive - Launch interactive menu-driven interface.
bench - Benchmark MFC (for CI).
bench_diff - Compare MFC Benchmarks (for CI).
count - Count LOC in MFC.
count_diff - Compare LOC between branches.

Commands

build

Alias: b

Build MFC targets with optional GPU support and case optimization.

Usage: ./mfc.sh build [OPTIONS]

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
-i, --input (GPU Optimization) Build a version of MFC optimized for a case. -
--case-optimization (GPU Optimization) Compile MFC targets with some case parameters hard-coded (requires –input). false
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Build all default targets (CPU)
./mfc.sh build
# Build with 8 parallel jobs
./mfc.sh build -j 8
# Build with GPU (OpenACC) support
./mfc.sh build --gpu
# Case optimization (10x faster!)
./mfc.sh build -i case.py --case-optimization -j 8

run

Alias: r

Run an MFC simulation case interactively or submit as a batch job.

Usage: ./mfc.sh run INPUT [OPTIONS]

Arguments:

  • INPUT - Input file to run.

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
-g, --gpus (Optional GPU override) List of GPU #s to use (environment default if unspecified). -
-e, --engine Job execution/submission engine choice. interactive
-p, --partition (Batch) Partition for job submission. -
-q, --quality_of_service (Batch) Quality of Service for job submission. -
-N, --nodes (Batch) Number of nodes. 1
-n, --tasks-per-node Number of tasks per node. 1
-w, --walltime (Batch) Walltime. 01:00:00
-a, --account (Batch) Account to charge. -
-@, --email (Batch) Email for job notification. -
-#, --name (Batch) Job name. MFC
-s, --scratch Build from scratch. false
-b, --binary (Interactive) Override MPI execution binary -
--dry-run (Batch) Run without submitting batch file. false
--case-optimization (GPU Optimization) Compile MFC targets with some case parameters hard-coded. false
--no-build (Testing) Do not rebuild MFC. false
--wait (Batch) Wait for the job to finish. false
-c, --computer (Batch) Path to a custom submission file template or one of the built-in templates. default
-o, --output-summary Output file (YAML) for summary. -
--clean Clean the case before running. false
--ncu Profile with NVIDIA Nsight Compute. -
--nsys Profile with NVIDIA Nsight Systems. -
--rcu Profile with ROCM rocprof-compute. -
--rsys Profile with ROCM rocprof-systems. -
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Run interactively with 1 rank
./mfc.sh run case.py
# Run with 4 MPI ranks
./mfc.sh run case.py -n 4
# 10x faster with case optimization!
./mfc.sh run case.py --case-optimization -j 8
# Submit batch job: 2 nodes, 4 ranks/node
./mfc.sh run case.py -e batch -N 2 -n 4

test

Alias: t

Run MFC's test suite with various filtering and generation options.

Usage: ./mfc.sh test [OPTIONS]

Options:

Option Description Default
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
-g, --gpus (Optional GPU override) List of GPU #s to use (environment default if unspecified). -
-l, --list List all available tests. -
-f, --from First test UUID to run. -
-t, --to Last test UUID to run. -
-o, --only Only run tests with specified properties. []
-a, --test-all Run the Post Process Tests too. false
-%, --percent Percentage of tests to run. 100
-m, --max-attempts Maximum number of attempts to run a test. 1
--rdma-mpi Run tests with RDMA MPI enabled false
--no-build (Testing) Do not rebuild MFC. false
--no-examples Do not test example cases. false
--case-optimization (GPU Optimization) Compile MFC targets with some case parameters hard-coded. false
--dry-run Build and generate case files but do not run tests. false
--shard Run only a subset of tests (e.g., '1/2' for first half, '2/2' for second half). -
--generate (Test Generation) Generate golden files. false
--add-new-variables (Test Generation) If new variables are found in D/ when running tests, add them to the golden files. false
--remove-old-tests (Test Generation) Delete test directories that are no longer needed. false
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Run all tests
./mfc.sh test
# Run with 4 parallel jobs
./mfc.sh test -j 4
# Run only 3D tests
./mfc.sh test --only 3D
# Regenerate golden files
./mfc.sh test --generate

clean

Alias: c

Remove build artifacts and cache files.

Usage: ./mfc.sh clean [OPTIONS]

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Clean all build files
./mfc.sh clean

validate

Alias: v

Check a case file for syntax errors and constraint violations.

Usage: ./mfc.sh validate INPUT [OPTIONS]

Arguments:

  • INPUT - Path to case file to validate.

Options:

Option Description Default
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -

Examples:

# Check syntax and constraints
./mfc.sh validate case.py
# Validate with toolchain debug output
./mfc.sh validate case.py -d

Utility Commands

new

Create a new simulation case directory from a built-in or example template.

Usage: ./mfc.sh new [NAME] [OPTIONS]

Arguments:

  • NAME - Name/path for the new case directory.

Options:

Option Description Default
-t, --template Template to use (e.g., 1D_minimal, 2D_minimal, 3D_minimal, or example:<name>). 1D_minimal
-l, --list List available templates. -

Examples:

# Create with 1D_minimal template
./mfc.sh new my_case
# Create with 2D template
./mfc.sh new my_case -t 2D_minimal
# Copy from example
./mfc.sh new my_case -t example:3D_sphbubcollapse
# List available templates
./mfc.sh new --list

viz

Render post-processed MFC output as PNG images or MP4 video, or explore interactively. Supports 1D line plots, 2D colormaps, 3D midplane slices, and tiled all-variable views.

Output modes: (default) Launch a terminal UI (works over SSH, no browser needed) –interactive Launch a Dash web UI in your browser –png Save PNG image(s) to case_dir/viz/ –mp4 Encode frames into an MP4 video

Variable selection: –var NAME Plot a single variable (omit –var) 1D/2D: tiled layout of all variables; 3D: first variable

Quick-start workflow:

  1. ./mfc.sh viz case_dir/ –list-steps
  2. ./mfc.sh viz case_dir/ –list-vars –step 0
  3. ./mfc.sh viz case_dir/

Usage: ./mfc.sh viz INPUT [OPTIONS]

Arguments:

  • INPUT - Path to the case directory containing binary/ or silo_hdf5/ output.

Options:

Option Description Default
--var Variable to visualize (e.g. pres, rho, vel1). Omit (or pass 'all') for a tiled layout of all variables (1D and 2D data) or the first variable (3D data). Use –list-vars to see available names. -
--step Timestep(s) to render. Formats: a single integer (e.g. 1000), a range start:end:stride (e.g. 0:5000:500), a comma list (e.g. 0,100,200), an ellipsis list (e.g. 0,100,...,1000), 'last' (default — renders the final step only), or 'all'. Use –list-steps to see available timesteps. last
-f, --format Input data format: binary or silo (auto-detected from directory structure if omitted). -
-o, --output Output directory for –png and –mp4. -
--cmap Matplotlib colormap name (–png, –mp4 only). viridis
--vmin Minimum value for color scale (–png, –mp4 only). -
--vmax Maximum value for color scale (–png, –mp4 only). -
--dpi Image resolution in DPI (–png, –mp4). 150
--slice-axis Axis for 3D slice (–png, –mp4 only). z
--slice-value Coordinate value at which to take the 3D slice (–png, –mp4 only). -
--slice-index Array index at which to take the 3D slice (–png, –mp4 only). -
--mp4 Encode all rendered frames into an MP4 video (requires –step with multiple timesteps). false
--fps Frames per second for –mp4 output. 10
--list-vars Print the variable names available at the given timestep and exit. false
--list-steps Print all available timesteps and exit. false
--log-scale Logarithmic color/y scale (–png, –mp4 only). false
-i, --interactive Launch an interactive Dash web UI in your browser. Loads all timesteps (or the set given by –step) and lets you scrub through them and switch variables live. false
--port Port for –interactive web server. 8050
--host Bind address for –interactive web server. 127.0.0.1
--png Save PNG image(s) to the output directory instead of launching the terminal UI. false

Examples:

# Launch terminal UI (default mode)
./mfc.sh viz case_dir/
# Discover available timesteps
./mfc.sh viz case_dir/ --list-steps
# Discover available variables at step 0
./mfc.sh viz case_dir/ --list-vars --step 0
# Browser UI — scrub timesteps and switch vars
./mfc.sh viz case_dir/ --var pres --interactive
# Save pressure PNG at step 1000
./mfc.sh viz case_dir/ --var pres --step 1000 --png
# Encode pressure MP4 from range
./mfc.sh viz case_dir/ --var pres --step 0:10000:500 --mp4
# Render all steps 0–1000 as images
./mfc.sh viz case_dir/ --step 0,100,200,...,1000 --png
# 3D: x-plane slice of pressure
./mfc.sh viz case_dir/ --var pres --step 500 --slice-axis x --png

params

Search, list, and get information about MFC's ~3,300 case parameters.

Usage: ./mfc.sh params [QUERY] [OPTIONS]

Arguments:

  • QUERY - Search query (parameter name or pattern to search for).

Options:

Option Description Default
-t, --type Filter by type: int, real, log, str. -
-f, --families List parameter families (grouped by prefix). false
-F, --features List feature groups (mhd, bubbles, weno, etc.). false
--feature Show all parameters for a feature group (e.g., –feature mhd). -
--names-only Only search parameter names (not descriptions). false
-c, --count Show count statistics only. false
-n, --limit Maximum number of results to show (default: unlimited). 10000
-d, --describe Show parameter descriptions. false

Examples:

# Search for parameters (names + descriptions)
./mfc.sh params weno
# Find params mentioning 'magnetic'
./mfc.sh params magnetic
# Show all MHD-related parameters
./mfc.sh params --feature mhd
# List all feature groups
./mfc.sh params -F
# List parameter families (by prefix)
./mfc.sh params -f
# Show parameter count statistics
./mfc.sh params -c

packer

Pack simulation output into a single file or compare packed files.

Usage: ./mfc.sh packer [OPTIONS]

Examples:

# Pack case output
./mfc.sh packer pack case.py
# Compare two packed files
./mfc.sh packer compare a.pack b.pack

Subcommands:

packer pack

Pack a case into a single file.

Arguments:

  • INPUT - Input file of case to pack.

Options:

Option Description Default
-o, --output Base name of output file. -

packer compare

Compare two cases.

Arguments:

  • INPUT1 - First pack file.
  • INPUT2 - Second pack file.

Options:

Option Description Default
-rel, --reltol Relative tolerance. 1e-12
-abs, --abstol Absolute tolerance. 1e-12

completion

Install or manage shell tab-completion for MFC commands.

Usage: ./mfc.sh completion [COMPLETION_ACTION] [COMPLETION_SHELL] [OPTIONS]

Arguments:

  • COMPLETION_ACTION - Action: install, uninstall, or status
  • COMPLETION_SHELL - Shell type: bash or zsh (auto-detected if not specified)

Examples:

# Install tab completion for current shell
./mfc.sh completion install
# Install for bash specifically
./mfc.sh completion install bash
# Check completion installation status
./mfc.sh completion status

help

Show help on a topic.

Usage: ./mfc.sh help [TOPIC] [OPTIONS]

Arguments:

  • TOPIC - Help topic: gpu, clusters, batch, debugging, performance

generate

Regenerate shell completion scripts, documentation, and JSON schema from the CLI schema.

Usage: ./mfc.sh generate [OPTIONS]

Options:

Option Description Default
--check Check if generated files are up to date (exit 1 if not). false
--json-schema Generate JSON Schema for IDE auto-completion of case files. false

Examples:

# Regenerate completion scripts
./mfc.sh generate
# Check if completions are up to date
./mfc.sh generate --check
# Generate JSON Schema for IDE support
./mfc.sh generate --json-schema

Development Commands

lint

Run pylint and unit tests on MFC's toolchain Python code.

Usage: ./mfc.sh lint [OPTIONS]

Options:

Option Description Default
--no-test Skip running unit tests (only run pylint). -

Examples:

# Run pylint and unit tests
./mfc.sh lint
# Run only pylint (skip unit tests)
./mfc.sh lint --no-test

format

Format all code in the repository.

Usage: ./mfc.sh format [OPTIONS]

Examples:

# Format all code
./mfc.sh format
# Format with 8 parallel jobs
./mfc.sh format -j 8

spelling

Check spelling in the codebase.

Usage: ./mfc.sh spelling [OPTIONS]

Examples:

# Run spell checker
./mfc.sh spelling

precheck

Run the same fast checks that CI runs before expensive tests start. Use this locally before pushing to catch issues early.

Usage: ./mfc.sh precheck [OPTIONS]

Options:

Option Description Default
-j, --jobs Number of parallel jobs for formatting. -

Examples:

# Run all lint checks
./mfc.sh precheck
# Run with 8 parallel jobs
./mfc.sh precheck -j 8

count

Count LOC in MFC.

Usage: ./mfc.sh count [OPTIONS]

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Show LOC statistics
./mfc.sh count

count_diff

Compare LOC between branches.

Usage: ./mfc.sh count_diff [OPTIONS]

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

CI Commands

bench

Benchmark MFC (for CI).

Usage: ./mfc.sh bench [OPTIONS]

Options:

Option Description Default
-t, --targets Space-separated list of targets to act upon. pre_process, simulation, post_process
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
-g, --gpus (Optional GPU override) List of GPU #s to use (environment default if unspecified). -
-o, --output Path to the YAML output file to write the results to. -
-m, --mem Memory per task for benchmarking cases 1
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Examples:

# Run benchmarks and save results
./mfc.sh bench -o results.yaml

bench_diff

Compare MFC Benchmarks (for CI).

Usage: ./mfc.sh bench_diff LHS RHS [OPTIONS]

Arguments:

  • LHS - Path to a benchmark result YAML file.
  • RHS - Path to a benchmark result YAML file.

Options:

Option Description Default
-j, --jobs Allows for JOBS concurrent jobs. 1
-v, --verbose Increase output verbosity (-v, -vv, -vvv for more detail). 0
-d, --debug-log Enable Python toolchain debug logging (not MFC code). -
--mpi, --no-mpi Enable/disable MPI true
--gpu [acc/mp], --no-gpu Enable GPU (OpenACC/OpenMP) no
--debug, --no-debug Build with debug compiler flags false

Other Commands

load

Load MFC environment modules (use with source).

Usage: ./mfc.sh load [OPTIONS]

Examples:

# Load Phoenix GPU modules
source ./mfc.sh load -c p -m g
# Load Frontier CPU modules
source ./mfc.sh load -c f -m c

interactive

Launch an interactive menu for MFC operations.

Usage: ./mfc.sh interactive [OPTIONS]

Common Options

Many commands share common option sets:

Target Selection (-t, --targets)

Available targets:

  • pre_process - Pre-processor
  • simulation - Main simulation
  • post_process - Post-processor
  • syscheck - System check utility
  • documentation - Build documentation

Build Configuration Flags

Flag Description
--mpi / --no-mpi Enable/disable MPI support
--gpu [acc/mp] / --no-gpu Enable GPU with OpenACC or OpenMP
--debug / --no-debug Build with debug compiler flags
--gcov / --no-gcov Enable code coverage
--single / --no-single Single precision
--mixed / --no-mixed Mixed precision

Verbosity (-v, --verbose)

Controls output verbosity level:

  • -v - Basic verbose output
  • -vv - Show build commands
  • -vvv - Full verbose output including CMake details

Debug Logging (-d, --debug-log)

Enables debug logging for the Python toolchain (mfc.sh internals). This is for troubleshooting the build system, not the MFC simulation code.

Page last updated: 2026-03-05