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

qlbm can 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

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 [email protected]: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

qlbm additionally supports several other options, including GPU and MPI simulation. There are also Docker container images in the Docker directory. Due to how quickly the code base is evolving, we recommend using the CPU option for stability purposes.

Currently, qlbm supports two algorithms:

• The 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 described in On the importance of data encoding in quantum Boltzmann methods by M.A. Schalkers and M. Möller.

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.

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"
    }
  ]
}

A preprint describing qlbm in detail is currently available on arXiv. If you use qlbm, you can cite it as per the CITATION.bib file.