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`).
