Usage Notes

By default, the eigensolvers search for eigenvalues near zero using sigma=0. Use the sigma keyword argument to change the energy around which eigenvalues are requested.

Complex absorbing potentials

By default, both solvers use Hermitian sparse eigensolvers and assume that the input Hamiltonian is Hermitian. Complex absorbing potentials can be included by adding the imaginary term to the potential function U and setting nonHermitian=True in eigensolver or Ceigensolver. This switches the backend to a non-Hermitian eigenvalue solve.

Performance tips

To discretize the Hamiltonian operator, the supplied potential function U is evaluated many times. For good performance, U should be written in a vectorized NumPy style. Python branching with if statements and explicit for loops can substantially increase solve time. Where branching is needed, prefer NumPy operations such as np.where. Avoid using np.vectorize to make a scalar Python function appear vectorized; it still evaluates through Python-level looping.

Although pygenstates can construct finite-difference problems in arbitrary dimension, dimensions above three can become expensive quickly. With x grid points in each direction, the number of grid points grows like \(O(x^n)\).

Using which='SA' and sigma=None requests the smallest algebraic eigenvalues and uses SciPy’s standard (and typically fastest) Hermitian sparse eigensolver mode. To target a different energy while still using this mode, add a constant offset to the supplied potential U so that the desired energy region is shifted near zero.

Backends

The default backend is "finite_difference". It supports arbitrary continuous dimension, subject to sparse-matrix size and available memory.

The "FEM" backend uses scikit-fem and supports one-, two-, and three-dimensional problems. It accepts intorder to control the finite-element integration order.

SciPy Eigensolver Options

The solvers discretize the differential operator into a sparse matrix and pass that matrix to SciPy’s sparse eigensolvers. For more control over the solve, additional keyword arguments can be passed through to SciPy. See the SciPy eigsh API page for more details.

Common options include sigma, which, tol, maxiter, and ncv. Use Enum to choose the number of eigenpairs; do not pass SciPy’s k argument directly.