HemeLB Setup Instructions (macOS)

Author: Google Gemini and Joyanta Mondal Last Updated: May 15, 2026 Commit: 432d338

For the most comprehensive and updated information, refer to the full documentation.

Automated Mac Installation Script (Gist)

Note: This is not official documentation. It is an independently created guide developed by someone who started working with HemeLB and quickly discovered that the available documentation and tutorials were extremely limited, fragmented, and often unclear for beginners. After spending an unreasonable amount of time struggling through setup issues, missing instructions, and undocumented workflows, this resource was created to document the process, highlight common challenges, and provide practical solutions that may help future users avoid the same frustrations.
Prefer an easier install? The improved HemeLB fork installs HemeLB, the geometry tool, and the Python tools with one script on macOS and Ubuntu.
On this page
  1. 1. Prerequisites
  2. 2. Installation Steps
  3. 3. Geometry and Python Tool Setup
  4. 4. Uninstall Instructions
  5. 6. Useful References

1. Prerequisites

  • Operating System: macOS (Apple Silicon / ARM64)
  • Package Managers: Homebrew and Anaconda
  • Rosetta 2: Required for the Geometry Tool environment. Install via terminal: softwareupdate --install-rosetta --agree-to-license

2. Installation Steps

Step 1: Install System Dependencies via Homebrew

brew update
brew install cmake open-mpi boost cgal metis ctemplate git curl pkg-config

Step 2: Build TinyXML (v1) from Source

macOS package managers often do not supply the older version of TinyXML required by HemeLB. We must compile it manually and place it in a local directory (e.g., ~/local):

mkdir -p ~/build && cd ~/build
git clone https://github.com/robotology-dependencies/tinyxml.git
cd tinyxml && mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX="$HOME/local" -DBUILD_SHARED_LIBS=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..
make -j4 install

Step 3: Clone, Lock Commit, and Patch HemeLB

Apple Clang 21 enforces strict C++ parsing that breaks standard HemeLB templates. Clone the repository, lock the commit for reproducibility, and run a quick Python patch to fix the ->template syntax errors:

git clone https://github.com/hemelb-codes/hemelb.git
cd hemelb
git checkout 432d338
chmod -R u+w Code/

# Run the patch:
python3 -c "
import os, re
for root, dirs, files in os.walk('Code'):
    for f in files:
        if f.endswith(('.h', '.cc', '.cpp')):
            path = os.path.join(root, f)
            with open(path, 'r', encoding='utf-8', errors='ignore') as fh:
                data = fh.read()
            new_data = re.sub(r'->template\s+([A-Za-z_][A-Za-z0-9_]*)\(', r'->\1(', data)
            if data != new_data:
                with open(path, 'w', encoding='utf-8') as fh: fh.write(new_data)
                print(f'  Patched: {path}')
"
# Fix minimum CMake versions required for macOS
find . -name "CMakeLists.txt" -exec sed -i '' 's/cmake_minimum_required(VERSION [1-2]\.[0-9]*/cmake_minimum_required(VERSION 3.5/g' {} +

Step 4: Configure and Build the Core Engine

Point CMake to the Homebrew and custom TinyXML paths, then compile:

mkdir build && cd build

cmake -DCMAKE_C_COMPILER=$(which clang) \
      -DCMAKE_CXX_COMPILER=$(which clang++) \
      -DCMAKE_INSTALL_PREFIX="/usr/local/" \
      -DCMAKE_PREFIX_PATH="$HOME/local;/opt/homebrew" \
      -DMETIS_INCLUDE_DIR="/opt/homebrew/include/" \
      -DTINYXML_INCLUDE_DIR="$HOME/local/include" \
      -DTINYXML_LIBRARIES="$HOME/local/lib/libtinyxml.dylib" \
      -DHEMELB_USE_ALL_WARNINGS_GNU=OFF \
      -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..

sudo make -j4

Note: If ParMETIS is found during configuration, you may need to run a second CMake pass to link it properly. Refer to the automated script for the dual-pass logic.

3. Geometry and Python Tool Setup

HemeLB requires C++20 for its tools, but Conda's macOS libraries often have compatibility bugs. We must use Rosetta to emulate an Intel environment (osx-64) and surgically patch the CGAL libraries.

Step 1: Create the Intel-Emulated Conda Environment

git clone https://gist.github.com/lepotatoguy/a51d9fc80c44a687e20ac33750ee8be5.git mac-env-temp
cp mac-env-temp/hlb-gmy-mac.yml .
rm -rf mac-env-temp

export CONDA_SUBDIR=osx-64 
conda env create -f hlb-gmy-mac.yml

conda activate gmy-tool
conda config --env --set subdir osx-64
conda install -y -c conda-forge cgal ninja "boost>=1.82" "cgal>=5.6"

Step 2: Patch the CGAL C++20 Bug

Apple Clang crashes on a buggy nullptr check inside Conda's CGAL iterator. Fix it directly:

CGAL_ITERATOR_HEADER="$CONDA_PREFIX/include/CGAL/boost/graph/iterator.h"
chmod u+w "$CGAL_ITERATOR_HEADER"
sed -i '' 's/this->base_reference() == nullptr/false/g' "$CGAL_ITERATOR_HEADER"
sed -i '' 's/this->base() == nullptr/false/g' "$CGAL_ITERATOR_HEADER"

Step 3: Install Python and Geometry Tools

# Install Python Tools
cd hemelb/python-tools
pip install .

# Compile Geometry Tool
cd ../geometry-tool
rm -rf _skbuild
export CMAKE_PREFIX_PATH="$CONDA_PREFIX"
pip install '.[gui]'

Note: If VMTK strictly checks for version 1.5 in setup.py, you may need to comment out the VMTK requirement line before running pip install.

Step 4: Enable GUI on macOS

macOS restricts windows to "Framework builds". To run the GUI, install the wrapper and map it:

conda install -y -c conda-forge python.app
alias hlb-gmy-gui="pythonw $(which hlb-gmy-gui)"

Step 5: Validate Installation

pip install pytest
hemelb-tests

4. Uninstall Instructions

sudo rm /usr/local/bin/hemelb
sudo rm -f /usr/local/bin/hemelb-confcheck /usr/local/bin/hemelb-tests
sudo rm -rf /usr/local/share/hemelb
rm -rf ~/local/include/tinyxml* ~/local/lib/libtinyxml*
conda remove -n gmy-tool --all

6. Useful References