HemeLB Setup Instructions

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

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

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. Post-Installation Verification
  4. 4. Geometry and Python Tool Setup
  5. 5. Uninstall Instructions
  6. 6. Useful References

1. Prerequisites

  • Operating System: Ubuntu 24.04.1
  • Pre-installed: git and Anaconda

2. Installation Steps

Step 1: Install Required Packages

sudo apt-get install cmake-curses-gui
sudo apt install cmake build-essential
sudo apt install libopenmpi-dev openmpi-bin
sudo apt-get install libtinyxml-dev
sudo apt install libboost-all-dev
sudo apt install libcgal-dev

Step 2: Clone and Configure HemeLB

git clone https://github.com/hemelb-codes/hemelb.git
cd hemelb
git checkout 432d338
mkdir build && cd build
ccmake ..

Press c to configure, update any necessary values, then press c again and finally g to generate build files.

Step 3: Build the Project

make        # or use make -j4 for parallel build

Use sudo if you encounter permission errors.

3. Post-Installation Verification

Check if the binary is accessible via:

which hemelb

If not, you may need to add the binary directory to your system's PATH environment variable.

4. Geometry and Python Tool Setup

Step 1: Install Geometry Tool Dependencies

Download the required environment file hemelb-geometry-python-env.txt and create the environment:

conda create --name gmy-tool --file hemelb-geometry-python-env.txt --yes

Step 2: Install Python Tools

cd hemelb/python-tools
pip install .

Step 3: Install Geometry Tool (GUI)

cd ../geometry-tool
pip install '.[gui]'

Optional: Fix for VMTK Detection Error

If vmtk is installed but not detected, either:

  • Edit geometry-tool/setup.py and comment out the VMTK dependency line
  • Or follow Appendix 5.3 in the documentation.

Re-run the installation afterwards:

pip install '.[gui]'

Step 4: Validate Installation

pip install pytest
hemelb-tests

Ensure the tests complete successfully without errors.

5. 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
conda remove -n gmy-tool --all

6. Useful References