ABQLBM Specular Reflection

.github/workflows/docs.yml

@@ -23,7 +23,17 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: 3.12.5
-
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ${{ env.pythonLocation }}
+          key: pip-docs-3.12.5-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            pip-docs-3.12.5-
+
       - name: Install dependencies
         run: |
           sudo apt-get install -y -qq pandoc libglfw3-dev libgles2-mesa-dev
@@ -37,8 +47,8 @@ jobs:
         run: |
           make -C docs doctest
 
-      - name: Build docs
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+      - name: Build Docs
+        if: ${{ github.ref == 'refs/heads/main' }}
         run: |
           sphinx-build docs/source _build
 

.github/workflows/format.yml

@@ -18,7 +18,15 @@ jobs:
         with:
           python-version: 3.12.5
           architecture: x64
-          cache: "pip" # caching pip dependencies
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ${{ env.pythonLocation }}
+          key: pip-format-3.12.5-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            pip-format-3.12.5-
       - name: Install Ruff
         run: |
           pip install --upgrade pip

.github/workflows/tests.yml

@@ -2,7 +2,7 @@ name: Test using pytest
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
     branches: [main]
 
@@ -20,15 +20,29 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "pip" # caching pip dependencies
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ${{ env.pythonLocation }}
+          key: pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            pip-${{ matrix.python-version }}-
       - name: Install dependencies
         run: |
           sudo apt-get update && sudo apt-get install -y -qq libboost-all-dev cmake
       - name: Install qlbm
         run: |
-          pip install --upgrade pip 
+          pip install --upgrade pip
           pip install -e .[cpu,dev]
       - name: Display Python version
         run: python -c "import sys; print(sys.version)"
-      - name: Run unit tests
-        run: pytest test/unit --doctest-modules --junitxml=junit/test-results.xml --cov=qlbm --cov-report=xml --cov-report=html
+      - name: Run tests
+        run: pytest test --doctest-modules --junitxml=junit/test-results.xml --cov=qlbm --cov-report=xml --cov-report=html
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report-${{ matrix.python-version }}
+          path: htmlcov/

.github/workflows/typecheck.yml

@@ -18,7 +18,15 @@ jobs:
         with:
           python-version: 3.12.5
           architecture: x64
-          cache: "pip" # caching pip dependencies
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ${{ env.pythonLocation }}
+          key: pip-typecheck-3.12.5-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            pip-typecheck-3.12.5-
       - name: Install mypy
         run: |
           pip install --upgrade pip

demos/simulation/ab_simulation.ipynb

@@ -45,7 +45,7 @@
     ")\n",
     "\n",
     "\n",
-    "output_dir = \"qlbm-output/ab-d2q9-64x32-1-obstacle-qiskit\"\n",
+    "output_dir = \"qlbm-output/ab-d2q9-64x32-1-obstacle-cuboid-qiskit\"\n",
     "create_directory_and_parents(output_dir)"
    ]
   },

demos/simulation/ab_simulation_parallel_bcs.ipynb

@@ -18,8 +18,6 @@
     "from qiskit_aer import AerSimulator\n",
     "\n",
     "from qlbm.components import (\n",
-    "    CQLBM,\n",
-    "    ABDiscreteUniformInitialConditions,\n",
     "    ABGridMeasurement,\n",
     "    EmptyPrimitive,\n",
     ")\n",
@@ -42,7 +40,7 @@
     "    }\n",
     ")\n",
     "\n",
-    "output_dir = \"qlbm-output/ab-pbc-d2q9-16x16-1-obstacle-qiskit\"\n",
+    "output_dir = \"qlbm-output/ab-pbc-d2q9-16x16-qiskit\"\n",
     "create_directory_and_parents(output_dir)"
    ]
   },
@@ -54,16 +52,15 @@
    "outputs": [],
    "source": [
     "# Geometry of marker |0>: two \"stacked\" \"wide\" rectangles\n",
-    "# Geometry of the marker |1>: one \"tall\" rectangle under the first two\n",
+    "# Geometry of the marker |1>: only the \"top\" rectangle is present\n",
     "# These geometries will act fully in parallel, and we will observe the average behavior\n",
     "lattice.set_geometries(\n",
     "    [\n",
     "        [\n",
     "            {\"shape\": \"cuboid\", \"x\": [6, 12], \"y\": [12, 14], \"boundary\": \"bounceback\"},\n",
     "            {\"shape\": \"cuboid\", \"x\": [6, 12], \"y\": [8, 10], \"boundary\": \"bounceback\"},\n",
-    "            # {\"shape\": \"cuboid\", \"x\": [6, 8], \"y\": [0, 6], \"boundary\": \"bounceback\"},\n",
     "        ],\n",
-    "        [{\"shape\": \"cuboid\", \"x\": [6, 8], \"y\": [0, 6], \"boundary\": \"bounceback\"}],\n",
+    "        [{\"shape\": \"cuboid\", \"x\": [6, 12], \"y\": [12, 14], \"boundary\": \"bounceback\"},],\n",
     "    ]\n",
     ")"
    ]
@@ -85,15 +82,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from qlbm.components.ab.ab import ABQLBM\n",
     "from qlbm.components.ab.initial import ABParallelDiscreteUniformInitialConditions\n",
     "\n",
     "cfg = SimulationConfig(\n",
     "    initial_conditions=ABParallelDiscreteUniformInitialConditions(\n",
     "        lattice,\n",
-    "        [[1], [1]],\n",
+    "        [[5], [5]],\n",
     "        [([0, 1], [0, 1, 2, 3]), ([0, 1], [0, 1, 2, 3])],\n",
     "    ),\n",
-    "    algorithm=CQLBM(lattice),\n",
+    "    algorithm=ABQLBM(lattice, use_agnostic_bcs=False),\n",
     "    postprocessing=EmptyPrimitive(lattice),\n",
     "    measurement=ABGridMeasurement(lattice),\n",
     "    target_platform=\"QISKIT\",\n",
@@ -158,6 +156,16 @@
    "metadata": {},
    "outputs": [],
    "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "395acbf2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    " "
+   ]
   }
  ],
  "metadata": {

demos/simulation/ab_simulation_y_monomial.ipynb

@@ -0,0 +1,126 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cc98e730",
+   "metadata": {},
+   "source": [
+    "# Simulating the ABQLBM with a `YMonomial` object"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6c6d0765",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit_aer import AerSimulator\n",
+    "\n",
+    "from qlbm.components import (\n",
+    "    EmptyPrimitive,\n",
+    ")\n",
+    "from qlbm.components.ab.ab import ABQLBM\n",
+    "from qlbm.components.ab.initial import ABDiscreteUniformInitialConditions\n",
+    "from qlbm.components.ab.measurement import ABGridMeasurement\n",
+    "from qlbm.infra import QiskitRunner, SimulationConfig\n",
+    "from qlbm.lattice import ABLattice\n",
+    "from qlbm.tools.utils import create_directory_and_parents\n",
+    "\n",
+    "lattice = ABLattice(\n",
+    "    {\n",
+    "        \"lattice\": {\"dim\": {\"x\": 8, \"y\": 16}, \"velocities\": \"D2Q9\"},\n",
+    "        \"geometry\": [\n",
+    "            {\n",
+    "                \"shape\": \"ymonomial\",\n",
+    "                \"exponent\": 2,\n",
+    "                \"comparator\": \"<\",\n",
+    "                \"boundary\": \"bounceback\",\n",
+    "            }\n",
+    "        ],\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "output_dir = \"qlbm-output/ab-d2q9-8x16-1-obstacle-ymonomial-qiskit\"\n",
+    "create_directory_and_parents(output_dir)\n",
+    "\n",
+    "cfg = SimulationConfig(\n",
+    "    initial_conditions=ABDiscreteUniformInitialConditions(\n",
+    "        lattice,\n",
+    "        [1, 5, 8],\n",
+    "        ([], list(range(lattice.num_gridpoints[1].bit_length()))),\n",
+    "    ),\n",
+    "    algorithm=ABQLBM(lattice, True),\n",
+    "    postprocessing=EmptyPrimitive(lattice),\n",
+    "    measurement=ABGridMeasurement(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",
+    ")\n",
+    "\n",
+    "cfg.prepare_for_simulation()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12b8f1f8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Number of shots to simulate for each timestep when running the circuit\n",
+    "NUM_SHOTS = 2**12\n",
+    "\n",
+    "\n",
+    "# Number of timesteps to simulate\n",
+    "NUM_STEPS = 20\n",
+    "\n",
+    "runner = QiskitRunner(\n",
+    "    cfg,\n",
+    "    lattice,\n",
+    ")\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": "33c4b96d",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "qlbm-cpu-venv",
+   "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.13.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/_static/css/custom.css

@@ -3,16 +3,40 @@
   }
 
 .bd-page-width {
-    max-width: 80%;  /* default is 88rem */
+  max-width: 92%;
   }
 
 .sphinxsidebarwrapper {  overflow-y: scroll; }
 
 .bd-sidebar-primary {
-  max-width: 230px
+  max-width: 190px;
+}
+
+html {
+  --pst-sidebar-secondary: 13rem;
+}
+
+@media (min-width: 960px) {
+  .bd-sidebar-primary {
+    width: 18%;
+    min-width: 160px;
+    max-width: 190px;
+  }
+}
+
+@media (min-width: 1200px) {
+  .bd-sidebar-secondary {
+    width: var(--pst-sidebar-secondary);
+  }
 }
 
 table.center-align-col {
     margin-left: auto;
     margin-right: auto;
+}
+
+table.center-align-col th,
+table.center-align-col td {
+  text-align: center;
+  vertical-align: middle;
 }

docs/source/code/comps_cqlbm.rst

@@ -113,8 +113,19 @@ Reflection
 
 .. autoclass:: qlbm.components.ms.primitives.EdgeComparator
 
+
+.. note::
+    The amplitude-based QLBM supports two kinds of reflection operators: segment-wise (or standard) and zone-agnostic.
+    The two methods are physically equivalent, but their implementation differs algorithmically.
+    For multi-geometry cases, only the segment-wise implementation is currently supported.
+
+
 .. autoclass:: qlbm.components.ab.reflection.ABReflectionOperator
 
+.. autoclass:: qlbm.components.ab.reflection.ABBounceBackReflectionOperator
+
+.. autoclass:: qlbm.components.ab.reflection.ABSpecularReflectionOperator
+
 .. autoclass:: qlbm.components.ab.reflection.ABZoneAgnosticReflectionOperator 
 
 .. autoclass:: qlbm.components.ab.reflection.ABZoneAgnosticReflectionOracle