qlbm

qlbm is a package for the development, simulation, and analysis of Quantum Lattice Boltzmann Methods.

---

qlbm is a rapidly evolving, research-oriented piece of software. It contains building blocks for constructing quantum circuits for quantum LBMs and connects these with quantum software infrastructure. qlbm is built with end-to-end development environment in mind, including:

• Parsing human-readable JSON specifications for QLBMs
• Constructing quantum circuits in Qiskit that implement QLBMs
• Compiling quantum circuits to quantum computer and simulator platforms with Qiskit and Pytket
• Simulating quantum circuits on classical hardware with Qiskit and Qulacs
• Visualizing results in Paraview
• Analyzing the properties , scalability, and performance of quantum algorithms

Install from source

Alternatively, you can also install the latest version of qlbm by cloning the repository and installing from source as follows (again using Python 3.12 or 3.13):

git clone git@github.com:QCFD-Lab/qlbm.git
cd qlbm
python -m venv qlbm-cpu-venv
source qlbm-cpu-venv/bin/activate
pip install --upgrade pip
pip install -e .[cpu,dev,docs]

If you are using zsh you need to replace the last line by

pip install -e .\[cpu,dev,docs\]

We also provide a make script for this purpose, which will create the environment from scratch:

make install-cpu
source qlbm-cpu-venv/bin/activate

PyPI installation

qlbm can also be installed through pip. We recommend the use of a Python 3.12 or 3.13 virtual environment:

python -m venv qlbm-cpu-venv
pip install --upgrade pip
pip install qlbm

Note that qlbm evolves quickly and it is likely that the GitHub repository contains new features that the PyPI installation does not. To get the latest developments, we recommend the source installation.

Container installation

There are also Docker container images in the Docker directory that can be used to install qlbm in a container environment. Due to how quickly the code base is evolving, we recommend using the CPU option for stability purposes.

Algorithms and Usage

Currently, qlbm supports two algorithms:

• The Quantum Transport Method (Collisionless QLBM) described in Efficient and fail-safe quantum algorithm for the transport equation (arXiv:2211.14269) by M.A. Schalkers and M. Möller.
• The Space-Time QLBM/QLGA described in On the importance of data encoding in quantum Boltzmann methods by M.A. Schalkers and M. Möller and expanded in Fully Quantum Lattice Gas Automata Building Blocks for Computational Basis State Encodings.
• The Linear-encoding Quantum Lattice Gas Automata (LQLGA) described in On quantum extensions of hydrodynamic lattice gas automata by P. Love and Fully Quantum Lattice Gas Automata Building Blocks for Computational Basis State Encodings.

The demos directory contains several use cases for simulating and analyzing these algorithms. Each demo requires minimal setup once the virtual environment has been configured. Consult the README.md file in the demos directory for further details.

Note on visualization: we rely on Paraview for visualizing the flow field of the simulation. You can install Paraview from this link.

Configuration

qlbm uses quantum circuits to simulate systems that users can specify in simple JSON configuration files. For instance, the following configuration describes a 2D system of 64x32 gridpoints, 4 discrete velocities per dimension, and with 3 solid objects placed in the fluid domain:

{
  "lattice": {
    "dim": {
      "x": 64,
      "y": 32
    },
    "velocities": {
      "x": 4,
      "y": 4
    }
  },
  "geometry": [
    { 
      "shape": "cuboid",
      "x": [18, 20],
      "y": [6, 25],
      "boundary": "specular"
    },
    {
      "shape": "cuboid",
      "x": [23, 25],
      "y": [3, 17],
      "boundary": "bounceback"
    },
    {
      "shape": "cuboid",
      "x": [28, 29],
      "y": [16, 29],
      "boundary": "specular"
    }
  ]
}

Citation

An open access peer-reviewed article describing qlbm is available here. If you use qlbm, you can cite it as:

@article{georgescu2025qlbm,
title = {qlbm – A quantum lattice Boltzmann software framework},
journal = {Computer Physics Communications},
volume = {315},
pages = {109699},
year = {2025},
issn = {0010-4655},
doi = {https://doi.org/10.1016/j.cpc.2025.109699},
url = {https://www.sciencedirect.com/science/article/pii/S0010465525002012},
author = {C\u{{a}}lin A. Georgescu and Merel A. Schalkers and Matthias M\"{o}ller},
}

Contact

In addition to opening issues, you can contact the developers of qlbm at qcfd-EWI@tudelft.nl.