QLGA primitives for CBSE encodings

.github/workflows/release.yml

@@ -133,7 +133,7 @@ jobs:
           name: python-package-distributions
           path: dist/
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v2.1.1
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
         with:
           inputs: |
             ./dist/*.tar.gz

CITATION.cff

@@ -0,0 +1,35 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Georgescu"
+  given-names: "Calin A."
+  orcid: "https://orcid.org/0000-0002-8102-6389"
+- family-names: "Schalkers"
+  given-names: "Merel A."
+  orcid: "https://orcid.org/0000-0001-7751-9060"
+- family-names: "Möller"
+  given-names: "Matthias"
+  orcid: "https://orcid.org/0000-0003-0802-945X"
+title: "qlbm – A Qantum Lattice Boltzmann Software Framework"
+version: 0.0.5
+doi: "10.1016/j.cpc.2025.109699"
+date-released: 2025-03-24
+url: "https://doi.org/10.1016/j.cpc.2025.109699"
+preferred-citation:
+  type: article
+  authors:
+  - family-names: "Georgescu"
+    given-names: "Calin A."
+    orcid: "https://orcid.org/0000-0002-8102-6389"
+  - family-names: "Schalkers"
+    given-names: "Merel A."
+    orcid: "https://orcid.org/0000-0001-7751-9060"
+  - family-names: "Möller"
+    given-names: "Matthias"
+    orcid: "https://orcid.org/0000-0003-0802-945X"
+  doi: "10.1016/j.cpc.2025.109699"
+  journal: "Computer Physics Communications"
+  title: "qlbm – A Qantum Lattice Boltzmann Software Framework"
+  volume: 315
+  year: 2025
+  issue: 109699

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Pull requests are welcome. To make a PR, first fork the repo, make your proposed changes on the main branch, and open a PR from your fork. If it passes tests and is accepted after review, it will be merged. For discussions about feature requests and contributions, please contact `c.a.georgescu@tudelft.nl`.
+
+## Code style
+
+### Formatting and Linting
+
+All code should be formatted using `ruff` with default options. You should verify that your changes adhere to the `ruff` standards before submitting a PR. The exact version used in the CI pipeline can be found in the `pyproject.toml` file. Both the source code `ruff check qlbm` and the demos `ruff check demos` should adhere to these standards.
+
+### Type annotation
+
+`mypy` is used as a static type checker and all submissions must pass its checks. YYou should verify that your changes adhere to the `mypy` standards before submitting a PR.  The exact version used in the CI pipeline can be found in the `pyproject.toml` file. There are some custom rules used for type checking: you can check whether your submission adheres to them by running `mypy qlbm test --config-file pyproject.toml`.
+Linting
+
+
+### Tests
+
+We encourage each contribution to include unit tests for the added functionality. Tests reside in the `test` directory and can be executed using `pytest test/unit`.
+Please sure all tests are passing before submitting a PR, and verify that simple flow simulations work as intended.
+When fixing a bug, please add a test that demonstrates the fix.
+
+### Documentation
+
+We encourage all contributions to contain an adequate and thorough documentation of the changes. All contributed classes, methods, and attributes should be documented using the established style. Where appropriate, please include code-block examples and references to the scientific literature.
+
+We use `sphinx` to automatically generate our documentation website. To make sure your contribution fits the standards of the code base, you can execute `make docs` in the root directory. To check the documentation website locally, you can first `cd docs` and then `make clean html` to build the website locally. You can view the updated web pages by opening `docs/build/html/index.html`.
+
+### Easy verification
+
+To verify that your changes comply with our checks, you can simply run `make check-ci` to run all checks.

Makefile

@@ -13,8 +13,8 @@ check-python-version:
 	@PYTHON_VERSION=$$($(PYTHON) --version 2>&1 | awk '{print $$2}'); \
 	MAJOR_VERSION=$$(echo $$PYTHON_VERSION | cut -d. -f1); \
 	MINOR_VERSION=$$(echo $$PYTHON_VERSION | cut -d. -f2); \
-	if [ "$$MAJOR_VERSION" -ne 3 ] || [ "$$MINOR_VERSION" -lt 8 ] || [ "$$MINOR_VERSION" -gt 13 ]; then \
-	    echo "Python version must be between 3.8 and 3.13"; \
+	if [ "$$MAJOR_VERSION" -ne 3 ] || [ "$$MINOR_VERSION" -lt 12 ] || [ "$$MINOR_VERSION" -gt 13 ]; then \
+	    echo "Python version must be between 3.12 and 3.13"; \
 	    exit 1; \
 	fi
 

README.md

@@ -62,8 +62,9 @@ source qlbm-cpu-venv/bin/activate
 
 
 Currently, `qlbm` supports two algorithms:
- - The Collisionless QLBM described in [Efficient and fail-safe quantum algorithm for the transport equation](https://doi.org/10.1016/j.jcp.2024.112816) ([arXiv:2211.14269](https://arxiv.org/abs/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](https://link.springer.com/article/10.1007/s11128-023-04216-6) by M.A. Schalkers and M. Möller.
+ - The Quantum Transport Method (Collisionless QLBM) described in [Efficient and fail-safe quantum algorithm for the transport equation](https://doi.org/10.1016/j.jcp.2024.112816) ([arXiv:2211.14269](https://arxiv.org/abs/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](https://link.springer.com/article/10.1007/s11128-023-04216-6) by M.A. Schalkers and M. Möller and expanded in [Fully Quantum Lattice Gas Automata Building Blocks for Computational Basis State Encodings](https://arxiv.org/abs/2506.12662).
+ - The Linear-encoding Quantum Lattice Gas Automata (LQLGA) described in [On quantum extensions of hydrodynamic lattice gas automata](https://www.mdpi.com/2410-3896/4/2/48) by P. Love and [Fully Quantum Lattice Gas Automata Building Blocks for Computational Basis State Encodings](https://arxiv.org/abs/2506.12662).
 
 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.
 
@@ -110,4 +111,18 @@ The `demos` directory contains several use cases for simulating and analyzing th
 
 ## Citation
 
-A preprint describing `qlbm` in detail is currently available on [arXiv](https://arxiv.org/abs/2411.19439). If you use `qlbm`, you can cite it as per the [CITATION.bib file](CITATION.bib).
+An open access peer-reviewed article describing `qlbm` is available [here](https://doi.org/10.1016/j.cpc.2025.109699). 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},
+}
+```

demos/simulation/lqlga_simulation.ipynb

@@ -0,0 +1,268 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "70305ef3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit_aer import AerSimulator\n",
+    "\n",
+    "from qlbm.components import EmptyPrimitive\n",
+    "from qlbm.components.lqlga.initial import LQGLAInitialConditions\n",
+    "from qlbm.components.lqlga.lqlga import LQLGA\n",
+    "from qlbm.components.lqlga.measurement import LQLGAGridVelocityMeasurement\n",
+    "from qlbm.infra import QiskitRunner, SimulationConfig\n",
+    "from qlbm.lattice.lattices.lqlga_lattice import LQLGALattice\n",
+    "from qlbm.tools.utils import create_directory_and_parents\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec2f4062",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qlbm.components.lqlga import LQGLAInitialConditions\n",
+    "from qlbm.lattice import LQLGALattice\n",
+    "\n",
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 7},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [{\"shape\": \"cuboid\", \"x\": [3, 5], \"boundary\": \"bounceback\"}],\n",
+    "    },\n",
+    ")\n",
+    "initial_conditions = LQGLAInitialConditions(lattice, [(tuple([2]), (True, True, True))])\n",
+    "initial_conditions.draw(\"mpl\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "05e422b4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qlbm.components.lqlga import LQLGAStreamingOperator\n",
+    "from qlbm.lattice import LQLGALattice\n",
+    "\n",
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 4},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [],\n",
+    "        # \"geometry\": [{\"shape\": \"cuboid\", \"x\": [3, 5], \"boundary\": \"bounceback\"}],\n",
+    "    },\n",
+    ")\n",
+    "streaming_operator = LQLGAStreamingOperator(lattice)\n",
+    "streaming_operator.draw(\"mpl\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "020bb111",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qlbm.components.lqlga import LQLGAReflectionOperator\n",
+    "from qlbm.lattice import LQLGALattice\n",
+    "\n",
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 7},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [{\"shape\": \"cuboid\", \"x\": [3, 5], \"boundary\": \"bounceback\"}],\n",
+    "    },\n",
+    ")\n",
+    "reflection_operator = LQLGAReflectionOperator(\n",
+    "    lattice, shapes=lattice.shapes[\"bounceback\"]\n",
+    ")\n",
+    "reflection_operator.draw(\"mpl\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "db7e5c99",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qlbm.components.lqlga import LQLGA\n",
+    "from qlbm.lattice import LQLGALattice\n",
+    "\n",
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 7},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [{\"shape\": \"cuboid\", \"x\": [3, 5], \"boundary\": \"bounceback\"}],\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "LQLGA(lattice=lattice).draw(\"mpl\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bb1f01f6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qlbm.components.lqlga import LQLGAGridVelocityMeasurement\n",
+    "from qlbm.lattice import LQLGALattice\n",
+    "\n",
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 5},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [],\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "LQLGAGridVelocityMeasurement(lattice=lattice).draw(\"mpl\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34715b68",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lattice = LQLGALattice(\n",
+    "    {\n",
+    "        \"lattice\": {\n",
+    "            \"dim\": {\"x\": 4},\n",
+    "            \"velocities\": \"D1Q3\",\n",
+    "        },\n",
+    "        \"geometry\": [],\n",
+    "        # \"geometry\": [{\"shape\": \"cuboid\", \"x\": [3, 5], \"boundary\": \"bounceback\"}],\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "output_dir = f\"qlbm-output/lqlga-{lattice.logger_name()}-qiskit\"\n",
+    "create_directory_and_parents(output_dir)\n",
+    "\n",
+    "lattice.circuit.draw(\"mpl\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b084dda3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "LQLGA(lattice).circuit.draw(\"mpl\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "86ec87a5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cfg = SimulationConfig(\n",
+    "    initial_conditions=LQGLAInitialConditions(\n",
+    "        lattice, [(tuple([2]), (True, True, True))]\n",
+    "    ),\n",
+    "    algorithm=LQLGA(lattice),\n",
+    "    postprocessing=EmptyPrimitive(lattice),\n",
+    "    measurement=LQLGAGridVelocityMeasurement(lattice),\n",
+    "    target_platform=\"QISKIT\",\n",
+    "    compiler_platform=\"QISKIT\",\n",
+    "    optimization_level=0,\n",
+    "    statevector_sampling=True,\n",
+    "    execution_backend=AerSimulator(method=\"statevector\"),\n",
+    "    sampling_backend=AerSimulator(method=\"statevector\"),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4d54ef63",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cfg.prepare_for_simulation()\n",
+    "\n",
+    "# Number of shots to simulate for each timestep when running the circuit\n",
+    "# NUM_SHOTS = 2**10\n",
+    "\n",
+    "NUM_SHOTS = 2**10\n",
+    "\n",
+    "# Number of timesteps to simulate\n",
+    "NUM_STEPS = 100\n",
+    "\n",
+    "# Create a runner object to simulate the circuit\n",
+    "runner = QiskitRunner(\n",
+    "    cfg,\n",
+    "    lattice,\n",
+    ")\n",
+    "\n",
+    "# Simulate the circuits using both snapshots\n",
+    "runner.run(\n",
+    "    NUM_STEPS,  # Number of time steps\n",
+    "    NUM_SHOTS,  # Number of shots per time step\n",
+    "    output_dir,\n",
+    "    statevector_snapshots=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "76799b9e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cfg.initial_conditions.draw(\"mpl\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "244ed487",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}