HemeLB Improved Fork

What this is

HemeLB simulates fluid flow, most often blood flow, through complex 3D shapes such as vessel networks. lepotatoguy/hemelb is an improved version of it, with an installer, bug fixes, and updated documentation. The full list of changes is in the changelog.

Why use it

Compared with the upstream repository, this fork adds a portable installer, safer geometry and checkpoint handling, repaired geometry and Python tools, and updated guides. It also includes a ready-to-run example and an installed command for exporting results to ParaView.

• One script installs everything on macOS (Intel or Apple Silicon) and Ubuntu.
• No manual workarounds: no editing setup.py and no extra scripts for VMTK.
• Pinned geometry environment packages, so installations use the same tool dependency versions.
• Clear error messages for common mistakes, where HemeLB used to crash or fail silently.
• Warnings from the geometry tool when an inlet, outlet, or seed point is misplaced.
• Checkpoints can be restarted with a different number of MPI processes.
• The Python tools work on Python 3.12 and 3.13.
• A matching STL, profile, GMY, and XML example is included, with field output and checkpoints enabled.
• The installed hlb-extracted-to-vtk command exports results for ParaView.

This guide describes fix/hemelb-improvements: solver XML and extraction output use version 5, pressure output is in mmHg, and velocity is in m/s. Use this branch's documentation and tools with it. The separate feature branch has different formats and additional CPU models.

What you need

• macOS or Ubuntu Linux, git, and an internet connection. The script installs the remaining dependencies; on macOS, install the Xcode Command Line Tools when prompted.
• Tested on macOS 14 and 27 (Apple Silicon), macOS 15 (Intel), and Ubuntu 24.04.
• Not tested: Debian, older Ubuntu releases, Linux on ARM, and Linux without apt.

Dependency requirements, bundled versions, and exact environment lock-file locations are listed in INSTALL.

The geometry environment supports Python 3.8 through 3.11 because of VMTK; the Python tools can also be installed separately on Python 3.12/3.13. On Apple Silicon, the solver runs natively and the geometry environment uses Intel macOS packages under Rosetta. Environment lock files pin the tool packages; system compilers, MPI, and package-manager versions can vary.

Install

git clone --branch fix/hemelb-improvements https://github.com/lepotatoguy/hemelb.git
cd hemelb
bash Scripts/install_hemelb.sh

On macOS, accept the offer to install the Xcode Command Line Tools if it appears, then run the script again. The script may ask for your password (to install system packages). It then:

1. Installs the system packages HemeLB needs.
2. Builds HemeLB into ~/.local/hemelb and runs its tests.
3. Creates a conda environment called gmy-tool with the geometry tool and Python tools (installing conda first if you do not have it).

Installation time depends on the machine, downloads, and build cache. Follow the installer output for progress; timings from earlier versions do not establish the time for a new installation.

Useful options

Run bash Scripts/install_hemelb.sh --help for all of them.

• --prefix DIR: install HemeLB into DIR instead of ~/.local/hemelb
• --jobs N: number of parallel build jobs
• --env-name NAME: name of the conda environment (default gmy-tool)
• --env-prefix DIR: create the conda environment at a path instead of using a name
• --no-gmy-tool: build HemeLB only, skipping both geometry and Python tools
• --no-system-deps: skip installing system packages, if you already have them
• --no-tests: skip running the unit tests; they are still built
• --no-gui: skip macOS GUI launcher setup

Check that it worked

export PATH="$HOME/.local/hemelb/bin:$PATH"   # makes hemelb and hemelb-tests available

hemelb-tests

Quick start

Once installed, you use HemeLB the same way as in the Tutorial: prepare the geometry, set up the configuration, run the simulation, and analyse the results. Open a new terminal and run the two commands under Check that it worked first.

A worked example with sample files is also in the fork's Quick start guide.

Analyse the results

The run creates results/report.txt and report.xml, field output in results/Extracted/whole.xtr with its companion whole.off, and checkpoints at timesteps 100 and 200 with shared offsets checkpoint_.off.

Export results to readable CSV

hlb-dump-extracted-properties results/Extracted/whole.xtr whole.csv

The file has comment headers and a separate block of rows for each saved timestep. Keep the headers: the timestep is recorded there, rather than repeated in each row. Vector fields use component columns. Velocity is in m/s and pressure is in mmHg on this branch.

Export for ParaView

hlb-extracted-to-vtk results/Extracted/whole.xtr paraview/whole --step-length 0.0001

Use the ParaView 5.13.3 GUI (tested). Open paraview/whole.pvd, click Apply, and select pressure or velocity (Magnitude) under cell data. Use the time controls to view the saved frames.

Restart a saved checkpoint (optional)

If a run stops before finishing, resume from a checkpoint saved before it stopped. A completed run can also be continued to a later final timestep. Keep both the checkpoint .xtr and its matching .off file.

For the bundled example, create restart.xml by running this command beside first-run.xml and results/:

python - <<'PYCODE'
import xml.etree.ElementTree as ET

tree = ET.parse("first-run.xml")
initial = tree.getroot().find("initialconditions")
initial.clear()
ET.SubElement(initial, "checkpoint",
              file="results/Extracted/checkpoint_100.xtr",
              offsets="results/Extracted/checkpoint_.off")
tree.write("restart.xml", encoding="utf-8", xml_declaration=True)
PYCODE
mpirun -n 4 hemelb -in restart.xml -out resumed

This resumes the two-rank run from timestep 100 using four ranks and continues to timestep 200. The configured steps is the final timestep, not the number of additional steps. Use a larger value to continue longer, and a new output directory for the restart.

Keep the same fluid geometry, voxel size, origin, lattice, and physical model. This restores fluid distributions; it does not restore red blood cell or colloid state. See the checkpoint guide for file requirements, timestep selection, and geometry checks.

Troubleshooting

• Geometry file ... does not exist: the <datafile path="..."> in the XML is wrong. Relative paths are resolved relative to the XML file, not the current directory.
• The geometry file uses N outlet(s) but the configuration defines M: add the missing inlets or outlets to the XML, in the same order as in the profile.
• The geometry has N block(s) containing fluid but HemeLB is running on P MPI processes: run with fewer processes, as the message says.
• Output directory ... already exists.: pick a new -out folder name for each run.
• A Warning: from the geometry tool: an inlet, outlet, or the seed point is probably misplaced, so the geometry may be wrong. See "Things to watch" in geometry-tool.md.
• Permission denied or No such file or directory when starting the installer: run it with bash in front, from inside the hemelb folder. If Scripts/install_hemelb.sh is missing, follow Install to clone fix/hemelb-improvements into a new folder.
• This program needs access to the screen when starting hlb-gmy-gui on macOS: run python geometry-tool/macos-fix-gui-launcher.py from the hemelb folder with gmy-tool active. The install script already does this.
• The installer says the conda environment already exists: remove it with conda env remove -n gmy-tool, or choose another name with --env-name.
• hlb-extracted-to-vtk: command not found: activate the tools environment. If it was installed before this command was added, reinstall the package with python -m pip install --no-deps --no-build-isolation ./python-tools from the repository root.
• Missing checkpoint offsets: for the example, explicitly set offsets="results/Extracted/checkpoint_.off" in the restart XML. The default inferred name would be checkpoint_100.off, which is not the shared offsets file.

Glossary

• STL: a file describing a surface as triangles; the shape of your vessel.
• Profile (.pr2): the geometry tool's settings (STL, units, voxel size, inlets, outlets, seed point, time step), stored as YAML.
• Voxel, lattice site: the simulation divides space into small cubes of one size (the voxel size); each fluid cube is a site.
• Block: a group of 8×8×8 sites, the unit HemeLB shares out between processes.
• Geometry (.gmy): the voxelised vessel, recording which sites are fluid and where the walls, inlets, and outlets cut them.
• Configuration (.xml): the simulation settings HemeLB reads.
• Inlet, outlet, iolet: where fluid enters or leaves ("iolet" means either); each is a disc with a centre, a normal pointing into the fluid, and a radius.
• Seed point: any point inside the fluid; the geometry tool keeps the part of the surface closest to it.
• Extraction file (.xtr): results saved during a run, such as velocity and pressure.
• MPI process (rank): one of the parallel copies of HemeLB started by mpirun -n N.
• Checkpoint: a saved state that a later run can restart from.
• VTU / PVD: a VTK unstructured-grid frame and a collection that ParaView opens as a time series.

Uninstalling

rm -rf ~/.local/hemelb
conda env remove -n gmy-tool

If the script installed Miniforge for you, you can also delete ~/miniforge3.

Getting help

• Documentation index, with a glossary and links to every guide
• Installing HemeLB (the installer, its options, and platform notes)
• Quick start (run the bundled example)
• Bundled examples (matching STL, profile, GMY, and XML)
• Geometry tool (GUI and command-line generation)
• Python tools (converting and inspecting output)
• Building and running HemeLB (building by hand)
• Fluid checkpoints (save and resume a run)
• Troubleshooting (configuration, geometry, MPI, and output failures)
• Changelog (every change in this fork, and how it was checked)

Found a problem with the fork itself? Report it on GitHub Issues.

For advanced users

An upgraded version of HemeLB is being developed on the feat/scalability-input-improvements branch. It addresses limitations in the official HemeLB and HemePure, supports existing input files from both, and aims to improve performance over both. See the branch's compatibility guide and performance results for details. I no longer work on this project actively, so contributions are welcome.