quantumhall-matrixelements 0.1.0__py3-none-any.whl

quantumhall_matrixelements/__init__.py

@@ -0,0 +1,80 @@
+"""Landau-level plane-wave form factors and exchange kernels.
+
+This package provides reusable numerical kernels for quantum Hall matrix
+elements in a Landau-level basis:
+
+- `get_form_factors` for plane-wave form factors :math:`F_{n',n}(G)`.
+- `get_exchange_kernels` (and backend-specific variants) for exchange kernels
+  :math:`X_{n_1 m_1 n_2 m_2}(G)` built from LL wavefunctions.
+- Optional symmetry diagnostics for sanity-checking kernel implementations.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .planewave import get_form_factors
+from .exchange_gausslag import get_exchange_kernels_GaussLag
+from .exchange_hankel import get_exchange_kernels_hankel
+from .exchange_legendre import get_exchange_kernels_GaussLegendre
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    ComplexArray = NDArray[np.complex128]
+    RealArray = NDArray[np.float64]
+
+
+def get_exchange_kernels(
+    G_magnitudes: "RealArray",
+    G_angles: "RealArray",
+    nmax: int,
+    *,
+    method: str | None = None,
+    **kwargs,
+) -> "ComplexArray":
+    """Dispatcher for exchange kernels.
+
+    Parameters
+    ----------
+    G_magnitudes, G_angles :
+        Arrays describing the reciprocal vectors :math:`G` in polar form.
+        Both must have the same shape; broadcasting is not applied.
+    nmax :
+        Number of Landau levels (0..nmax-1) to include.
+    method :
+        Backend selector:
+
+        - ``'gausslegendre'`` (default): Gauss-Legendre quadrature with rational mapping.
+          Recommended for all nmax.
+        - ``'gausslag'``: generalized Gauss–Laguerre quadrature.
+          Fast for small nmax (< 10), but unstable for large nmax.
+        - ``'hankel'``: Hankel-transform based implementation.
+
+    **kwargs :
+        Additional arguments passed to the backend (e.g. ``nquad``, ``scale``).
+
+    Notes
+    -----
+    Both backends return kernels normalized for :math:`\\kappa = 1`. Any
+    physical interaction strength should be applied by the caller.
+    """
+    chosen = (method or "gausslegendre").strip().lower()
+    if chosen in {"gausslag", "gauss-lag", "gausslaguerre", "gauss-laguerre", "gl"}:
+        return get_exchange_kernels_GaussLag(G_magnitudes, G_angles, nmax, **kwargs)
+    if chosen in {"hankel", "hk"}:
+        return get_exchange_kernels_hankel(G_magnitudes, G_angles, nmax, **kwargs)
+    if chosen in {"gausslegendre", "gauss-legendre", "legendre", "leg"}:
+        return get_exchange_kernels_GaussLegendre(G_magnitudes, G_angles, nmax, **kwargs)
+    raise ValueError(f"Unknown exchange-kernel method: {method!r}. Use 'gausslegendre', 'gausslag', or 'hankel'.")
+
+
+__all__ = [
+    "get_form_factors",
+    "get_exchange_kernels",
+    "get_exchange_kernels_GaussLag",
+    "get_exchange_kernels_hankel",
+    "get_exchange_kernels_GaussLegendre",
+]
+

quantumhall_matrixelements/_debug_symmetry.py

@@ -0,0 +1,50 @@
+"""Debug helper to print exchange-kernel symmetry deviations.
+
+This is not part of the public API; it exists only to make it easy to
+inspect symmetry errors for different backends via
+
+    python -m quantumhall_matrixelements._debug_symmetry
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from . import get_exchange_kernels
+
+
+def main() -> None:
+    nmax = 2
+    Gs_dimless = np.array([0.0, 1.0, 1.0])
+    thetas = np.array([0.0, 0.0, np.pi])
+    thetas_minus = (thetas + np.pi) % (2 * np.pi)
+
+    methods = ["gausslag", "hankel"]
+
+    for method in methods:
+        print(f"=== method={method} ===")
+        X_G = get_exchange_kernels(Gs_dimless, thetas, nmax, method=method)
+        X_mG = get_exchange_kernels(Gs_dimless, thetas_minus, nmax, method=method)
+
+        expected_mG = np.transpose(X_G, (0, 3, 4, 1, 2)).conj()
+        diff_G_to_mG = float(np.max(np.abs(X_mG - expected_mG)))
+        print(f"max |X(-G) - (X^T(G))†| = {diff_G_to_mG:.3e}")
+
+        idx = np.arange(nmax)
+        N = (
+            idx[:, None, None, None]
+            - idx[None, :, None, None]
+            - idx[None, None, :, None]
+            + idx[None, None, None, :]
+        )
+        phase = (-1.0) ** np.abs(N)
+        expected_internal = phase[None, ...] * expected_mG
+        diff_internal = float(np.max(np.abs(X_G - expected_internal)))
+        print(
+            "max |X(G) - (-1)^|N| (X^T(G))†| = "
+            f"{diff_internal:.3e}",
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover - manual debug entry point
+    main()
+

quantumhall_matrixelements/diagnostic.py

@@ -0,0 +1,53 @@
+"""Diagnostic helpers for exchange-kernel symmetry checks."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from . import get_exchange_kernels
+
+if TYPE_CHECKING:  # pragma: no cover - aliases only
+    from numpy.typing import NDArray
+
+    RealArray = NDArray[np.float64]
+    ComplexArray = NDArray[np.complex128]
+
+__all__ = [
+    "verify_exchange_kernel_symmetries",
+]
+
+
+def verify_exchange_kernel_symmetries(
+    G_magnitudes: "RealArray",
+    G_angles: "RealArray",
+    nmax: int,
+    rtol: float = 1e-7,
+    atol: float = 1e-9,
+) -> None:
+    """Verify the exchange-kernel G-inversion symmetry implied by Σ^F(-G)=Σ^F(G)^†.
+
+    With the convention
+
+      Σ^F_{mn}(G) = - Σ_{r,t} X_{nrtm}(G) ρ_{tr}(G),
+
+    Hermiticity Σ^F(-G) = Σ^F(G)^† for densities obeying ρ(-G)=ρ(G)^† requires
+
+      X_{nrtm}(-G) = X_{m r t n}(G)^*,
+
+    i.e. in array form (Xs[g, n1, m1, n2, m2]):
+
+      Xs[g, n1, m1, n2, m2]_(-G) = Xs[g, m2, n2, m1, n1]_G^*.
+    """
+    Xs_G = get_exchange_kernels(G_magnitudes, G_angles, nmax)
+    G_angles_minus = (G_angles + np.pi) % (2 * np.pi)
+    Xs_minusG = get_exchange_kernels(G_magnitudes, G_angles_minus, nmax)
+
+    # expected_minus[g, n1, m1, n2, m2] = X_G[g, m2, n2, m1, n1]^*
+    expected_Xs_minusG = np.transpose(Xs_G, (0, 4, 3, 2, 1)).conj()
+    if not np.allclose(Xs_minusG, expected_Xs_minusG, rtol=rtol, atol=atol):
+        diff = float(np.max(np.abs(Xs_minusG - expected_Xs_minusG)))
+        raise AssertionError(
+            f"Exchange kernel G-inversion symmetry failed: max|Δ|={diff:.3e} "
+            f"(rtol={rtol}, atol={atol})"
+        )

quantumhall_matrixelements/exchange_gausslag.py

@@ -0,0 +1,163 @@
+"""Exchange kernels via generalized Gauss–Laguerre quadrature."""
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+import numpy as np
+import scipy.special as sps
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    ComplexArray = NDArray[np.complex128]
+    RealArray = NDArray[np.float64]
+
+
+def _N_order(n1: int, m1: int, n2: int, m2: int) -> int:
+    return (n1 - m1) - (m2 - n2)
+
+
+def _parity_factor(N: int) -> int:
+    """(-1)^((N+|N|)/2) → (-1)^N for N>=0, and 1 for N<0."""
+    return (-1) ** ((N + abs(N)) // 2)
+
+
+@lru_cache(maxsize=None)
+def _lag_nodes_weights(nquad: int, alpha: float):
+    """Generalized Gauss–Laguerre nodes/weights for ∫_0^∞ e^{-z} z^α f(z) dz."""
+    x, w = sps.roots_genlaguerre(nquad, alpha)
+    return x, w
+
+
+@lru_cache(maxsize=None)
+def _logfact(n: int) -> float:
+    return float(sps.gammaln(n + 1))
+
+
+def _C_and_indices(n1: int, m1: int, n2: int, m2: int):
+    """Constants and Laguerre parameters for f_{n1,m1} * f_{m2,n2}."""
+    p, d1 = min(n1, m1), abs(n1 - m1)
+    q, d2 = min(m2, n2), abs(m2 - n2)
+    logC = 0.5 * ((_logfact(p) - _logfact(p + d1)) + (_logfact(q) - _logfact(q + d2)))
+    C = np.exp(logC)
+    return C, p, d1, q, d2
+
+
+_L_cache: dict[tuple[int, int, float, int], np.ndarray] = {}
+
+
+def _laguerre_on_grid(p: int, d: int, alpha: float, nquad: int, z):
+    key = (p, d, float(alpha), int(nquad))
+    L = _L_cache.get(key)
+    if L is None:
+        L = sps.eval_genlaguerre(p, d, z)
+        _L_cache[key] = L
+    return L
+
+
+def get_exchange_kernels_GaussLag(
+    G_magnitudes,
+    G_angles,
+    nmax: int,
+    *,
+    potential: str = "coulomb",
+    kappa: float = 1.0,
+    V_of_q=None,
+    nquad: int = 200,
+    ell: float = 1.0,
+) -> "ComplexArray":
+    """Compute X_{n1,m1,n2,m2}(G) using analytic angle and Gauss–Laguerre radial quadrature.
+
+    Parameters
+    ----------
+    G_magnitudes, G_angles :
+        Arrays of the same shape describing |G| and polar angle θ_G.
+    nmax :
+        Number of Landau levels.
+    potential :
+        Either ``'coulomb'`` (default) or ``'general'``. In the latter case
+        a callable ``V_of_q(q)`` must be provided.
+    kappa :
+        Interaction strength prefactor. For Coulomb this corresponds to
+        :math:`\\kappa = e^2/(\\varepsilon\\ell_B)/\\hbar\\omega_c`.
+    V_of_q :
+        Callable ``V_of_q(q) -> V(q)`` used when ``potential='general'``.
+    nquad :
+        Number of Gauss–Laguerre quadrature points.
+    ell :
+        Magnetic length ℓ_B (default 1.0); |G| is interpreted in 1/ℓ_B units.
+
+    Returns
+    -------
+    Xs : (nG, nmax, nmax, nmax, nmax) complex array
+        Exchange kernels normalized with the chosen kappa.
+    """
+    G_magnitudes = np.asarray(G_magnitudes, dtype=float)
+    G_angles = np.asarray(G_angles, dtype=float)
+    if G_magnitudes.shape != G_angles.shape:
+        raise ValueError("G_magnitudes and G_angles must have the same shape.")
+    nG = G_magnitudes.size
+
+    Gscaled = G_magnitudes * float(ell)
+    Xs = np.zeros((nG, nmax, nmax, nmax, nmax), dtype=np.complex128)
+
+    J_cache: dict[tuple[int, float], np.ndarray] = {}
+
+    for n1 in range(nmax):
+        for m1 in range(nmax):
+            for n2 in range(nmax):
+                for m2 in range(nmax):
+                    N = _N_order(n1, m1, n2, m2)
+                    absN = abs(N)
+                    C, p, d1, q, d2 = _C_and_indices(n1, m1, n2, m2)
+
+                    if potential == "coulomb":
+                        alpha = 0.5 * (d1 + d2 - 1)
+                        if alpha <= -1:
+                            raise ValueError(f"Invalid alpha={alpha} for Coulomb case.")
+                        z, w = _lag_nodes_weights(nquad, alpha)
+                        L1 = _laguerre_on_grid(p, d1, alpha, nquad, z)
+                        L2 = _laguerre_on_grid(q, d2, alpha, nquad, z)
+                        W = w * L1 * L2
+                        key = (absN, float(alpha))
+                        J_abs = J_cache.get(key)
+                        if J_abs is None:
+                            arg = np.sqrt(2.0 * z)[None, :] * Gscaled[:, None]
+                            J_abs = sps.jv(absN, arg)
+                            J_cache[key] = J_abs
+                        signN = _parity_factor(N)
+                        radial = (signN * J_abs) @ W
+                        phase_factor = (1j) ** (d1 - d2)
+                        pref = (kappa * C / np.sqrt(2.0)) * phase_factor
+                    else:
+                        if not callable(V_of_q):
+                            raise ValueError(
+                                "For potential='general', provide V_of_q: callable(q)->V(q)."
+                            )
+                        alpha = 0.5 * (d1 + d2)
+                        z, w = _lag_nodes_weights(nquad, alpha)
+                        L1 = _laguerre_on_grid(p, d1, alpha, nquad, z)
+                        L2 = _laguerre_on_grid(q, d2, alpha, nquad, z)
+                        qvals = np.sqrt(2.0 * z) / float(ell)
+                        Veff = V_of_q(qvals) / (2.0 * np.pi * float(ell) ** 2)
+                        W = w * L1 * L2 * Veff
+                        key = (absN, float(alpha))
+                        J_abs = J_cache.get(key)
+                        if J_abs is None:
+                            arg = np.sqrt(2.0 * z)[None, :] * Gscaled[:, None]
+                            J_abs = sps.jv(absN, arg)
+                            J_cache[key] = J_abs
+                        signN = _parity_factor(N)
+                        radial = (signN * J_abs) @ W
+                        phase_factor = (1j) ** (d1 - d2)
+                        pref = C * phase_factor
+
+                    phase = np.exp(-1j * N * G_angles)
+                    Xs[:, n1, m1, n2, m2] = (pref * phase) * radial
+
+    return Xs
+
+
+__all__ = ["get_exchange_kernels_GaussLag"]
+

quantumhall_matrixelements/exchange_hankel.py

@@ -0,0 +1,165 @@
+"""Exchange kernels via Hankel transforms."""
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+import numpy as np
+from hankel import HankelTransform
+from scipy.special import genlaguerre, rgamma
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    ComplexArray = NDArray[np.complex128]
+    RealArray = NDArray[np.float64]
+
+
+def _N_order(n1: int, m1: int, n2: int, m2: int) -> int:
+    return (n1 - m1) - (m2 - n2)
+
+
+def _parity_factor(N: int) -> int:
+    return (-1) ** ((N + abs(N)) // 2)
+
+
+@lru_cache(maxsize=None)
+def _get_hankel_transformer(order: int) -> HankelTransform:
+    """Cached HankelTransform instance for a given Bessel order."""
+    return HankelTransform(nu=order, N=6000, h=7e-6)
+
+
+def _radial_exchange_integrand_rgamma(
+    q_magnitudes,
+    n1,
+    m1,
+    n2,
+    m2,
+    potential: str | callable = "coulomb",
+    kappa: float = 1.0,
+):
+    """Build integrand g(q) for Hankel transform with rgamma-normalization.
+
+    For Coulomb: g(q) = κ F1F2 / q. We parameterize q = √2 r and absorb factors
+    into a stable radial base constructed from generalized Laguerres.
+    """
+    q = np.asarray(q_magnitudes, dtype=float)
+    r = q / np.sqrt(2.0)
+
+    Δ1, N1 = abs(n1 - m1), min(n1, m1)
+    Δ2, N2 = abs(n2 - m2), min(n2, m2)
+
+    power = Δ1 + Δ2 - 1
+
+    lag1 = genlaguerre(N1, Δ1)
+    lag2 = genlaguerre(N2, Δ2)
+
+    nrm1 = np.sqrt(lag1(0))
+    nrm2 = np.sqrt(lag2(0))
+    nrm0 = np.sqrt(rgamma(1 + Δ1) * rgamma(1 + Δ2))
+
+    z = r * r
+    base = np.exp(-z) * nrm0 * (r**power) * (lag1(z) / nrm1) * (lag2(z) / nrm2)
+
+    if potential == "coulomb":
+        return (kappa / np.sqrt(2.0)) * base
+    if potential == "constant":
+        return (kappa / (2 * np.pi)) * (r * base)
+    if callable(potential):
+        qphys = np.sqrt(2.0) * r
+        return (potential(qphys) / (2 * np.pi)) * (r * base)
+    raise ValueError("potential must be 'coulomb', 'constant', or callable V(q)")
+
+
+def get_exchange_kernels_hankel(
+    G_magnitudes: "RealArray",
+    G_angles: "RealArray",
+    nmax: int,
+    **kwargs,
+) -> "ComplexArray":
+    """Compute X_{n1,m1,n2,m2}(G) via Hankel transforms (κ=1 convention).
+
+    This backend parametrizes the radial integral via Hankel transforms with
+    robust Laguerre-based normalization and explicit control over the Bessel
+    order. It is numerically more intensive than the Gauss–Laguerre backend
+    but can be useful for cross-checks or alternative potentials.
+    """
+    G_magnitudes = np.asarray(G_magnitudes, dtype=float)
+    G_angles = np.asarray(G_angles, dtype=float)
+    if G_magnitudes.shape != G_angles.shape:
+        raise ValueError("G_magnitudes and G_angles must have same shape")
+
+    # Unique |G| to shrink Hankel workload (same radial value for all with same |G|)
+    # Note: np.unique sorts; use inverse map to scatter back to original order.
+    k_unique, inv_idx = np.unique(G_magnitudes, return_inverse=True)
+    nG = G_magnitudes.size
+
+    # Precompute angular phase vectors for all possible N values
+    # N = (n1 - m1) - (m2 - n2) ∈ [Nmin, Nmax]
+    N_min = -2 * (nmax - 1)
+    N_max = +2 * (nmax - 1)
+    Ns = np.arange(N_min, N_max + 1, dtype=int)
+    phase_by_N: dict[int, ComplexArray] = {}
+    for N in Ns:
+        phase = -N * G_angles
+        phase_by_N[int(N)] = (np.cos(phase) + 1j * np.sin(phase)) * _parity_factor(int(N))
+
+    # Small lookup for internal (i)^(d1-d2), indexed by d1,d2 in [0..nmax-1]
+    d_vals = np.arange(nmax, dtype=int)
+    phase_internal_table = (1j) ** (d_vals[:, None] - d_vals[None, :])  # (nmax,nmax)
+    d_lookup = np.abs(np.subtract.outer(np.arange(nmax), np.arange(nmax)))  # (nmax,nmax)
+    # Precompute abs diffs (d) and mins (Nmin) for quick indexing
+    d_mat = d_lookup  # alias
+    Nmin_mat = np.minimum(
+        np.arange(nmax)[:, None].repeat(nmax, axis=1),
+        np.arange(nmax)[None, :].repeat(nmax, axis=0),
+    )
+
+    # Cache for radial Hankel transforms keyed by (d1,N1,d2,N2,absN)
+    radial_cache: dict[tuple[int, int, int, int, int], np.ndarray] = {}
+
+    # Output
+    Xs = np.zeros((nG, nmax, nmax, nmax, nmax), dtype=np.complex128)
+
+    # Helper to fetch/compute the radial piece for given indices
+    def get_radial_block(n1: int, m1: int, n2: int, m2: int, absN: int) -> np.ndarray:
+        d1 = int(d_mat[n1, m1])
+        d2 = int(d_mat[n2, m2])
+        N1 = int(Nmin_mat[n1, m1])
+        N2 = int(Nmin_mat[n2, m2])
+        key = (d1, N1, d2, N2, int(absN))
+        arr = radial_cache.get(key)
+        if arr is not None:
+            return arr
+
+        def integrand(q):
+            return _radial_exchange_integrand_rgamma(q, n1, m1, n2, m2)
+
+        ht = _get_hankel_transformer(absN)
+        # Compute only on unique radii, then cache
+        arr_unique = ht.transform(integrand, k_unique, ret_err=False)
+        radial_cache[key] = arr_unique
+        return arr_unique
+
+    # Main assignment: iterate indices but reuse cached radial data and phases
+    for n1 in range(nmax):
+        for m1 in range(nmax):
+            d1 = int(d_mat[n1, m1])
+            for n2 in range(nmax):
+                for m2 in range(nmax):
+                    d2 = int(d_mat[n2, m2])
+                    N = _N_order(n1, m1, n2, m2)
+                    absN = abs(N)
+                    # Radial part (on unique k), then scatter to all G via inv_idx
+                    X_radial_unique = get_radial_block(n1, m1, n2, m2, absN)
+                    X_radial = X_radial_unique[inv_idx]
+                    # Angular/internal phases
+                    phase_internal = phase_internal_table[d1, d2]
+                    phase_angle = phase_by_N[N]
+                    Xs[:, n1, m1, n2, m2] = phase_internal * phase_angle * X_radial
+
+    return Xs
+
+
+__all__ = ["get_exchange_kernels_hankel"]
+

quantumhall_matrixelements/exchange_legendre.py

@@ -0,0 +1,186 @@
+"""Exchange kernels via Gauss-Legendre quadrature with rational mapping."""
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+import numpy as np
+import scipy.special as sps
+from scipy.special import roots_legendre
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    ComplexArray = NDArray[np.complex128]
+    RealArray = NDArray[np.float64]
+
+
+def _N_order(n1: int, m1: int, n2: int, m2: int) -> int:
+    return (n1 - m1) - (m2 - n2)
+
+
+def _parity_factor(N: int) -> int:
+    """(-1)^((N+|N|)/2) → (-1)^N for N>=0, and 1 for N<0."""
+    return (-1) ** ((N + abs(N)) // 2)
+
+
+@lru_cache(maxsize=None)
+def _logfact(n: int) -> float:
+    return float(sps.gammaln(n + 1))
+
+
+def _C_and_indices(n1: int, m1: int, n2: int, m2: int):
+    """Constants and Laguerre parameters for f_{n1,m1} * f_{m2,n2}."""
+    p, d1 = min(n1, m1), abs(n1 - m1)
+    q, d2 = min(m2, n2), abs(m2 - n2)
+    logC = 0.5 * ((_logfact(p) - _logfact(p + d1)) + (_logfact(q) - _logfact(q + d2)))
+    C = np.exp(logC)
+    return C, p, d1, q, d2
+
+
+@lru_cache(maxsize=None)
+def _legendre_nodes_weights_mapped(nquad: int, scale: float):
+    """
+    Gauss-Legendre nodes/weights mapped from [-1, 1] to [0, inf).
+    Mapping: z = scale * (1+x)/(1-x)
+    Jacobian: dz/dx = scale * 2/(1-x)^2
+    """
+    x, w_leg = roots_legendre(nquad)
+    denom = 1.0 - x
+    z = scale * (1.0 + x) / denom
+    w = w_leg * (scale * 2.0 / (denom * denom))
+    return z, w
+
+
+def get_exchange_kernels_GaussLegendre(
+    G_magnitudes,
+    G_angles,
+    nmax: int,
+    *,
+    potential: str = "coulomb",
+    kappa: float = 1.0,
+    V_of_q=None,
+    nquad: int = 1000,
+    scale: float = 0.5,
+    ell: float = 1.0,
+) -> "ComplexArray":
+    """Compute X_{n1,m1,n2,m2}(G) using Gauss-Legendre quadrature with rational mapping.
+
+    This backend maps the semi-infinite radial integral to the finite interval [-1, 1]
+    using the rational mapping z = scale * (1+x)/(1-x). It avoids the numerical instability
+    of Gauss-Laguerre quadrature for large quantum numbers while remaining faster than
+    Hankel transforms.
+
+    Parameters
+    ----------
+    G_magnitudes, G_angles :
+        Arrays of the same shape describing |G| and polar angle θ_G.
+    nmax :
+        Number of Landau levels.
+    potential :
+        Either ``'coulomb'`` (default) or ``'general'``.
+    kappa :
+        Interaction strength prefactor.
+    V_of_q :
+        Callable ``V_of_q(q) -> V(q)`` used when ``potential='general'``.
+    nquad :
+        Number of quadrature points (default 1000).
+    scale :
+        Mapping scale factor (default 0.5). Controls the distribution of points.
+        Smaller values cluster points near the peak of the integrand for large n.
+    ell :
+        Magnetic length ℓ_B (default 1.0).
+
+    Returns
+    -------
+    Xs : (nG, nmax, nmax, nmax, nmax) complex array
+    """
+    G_magnitudes = np.asarray(G_magnitudes, dtype=float)
+    G_angles = np.asarray(G_angles, dtype=float)
+    if G_magnitudes.shape != G_angles.shape:
+        raise ValueError("G_magnitudes and G_angles must have the same shape.")
+    nG = G_magnitudes.size
+
+    Gscaled = G_magnitudes * float(ell)
+    Xs = np.zeros((nG, nmax, nmax, nmax, nmax), dtype=np.complex128)
+
+    # Get mapped grid
+    z, w = _legendre_nodes_weights_mapped(nquad, scale)
+
+    # Precompute Bessel functions J_N(sqrt(2z)*G)
+    # We cache by absN to avoid recomputing
+    J_cache: dict[int, np.ndarray] = {}
+
+    # Cache for Laguerre evaluations
+    # We evaluate L_n^d(z) for many n, d.
+    # Since n, d are small integers, we can just compute on the fly or use sps.eval_genlaguerre
+    # sps.eval_genlaguerre is efficient enough.
+
+    for n1 in range(nmax):
+        for m1 in range(nmax):
+            for n2 in range(nmax):
+                for m2 in range(nmax):
+                    N = _N_order(n1, m1, n2, m2)
+                    absN = abs(N)
+                    C, p, d1, q, d2 = _C_and_indices(n1, m1, n2, m2)
+
+                    # Compute radial integral
+                    if potential == "coulomb":
+                        # Integrand factor: exp(-z) * z^alpha * L * L * J
+                        # alpha = (d1 + d2 - 1) / 2
+                        alpha = 0.5 * (d1 + d2 - 1)
+                        
+                        L1 = sps.eval_genlaguerre(p, d1, z)
+                        L2 = sps.eval_genlaguerre(q, d2, z)
+                        
+                        # Bessel part
+                        if absN not in J_cache:
+                            arg = np.sqrt(2.0 * z)[None, :] * Gscaled[:, None]
+                            J_cache[absN] = sps.jv(absN, arg)
+                        J_abs = J_cache[absN]
+                        
+                        # Full integrand term (excluding J and weights)
+                        # exp(-z) handles x->1 decay
+                        # z^alpha handles x->-1 behavior
+                        term = np.exp(-z) * (z**alpha) * L1 * L2
+                        
+                        # Sum over quadrature points
+                        # J_abs is (nG, nquad), term is (nquad,), w is (nquad,)
+                        # Result is (nG,)
+                        radial = (J_abs * term) @ w
+                        
+                        signN = _parity_factor(N)
+                        phase_factor = (1j) ** (d1 - d2)
+                        pref = (kappa * C / np.sqrt(2.0)) * phase_factor
+                        
+                    else:
+                        # General potential
+                        if not callable(V_of_q):
+                            raise ValueError("Provide V_of_q for potential='general'")
+                        
+                        alpha = 0.5 * (d1 + d2)
+                        L1 = sps.eval_genlaguerre(p, d1, z)
+                        L2 = sps.eval_genlaguerre(q, d2, z)
+                        
+                        qvals = np.sqrt(2.0 * z) / float(ell)
+                        Veff = V_of_q(qvals) / (2.0 * np.pi * float(ell) ** 2)
+                        
+                        if absN not in J_cache:
+                            arg = np.sqrt(2.0 * z)[None, :] * Gscaled[:, None]
+                            J_cache[absN] = sps.jv(absN, arg)
+                        J_abs = J_cache[absN]
+                        
+                        term = np.exp(-z) * (z**alpha) * L1 * L2 * Veff
+                        radial = (J_abs * term) @ w
+                        
+                        signN = _parity_factor(N)
+                        phase_factor = (1j) ** (d1 - d2)
+                        pref = C * phase_factor
+
+                    phase = np.exp(-1j * N * G_angles)
+                    Xs[:, n1, m1, n2, m2] = (pref * phase) * (signN * radial)
+
+    return Xs
+
+
+__all__ = ["get_exchange_kernels_GaussLegendre"]

quantumhall_matrixelements/planewave.py

@@ -0,0 +1,87 @@
+"""Plane-wave form factors F_{n',n}(G) in a Landau-level basis."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy.special import eval_genlaguerre, gammaln
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    ComplexArray = NDArray[np.complex128]
+    RealArray = NDArray[np.float64]
+    IntArray = NDArray[np.int64]
+
+
+def _analytic_form_factor(
+    n_row: "IntArray",
+    n_col: "IntArray",
+    q_magnitudes: "RealArray",
+    q_angles: "RealArray",
+    lB: float,
+) -> "ComplexArray":
+    """Vectorized Landau level form factor F_{n_row, n_col}(q).
+
+    F_{n',n}(q) = i^{|n-n'|} e^{i(n-n')θ}
+                  sqrt(n_min!/n_max!) (|q|ℓ/√2)^{|n'-n|}
+                  L_{n_min}^{|n'-n|}(|q|²ℓ²/2) e^{-|q|²ℓ²/4}
+    """
+    n_min = np.minimum(n_row, n_col)
+    n_max = np.maximum(n_row, n_col)
+    delta_n_abs = np.abs(n_row - n_col)
+
+    ql = q_magnitudes * lB
+    arg_z = 0.5 * (ql**2)
+
+    log_ratio = 0.5 * (gammaln(n_min + 1) - gammaln(n_max + 1))
+    ratio = np.exp(log_ratio)
+
+    laguerre_poly = eval_genlaguerre(n_min, delta_n_abs, arg_z)
+
+    # Phase convention: F_{n',n}(q) ∝ i^{|Δn|} e^{i (n - n') θ}
+    angles = (n_col - n_row) * q_angles + (np.pi / 2) * delta_n_abs
+    angular_phase = np.cos(angles) + 1j * np.sin(angles)
+
+    F = (
+        angular_phase
+        * ratio
+        * np.power(ql / np.sqrt(2.0), delta_n_abs)
+        * laguerre_poly
+        * np.exp(-0.5 * arg_z)
+    )
+    return F if F.ndim > 0 else F[()]
+
+
+def get_form_factors(
+    q_magnitudes: "RealArray", q_angles: "RealArray", nmax: int, lB: float = 1.0
+) -> "ComplexArray":
+    """Precompute F_{n',n}(G) for all G and Landau levels.
+
+    Parameters
+    ----------
+    q_magnitudes, q_angles :
+        Arrays with the same shape, describing |G|ℓ_B and polar angle θ.
+    nmax :
+        Number of Landau levels (0..nmax-1).
+    lB :
+        Magnetic length ℓ_B (default 1.0). ``q_magnitudes`` are understood
+        to be in units of 1/ℓ_B.
+
+    Returns
+    -------
+    F : (nG, nmax, nmax) complex array
+        Plane-wave form factors F_{n',n}(G).
+    """
+    n_indices = np.arange(nmax)
+    return _analytic_form_factor(
+        n_row=n_indices[None, :, None],
+        n_col=n_indices[None, None, :],
+        q_magnitudes=np.asarray(q_magnitudes)[:, None, None],
+        q_angles=np.asarray(q_angles)[:, None, None],
+        lB=lB,
+    ).astype(np.complex128)
+
+
+__all__ = ["get_form_factors"]
+

quantumhall_matrixelements-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: quantumhall_matrixelements
+Version: 0.1.0
+Summary: Landau-level plane-wave form factors and exchange kernels for quantum Hall systems.
+Author-email: Tobias Wolf <public@wolft.xyz>
+License: MIT
+Project-URL: Homepage, https://github.com/wolft/quantumhall_matrixelements
+Project-URL: Issues, https://github.com/wolft/quantumhall_matrixelements/issues
+Keywords: quantum Hall,matrix elements,form factors,exchange kernels,Landau levels
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: hankel>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# quantumhall-matrixelements: Quantum Hall Landau-Level Matrix Elements
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17646027.svg)](https://doi.org/10.5281/zenodo.17646027)
+
+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:
+  - Gauss-Legendre quadrature with rational mapping (`gausslegendre` backend, default).
+  - Generalized Gauss–Laguerre quadrature (`gausslag` backend).
+  - Hankel-transform based integration (`hankel` backend).
+- Symmetry diagnostics for verifying kernel implementations on a given G-grid.
+
+## Backends and Reliability
+
+The package provides three backends for computing exchange kernels, each with different performance and stability characteristics:
+
+1.  **`gausslegendre` (Default)**:
+    -   **Method**: Gauss-Legendre quadrature mapped from $[-1, 1]$ to $[0, \infty)$ via a rational mapping.
+    -   **Pros**: Fast and numerically stable for all Landau level indices ($n$).
+    -   **Cons**: May require tuning `nquad` for extremely large momenta or indices ($n > 100$).
+    -   **Recommended for**: General usage, especially for large $n$ ($n \ge 10$).
+
+2.  **`gausslag`**:
+    -   **Method**: Generalized Gauss-Laguerre quadrature.
+    -   **Pros**: Very fast for small $n$.
+    -   **Cons**: Numerically unstable for large $n$ ($n \ge 12$) due to high-order Laguerre polynomial roots.
+    -   **Recommended for**: Small systems ($n < 10$) where speed is critical.
+
+3.  **`hankel`**:
+    -   **Method**: Discrete Hankel transform.
+    -   **Pros**: High precision and stability.
+    -   **Cons**: Significantly slower than quadrature methods.
+    -   **Recommended for**: Reference calculations and verifying other backends.
+
+## 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 PyPI (once published):
+
+```bash
+pip install quantumhall-matrixelements
+```
+
+From a local checkout (development install):
+
+```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 'gausslegendre' backend
+
+print("F shape:", F.shape)
+print("X shape:", X.shape)
+```
+
+For more detailed examples, see the example scripts under `examples/` and the tests under `tests/`.
+
+## Citation
+
+If you use the package `quantumhall-matrixelements` in academic work, please cite:
+
+> Tobias Wolf, *quantumhall-matrixelements: Quantum Hall Landau-Level Matrix Elements*, version 0.1.0, 2025.  
+> DOI: https://doi.org/10.5281/zenodo.17646027
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17646027.svg)](https://doi.org/10.5281/zenodo.17646027)
+
+A machine-readable `CITATION.cff` file is included in the repository and can be used with tools that support it (for example, GitHub’s “Cite this repository” button).
+
+## Development
+
+- Run tests and coverage:
+
+  ```bash
+  pytest
+  ```
+
+- Lint and type-check:
+
+  ```bash
+  ruff check .
+  mypy .
+  ```
+
+## Authors and license
+
+- Author: Tobias Wolf
+- Copyright © 2025 Tobias Wolf
+- License: MIT (see `LICENSE`).

quantumhall_matrixelements-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+quantumhall_matrixelements/__init__.py,sha256=4PGAH9H62gBRkHsuxQFpbbKe7l6KuFw2uS9staaE4UM,2827
+quantumhall_matrixelements/_debug_symmetry.py,sha256=ieQc5fVwroC3TLcIkfeGNmEvJde6heyC6gOvRS3RQq4,1543
+quantumhall_matrixelements/diagnostic.py,sha256=A6f8EzEWZiK5B54xKSS7qgdX2XXQi9FymVUVJPmb_wY,1637
+quantumhall_matrixelements/exchange_gausslag.py,sha256=vqF8eBGXatEa1dqOYKOxzAQE2ZB8p4zJ5PTlP6H7wzY,5875
+quantumhall_matrixelements/exchange_hankel.py,sha256=PCNKMcLa_71JzvfvHKp4fd0dFL5YJh_KraVGUIaaNDI,5784
+quantumhall_matrixelements/exchange_legendre.py,sha256=qYcd27g90R7Fv8dxP-sFL2l0eAflUULCJozXp9Y6IlU,6787
+quantumhall_matrixelements/planewave.py,sha256=v_xvM8P-jynXL8ML8TEb5k_qfnJ1ztDvZltSdYLvkT0,2466
+quantumhall_matrixelements-0.1.0.dist-info/licenses/LICENSE,sha256=jFCGBoPJ8yDW1bqyaj2jwNsZQMmVE42yqE42hGBqJEQ,1069
+quantumhall_matrixelements-0.1.0.dist-info/METADATA,sha256=WaL5Kb4tRU5bpDpZ12EJ_qj4_lEf91wsAMa7h6dXCco,6949
+quantumhall_matrixelements-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+quantumhall_matrixelements-0.1.0.dist-info/top_level.txt,sha256=-Xq3KN3v4pwYuKSv92x2m3SC2GXYGYcKoE1Wp0IdAi0,27
+quantumhall_matrixelements-0.1.0.dist-info/RECORD,,

quantumhall_matrixelements-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quantumhall_matrixelements-0.1.0.dist-info/licenses/LICENSE

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

quantumhall_matrixelements-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantumhall_matrixelements