HemeLB Tutorial

Author: Joyanta Mondal Last Updated: May 15, 2026

Extensive HemeLB Documentation →

This tutorial covers the workflow for using HemeLB after installation, focusing on geometry preparation, simulation execution, and data analysis.

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. 0. Files You Need to Get Started
  2. 1. Geometry Setup
  3. 2. Running Simulation
  4. 3. Extracting and Visualizing Results
  5. 4. Understanding the .pr2 Profile File
  6. 5. References

0. Files You Need to Get Started

  • Your STL geometry file.
  • HemeLB installed.
  • (Optional) .pr2 file for the CLI tool.

1. Geometry Setup

1.1. Launch the Geometry Tool

hlb-gmy-gui [--stl <path-to-stl>]

In the GUI:

  • Load your STL file.
  • Add inlet (green) and outlet (red) discs.
  • Set disc radius > geometry radius.
  • Specify voxel size and seed position (inside geometry).
  • Choose output paths for .gmy and .xml files.
  • Use "Save Profile" to generate a reusable .pr2 YAML file.

1.2. Use CLI Tool (Alternative)

Requires a .pr2 profile (see Section 4).

hlb-gmy-cli <path-to-profile.pr2>

2. Running Simulation

2.1. Prepare Your XML Configuration

Add the following block just before the last line of your XML to enable data output:

<properties>
  <propertyoutput file="whole.xtr" period="100">
    <geometry type="whole" />
    <field type="velocity" />
    <field type="pressure" />
  </propertyoutput>
</properties>

2.2. Execute HemeLB Simulation

mpirun -n 4 hemelb -in large_cylinder.xml -out ./output/large_cylinder_test

Ensure .xml and .gmy files are in the same directory. Adjust -n as appropriate.

3. Extracting and Visualizing Results

3.1. Extract Simulation Output

hlb-dump-extracted-properties whole.xtr > whole.csv

3.2. Visualize Using ParaView

Download ParaView from the official site.

  1. Open the CSV file.
  2. Use the "Calculator" filter with: 
    iHat*vel_x + jHat*vel_y + kHat*vel_z
  3. Apply the "Glyph" filter to visualize flow vectors.

4. Understanding the .pr2 Profile File

The .pr2 file is a YAML-based configuration used by hlb-gmy-cli to generate both the voxelized geometry (.gmy) and simulation configuration file (.xml).

4.1 Purpose

  • Encapsulates all geometry setup parameters in a reusable, human-readable format.
  • Enables reproducible workflows and automation of geometry generation.
  • Required input for command-line generation using hlb-gmy-cli.

4.2 Structure Overview

DurationSeconds: <float>
Iolets:
  - Centre:
      x: <float>
      y: <float>
      z: <float>
    Name: <string>
    Normal:
      x: <float>
      y: <float>
      z: <float>
    Pressure:
      x: <float>
      y: <float>
      z: <float>
    Radius: <float>
    Type: Inlet | Outlet
OutputGeometryFile: <string>
OutputXmlFile: <string>
SeedPoint:
  x: <float>
  y: <float>
  z: <float>
StlFile: <string>
StlFileUnitId: 0 | 1 | 2    # 0=meters, 1=mm, 2=micrometers
TimeStepSeconds: <float>
VoxelSize: <float>

4.3 Notes on Field Values

  • All floats should be in hexadecimal format (e.g., 0x1.0p+0 for 1.0).
  • Inlets/Outlets must specify center, normal vector, radius, and type.
  • SeedPoint must be inside the fluid volume for correct voxelization.
  • VoxelSize determines resolution of the simulation grid.

4.4 Example

DurationSeconds: 0x1.8000000000000p+2
Iolets:
  - Centre:
      x: 0x0.0p+0
      y: 0x0.0p+0
      z: -0x1.c3c0000000000p+4
    Name: Inlet1
    Normal:
      x: 0x0.0p+0
      y: 0x0.0p+0
      z: 0x1.0p+0
    Pressure:
      x: 0x1.0p+4
      y: 0x0.0p+0
      z: 0x1.0p+0
    Radius: 0x1.0p+1
    Type: Inlet
  - Centre:
      x: 0x0.0p+0
      y: 0x0.0p+0
      z: 0x1.c3c0000000000p+4
    Name: Outlet1
    Normal:
      x: 0x0.0p+0
      y: 0x0.0p+0
      z: -0x1.0p+0
    Pressure:
      x: 0x0.0p+0
      y: 0x0.0p+0
      z: 0x0.0p+0
    Radius: 0x1.0p+1
    Type: Outlet
OutputGeometryFile: cylinder.gmy
OutputXmlFile: cylinder.xml
SeedPoint:
  x: 0x0.0p+0
  y: 0x0.0p+0
  z: 0x0.0p+0
StlFile: cylinder.stl
StlFileUnitId: 1
TimeStepSeconds: 0x1.52d02c7e14af6p-17
VoxelSize: 0x1.999999999999ap-3

4.5 Usage

hlb-gmy-cli profile.pr2

Note: Using integer values instead of floats will raise:

ValueError: invalid hexadecimal floating-point string

4.6 Best Practices

  • Validate that all floating-point values conform to hexadecimal format.
  • Keep backups of .pr2 profiles for reproducibility and batch processing.

5. References