Skip to main content

qlbm

GitHub License GitHub top language Python Version from PEP 621 TOML PyPI - Version GitHub commits since latest release GitHub branch check runs Static Badge

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

Static Badge

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 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.

Metadata

Release files for qlbm 0.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qlbm 0.0.6
File Size Uploaded Provenance Actions
qlbm-0.0.6.tar.gz 102.3 kB With provenance Details for qlbm-0.0.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qlbm 0.0.6
File Interpreter ABI Platform Actions
qlbm-0.0.6-py3-none-any.whl Python 3 none any Details for qlbm-0.0.6-py3-none-any.whl

Total release size: 252.0 kB

Release files / qlbm-0.0.6.tar.gz

Download URL qlbm-0.0.6.tar.gz
Size 102.3 kB
Tags Source
SHA-256 checksum
How to use checksums
23c74533a9c28143e72288e0b0021f68a022967b949409b241fc54c6dddf8b2a
BLAKE2b-256 checksum
How to use checksums
5b46e6f163ecea38980fd86e0b8a4db077a8f79a9d28e27788b3677feceff436
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2025.

Transparency log

Release files / qlbm-0.0.6-py3-none-any.whl

Download URL qlbm-0.0.6-py3-none-any.whl
Size 149.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
03b4b305737709aa3bc2624fe402e501569c51aa6feaba26f375b20d2bc04880
BLAKE2b-256 checksum
How to use checksums
ef911f2458c3610c015e118fa6ba8ad2731aa85f0d2b6aee458e9dbb2fe6bd94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2025.

Transparency log

Security for qlbm 0.0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qlbm-0.0.6.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 4, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page