macOS Installation (native)

This guide covers native installation on macOS (Intel and Apple Silicon). For a container-based build — which ships every system dependency pre-installed and is the easiest path for newcomers — see Containers (Docker and Apptainer).

Note

CUDA (USE_CUDA=ON) is not supported on macOS because Apple has dropped NVIDIA support. For GPU runs, use a Linux workstation or HPC cluster with the CUDA Apptainer recipe.

Quick Start (Apple Silicon / Intel, via Homebrew)

# 1. Install Xcode Command Line Tools (one-time)
xcode-select --install

# 2. Install Homebrew dependencies
brew install cmake armadillo libomp nlohmann-json hdf5
# optional, for MPI runs:
brew install open-mpi

# 3. Clone and build
git clone https://github.com/ue-hydro/FLUXOS_cpp.git
cd FLUXOS_cpp
mkdir build && cd build
cmake -DMODE_release=ON ..
make -j$(sysctl -n hw.ncpu)

# 4. Run the bundled Rosa Creek example
cd ..
./build/bin/fluxos Working_example/modset_trimesh.json

Dependency notes

Apple Silicon (M1/M2/M3/M4): use ARM-native Homebrew (installed under /opt/homebrew). Mixing Rosetta / x86_64 Homebrew with an ARM-native compile breaks linking.

OpenMP on macOS Clang: Apple’s Clang ships without OpenMP headers. brew install libomp provides them; CMake’s FindOpenMP picks them up if Homebrew is on the default search path. If the build reports “OpenMP: NOT FOUND”, prepend the Homebrew OpenMP path explicitly:

export OpenMP_ROOT=$(brew --prefix)/opt/libomp
cmake -DMODE_release=ON ..

Armadillo: Homebrew’s armadillo formula is current (12.x). If you installed an older one, brew upgrade armadillo.

Build variants

The CMake flag matrix is the same as on Linux — see Building Requirements for the full list. The most common combinations on macOS:

Goal	CMake flags
OpenMP only, regular mesh	`-DMODE_release=ON`
OpenMP + triangular mesh	`-DMODE_release=ON`
MPI + OpenMP	`-DMODE_release=ON -DUSE_MPI=ON`

Running the example

After make, the compiled fluxos binary lives at build/bin/fluxos inside your checkout. The Working_example/ directory ships with seven canned modset JSONs that point to the bundled Rosa Creek DEM and forcing files:

./build/bin/fluxos Working_example/modset_trimesh.json

For your own domain, edit the _config dict in supporting_scripts/1_Model_Config/model_config_template.py (see Supporting Scripts) and run it to produce .asc / .msh / modset.json in one shot.

Troubleshooting

“clang: error: unsupported option ‘-fopenmp’” — Homebrew’s libomp is not installed, or its path isn’t on the search path. Install and retry:

brew install libomp
export OpenMP_ROOT=$(brew --prefix)/opt/libomp

Armadillo link errors on Apple Silicon — you’re likely mixing Rosetta Homebrew with the ARM-native compiler. Run brew config and verify the prefix is /opt/homebrew (ARM) rather than /usr/local (x86_64).

``make`` fails with “operator not supported” in nlohmann/json — Apple’s stock Clang is too old. Update with xcode-select --install or install a newer Clang via brew install llvm and re-run CMake.