feat: Add Gauss-Laguerre and Hankel backends for exchange kernels, form factor calculations, and related tests/examples.

Author: skilledwolf

.coverage

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

.vscode/settings.json

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Tobias Wolf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

LICENSE

@@ -0,0 +1,91 @@
+# quantumhall_matrixelements
+
+Landau-level plane-wave form factors and exchange kernels for quantum Hall systems.
+
+This library factors out the continuum matrix-element kernels used in Hartree–Fock and
+related calculations into a small, reusable package. It provides:
+
+- Analytic Landau-level plane-wave form factors $F_{n',n}(\mathbf{q})$.
+- Exchange kernels $X_{n_1 m_1 n_2 m_2}(\mathbf{G})$ computed via:
+  - Generalized Gauss–Laguerre quadrature (`gausslag` backend).
+  - Hankel-transform based integration (`hankel` backend).
+- Symmetry diagnostics for verifying kernel implementations on a given G-grid.
+
+## Mathematical Definitions
+
+### Plane-Wave Form Factors
+
+The form factors are the matrix elements of the plane-wave operator $e^{i \mathbf{q} \cdot \mathbf{R}}$ in the Landau level basis $|n\rangle$:
+
+$$ F_{n',n}(\mathbf{q}) = \langle n' | e^{i \mathbf{q} \cdot \mathbf{R}} | n \rangle $$
+
+Analytically, these are given by:
+
+$$ F_{n',n}(\mathbf{q}) = i^{|n-n'|} e^{i(n-n')\theta_\mathbf{q}} \sqrt{\frac{n_<!}{n_>!}} \left( \frac{|\mathbf{q}|\ell_B}{\sqrt{2}} \right)^{|n-n'|} L_{n_<}^{|n-n'|}\left( \frac{|\mathbf{q}|^2\ell_B^2}{2} \right) e^{-|\mathbf{q}|^2\ell_B^2/4} $$
+
+where $n_< = \min(n, n')$, $n_> = \max(n, n')$, and $L_n^\alpha$ are the generalized Laguerre polynomials, and $\ell_B$ is the magnetic length.
+
+### Exchange Kernels
+
+The exchange kernels $X_{n_1 m_1 n_2 m_2}(\mathbf{G})$ are defined as the Fourier transform of the interaction potential weighted by the form factors:
+
+$$ X_{n_1 m_1 n_2 m_2}(\mathbf{G}) = \int \frac{d^2 q}{(2\pi)^2} V(q) F_{n_1, m_1}(\mathbf{q}) F_{m_2, n_2}(-\mathbf{q}) e^{-i \mathbf{q} \cdot \mathbf{G} \ell_B^2} $$
+
+where $V(q)$ is the interaction potential. For the Coulomb interaction, $V(q) = \frac{2\pi e^2}{\epsilon q}$.
+
+### Units and Interaction Strength
+
+The package performs calculations in dimensionless units where lengths are scaled by $\ell_B$. The interaction strength is parameterized by a dimensionless prefactor $\kappa$.
+
+- **Coulomb Interaction**: The code assumes a potential of the form $V(q) = \kappa \frac{2\pi \ell_B}{q \ell_B}$ (in effective dimensionless form).
+    - If you set `kappa = 1.0`, the resulting exchange kernels will be in units of the **Coulomb energy scale** $E_C = e^2 / (\epsilon \ell_B)$.
+    - If you want the results in units of the cyclotron energy $\hbar \omega_c$, you should set $\kappa = E_C / (\hbar \omega_c) = (e^2/\epsilon \ell_B) / (\hbar \omega_c)$.
+
+- **General Potential**: For a general $V(q)$, the function `V_of_q` should return values in your desired energy units. The integration measure $d^2q/(2\pi)^2$ introduces a factor of $1/\ell_B^2$, so ensure your potential scaling is consistent.
+
+## Installation
+
+From a local checkout:
+
+```bash
+pip install -e .[dev]
+```
+
+## Basic usage
+
+```python
+import numpy as np
+from quantumhall_matrixelements import (
+    get_form_factors,
+    get_exchange_kernels,
+)
+
+# Simple G set: G0=(0,0), G+=(1,0), G-=(-1,0)
+Gs_dimless = np.array([0.0, 1.0, 1.0])
+thetas = np.array([0.0, 0.0, np.pi])
+nmax = 2
+
+F = get_form_factors(Gs_dimless, thetas, nmax)          # shape (nG, nmax, nmax)
+X = get_exchange_kernels(Gs_dimless, thetas, nmax)      # default 'gausslag' backend
+
+print("F shape:", F.shape)
+print("X shape:", X.shape)
+```
+
+For more detailed examples, see the tests under `tests/`.
+
+## Development
+
+- Run tests and coverage:
+
+  ```bash
+  pytest
+  ```
+
+- Lint and type-check:
+
+  ```bash
+  ruff check .
+  mypy .
+  ```
+

README.md

@@ -0,0 +1,43 @@
+"""Compare Gauss–Laguerre and Hankel exchange-kernel backends.
+
+For a small |G|ℓ_B grid and nmax=2, this script computes the exchange
+kernels using both the Gauss–Laguerre and Hankel backends and plots the
+relative difference of a representative diagonal element X_{0000}(G).
+"""
+from __future__ import annotations
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from quantumhall_matrixelements import get_exchange_kernels
+
+
+def main() -> None:
+    nmax = 2
+    q = np.linspace(0.2, 3.0, 60)
+    theta = np.zeros_like(q)
+
+    X_gl = get_exchange_kernels(q, theta, nmax, method="gausslag")
+    X_hk = get_exchange_kernels(q, theta, nmax, method="hankel")
+
+    # Focus on X_{0000}(G) as a simple representative component
+    X_gl_diag = X_gl[:, 0, 0, 0, 0]
+    X_hk_diag = X_hk[:, 0, 0, 0, 0]
+
+    abs_diff = np.abs(X_gl_diag - X_hk_diag)
+    denom = np.maximum(np.abs(X_gl_diag), np.abs(X_hk_diag))
+    rel_diff = np.where(denom > 0, abs_diff / denom, 0.0)
+
+    fig, ax = plt.subplots()
+    ax.plot(q, rel_diff, marker="o", linestyle="-")
+    ax.set_xlabel(r"$|G| \ell_B$")
+    ax.set_ylabel(r"relative difference")
+    ax.set_title(r"Relative difference of $X_{0000}(G)$: Gauss–Laguerre vs Hankel")
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()
+

examples/compare_exchange_backends.py

@@ -0,0 +1,43 @@
+"""Exchange kernel diagonal elements X_{nnnn}(G) vs |G|ℓ_B.
+
+This example computes selected diagonal components of the exchange kernel
+using the Gauss–Laguerre backend and plots their real parts as a function
+of |G|ℓ_B.
+"""
+from __future__ import annotations
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from quantumhall_matrixelements import get_exchange_kernels
+
+
+def main() -> None:
+    nmax = 3
+    # Avoid G=0 to dodge the Coulomb singularity; start from small q
+    q = np.linspace(0.2, 4.0, 80)
+    theta = np.zeros_like(q)
+
+    X = get_exchange_kernels(q, theta, nmax, method="gausslag")
+
+    fig, ax = plt.subplots()
+    for n in range(nmax):
+        vals = X[:, n, n, n, n]
+        ax.plot(q, vals.real, label=fr"$\mathrm{{Re}}\,X_{{{n}{n}{n}{n}}}(G)$")
+
+    for n in range(1,nmax):
+        vals = X[:, n, n-1, n-1, n]
+        ax.plot(q, vals.real, label=fr"$\mathrm{{Re}}\,X_{{{n}{n-1}{n-1}{n}}}(G)$")
+
+    ax.set_xlabel(r"$|G| \ell_B$")
+    ax.set_ylabel(r"$\mathrm{Re}\,X_{nnnn}(G)$  (κ=1)")
+    ax.set_title("Diagonal exchange kernels (Gauss–Laguerre backend)")
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()
+

examples/plot_exchange_kernels_radial.py

@@ -0,0 +1,38 @@
+"""Radial Landau-level form factors F_{n',n}(q) vs qℓ_B.
+
+This example plots the lowest diagonal LL form factors as a function of
+dimensionless momentum qℓ_B, illustrating the Gaussian envelope and
+Laguerre oscillations.
+"""
+from __future__ import annotations
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from quantumhall_matrixelements import get_form_factors
+
+
+def main() -> None:
+    # Dimensionless |G|ℓ_B grid
+    q = np.linspace(0.0, 5.0, 400)
+    theta = np.zeros_like(q)
+    nmax = 3
+
+    F = get_form_factors(q, theta, nmax)  # shape (nq, nmax, nmax)
+
+    fig, ax = plt.subplots()
+    for n in range(nmax):
+        ax.plot(q, F[:, n, n].real, label=fr"$\mathrm{{Re}}\,F_{{{n}{n}}}(q)$")
+
+    ax.set_xlabel(r"$q \ell_B$")
+    ax.set_ylabel(r"$\mathrm{Re}\,F_{nn}(q)$")
+    ax.set_title("Diagonal Landau-level form factors")
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()
+

examples/plot_form_factors_radial.py

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantumhall_matrixelements"
+version = "0.1.0"
+description = "Landau-level plane-wave form factors and exchange kernels for quantum Hall systems."
+readme = "README.md"
+authors = [
+  { name = "Tobias Wolf", email = "public@wolft.xyz" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["quantum Hall", "matrix elements", "form factors", "exchange kernels", "Landau levels"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Physics"
+]
+dependencies = [
+  "numpy>=1.26",
+  "scipy>=1.11",
+  "hankel>=1.2"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.5.0",
+  "mypy>=1.10",
+  "build",
+  "twine"
+]
+
+[project.urls]
+Homepage = "https://github.com/wolft/quantumhall_matrixelements"
+Issues = "https://github.com/wolft/quantumhall_matrixelements/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "B", "UP", "SIM", "NPY", "PERF"]
+ignore = ["E203"]
+
+[tool.ruff.isort]
+known-first-party = ["quantumhall_matrixelements"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --cov=quantumhall_matrixelements --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.coverage.run]
+branch = true
+source = ["quantumhall_matrixelements"]
+