HemeLB Tutorial

Author: Joyanta Mondal (joyanta@udel.edu)

Last Updated: May 12

Extensive and Most Updated HemeLB Documentation and Tutorial

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

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)

Initially, you have to have a .pr2 profile to execute it. You can find it more in section 4.

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

2. Running Simulation

2.1. Prepare Your XML Configuration

Add the following block to 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 processor count (-n) as appropriate.

3. Extracting and Visualizing Results

3.1. Extract Simulation Output

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

This converts the output to a CSV file readable for analysis or visualization.

3.2. Visualize Using ParaView

Download ParaView from the official site.

In ParaView:

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

4. Understanding the .pr2 Profile File

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

4.1 Purpose

Encapsulates all geometry setup parameters in a reusable and 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>    # e.g., "cylinder.gmy"
OutputXmlFile: <string>         # e.g., "cylinder.xml"
SeedPoint:
  x: <float>
  y: <float>
  z: <float>
StlFile: <string>               # e.g., "cylinder.stl"
StlFileUnitId: 0 | 1 | 2        # 0 = meters, 1 = millimeters, 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) to ensure compatibility.
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  # 6.0 s
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

This command reads profile.pr2 and produces the corresponding .gmy and .xml output files.

Important: If using integer values instead of floats, it may 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.