Documentation for Polfed.jl

polfed(mat, x0, howmany, target; kwargs...)
polfed(f!, x0, howmany, target; kwargs...)

Solve an eigenvalue problem using the Polynomial Filtering Eigenvalue Decomposition (POLFED) algorithm with a given matrix input.

This method employs Chebyshev polynomial spectral filtering to efficiently extract eigenvalues and eigenvectors within a specified spectral region of a dense or sparse matrix. When optimize_mapping = true, the operator is internally rescaled and optimized to reduce memory access, particularly effective for Hamiltonians with a small number of unique off-diagonal elements.

Arguments

• mat::AbstractMatrix: The Hamiltonian or operator matrix (dense or sparse).
• f!::Function: In-place linear operator callback with signature f!(Y, X).
• x0::AbstractVecOrMat: The initial vector or block of vectors used to start the iteration. If a vector is provided, a standard Lanczos factorization is performed; if a matrix is provided, the Block Lanczos variant is used.
• howmany::Integer: Number of eigenvalues to compute.
• target: Spectral region to target (in unscaled units). Accepts a numeric value (treated as unrescaled) or a spec such as :maxdos, :middle, (:offset, frac), (:unrescaled, value), or (:rescaled, value).

Keyword Arguments

• produce_report::Bool = PolfedDefaults.produce_report Whether to return detailed diagnostic information about the run. If enabled, a Report struct is returned alongside eigenvalues and eigenvectors.
• mapping::MappingConfig = MappingConfig() Configuration for mapping, rescaling, parallelization, and optional optimized kernels.
• transform::TransformConfig = TransformConfig() Configuration for polynomial coefficients, normalization, interval, and order.
• fact::FactorizationConfig = FactorizationConfig() Configuration for the underlying Lanczos/Krylov factorization (see FactorizationConfig). Includes settings for numerical tolerance, reorthogonalization strategy, and eigenvalue convergence criteria.
• dos::DoSConfig = DoSConfig() Configuration for the stochastic density-of-states (DoS) estimation (see DoSConfig). Parameters include the number of random vectors, number of Chebyshev moments, and statistical averaging options.

Returns

• (vals, vecs) — Eigenvalues and eigenvectors.
• (vals, vecs, report) — If produce_report = true, also returns a Report containing:
  • Spectral transform diagnostics (mapping, scaling, polynomial order)
  • Factorization statistics (iterations, reorthogonalization)
  • Benchmark metrics (wall time, CPU time, and device information)

Notes

• If x0 is not normalized (vector input) or orthonormal (matrix input), POLFED emits a warning and uses a normalized/orthonormalized copy without mutating the caller's array.
• The polynomial order is chosen automatically unless explicitly set via TransformConfig.order.
• When mapping.optimize_mapping = true, a rescaled operator and optimized Clenshaw recurrence are used to reduce memory bandwidth usage, especially beneficial for structured Hamiltonians.
• GPU execution is automatically enabled when is_gpu_array(x0).

See also

MappingConfig, TransformConfig, FactorizationConfig, DoSConfig, display_report

polfed(f!::Function, x0::AbstractVecOrMat, howmany::Integer, target; kwargs...)

Operator-callback overload of polfed.

Use this when the matrix is represented implicitly through f!(Y, X).

optimized_mapping!(diagonals::AbstractVector, offdiagonals::Offdiagonals, parallel_strategy::Parallelization) -> Function

Build an optimized in-place mapping callback f!(Y, X) from packed diagonal and off-diagonal data.

optimized_clenshaw_recurrence_relation!(diagonals, offdiagonals, parallel_strategy) -> Function

Build an optimized Clenshaw recurrence callback compatible with POLFED's internal recurrence signature.

optimized_clenshaw_final_sum!(diagonals, offdiagonals, parallel_strategy) -> Function

Build an optimized callback for the terminal Clenshaw combination step.

lanczos_extrema(mat::AbstractMatrix; x0=nothing, maxdim=1000, tol=1e-14, eigentol=1e-8, kwargs...)
lanczos_extrema(f!::Function, x0::AbstractVector; maxdim=1000, tol=1e-14, eigentol=1e-8, kwargs...)

Estimate the smallest and largest eigenvalues of a Hermitian/symmetric matrix or linear operator using two short Lanczos probes.

The returned tuple is (Emin, Emax), where Emin is obtained with which=:SR and Emax with which=:LR. If x0 is provided, it is copied and normalized before use. If omitted for matrix input, a random normalized vector with a floating element type compatible with mat is generated.

Extra keyword arguments are forwarded to lanczos, except that which and howmany are fixed internally.

lanczos(mat::AbstractMatrix, x0::AbstractVecOrMat, howmany::Int; 
        basistype::Type{<:OrthonormalBasis}=MatrixBasis, 
        rot::ReOrthTechnique=FullRO(), 
        maxdim::Int=10howmany, 
        which::Symbol=:SR, 
        tol::Real=1e-14, 
        eigentol::Real=1e-8, 
        mapvals::Union{Function,Nothing}=nothing)

lanczos(f!::Function, x0::AbstractVecOrMat, howmany::Int; 
        basistype::Type{<:OrthonormalBasis}=MatrixBasis, 
        rot::ReOrthTechnique=FullRO(), 
        maxdim::Int=10howmany, 
        which::Symbol=:SR, 
        tol::Real=1e-14, 
        eigentol::Real=1e-8, 
        mapvals::Function=f!)

Performs the block Lanczos factorization to compute a specified number of extremal eigenvalues and eigenvectors of a matrix or a linear operator. This method automatically detects whether the input data lives on the CPU or GPU, and dispatches to the appropriate optimized backend.

Arguments

• mat::AbstractMatrix: The input matrix for which the spectral decomposition is sought.
• f!::Function: Matrix–vector multiplication routine, defined as f!(Y, X) = A * X. Used when the matrix is represented implicitly or stored on GPU.
• x0::AbstractVecOrMat: Initial block of orthonormal starting vectors. The number of columns determines the block size.
• howmany::Int: Number of desired eigenpairs.

Keyword Arguments

• basistype::Type{<:OrthonormalBasis}=MatrixBasis: Type of orthonormal basis used (MatrixBasis, HybridMatrixBasis, or VectorBasis).
• maxdim::Int=500howmany: Maximum dimension of the Krylov subspace.
• which::Symbol=:SR: Determines which eigenvalues to converge (:SR, :LR, or :amplitude).
• tol::Real=1e-14: Numerical tolerance for orthogonality loss in the Lanczos basis.
• eigentol::Real=1e-8: Convergence tolerance for eigenvalue residuals.
• mapvals::Union{Function,Nothing}=nothing: Optional mapping function applied to the spectral transformation. Defaults to standard matrix–vector multiplication.

Description

The Lanczos algorithm is a Krylov subspace method used to approximate the smallest (or largest) eigenvalues and corresponding eigenvectors of large Hermitian or symmetric operators.

Two calling conventions are supported:

1. Matrix interface: Pass a concrete matrix mat — a multiplication function f! is generated internally.
2. Operator interface: Pass a user-defined function f!(Y, X) for custom or GPU-resident operators.

The function constructs:

• A LanczosIterator to manage Krylov basis vectors and reorthogonalization.
• A ConvergenceInfo object to track eigenvalue convergence and stopping criteria.
• A FactorizationReport for diagnostic output and benchmarking.

GPU arrays are automatically detected via is_gpu_array, and computations are performed on the GPU via CUDA.

Returns

A tuple containing:

1. vals: Approximated eigenvalues (sorted according to which).
2. vecs: Corresponding approximate eigenvectors (as columns).
3. report::FactorizationReport: Detailed factorization report containing timing, convergence, and iteration statistics.

lanczos(f!::Function, x0::AbstractVecOrMat, howmany::Int; kwargs...)

Operator-callback overload of lanczos.