hqs_distiller.analyzer

Helpers to analyze spectral window.

This module defines the functions to split the spectral window, on which the HQS Distiller spectral projections algorithm is executed, if too many states are detected in the spectral window. It is currently based on a simple integration of the density of states (DOS).

To do:

  • rewrite doc-string
  • clean up "legacy" functions

@private

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

def analyze_window( cmg: hqs_distiller.chebyshev.ChebyshevIterator, window: tuple[float, float], chebyshev_window: tuple[float, float], n_chebyshev: int, n_states_limit: int, n_initial: int = 8, verbose: bool = False) -> tuple[numpy.ndarray, numpy.ndarray, list[tuple[float, float]], int]:

Calculates and analyses DOS to determine if and how to split the window.

Arguments:
  • cmg (ChebyshevIterator): Generator for Chebyshev moments.
  • window (tuple[float, float]): Energy window for spectral decomposition.
  • chebyshev_window (tuple[float, float]): Energy window scaled into Chebyshev interval.
  • n_chebyshev (int): Number of moments for Chebyshev expansion.
  • n_states_limit (int): Maximal number of states within window.
  • n_initial (int): Number of random states used to compute DOS. Defaults to 8.
  • verbose (bool): Trigger output. Specifically this function also produces an svg file 'window_splitting.svg' showing the detected windows. Defaults to False.
Returns:

tuple[np.ndarray, list[tuple[float, float], int]: tuple of array containing initial guesses for states in energy interval, array containing Chebyshev moments for random states, list of tuples defining the sub-intervals of the energy window, integer estimate for number of states in each sub-interval.

def setup_subspace( cmg: hqs_distiller.chebyshev.ChebyshevIteratorOperator, window: tuple[float, float], chebyshev_window: tuple[float, float], n_chebyshev: int, n_states_limit: int, initial_subspace: list[hqs_distiller.state_io.State], dtype: numpy.dtype, svd_cutoff: float = 1e-06, verbose: bool = False) -> tuple[list[hqs_distiller.state_io.StateBatch], tuple[float, float], int]:

Calculates and analyses DOS to determine if and how to split the window.

Arguments:
  • cmg (ChebyshevIteratorOperator): Generator for Chebyshev moments.
  • window (tuple[float, float]): Energy window for spectral decomposition.
  • chebyshev_window (tuple[float, float]): Energy window scaled into Chebyshev interval.
  • n_chebyshev (int): Number of moments for initial Chebyshev expansion.
  • n_states_limit (int): Maximal number of states within window.
  • initial_subspace (list[State]): Initial subspace.
  • dtype (xp.dtype): Data type for computations.
  • svd_cutoff (float): Relative cutoff for singular values. Defaults to SVD_CUTOFF.
  • verbose (bool): Trigger output. Specifically this function also produces an svg file 'window_splitting.svg' showing the detected windows. Defaults to False.
  • use_gpu (bool): Use GPU implementation if possible. Defaults to False.
Returns:

tuple[list[StateBatch], tuple[float, float], int]: tuple of list containing initial guesses for batched states in energy interval, tuple defining the energy window, integer defining number of moments used for final Chebyshev expansion.