Configuration

template<class T>
class chase::ChaseConfig

A class to set up all the parameters of the eigensolver.

Besides setting up the standard parameters such as size of the matrix N_ defining the eigenproblem, number of wanted eigenvalues nev_, the public functions of this class initialize all internal parameters and allow the experienced user to set up the values of parameters of core functionalities (e.g. lanczos DoS). The aim is to influence the behavior of the library in special cases when the default values of the parameters return a suboptimal efficiency in terms of performance and/or accuracy.

Public Functions

ChaseConfig(std::size_t _N, std::size_t _nev, std::size_t _nex)

Constructor for the ChaseConfig class.

Requires the explicit values for the initalization of the size N_ of the matrix A, the number of sought after extremal eigenvalues nev_, and the number of extra eigenvalue nex_ which defines, together with nev_, the search space. All the other private members of the class are initialized using default values either specified directly (e.g. max_iter_) or specified using a function that is part of the ChaseConfig namespace (e.g. initMaxDeg).

Parameters

• _N: Size of the square matrix defining the eigenproblem.

• _nev: Number of desired extremal eigenvalues.

• _nex: Number of eigenvalues augmenting the search space. Usually a relatively small fraction of nev.

bool UseApprox() const

Returns the value of the approx_ flag.

The value of the approx_ flag indicates if ChASE has been used with the engagement of approximate solutions as it is typical when solving for sequences of eigenvalue problems occurring in Density Functional Theory.

Return

The value of the approx_ flag.

void SetApprox(bool flag)

Sets the approx_ flag to either true or false.

This function is used to change the value of approx_ so that the eigensolver can use approximate solutions inputed through a matrix of initial vectors.

Parameters

• flag: A boolean parameter which admits either a true or false value.

bool DoOptimization() const

Returns the value of the optimization_ flag.

The value of the optimization_ flag indicates when ChASE computes a polynomial degree optimized for each single desired eigenpairs. The optimization minimizes the number of operations required for the eigenpairs to have a residual which is just below the specified tolerance threshold.

Return

The value of the optimization_ flag

void SetOpt(bool flag)

Sets the optimization_ flag to either true or false.

This function is used to change the value of optimization_ so that the eigensolver minimizes the number of FLOPs needed to reach convergence for the entire sought after subspace of the spectrum.

Parameters

• flag: A boolean parameter which admits either a true or false value.

std::size_t GetDeg() const

Returns the degree of the Chebyshev filter used by ChASE.

The value returned is the degree used by the filter when it is called (when optimization_ == 'true' this value is used only the first time the filter is called)

Return

The value used by the Chebyshev filter

void SetDeg(std::size_t _deg)

Set the value of the initial degree of the Chebyshev filter.

Depending if the optimization_ parameter is set to false or true, the value of _deg is used by the Chebyshev filter respectively every time or just the first time it is called.

Parameters

• _deg: Value set by the expert user and should in general be between 10 and 25. The default value is 20. If a odd value is inserted, the function makes it even. This is necessary due to the swapping of the matrix of vectors within the filter. It is strongly suggested to avoid values above the higher between 40 and the value returned by GetMaxDeg().

double GetTol() const

Returns the threshold value of the eigenpair’s residual tolerance.

The value of the tolerance is used as threshold for all the residuals of the desired eigenpaits. Whenever an eigenpair’s residual decreases below such a value it is declared as converged, and is consequently deflated and locked. For an eigenpair \((\lambda_i,V_i)\), the residual in ChASE is defined as the Euclidean norm: \(||AV_i-\lambda_iV_i||_2\).

Return

The value of the tol_ parameter.

void SetTol(double _tol)

Sets the value of the threshold of the eigenpair’s residual tolerance.

The value of the tolerance should be set carefully keeping in mind that the residual of the eigenpairs is limited by the accuracy of the dense eigensolver used within the Rayleigh-Ritz procedure. As such it should hardly be set below \(1e-14\) in double precision. As a rule of thumb a minimum value of 1e-04 and 1e-08 should be used respectively in single and double precision.

Parameters

• _tol: A type double number usually specified in scientific notation (e.g. 1e-10).

std::size_t GetMaxDeg() const

Returns the integer value of the maximum degree used by the polynomial filter.

The value of max_deg_ indicates the upper bound for the degree of the polynomial for any of the vectors filtered. Such bound is important to avoid potential numerical instabilities that may occur and impede the convergence of the eigenpairs, expecially the one close to the upper end of the desired subspace of the spectrum.

Return

The value of the maximum degree of the Chebyshev filter.

void SetMaxDeg(std::size_t _maxDeg)

Sets the maximum value of the degree of the Chebyshev filter.

When optimization_ == 'true', the Chebyshev filter degree is computed automatically. Because the computed values could be quite large for eigenvectors at the end of the sought after spectrum, a maximum value is set to avoid numerical instabilities that may trigger eigenpairs divergence.

Parameters

• _maxDeg: This value should be set by the expert user. It is set to 36 by default. It can be lowered in case of the onset of early instabilities but it should not be lower than 20-25 to avoid the filter becomes ineffective. It can be increased whenever it is known there is a spectral gap between the value of nev_ and the value of nev_ + nex_. It is strongly suggested to never exceed the value of 70.

std::size_t GetDegExtra() const

Returns the extra degree added to the polynomial filter.

When optimization_ == 'true', each vector is filtered with a polynomial of a given calculated degree. Because the degree is predicted based on an heuristic fomula, such degree is augmented by a small value to ensure that the residual of the corresponding vector will be almost always lower than the required threshold tolerance.

Return

The extra value added to a computed vector of polynomial degrees.

void SetDegExtra(std::size_t degExtra)

Sets the value of the extra degree added to the polynomial filter.

The value of degExtra should be a single digit number usually not exceeding 5 or 6. The expert user can modify the default value (which is 2) in those cases where the heuristic to automatically compute the vector of optimal degrees seems to underestimate the value of the degree necessary for the eigenpairs to be declared converged.

Parameters

• degExtra: Value of the extra degree.

std::size_t GetMaxIter() const

Returns the value of the maximum number of subspace iterations allowed within ChASE.

In order to avoid that the eigensolver would runoff unchecked, ChASE is given a upper bound on the number of subspace iteration it can execute. This is a normal safety mechanism when the algorithm fails to converge some eigenpairs whose residuals would continue to oscillate without above the tolerance threshold.

Return

The value of the maximum number of subspace iterations allowed.

void SetMaxIter(std::size_t maxIter)

Sets the value of the maximum number of subspace iterations within ChASE.

Typically ChASE requires a number of single digit iterations to converge. In extreme cases such number can grow up to 10 or 12. An increasing number of iterations usually implies that the eigensolver is not used for the intended purpose or that the spectrum of eigenproblem tackled is particularly problematic. The default value of maxIter is set to 25.

Parameters

• maxIter: Value of the maximum number of subspace iterations.

std::size_t GetLanczosIter() const

Returns the number of Lanczos iterations executed by ChASE.

In order to estimate the spectral bounds, ChASE executes a limited number of Lanczos steps. These steps are then used to compute a spectral estimate based on the Density of State (DoS) algorithm.

Return

The total number of the Lanczos iterations used by the DoS algorithm.

void SetLanczosIter(std::size_t lanczosIter)

Sets the number of Lanczos iterations executed by ChASE.

For the DoS algorithm to work effectively without overburdening the eigensolver, the number of Lanczos iteration should be not less than 10 but also no more than 100 . ChASE does not need very precise spectral estimates because at each iteration such estimates are automatically improved by the approximate spectrum computed. This is the reason why the default value of lanczos_iter_ is 25.

Parameters

• lanczosIter: Value of the total number of Lanczos iterations executed by ChASE.

std::size_t GetNumLanczos() const

Returns the number of stochastic vectors used for the spectral estimates.

After having executed a number of Lanczos steps, ChASE uses a cheap and efficient estimator to calculate the value of the upper extremum of the search space. Such an estimator uses a small number of stochastic vectors.

Return

Number of stochastic vectors used by ChASE for the spectral estimate.

void SetNumLanczos(std::size_t lanczosIter)

Sets the number of stochastic vectors used for the spectral estimates.

The stochastic estimator used by ChASE is based on a cheap and efficient DoS algorithm. Because ChASE does not need precise estimates of the upper extremum of the search space, the number of vectors used is quite small. The default value used is 4. The expert user can change the value to a larger number (it is not suggested to use a smaller value) and pay a slightly higher computing cost. It is not suggested to exceed a value for num_lanczos_ higher than 20.

Parameters

• lanczosIter: Number of stochastic vectors used by ChASE.

std::size_t GetN() const

Returns the size of the eigenproblem.

This function returns the size of the matrix defining the standard or the generalized eigenvalue problem.

Return

Rank of the matrix.

std::size_t GetNev() const

Returns the number of desired eigenpairs.

The number of sought after eigenpairs as also specified in the constructor ChASEConfig.

Return

Number of desired eigenpairs.

std::size_t GetNex() const

Returns the number of extra eigenpairs that are used to augment the search subspace.

ChASE effectively uses an enlarged subspace to improve the convergence of the algorithm. With a very small value of nex_, the eigenpairs at the end of the desired interval may have hard time to converge. By including a small but substantial number of extra values (in most case no more than 20% of nev_), ensures that ChASE converges smoothly without stagnating.

Return

Number of extra eigenpairs augmenting the search space.

Private Members

std::size_t const N_

Rank of the matrix A defining the eigenproblem.

This variable is initialized by the constructor using the value of the first of its input parameters _N. There is no default value.

std::size_t const nev_

Number of desired extremal eigenpairs.

This variable is initialized by the constructor using the value of the second of its input parameters _nev. There is no default value.

std::size_t const nex_

Increment of the search subspace so that its total size is _nev + _nex.

This variable is initialized by the constructor using the value of the third of its input parameters _nex. There is no default value.

bool approx_

An optional flag indicating if approximate eigenvectors are provided by the user.

This variable is initialized by the constructor. Its default value is set to false.

std::size_t max_iter_

An optional parameters limiting the total number of internal while loops ChASE executes.

This variable is initialized by the constructor. Its default value is 25*

double tol_

An optional parameters indicating the minimal value of the threshold below which the desired eigenpairs are declared converged.

This variable is initialized by the constructor. Its default value is set to 1e-10 and 1e-05 respectively in double and single precision.

std::size_t deg_

An optional parameter indicating the degree of the polynomial filter.

When the flag optimization_ is set to true, its value is used only the first first time the filter routine is called. Otherwise this value is used for each vector and all subsequent subspace iterations. This variable is initialized by the constructor. Its default value is set to 20 and 10 in double and single precision, respectively.

bool optimization_

An optional flag indicating if the filter uses a polynomial degree optimized for each single vector.

This variable is initialized by the constructor. Its default value is set to true.

std::size_t max_deg_

An optional parameter that limits from above the value of the allowed polynomial filter.

When the flag optimization_ is set to true, it avoids that a vector is filtered with a too high of a degree which may introduce numerical instabilities and slow or even impede convergence. This variable is initialized by the constructor. Its default value is set to 36 and 18 in double and single precision, respectively.

std::size_t deg_extra_

An optional parameter augmenting of few units the polynomial degree automatic computed by ChASE.

This parameter is exclusively used when the flag optimization_ is set to true and should never be larger than a single digit. This variable is initialized by the constructor. Its default value is set to 2.

std::size_t lanczos_iter_

Optional parameter indicating the total number of steps executed by the Lanczos DoS.

This variable is initialized by the constructor. Its default value is set to 25.

std::size_t num_lanczos_

Optional parameter indicating the total number of vectors used for the vector estimate in the Lanczos DoS.

This variable is initialized by the constructor. Its default value is set to 4.