QCFD-Lab · gcalin · Sep 4, 2025 · Sep 2, 2025 · Sep 2, 2025 · Sep 2, 2025
diff --git a/Docker/README.md b/Docker/README.md
@@ -0,0 +1,29 @@
+# Container files
+
+We provide two docker files fo `qlbm`: one for regular development and one for GPU integration.
+
+## Development container
+
+`build_cpu.Dockerfile` can be used to build a container image that has all dependencies of `qlbm` for active development. You can build the image from the repository root as follows:
+
+```bash
+docker build -t qlbm -f Docker/build_cpu.Dockerfile .
+```
+
+Once the image is built, it will have all the dependencies, but not `qlbm` itself. You can actively link the repository files to the running container with the command
+
+```bash
+docker run -it --volume $(pwd):/qlbm/ qlbm
+```
+
+Once inside the container, you can quickly link the files in the volume to `pip` with
+
+```
+pip install -e .[cpu,dev,docs]
+```
+
+This will allow you to edit the files on your machine's file system in a text editor of your choice, and have the updates immediately available in the running container, without reinstalling anything.
+
+## GPU container
+
+`build_gpu.Dockerfile` contains an image allows you to simulate `qlbm` algorithms on nVidia GPU hardware with Qiskit and using the nVidia cuQuantum appliance.
diff --git a/Docker/build_cpu.Dockerfile b/Docker/build_cpu.Dockerfile
@@ -1,16 +1,12 @@
-FROM python:3.11-bookworm
+FROM python:3.13-bookworm
 
-RUN apt-get update -qq && apt-get install -y -qq libboost-all-dev cmake
+RUN apt-get update -qq && apt-get install -y -qq libboost-all-dev cmake pandoc libglfw3-dev libgles2-mesa-dev
 
 WORKDIR /qlbm
 
-COPY Makefile Makefile
 COPY pyproject.toml pyproject.toml
-COPY README.md README.md
-
-RUN make install-cpu
-
-COPY qlbm qlbm
-COPY test test
+RUN python -m pip install --upgrade pip \
+    && pip install --no-cache-dir -e ".[cpu,dev,docs]" \
+    && rm -rf /root/.cache/pip
 
 ENTRYPOINT /bin/bash
diff --git a/README.md b/README.md
@@ -21,18 +21,7 @@
 </a>
 </p>
 
-
-## PyPI installation
-
-`qlbm` can be installed through `pip`. We recommend the use of a Python 3.12 or 3.13 virtual environment:
-
-```bash
-python -m venv qlbm-cpu-venv
-pip install --upgrade pip
-pip install qlbm
-```
-
-## Local installation
+## 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):
 
@@ -56,7 +45,21 @@ 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.
+## PyPI installation
+
+`qlbm` can also be installed through `pip`. We recommend the use of a Python 3.12 or 3.13 virtual environment:
+
+```bash
+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
 

diff --git a/demos/simulation/collisionless_simulation.ipynb b/demos/simulation/collisionless_simulation.ipynb
@@ -1,15 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "6e87b04a-a016-4208-b38f-62a84692aedc",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install qlbm matplotlib seaborn pandas"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -131,7 +121,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "qlbm-cpu-venv",
    "language": "python",
    "name": "python3"
   },
@@ -145,7 +135,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

diff --git a/demos/simulation/lqlga_simulation.ipynb b/demos/simulation/lqlga_simulation.ipynb
@@ -37,137 +37,10 @@
     "        \"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\")"
+    "output_dir = \"qlbm-output/lqlga-d1q3-7-qiskit\"\n",
+    "create_directory_and_parents(output_dir)\n"
    ]
   },
   {
@@ -203,12 +76,10 @@
     "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",
+    "NUM_STEPS = 20\n",
     "\n",
     "# Create a runner object to simulate the circuit\n",
     "runner = QiskitRunner(\n",
@@ -228,25 +99,15 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "76799b9e",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "cfg.initial_conditions.draw(\"mpl\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "244ed487",
+   "id": "ed774960",
    "metadata": {},
    "outputs": [],
    "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "qiskit2-venv",
+   "display_name": "qlbm-cpu-venv",
    "language": "python",
    "name": "python3"
   },
@@ -260,7 +121,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.0"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

diff --git a/demos/simulation/spacetime_simulation.ipynb b/demos/simulation/spacetime_simulation.ipynb
@@ -1,14 +1,5 @@
 {
  "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%pip install qlbm matplotlib seaborn pandas"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -130,7 +121,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "qiskit2-venv",
+   "display_name": "qlbm-cpu-venv",
    "language": "python",
    "name": "python3"
   },
@@ -144,7 +135,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.0"
+   "version": "3.13.7"
   }
  },
  "nbformat": 4,

diff --git a/demos/visualization/collisionless_components.ipynb b/demos/visualization/collisionless_components.ipynb
@@ -5,7 +5,7 @@
    "id": "ca7a55e2-5729-4a0c-b1bc-19ace7be8100",
    "metadata": {},
    "source": [
-    "# Visualizing Collisionless circuits"
+    "# Visualizing Collisionless QLBM circuits"
    ]
   },
   {