nanotools.eig module

This module defines the Eig class.

class nanotools.eig.Eig(abstol=-1.0, algo='x', elpa_solver='ELPA_SOLVER_2STAGE', elpa_complex_kernel='ELPA_2STAGE_COMPLEX_DEFAULT', elpa_real_kernel='ELPA_2STAGE_REAL_DEFAULT', inclband: List[int] | None = None, lwork=-1, orfac=1e-06, reduAlgo=2, target_irange: List[int] | None = None)

Bases: Base

Eig class.

abstol

The absolute error tolerance for the eigenvalues.

Type:

float

algo

Determine the algorithm used to diagonalize the Kohn-Sham Hamiltonian, or its projection. For projected (dense) eigenvalue problems:

• “d”: calls the divide-and-conquer algorithm of ScaLAPACK.

• “elpa”: calls the ELPA library.

• “mrrr”: calls the MRRR routines of ScaLAPACK.

• “x”: calls the _expert_ driver of ScaLAPACK.

In our experience “x” is both fast and robust. “elpa” is the fastest, especially when solving large systems (i.e. > 1000 orbitals) and when using a lot of processes (i.e. > 100). However, “elpa” requires that mpidist.orbblk * mpidist.orbprc < n, where n is the number of orbitals.

Examples:

eig.algo = "elpa"

Type:

string

elpa_solver

Sets the ELPA library solver. Allowed values are:

• ELPA_SOLVER_1STAGE

• ELPA_SOLVER_2STAGE

Type:

string

elpa_complex_kernel

Sets the ELPA solver complex kernel. For all allowed values, see ELPA documentation. Some allowed values are:

• ELPA_2STAGE_COMPLEX_GENERIC

• ELPA_2STAGE_COMPLEX_SSE_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX2_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX512_BLOCK1

• ELPA_2STAGE_COMPLEX_DEFAULT

Type:

string

elpa_real_kernel

Sets the ELPA solver real kernel. For all allowed values, see ELPA documentation. Some allowed values are:

• ELPA_2STAGE_REAL_GENERIC

• ELPA_2STAGE_REAL_SSE_BLOCK2

• ELPA_2STAGE_REAL_AVX_BLOCK2

• ELPA_2STAGE_REAL_AVX2_BLOCK2

• ELPA_2STAGE_REAL_AVX512_BLOCK2

• ELPA_2STAGE_REAL_DEFAULT

Type:

string

inclband

Index range of the energy bands included in the calculation. If eig.inclband = [il,iu], the eigensolver will seek the eigenvalues and/or eigenvectors with an index between il and iu. il <= iu is required; not all eigenpairs need to converge (see target_irange).

Examples:

eig.inclband = [430,470]

Type:

1D array

lwork

Size of the work array in ScaLAPACK. If lwork is -1, then ScaLAPACK estimates the optimal work array size. If lwork is too small ScaLAPACK will compromise on precision or crash. Don’t worry, it will throw at least a warning. If that happends, just increase the value of lwork by a factor 2 until the message disappear.

Examples:

eig.lwork = 2000000

Type:

integer

orfac

Specifies which eigenvectors should be reorthogonalized. Eigenvectors that correspond to eigenvalues which are within tol=orfac*norm(A) of each other are to be reorthogonalized. However, if the workspace is insufficient (see lwork), tolerance may be decreased until all eigenvectors to be reorthogonalized can be stored in one process. No reorthogonalization will be done if orfac equals zero. A default value of 1e-3 is used if orfac is negative. orfac should be identical on all processes.

Examples:

eig.orfac = 1e-8

Type:

float

reduAlgo

Switch between triangular inverse (1) and ScaLAPACK’s sygst (2) to reduce the

eigenvalue problem from general to standard form. If algo=elpa then reduAlgo=3 uses ELPA’s Cannon algorithm if the number of process rows divides the number of process columns (see mpidist.orbprc). This parameter impacts performance.

Examples:

eig.reduAlgo = 2

Type:

integer

target_irange

Index range of the energy bands that are forced to converge according to the tolerance given by abstol.

Examples:

eig.target_irange = [440,460]

Type:

1D array

get_number_of_bands()

Returns the number of bands.

The total number of bands usually include some bands that act as a buffer and hence they are not necessarily accurate. For bands satifying the prescribed tolerance, refer to target_irange.

set_abstol(abstol)

Sets the parameter abstol.

The absolute error tolerance for the eigenvalues.

set_algo(algo)

Sets the parameter algo.

Determine the algorithm used to diagonalize the Kohn-Sham Hamiltonian, or its projection. For projected (dense) eigenvalue problems:

• “d”: calls the divide-and-conquer algorithm of ScaLAPACK.

• “elpa”: calls the ELPA library.

• “mrrr”: calls the MRRR routines of ScaLAPACK.

• “x”: calls the _expert_ driver of ScaLAPACK.

In our experience “x” is both fast and robust. “elpa” is the fastest, especially when solving large systems (i.e. > 1000 orbitals) and when using a lot of processes (i.e. > 100). However, “elpa” requires that mpidist.orbblk * mpidist.orbprc < n, where n is the number of orbitals.

set_elpa_complex_kernel(elpa_complex_kernel)

Sets the parameter elpa_complex_kernel.

For all allowed values, see ELPA documentation. Some allowed values are:

• ELPA_2STAGE_COMPLEX_GENERIC

• ELPA_2STAGE_COMPLEX_SSE_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX2_BLOCK1

• ELPA_2STAGE_COMPLEX_AVX512_BLOCK1

• ELPA_2STAGE_COMPLEX_DEFAULT

set_elpa_real_kernel(elpa_real_kernel)

Sets the parameter elpa_real_kernel.

For all allowed values, see ELPA documentation. Some allowed values are:

• ELPA_2STAGE_REAL_GENERIC

• ELPA_2STAGE_REAL_SSE_BLOCK2

• ELPA_2STAGE_REAL_AVX_BLOCK2

• ELPA_2STAGE_REAL_AVX2_BLOCK2

• ELPA_2STAGE_REAL_AVX512_BLOCK2

• ELPA_2STAGE_REAL_DEFAULT

set_elpa_solver(elpa_solver)

Sets the parameter elpa_solver.

Allowed values are:

• ELPA_SOLVER_1STAGE

• ELPA_SOLVER_2STAGE

set_lwork(lwork)

Sets the parameter lwork.

Size of the work array in ScaLAPACK. If lwork is -1, then ScaLAPACK estimates the optimal work array size. If lwork is too small ScaLAPACK will compromise on precision or crash. Don’t worry, it will throw at least a warning. If that happends, just increase the value of lwork by a factor 2 until the message disappear.

set_orfac(orfac)

Sets the parameter orfac.

Specifies which eigenvectors should be reorthogonalized. Eigenvectors that correspond to eigenvalues which are within tol=orfac*norm(A) of each other are to be reorthogonalized. However, if the workspace is insufficient (see lwork), tolerance may be decreased until all eigenvectors to be reorthogonalized can be stored in one process. No reorthogonalization will be done if orfac equals zero. A default value of 1e-3 is used if orfac is negative. orfac should be identical on all processes.

set_reduAlgo(reduAlgo)

Sets the parameter reduAlgo.

Switch between triangular inverse (1) and ScaLAPACK’s sygst (2) to reduce the eigenvalue problem from general to standard form. If algo=elpa then reduAlgo=3 uses ELPA’s Cannon algorithm if the number of process rows divides the number of process columns (see mpidist.orbprc). This parameter impacts performance.

set_target_irange(ispin=1, target_irange=None, valence_charge=None, n_orb=None)

Sets the included and target bands.

If target_irange is not provided, the valence charge is used to determine the number of bands.