Hamiltonian#

Public names: edinpy.fermion.Hamiltonian and edinpy.boson.Hamiltonian.

class edinpy.fermion.Hamiltonian(operator, sector)[source]#

Finite-sector Hamiltonian built from a symbolic operator expression.

Parameters:

  • operator (Operator) – Symbolic second-quantized operator expression. All primitive operators in the expression must use the same mode specification as sector.

  • sector (NParticleSector) – Built fermionic or bosonic sector that defines the ordered many-body basis.

Notes

The sparse CSC matrix is constructed lazily when matrix, calc_matrix(), or an explicit-matrix eigensolve requires it. Partial eigenproblems can instead use aslinearoperator() or eigsolve(matrix_free=True).

calc_matrix()[source]#

Construct and cache the Hamiltonian in CSC sparse format.

Returns:

Square Hamiltonian matrix in the ordering of sector.basis.

Return type:

scipy.sparse.csc_matrix

property matrix#

Lazily constructed Hamiltonian matrix.

Type:

scipy.sparse.csc_matrix

aslinearoperator(*, execution='numpy')[source]#

Return the Hamiltonian as a matrix-free SciPy LinearOperator.

Parameters:

execution ({"numpy", "numba-serial", "numba-parallel", "mixed"}, optional) – Hamiltonian-action implementation. "numpy" uses the NumPy implementation. "numba-serial" and "numba-parallel" are strict Numba requests and raise if the operator or basis is not supported. "numba-parallel" uses Numba’s configured thread count. "mixed" uses the statistics-specific conservative selection rule and does not enable parallel execution automatically.

Returns:

Matrix-free operator with forward and adjoint actions and shape (sector.dimension, sector.dimension).

Return type:

scipy.sparse.linalg.LinearOperator

Notes

The explicit CSC matrix is not constructed. The adjoint action is obtained from the symbolic Hermitian adjoint of the operator.

property solver_diagnostics#

Diagnostics from the most recent matrix-free eigensolve, or None.

The object is a frozen snapshot taken immediately when ARPACK returns. Subsequent uses of aslinearoperator(), such as residual checks, do not alter the stored diagnostics. Explicit-matrix solves clear it.

property compiler_stats#

Statistics for the lowered operator representation.

Type:

dict[str, int]

toarray()[source]#

Return the Hamiltonian as a dense NumPy array.

Returns:

Dense matrix with shape (sector.dimension, sector.dimension).

Return type:

numpy.ndarray

is_hermitian(atol=1e-12)[source]#

Test Hermiticity of the explicit Hamiltonian matrix.

Parameters:

atol (float, optional) – Absolute tolerance used when comparing the matrix with its Hermitian adjoint.

Returns:

True when the matrix is Hermitian within atol.

Return type:

bool

estimate_solver_memory(*, k=2, ncv=None)[source]#

Estimate dominant ARPACK workspace without materializing the matrix.

Parameters:

  • k (int, optional) – Number of requested eigenpairs.

  • ncv (int or None, optional) – Krylov subspace size. None uses SciPy’s default policy.

Returns:

Implementation-informed estimate of the dominant SciPy/ARPACK arrays. It excludes the Hamiltonian, basis storage, and general process overhead.

Return type:

ArpackMemoryEstimate

ncv_for_arpack_budget(budget_bytes, *, k=2, ncv=None)[source]#

Choose the largest ncv fitting an ARPACK workspace budget.

Parameters:

  • budget_bytes (int) – Maximum bytes assigned to the ARPACK arrays represented by estimate_solver_memory().

  • k (int, optional) – Number of requested eigenpairs.

  • ncv (int or None, optional) – Upper bound for the Krylov subspace size. None caps the search at SciPy’s normal default.

Returns:

Largest admissible ncv within the requested workspace budget.

Return type:

int

Notes

The budget excludes basis storage, Python and SciPy allocator overhead, linked libraries, and unrelated process memory.

plan_solver_memory(total_memory_bytes, *, k=2, ncv=None, reserve_bytes=0, reserve_fraction=0.25, safety_factor=1.25)[source]#

Estimate memory for a matrix-free ARPACK eigensolve.

Parameters:

  • total_memory_bytes (int) – Total memory envelope available to the process.

  • k (int, optional) – Number of requested eigenpairs.

  • ncv (int or None, optional) – Krylov subspace size. None uses SciPy’s default policy.

  • reserve_bytes (int, optional) – Fixed number of bytes withheld from the solver plan.

  • reserve_fraction (float, optional) – Fraction of total_memory_bytes withheld in addition to reserve_bytes. Must satisfy 0 <= value < 1.

  • safety_factor (float, optional) – Multiplicative factor applied to the ARPACK array estimate. Must be at least one.

Returns:

Estimated ARPACK storage, persistent basis storage, reserved memory, remaining headroom, and whether the plan fits.

Return type:

SolverMemoryPlan

ncv_for_memory_budget(total_memory_bytes, *, k=2, ncv=None, reserve_bytes=0, reserve_fraction=0.25, safety_factor=1.25)[source]#

Choose the largest ncv fitting a total-memory envelope.

Parameters:

  • total_memory_bytes (int) – Total memory envelope available to the process.

  • k (int, optional) – Number of requested eigenpairs.

  • ncv (int or None, optional) – Upper bound for the Krylov subspace size. None caps the search at SciPy’s normal default.

  • reserve_bytes (int, optional) – Fixed number of bytes withheld from the solver plan.

  • reserve_fraction (float, optional) – Fraction of total memory withheld in addition to reserve_bytes.

  • safety_factor (float, optional) – Multiplicative factor applied to the ARPACK array estimate.

Returns:

Largest admissible ncv satisfying the memory plan.

Return type:

int

eigsolve(*, sparse=True, k=2, which='SA', tol=1e-10, maxiter=None, ncv=None, v0=None, check_hermitian=True, matrix_free=False, execution='numpy')[source]#

Solve the Hermitian Hamiltonian eigenproblem.

Parameters:

  • sparse (bool, optional) – Use ARPACK through scipy.sparse.linalg.eigsh() when True and fewer than all eigenpairs are requested. Otherwise use the dense Hermitian solver scipy.linalg.eigh(). Matrix-free solves require sparse=True.

  • k (int or None, optional) – Number of eigenpairs to return. None requests the complete spectrum and therefore requires an explicit matrix.

  • which ({"SA", "LA", "SM", "LM"}, optional) – Spectral selection rule: smallest algebraic, largest algebraic, smallest magnitude, or largest magnitude, respectively.

  • tol (float, optional) – ARPACK convergence tolerance.

  • maxiter (int or None, optional) – Maximum number of ARPACK iterations. None uses SciPy’s default.

  • ncv (int or None, optional) – Number of Lanczos vectors used by ARPACK. It must satisfy k < ncv <= dimension. None uses SciPy’s default policy.

  • v0 (array_like or None, optional) – Initial vector for ARPACK. None lets SciPy choose the starting vector.

  • check_hermitian (bool, optional) – Check Hermiticity before an explicit-matrix solve. Matrix-free solves require False because an exact check would construct the matrix.

  • matrix_free (bool, optional) – Apply the Hamiltonian through a SciPy LinearOperator instead of constructing the CSC matrix. Only partial sparse solves with k < sector.dimension are supported.

  • execution ({"numpy", "numba-serial", "numba-parallel", "mixed"}, optional) – Hamiltonian-action implementation used when matrix_free=True. Explicit-matrix solves require "numpy". Strict Numba modes raise when the current operator or basis is unsupported.

Returns:

  • eigenvalues (numpy.ndarray) – Requested eigenvalues ordered according to which.

  • eigenvectors (numpy.ndarray) – Corresponding normalized eigenvectors stored by column in the sector-basis ordering.

Notes

The returned eigenpairs are also stored in eigvals and eigvecs. Use eigenstate() or eigenstates() to recover basis-aware Fock vectors.

eigenstate(index=0)[source]#

Return one computed eigenvector as a basis-aware Fock ket.

Parameters:

index (int, optional) – Column index in the eigenvector array from the most recent eigsolve(). Negative indices follow Python indexing.

Returns:

Eigenstate associated with eigvals[index].

Return type:

FockVector

eigenstates()[source]#

Return all computed eigenvectors as basis-aware Fock kets.

Returns:

Eigenstates in the same order as eigvals.

Return type:

tuple[FockVector, …]

property eigvals#

Eigenvalues from the most recent eigensolve.

Type:

numpy.ndarray or None

property eigvecs#

Eigenvectors from the most recent eigensolve.

Type:

numpy.ndarray or None