API Reference¶

This page is organized by workflow rather than by module path. For most users, the first two sections are enough.

Plane-wave and exchange workflows¶

quantumhall_matrixelements.get_form_factors(q_magnitudes, q_angles, nmax, lB=1.0, sign_magneticfield=-1)[source]¶

Precompute F_{n’,n}(G) for all G and Landau levels.

Parameters:

q_magnitudes (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays with the same shape, describing the wavevector magnitude |q| and polar angle θ.
q_angles (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays with the same shape, describing the wavevector magnitude |q| and polar angle θ.
nmax (int) – Number of Landau levels (0..nmax-1).
lB (float) – Magnetic length ℓ_B (default 1.0). The form factors depend on the dimensionless combination |q|ℓ_B, so the implementation multiplies q_magnitudes by lB internally. If you already work with dimensionless |q|ℓ_B values, leave lB=1 and pass those values directly as q_magnitudes.
sign_magneticfield (int) – Sign of the charge–field product σ = sgn(q B_z). Use -1 for the electron/positive-B convention used internally; +1 returns the complex-conjugated form factors with the appropriate phase flip.

Returns:

F – Plane-wave form factors F_{n’,n}(G).

Return type:

(nG, nmax, nmax) complex array

quantumhall_matrixelements.get_exchange_kernels(G_magnitudes, G_angles, nmax, *, method=None, materialize_limit_bytes=DEFAULT_FULL_TENSOR_LIMIT_BYTES, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, **kwargs)[source]¶

Compute and return the fully materialized 5D exchange tensor.

Parameters:

G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays describing the reciprocal vectors \(G\) in polar form. Both must have the same shape; broadcasting is not applied.
G_angles (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays describing the reciprocal vectors \(G\) in polar form. Both must have the same shape; broadcasting is not applied.
nmax (int) – Number of Landau levels (0..nmax-1) to include.
method (str | None) –
Backend selector:
- 'laguerre' (default): Numba-JIT quadrature on [0, qmax] with Laguerre three-term recurrence. Stable for all nmax and |G|.
- 'ogata': Ogata quadrature (Hankel/Ogata) with an automatic small-|G| fallback.
- 'hankel': Hankel-transform based implementation (slow but precise).
materialize_limit_bytes (float | int | None) – Soft cap (in bytes) for allocating a full (nG, nmax, nmax, nmax, nmax) complex tensor. Pass None to disable this safety check.
canonical_select_max_entries (int | None) – Soft cap on the number of canonical select entries constructed when select is omitted. This prevents accidentally building huge Python lists with O(nmax^4) entries.
**kwargs (Any) – Additional arguments passed to the backend (e.g. nquad, scale). Common keywords include sign_magneticfield (±1) to select the magnetic-field orientation convention and, for the Laguerre backend, workspace_limit_bytes to cap dense quadrature-table allocations.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

Notes

For the built-in potentials 'coulomb' and 'constant', the kappa keyword scales the kernel. For callable potentials, the provided function defines the overall energy scale.

To compute only a small set of entries without allocating the full tensor, use get_exchange_kernels_compressed() with an explicit select=....

quantumhall_matrixelements.get_exchange_kernels_compressed(G_magnitudes, G_angles, nmax, *, method=None, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, compressed_limit_bytes=DEFAULT_COMPRESSED_LIMIT_BYTES, **kwargs)[source]¶

Return the compressed exchange-kernel representation (values, select_list).

Unlike get_exchange_kernels(), this function never materializes the full 5D tensor, and always returns the select list used by the backend.

If select is omitted, the backend still constructs the canonical symmetry-reduced list, so the returned representation remains O(nmax^4) in the number of stored entries. compressed_limit_bytes caps the resulting (nG, n_select) complex output array. Pass an explicit select=... to compute only the entries you need.

Parameters:

G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]])
G_angles (ndarray[tuple[Any, ...], dtype[float64]])
nmax (int)
method (str | None)
select (Iterable[tuple[int, int, int, int]] | None)
canonical_select_max_entries (int | None)
compressed_limit_bytes (float | int | None)
kwargs (Any)

Return type:

tuple[ndarray[tuple[Any, …], dtype[complex128]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.get_fockmatrix_constructor(G_magnitudes, G_angles, nmax, *, method=None, materialize_full=False, select=None, **kwargs)[source]¶

Precompute an exchange Fock-matrix operator for repeated rho applications.

Parameters:

G_magnitudes (array-like) – Reciprocal vectors in polar coordinates (same shape, no broadcasting).
G_angles (array-like) – Reciprocal vectors in polar coordinates (same shape, no broadcasting).
nmax (int) – Landau-level cutoff.
method (str, optional) – Exchange-kernel backend name ('laguerre', 'ogata', or 'hankel').
materialize_full (bool, optional) – Deprecated/ignored; the constructor always uses the compressed format to avoid nmax^4 allocations.
select (iterable of index quadruples, optional) – If provided, compute only these symmetry representatives; otherwise uses the canonical symmetry-reduced list.
**kwargs – Forwarded to the chosen backend (e.g. potential, kappa, nquad).

Returns:

A function fock(rho, include_minus=True) that returns the exchange Fock matrix for each G given a density matrix rho of shape (nG, nmax, nmax). By default the returned Fock includes the leading minus sign (Σ = -X·ρ); pass include_minus=False to disable it.

Return type:

Callable

quantumhall_matrixelements.get_fockmatrix_constructor_hf(G_magnitudes, G_angles, nmax, *, method=None, materialize_full=False, select=None, **kwargs)[source]¶

Precompute an exchange Fock-matrix operator using the HF convention.

This mirrors get_fockmatrix_constructor(), but returns a callable that applies kernels in the quantumhall_hf exchange convention:

Σ^F_{n m}(G) = - Σ_{r,t} X_{m r n t}(G) ρ^*_{t r}(G).

Parameters:

G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]])
G_angles (ndarray[tuple[Any, ...], dtype[float64]])
nmax (int)
method (str | None)
materialize_full (bool)
select (Iterable[tuple[int, int, int, int]] | None)
kwargs (Any)

Return type:

Callable[[ndarray[tuple[Any, …], dtype[complex128]], bool], ndarray[tuple[Any, …], dtype[complex128]]]

quantumhall_matrixelements.build_fockmatrix_apply(values, select, nmax, *, convention='standard')[source]¶

Build a callable that applies compressed exchange kernels to a density.

Parameters:

values (ndarray[tuple[Any, ...], dtype[complex128]]) – Compressed kernel representation returned by quantumhall_matrixelements.get_exchange_kernels_compressed().
select (list[tuple[int, int, int, int]]) – Compressed kernel representation returned by quantumhall_matrixelements.get_exchange_kernels_compressed().
nmax (int) – Landau-level cutoff.
convention (str) – 'standard' (default) builds a map corresponding to Σ(G) = -X(G)·ρ(G) in the natural kernel index order. 'hf' implements the alternate HF convention used by quantumhall_hf.

Returns:

A function fock(rho, include_minus=True).

Return type:

Callable

Symmetric-gauge workflows¶

quantumhall_matrixelements.get_guiding_center_form_factors(q_magnitudes, q_angles, mmax, *, lB=1.0, sign_magneticfield=-1)[source]¶

Return guiding-center matrix elements <m'|exp(i q.R)|m>.

The guiding-center oscillator has the opposite chirality to the cyclotron sector, so this routine internally uses sigma_gc = -sign_magneticfield.

Parameters:

q_magnitudes (ndarray[tuple[Any, ...], dtype[float64]])
q_angles (ndarray[tuple[Any, ...], dtype[float64]])
mmax (int)
lB (float)
sign_magneticfield (int)

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

quantumhall_matrixelements.get_factorized_density_form_factors(q_magnitudes, q_angles, nmax, mmax, *, lB=1.0, sign_magneticfield=-1)[source]¶

Return the cyclotron and guiding-center factors separately.

Parameters:

q_magnitudes (ndarray[tuple[Any, ...], dtype[float64]])
q_angles (ndarray[tuple[Any, ...], dtype[float64]])
nmax (int)
mmax (int)
lB (float)
sign_magneticfield (int)

Return type:

tuple[ndarray[tuple[Any, …], dtype[complex128]], ndarray[tuple[Any, …], dtype[complex128]]]

quantumhall_matrixelements.get_central_onebody_matrix_elements_compressed(nmax, mmax, *, potential='coulomb', kappa=1.0, qmax=35.0, nquad=800, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES)[source]¶

Return compressed matrix elements of an origin-centered radial potential.

Parameters:

nmax (int)
mmax (int)
potential (str | Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]])
kappa (float)
qmax (float)
nquad (int)
select (Iterable[Sequence[int]] | None)
canonical_select_max_entries (int | None)

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.materialize_central_onebody_matrix(values, select, nmax, mmax)[source]¶

Materialize explicit-index form (n_row, m_row, n_col, m_col).

Parameters:

values (ndarray[tuple[Any, ...], dtype[float64]])
select (list[tuple[int, int, int, int]])
nmax (int)
mmax (int)

Return type:

ndarray[tuple[Any, …], dtype[float64]]

quantumhall_matrixelements.get_haldane_pseudopotentials(mmax, *, n_ll=0, potential='coulomb', kappa=1.0, qmax=25.0, nquad=2000)[source]¶

Return plane pseudopotentials V_m^(n_ll) for m = 0..mmax-1.

Parameters:

mmax (int)
n_ll (int)
potential (str | Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]])
kappa (float)
qmax (float)
nquad (int)

Return type:

ndarray[tuple[Any, …], dtype[float64]]

quantumhall_matrixelements.get_twobody_disk_from_pseudopotentials_compressed(V_m, mmax, *, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, antisymmetrize=False)[source]¶

Return compressed LLL disk two-body matrix elements.

Channels above len(V_m)-1 are treated as zero.

Parameters:

V_m (ndarray[tuple[Any, ...], dtype[float64]])
mmax (int)
select (Iterable[Sequence[int]] | None)
canonical_select_max_entries (int | None)
antisymmetrize (bool)

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.materialize_twobody_disk_tensor(values, select, mmax)[source]¶

Materialize explicit-index form (m1, m2, m3, m4).

Parameters:

values (ndarray[tuple[Any, ...], dtype[float64]])
select (list[tuple[int, int, int, int]])
mmax (int)

Return type:

ndarray[tuple[Any, …], dtype[float64]]

Diagnostics and opposite-field helpers¶

quantumhall_matrixelements.get_form_factors_opposite_field(F)[source]¶

Transform form factors to the opposite magnetic-field sign (σ→-σ).

Parameters:: F ((nG, nmax, nmax) complex array) – Form factors for sign_magneticfield = -1.
Returns:: Form factors for sign_magneticfield = +1 obtained via conjugation and the standard phase flip.
Return type:: ComplexArray

quantumhall_matrixelements.get_exchange_kernels_opposite_field(Xs)[source]¶

Transform exchange kernels to the opposite magnetic-field sign (σ→-σ).

Parameters:: Xs ((nG, nmax, nmax, nmax, nmax) complex array) – Exchange kernels for sign_magneticfield = -1.
Returns:: Exchange kernels for sign_magneticfield = +1.
Return type:: ComplexArray

Advanced backend-specific entry points¶

quantumhall_matrixelements.get_exchange_kernels_laguerre(G_magnitudes, G_angles, nmax, *, potential='coulomb', kappa=1.0, qmax=35.0, nquad=800, adaptive_nquad=True, use_ogata=False, ogata_h=0.01, ogata_N=None, kmin_ogata=20.0, sign_magneticfield=-1, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, workspace_limit_bytes=DEFAULT_WORKSPACE_LIMIT_BYTES)[source]¶

Compute exchange kernels using the finite-q fast precompute tables.

This backend uses Gauss-Legendre quadrature on [0, qmax] with a Numba-JIT form-factor table computed via the Laguerre three-term recurrence. This avoids intermediate overflow at large nmax and is numerically stable for arbitrarily high Landau-level indices.

Parameters:

adaptive_nquad (bool) – If True (default), automatically increase nquad so that the Gauss-Legendre grid resolves Bessel oscillations at the largest |G| in the input (at least 8 nodes per oscillation period).
use_ogata (bool) – If True, use Ogata quadrature in q-space for |G| >= kmin_ogata. This gives exponential convergence for oscillatory integrals with O(200) nodes regardless of |G|, combined with the same stable R-table. Gauss-Legendre is still used for |G| < kmin_ogata.
ogata_h (float) – Ogata step-size parameter (smaller gives more nodes, higher accuracy).
ogata_N (int or None) – Number of Ogata nodes per Bessel order. If None, uses int(pi/h).
kmin_ogata (float) – Threshold on |G| above which Ogata quadrature is used (when use_ogata=True).
workspace_limit_bytes (int, float, or None) – Soft cap on the dense Gauss-Legendre work tables used by this backend. Pass None to disable the guard.
G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]])
G_angles (ndarray[tuple[Any, ...], dtype[float64]])
nmax (int)
potential (str | Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]])
kappa (float)
qmax (float)
nquad (int)
sign_magneticfield (int)
select (Iterable[tuple[int, int, int, int]] | None)
canonical_select_max_entries (int | None)

Returns:

values (ndarray, shape (nG, n_select), complex128)
select_list (list of (n1, m1, n2, m2) tuples)

Return type:

tuple[ndarray[tuple[Any, …], dtype[complex128]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.get_exchange_kernels_Ogata(G_magnitudes, G_angles, nmax, *, potential='coulomb', kappa=1.0, nquad=8000, scale=0.5, nlag=80, sign_magneticfield=-1, ogata_h=0.0075, ogata_N=None, kmin_ogata=2.0, chunk_size=128, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, ogata_auto=False, ogata_auto_rtol=3e-3, ogata_auto_atol=1e-6, ogata_auto_refine=2.0, ogata_auto_max_refine=1, ogata_auto_fallback='gausslegendre')[source]¶

Compute exchange kernels using Ogata quadrature (Hankel/Ogata) with fallback.

This function is a drop-in alternative to the mapped Gauss–Legendre method. For moderately large \(k = |G| \ell_B\) it evaluates the oscillatory Bessel integrals using Ogata quadrature (exponentially convergent for Hankel transforms). For small k (including k=0), it automatically falls back to the original mapped Gauss–Legendre quadrature, where the integrand is non-oscillatory and Ogata can be inaccurate.

Parameters:

G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]]) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
G_angles (ndarray[tuple[Any, ...], dtype[float64]]) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
nmax (int) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
potential (str | Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
kappa (float) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
nquad (int) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
scale (float) – Same meaning as in the Gauss–Legendre implementation. nquad and scale are used for the fallback path.
ogata_h (float) – Ogata step size h (smaller => more nodes => higher accuracy, slower). Default 0.0075.
ogata_N (int or None) – Number of Ogata nodes. If None, uses int(pi/ogata_h).
kmin_ogata (float) – Threshold on \(k = |G| \ell_B\) below which we switch to the fallback quadrature. Default 2.0. If you know your regime, you can reduce it to use Ogata more aggressively.
chunk_size (int) – Number of quadruples processed at once per N bucket (controls memory).
select (iterable of (n1, m1, n2, m2), optional) – If provided, compute only these entries and return an array of shape (nG, n_select) in the input order. This avoids allocating the full (nG, nmax, nmax, nmax, nmax) tensor.
ogata_auto (bool, optional) – If True, attempt Ogata convergence by refining ogata_h (and ogata_N) and fall back for any |G| that does not converge within tolerances.
ogata_auto_rtol (float, optional) – Relative/absolute tolerances for the per-|G| convergence check between successive Ogata refinements.
ogata_auto_atol (float, optional) – Relative/absolute tolerances for the per-|G| convergence check between successive Ogata refinements.
ogata_auto_refine (float, optional) – Refinement factor for Ogata step size h (h -> h / refine).
ogata_auto_max_refine (int, optional) – Maximum number of refinements. Must be >= 1 if ogata_auto is enabled.
ogata_auto_fallback ({"gausslegendre", "hankel"}, optional) – Backend used for |G| values that fail Ogata convergence.
nlag (int)
sign_magneticfield (int)
canonical_select_max_entries (int | None)

Returns:

values (numpy.ndarray (nG, n_select)) – Compressed exchange values matching select_list.
select_list (list[tuple[int, int, int, int]]) – Quadruples corresponding to the columns of values.

Return type:

tuple[ndarray[tuple[Any, …], dtype[complex128]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.get_exchange_kernels_hankel(G_magnitudes, G_angles, nmax, *, potential='coulomb', kappa=1.0, sign_magneticfield=-1, select=None, canonical_select_max_entries=DEFAULT_CANONICAL_SELECT_MAX_ENTRIES, hankel_N=6000, hankel_h=7e-6, chunk_size=128, hankel_nlag=80, hankel_q_cut=7.5, hankel_trunc_kmin=2.0)[source]¶

Compute X_{n1,m1,n2,m2}(G) via vectorized Hankel quadrature.

Parameters:

G_magnitudes (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays describing |G| and polar angle \(\theta_G\) (same shape, no broadcasting).
G_angles (ndarray[tuple[Any, ...], dtype[float64]]) – Arrays describing |G| and polar angle \(\theta_G\) (same shape, no broadcasting).
nmax (int) – Number of Landau levels.
potential (str | Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]]) – 'coulomb' (default), 'constant', or a callable V(q) giving the interaction in 1/ℓ units.
kappa (float) – Prefactor for Coulomb/constant cases.
sign_magneticfield (int) – Sign of the charge–field product σ = sgn(q B_z). -1 matches the package’s internal convention; +1 returns the kernels for the opposite sign by applying the appropriate complex conjugation and phase factors.
select (Iterable[tuple[int, int, int, int]] | None) – Optional iterable of (n1, m1, n2, m2). If provided, only these entries are computed and the return array has shape (nG, n_select) in the input order. If omitted, a canonical set of representatives is used and returned in compressed form to avoid materializing the full tensor.
hankel_N (int) – Hankel transform grid parameters (passed to hankel.HankelTransform).
hankel_h (float) – Hankel transform grid parameters (passed to hankel.HankelTransform).
chunk_size (int) – Number of quadruples processed at once per N bucket.
hankel_nlag (int) – Order of generalized Gauss-Laguerre quadrature used for the k=0 slice.
hankel_q_cut (float | None) – Adaptive node window for k>0: keep nodes with q = x/k <= hankel_q_cut.
hankel_trunc_kmin (float) – Disable node truncation for k < hankel_trunc_kmin (keeps full grid for small k).
canonical_select_max_entries (int | None)

Returns:

values (numpy.ndarray (nG, n_select)) – Compressed exchange values matching select_list.
select_list (list[tuple[int,int,int,int]]) – Quadruples corresponding to the columns of values.

Return type:

tuple[ndarray[tuple[Any, …], dtype[complex128]], list[tuple[int, int, int, int]]]

quantumhall_matrixelements.build_exchange_fock_precompute(nmax, G_mags, G_thetas, params, *, sigma=-1.0, kappa=1.0, potential=None, include_minus=True, workspace_limit_bytes=DEFAULT_WORKSPACE_LIMIT_BYTES)[source]¶

Precompute the fast Laguerre Fock-application tables.

The default sigma=-1 matches the package-wide sign_magneticfield=-1 convention used by the public APIs. The dense precompute tables are guarded by workspace_limit_bytes by default.

Parameters:

nmax (int)
G_mags (ndarray[tuple[Any, ...], dtype[float64]])
G_thetas (ndarray[tuple[Any, ...], dtype[float64]])
params (QuadratureParams)
sigma (float)
kappa (float)
potential (Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[float64]]] | None)
include_minus (bool)
workspace_limit_bytes (float | int | None)

Return type:

ExchangeFockPrecompute