hqs_distiller.distiller

Module providing Distiller class.

This module provides the Distiller class which implements the FEAST algorithm to diagonalize a hermitean, sparse matrix in a user-specified energy window. The FEAST algorithm is based on a rational filter to project trial eigenstates into the subspace spanned by the eigenstates lying in the user-specified energy window. The matrix can then be diagonalized in this subspace using a eigensolver for dense matrices. This implies that the energy window should be chosen small enough to allow for an efficient use of the dense eigensolver. The rational filter is approximated using a Chebyshev expansion of the resolvent matrix, which renders the implementation memory efficient.

NOTE: Refactored from original LegacyDistiller class.

Copyright © 2024-2025 HQS Quantum Simulations GmbH. All Rights Reserved.

class Distiller:

Class representing solver for partial spectral decompositions.

A solver object can be instantiated using a generator for a linear operator, i.e., a

Callable[[xp.ndarray, float, float, int], Callable[[xp.ndarray, xp.ndarray], xp.ndarray]]

The first arguments must be a numpy/cupy array on which the linear operator can be applied ("user must know how to allocate a state"). The two floats provided as input for the generator, determine a uniform shift and scale of the operator. This can be used to ensure that the spectrum of the operator falls in to the intervall (-1, 1), as required for a stable Chebyshev recursion. The last argument allows to specify the batch size of the state arrays.

A Distiller calculation using the Chebyshev expansion depends at the number of trial states and the number of Chebyshev moments used in the projection. The function 'get_number_of_chebyshev_moments' implements the default setter. It uses the spectral interval for the projection together with the total spectral width of the Hamiltonian and the (estimated) number of states in the spectral interval to determine the number of Chebyshev moments via the formula:

n_chebyshev_moments = C * n_states * spectral_width / spectral_window

NOTE: The constant C is hard-coded to 1/2 at the moment.

The number of trial states is determined by:

n_trial_states = A * n_states

NOTE: The constant A is hard-coded to 1.5 at the moment.

The user can manually specify the number of Chebyshev moments.

Distiller( gen_lin_op: Callable[[numpy.ndarray, float, float, int], Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray]], state_shape: tuple[int, int], spectral_bounds: tuple[float, float], spectral_buffer: float = 0.05, batch_size: int = 1, max_n_chebyshev_moments: int = 65536, dtype: numpy.dtype = <class 'numpy.complex64'>, verbose: bool = True)

Initialize Distiller.

After initialization this object provides methods to extract eigenvalue, eigenvector pairs falling into a user-specified energy window.

NOTE: Only for hermitian matrices (real and complex). Not checked in initialization!!!

Arguments:
  • gen_lin_op (OperatorGenerator): Generator for Hermitean linear operator.
  • state_shape: (tuple[int, int]): Tuple defining the shape of the state on which the linear operator acts.
  • spectral_bounds (tuple[float, float]): Spectral bounds of the linear operator.
  • spectral_buffer (float): relative buffer for spectral window. Must be in (0, 0.9). Defaults to 0.05.
  • batch_size (int): Number of states in batch. Defaults to 1.
  • max_n_chebyshev_moments (int): (Maximal) number of Chebyshev moments used. Defaults to 8192.
  • dtype (xp.dtype): Data type for the returned overlap matrix. Defaults to single precision complex data type.
  • verbose (bool): General flag triggering outputs. Defaults to True.
def get_spectral_decomposition( self, window: tuple[float, float], max_iter: int = 10, eps: float = 1e-06, n_states_limit: int = 64, n_chebyshev_moments: Optional[int] = None, initial_states: Optional[list[hqs_distiller.state_io.State]] = None, skip_subspace_init: bool = False, verbose: Optional[bool] = None) -> tuple[numpy.ndarray, numpy.ndarray, list[hqs_distiller.state_io.State]]:

Get partial spectral decomposition using a chebyshev expansion.

NOTE: This method assumes hermiticity of Hamiltonian.

NOTE: The trial states proposed by the user are augmented with randomly generated trial states to span the subspace to the sub-space dimension auto-detected by the algorithm for the given spectral window. The trial states provided by the user are only used if there energy is within the spectral window.

Arguments:
  • window (tuple[float, float]): Energy window for spectral decomposition.
  • eps (float): Convergence criterion for solver. Defaults to 1.e-6.
  • max_iter (int): Maximum number of iterations for solver. Defaults to 10.
  • n_states_limit (int): Maximum allowed number of states in spectral window. Defaults to 64.
  • n_chebyshev_moments (Optional[int]): Number of Chebyshev moments used for projector. Defaults to None, which determines the number based on provided spectral window.
  • initial_states (Optional[list[State]): List of states spanning initial sub-space. Defaults to None.
  • skip_subspace_init (bool): Flag triggering skipping of subspace initialization. Defaults to False.
  • verbose (Optional[bool]): Flag triggering output. Defaults to None, which implies that the verbose flag provided during initialization is used.
Returns:

tuple[np.ndarray, np.ndarray, list[State]]: Tuple of boolean array indicating convergence for each state in spectral window, float array containing eigenvalues within spectral window. list of States within spectral window.