DIIS (‘‘direct inversion of iterative subspace’’) extrapolation. More...

#include <diis.h>

Public Types
typedef D::element_type	value_type

typedef detail::scalar_t< value_type >	scalar_type

typedef Eigen::Matrix< value_type, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor >	EigenMatrixX

typedef Eigen::Matrix< value_type, Eigen::Dynamic, 1 >	EigenVectorX

Public Member Functions
	DIIS (unsigned int strt=1, unsigned int ndi=5, scalar_type dmp=0, unsigned int ngr=1, unsigned int ngrdiis=1, scalar_type mf=0)
	Constructor. More...

	~DIIS ()

void	extrapolate (D &x, D &error, bool extrapolate_error=false)

void	extrapolate (D &x, const EigenVectorX &c, unsigned int nskip=0, bool increase_iter=false)

void	compute_extrapolation_parameters (const D &error, bool increase_iter=false)

void	start_extrapolation ()

void	reinitialize (const D *data=0)

const EigenVectorX &	get_coeffs ()
	calling this function returns extrapolation coefficients More...

unsigned int	get_nskip ()
	calling this function returns number of skipped vectors in extrapolation More...

bool	parameters_computed ()
	calling this function returns whether diis parameters C_ and nskip_ have been computed More...

Detailed Description

template<typename D>
class TiledArray::DIIS< D >

DIIS (‘‘direct inversion of iterative subspace’’) extrapolation.

The DIIS class provides DIIS extrapolation to an iterative solver of (systems of) linear or nonlinear equations of the $ f(x) = 0 $ form, where $ f(x) $ is a (non-linear) function of $ x $ (in general, $ x $ is a set of numeric values). Such equations are usually solved iteratively as follows:

given a current guess at the solution, , evaluate the error (`‘residual’') (NOTE that the dimension of and do not need to coincide);
use the error to compute an updated guess $x_{i+1} = x_i + g(e_i)$ ;
proceed until a norm of the error is less than the target precision $\epsilon$ . Another convergence criterion may include $||x_{i+1} - x_i|| < \epsilon$ .

For example, in the Hartree-Fock method in the density form, one could choose $x \equiv \mathbf{P}$ , the one-electron density matrix, and $f(\mathbf{P}) \equiv [\mathbf{F}, \mathbf{P}]$ , where $\mathbf{F} = \mathbf{F}(\mathbf{P})$ is the Fock matrix, a linear function of the density. Because $\mathbf{F}$ is a linear function of the density and DIIS uses a linear extrapolation, it is possible to just extrapolate the Fock matrix itself, i.e. $x \equiv \mathbf{F}$ and $f(\mathbf{F}) \equiv [\mathbf{F}, \mathbf{P}]$ .

Similarly, in the Hartree-Fock method in the molecular orbital representation, DIIS is used to extrapolate the Fock matrix, i.e. $x \equiv \mathbf{F}$ and $f(\mathbf{F}) \equiv \{ F_i^a \}$ , where $ i $ and $ a $ are the occupied and unoccupied orbitals, respectively.

Here's a short description of the DIIS method. Given a set of solution guess vectors $\{ x_k \}, k=0..i$ and the corresponding error vectors $\{ e_k \}$ DIIS tries to find a linear combination of $ x $ that would minimize the error by solving a simple linear system set up from the set of errors. The solution is a vector of coefficients $\{ C_k \}$ that can be used to obtain an improved $ x $ : $x_{\mathrm{extrap},i+1} = \sum\limits_{k=0}^i C_{k,i} x_{k}$ A more complicated version of DIIS introduces mixing: $x_{\mathrm{extrap},i+1} = \sum\limits_{k=0}^i C_{k,i} ( (1-f) x_{k} + f x_{extrap,k} )$ Note that the mixing is not used in the first iteration.

The original DIIS reference: P. Pulay, Chem. Phys. Lett. 73, 393 (1980).

Template Parameters

D	type of `x`

Definition at line 81 of file diis.h.

Member Typedef Documentation

◆ EigenMatrixX

template<typename D>

typedef Eigen::Matrix<value_type, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor> TiledArray::DIIS< D >::EigenMatrixX

Definition at line 85 of file diis.h.

◆ EigenVectorX

template<typename D>

typedef Eigen::Matrix<value_type, Eigen::Dynamic, 1> TiledArray::DIIS< D >::EigenVectorX

Definition at line 86 of file diis.h.

◆ scalar_type

template<typename D>

typedef detail::scalar_t<value_type> TiledArray::DIIS< D >::scalar_type

Definition at line 84 of file diis.h.

◆ value_type

template<typename D>

typedef D::element_type TiledArray::DIIS< D >::value_type

Definition at line 83 of file diis.h.

Constructor & Destructor Documentation

◆ DIIS()

template<typename D>

TiledArray::DIIS< D >::DIIS	(	unsigned int	strt = `1`,
		unsigned int	ndi = `5`,
		scalar_type	dmp = `0`,
		unsigned int	ngr = `1`,
		unsigned int	ngrdiis = `1`,
		scalar_type	mf = `0`
	)

inline

Constructor.

Parameters

strt	The DIIS extrapolation will begin on the iteration given by this integer (default = 1).
ndi	This integer maximum number of data sets to retain (default = 5).
dmp	This nonnegative floating point number is used to dampen the DIIS extrapolation (default = 0.0).
ngr	The number of iterations in a DIIS group. DIIS extrapolation is only used for the first `ngrdiis` of these iterations (default = 1). If `ngr` is 1 and `ngrdiis` is greater than 0, then DIIS will be used on all iterations after and including the start iteration.
ngrdiis	The number of DIIS extrapolations to do at the beginning of an iteration group. See the documentation for `ngr` (default = 1).
mf	This real number in [0,1] is used to dampen the DIIS extrapolation by mixing the input data with the output data for each iteration (default = 0.0, which performs no mixing). The approach described in Kerker, Phys. Rev. B, 23, p3082, 1981.

Definition at line 108 of file diis.h.

◆ ~DIIS()

template<typename D>

TiledArray::DIIS< D >::~DIIS ( )

inline

Definition at line 123 of file diis.h.

Member Function Documentation

◆ compute_extrapolation_parameters()

template<typename D>

void TiledArray::DIIS< D >::compute_extrapolation_parameters	(	const D &	error,
		bool	increase_iter = `false`
	)

inline

calling this function computes extrapolation parameters, i.e. coefficients C_ and number of skipped vectors nskip_

Parameters

error	the most recent error
increase_iter	whether to increase the diis iteration index (default = false)

Definition at line 225 of file diis.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ extrapolate() [1/2]

template<typename D>

void TiledArray::DIIS< D >::extrapolate	(	D &	x,
		D &	error,
		bool	extrapolate_error = `false`
	)

inline

Parameters

[in,out]	x	On input, the most recent solution guess; on output, the extrapolated guess
[in,out]	error	On input, the most recent error; on output, the if `extrapolate_error` `==` `true` will be the extrapolated error, otherwise the value unchanged
	extrapolate_error	whether to extrapolate the error (default = false).

Definition at line 136 of file diis.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ extrapolate() [2/2]

template<typename D>

void TiledArray::DIIS< D >::extrapolate	(	D &	x,
		const EigenVectorX &	c,
		unsigned int	nskip = `0`,
		bool	increase_iter = `false`
	)

inline

calling this function performs the extrapolation with provided coefficients.

Parameters

[in,out]	x	On input, the most recent solution guess; on output, the extrapolated guess
	c	provided coefficients
	nskip	number of old vectors to skip (default = 0)
	increase_iter	whether to increase the diis iteration index (default = false)

Definition at line 170 of file diis.h.

Here is the call graph for this function:

◆ get_coeffs()

template<typename D>

const EigenVectorX& TiledArray::DIIS< D >::get_coeffs ( )

inline

calling this function returns extrapolation coefficients

Definition at line 331 of file diis.h.

◆ get_nskip()

template<typename D>

unsigned int TiledArray::DIIS< D >::get_nskip ( )

inline

calling this function returns number of skipped vectors in extrapolation

Definition at line 338 of file diis.h.

◆ parameters_computed()

template<typename D>

bool TiledArray::DIIS< D >::parameters_computed ( )

inline

calling this function returns whether diis parameters C_ and nskip_ have been computed

Definition at line 341 of file diis.h.

◆ reinitialize()

template<typename D>

void TiledArray::DIIS< D >::reinitialize ( const D * data = 0 )

inline

Definition at line 322 of file diis.h.

Here is the call graph for this function:

◆ start_extrapolation()

template<typename D>

void TiledArray::DIIS< D >::start_extrapolation ( )

inline

calling this function forces the extrapolation to start upon next call to extrapolate() even if this object was initialized with start value greater than the current iteration index.

Definition at line 318 of file diis.h.

The documentation for this class was generated from the following file:

TiledArray/algebra/diis.h

Public Types

Public Member Functions

Detailed Description

template<typename D> class TiledArray::DIIS< D >

Member Typedef Documentation

◆ EigenMatrixX

◆ EigenVectorX

◆ scalar_type

◆ value_type

Constructor & Destructor Documentation

◆ DIIS()

◆ ~DIIS()

Member Function Documentation

◆ compute_extrapolation_parameters()

◆ extrapolate() [1/2]

◆ extrapolate() [2/2]

◆ get_coeffs()

◆ get_nskip()

◆ parameters_computed()

◆ reinitialize()

◆ start_extrapolation()

template<typename D>
class TiledArray::DIIS< D >