Template for Anderson mixing iterator algorithm. More...

#include <AmIteratorTmpl.h>

Inheritance diagram for Pscf::AmIteratorTmpl< Iterator, T >:

Public Member Functions
	AmIteratorTmpl ()
	Constructor.
	~AmIteratorTmpl ()
	Destructor.
virtual void	readParameters (std::istream &in)
	Read all parameters and initialize.
int	solve (bool isContinuation=false)
	Iterate to a solution.
void	outputTimers (std::ostream &out) const
	Log output timing results.
void	clearTimers ()
	Clear timers.

Protected Member Functions
void	readErrorType (std::istream &in)
	Read and validate the optional errorType string parameter.
virtual bool	isValidErrorType ()
	Checks if a string is a valid error type.
void	readMixingParameters (std::istream &in, bool useLambdaRamp=true)
	Read optional parameters used in default correction algorithm.
void	allocateAM ()
	Allocate memory required by AM algorithm, if necessary.
bool	isAllocatedAM () const
	Have data structures required by the AM algorithm been allocated?
virtual void	setup (bool isContinuation)
	Initialize just before entry to iterative loop.
virtual void	clear ()
	Clear information about history.
virtual double	computeError (T &residTrial, T &stateTrial, std::string errorType, int verbose)
	Compute and return error used to test for convergence.
double	computeError (int verbose)
	Compute and return error used to test for convergence.
double	lambdaRampFactor ()
	Compute ramped prefactor of mixing parameter lambda.
virtual double	computeLambda ()
	Compute mixing parameter for correction step of Anderson mixing.
int	verbose () const
	Verbosity level, allowed values 0, 1, or 2.
std::string	errorType () const
	Get error type string.
T const &	residual () const
	Get the current residual vector by const reference.
T const &	state () const
	Return the current state vector by const reference.
int	totalItr ()
	Return the total number of iterations needed to converge.
double	timerTotal ()
	Get total time.
double	timerMDE ()
	Get time spent solving the modified diffusion equation (MDE).
double	timerAM ()
	Get total time for AM algorithm, excluding MDE solution.
double	timerResid ()
	Get time spent computing residual.
double	timerError ()
	Get time evaluating scalar error.
double	timerCoeff ()
	Get time spent evaluating Anderson mixing coefficients.
double	timerOmega ()
	Get time spent updating w states.
template<typename Type>
ScalarParam< Type > &	read (std::istream &in, const char *label, Type &value)
	Add and read a new required ScalarParam < Type > object.
template<typename Type>
ScalarParam< Type > &	readOptional (std::istream &in, const char *label, Type &value)
	Add and read a new optional ScalarParam < Type > object.

Protected Attributes
double	epsilon_
	Error tolerance.
int	maxItr_
	Maximum number of iterations to attempt.
int	maxHist_
	Maximum number of basis vectors in AM algorithm.
int	verbose_
	Verbosity level.
std::string	errorType_
	Type of error criterion used to test convergence.

Detailed Description

template<typename Iterator, typename T>
class Pscf::AmIteratorTmpl< Iterator, T >

Template for Anderson mixing iterator algorithm.

Anderson mixing is an algorithm for solving a system of N nonlinear equations of the form R{i}(X) = 0 for i = 0, ..., N-1, where X denotes a vector or array of N unknown coordinate values. A vector of array of unknowns is referred here as the state vector, while a vector or array of values of the errors R{0} ,..., R{N-1} is referred to as the residual vector.

The template type parameter Iterator is a base class that must be derived from Util::ParamComposite. In applications to SCFT iterators, the Iterator class may declare a virtual solve function that is overridden by the solve() function defined by this template.

The template type parameter T is the type of data structure that is used to represent state and residual vectors.

See also: Anderson Mixing Solver Algorithms

Definition at line 47 of file AmIteratorTmpl.h.

Constructor & Destructor Documentation

◆ AmIteratorTmpl()

template<typename Iterator, typename T>

Pscf::AmIteratorTmpl< Iterator, T >::AmIteratorTmpl ( )

Constructor.

Definition at line 32 of file AmIteratorTmpl.tpp.

References epsilon_, errorType_, maxHist_, maxItr_, Util::ParamComposite::setClassName(), and verbose_.

◆ ~AmIteratorTmpl()

template<typename Iterator, typename T>

Pscf::AmIteratorTmpl< Iterator, T >::~AmIteratorTmpl ( )

Destructor.

Definition at line 53 of file AmIteratorTmpl.tpp.

Member Function Documentation

◆ readParameters()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::readParameters ( std::istream & in )

virtual

Read all parameters and initialize.

Parameters

in	input filestream

Reimplemented in Pscf::R1d::AmIterator, Pscf::Rpc::AmCompressor< D >, Pscf::Rpc::AmIteratorBasis< D >, Pscf::Rpc::AmIteratorGrid< D >, Pscf::Rpc::LrAmCompressor< D >, Pscf::Rpg::AmCompressor< D >, Pscf::Rpg::AmIteratorBasis< D >, Pscf::Rpg::AmIteratorGrid< D >, and Pscf::Rpg::LrAmCompressor< D >.

Definition at line 60 of file AmIteratorTmpl.tpp.

References epsilon_, and read().

◆ solve()

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::solve ( bool isContinuation = false )

Iterate to a solution.

Parameters

isContinuation true iff continuation within a sweep

Returns: 0 for convergence, 1 for failure

Definition at line 98 of file AmIteratorTmpl.tpp.

References maxItr_, setup(), and UTIL_CHECK.

◆ outputTimers()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::outputTimers ( std::ostream & out ) const

Log output timing results.

Parameters

out	output stream

Definition at line 235 of file AmIteratorTmpl.tpp.

◆ clearTimers()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::clearTimers ( )

Clear timers.

Definition at line 279 of file AmIteratorTmpl.tpp.

◆ readErrorType()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::readErrorType ( std::istream & in )

protected

Read and validate the optional errorType string parameter.

Parameters

in	input filestream

Definition at line 297 of file AmIteratorTmpl.tpp.

References errorType_, isValidErrorType(), readOptional(), and UTIL_THROW.

◆ isValidErrorType()

template<typename Iterator, typename T>

bool Pscf::AmIteratorTmpl< Iterator, T >::isValidErrorType ( )

protectedvirtual

Checks if a string is a valid error type.

Virtual to allow extension of allowed error type string values.

Returns: true if type is valid, false otherwise.

Definition at line 320 of file AmIteratorTmpl.tpp.

References errorType_.

Referenced by readErrorType().

◆ readMixingParameters()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::readMixingParameters	(	std::istream &	in,
		bool	useLambdaRamp = true )

protected

Read optional parameters used in default correction algorithm.

Sets a default value for useLambdaRamp, and then optionally reads lambda, useLambdaRamp, and (if useLambdaRamp == true) the ratio r used in the ramp.

Parameters

in	input filestream
useLambdaRamp	default value for useLambdaRamp

Definition at line 343 of file AmIteratorTmpl.tpp.

References readOptional().

◆ allocateAM()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::allocateAM ( )

protected

Allocate memory required by AM algorithm, if necessary.

If the required memory has been allocated previously, this function does nothing and returns.

Definition at line 362 of file AmIteratorTmpl.tpp.

References maxHist_.

Referenced by setup().

◆ isAllocatedAM()

template<typename Iterator, typename T>

bool Pscf::AmIteratorTmpl< Iterator, T >::isAllocatedAM ( ) const

protected

Have data structures required by the AM algorithm been allocated?

Definition at line 596 of file AmIteratorTmpl.h.

Referenced by setup().

◆ setup()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::setup ( bool isContinuation )

protectedvirtual

Initialize just before entry to iterative loop.

This function is called by the solve function before entering the loop over iterations. The default implementation calls allocateAM() if isAllocatedAM() is false, and clears state and residual histories. If isContinuation is false, it also clears state and residual basis vector lists.

Parameters

isContinuation true iff continuation within a sweep

Reimplemented in Pscf::R1d::AmIterator, Pscf::Rpc::AmCompressor< D >, Pscf::Rpc::AmIteratorBasis< D >, Pscf::Rpc::AmIteratorGrid< D >, Pscf::Rpc::LrAmCompressor< D >, Pscf::Rpg::AmCompressor< D >, Pscf::Rpg::AmIteratorBasis< D >, Pscf::Rpg::AmIteratorGrid< D >, and Pscf::Rpg::LrAmCompressor< D >.

Definition at line 394 of file AmIteratorTmpl.tpp.

References allocateAM(), and isAllocatedAM().

Referenced by solve().

◆ clear()

template<typename Iterator, typename T>

void Pscf::AmIteratorTmpl< Iterator, T >::clear ( )

protectedvirtual

Clear information about history.

This function clears the the history and basis vector ring buffer containers.

Definition at line 414 of file AmIteratorTmpl.tpp.

References UTIL_CHECK.

◆ computeError() [1/2]

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::computeError	(	T &	residTrial,
		T &	stateTrial,
		std::string	errorType,
		int	verbose )

protectedvirtual

Compute and return error used to test for convergence.

Parameters

residTrial	current residual vector
stateTrial	current state vector
errorType	type of error
verbose	verbosity level of output report.

Returns: error measure used to test for convergence.

Definition at line 637 of file AmIteratorTmpl.tpp.

References errorType(), Util::Log::file(), UTIL_CHECK, UTIL_THROW, and verbose().

Referenced by computeError().

◆ computeError() [2/2]

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::computeError ( int verbose )

protected

Compute and return error used to test for convergence.

Parameters

verbose verbosity level of output report

Returns: error error value used to test for convergence.

Definition at line 689 of file AmIteratorTmpl.tpp.

References computeError(), errorType_, and verbose().

◆ lambdaRampFactor()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::lambdaRampFactor ( )

protected

Compute ramped prefactor of mixing parameter lambda.

Returns: prefactor 1 - r^{nBasis} multiplying lambda.

◆ computeLambda()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::computeLambda ( )

protectedvirtual

Compute mixing parameter for correction step of Anderson mixing.

If useLambdaRamp_ == true and nBasis_ < maxHist_, then return the ramped parameter lambda_ * ( 1 - r_^(nBasis) ). Otherwise, return the parameter lambda_.

Returns: lambda mixing parameter

Definition at line 573 of file AmIteratorTmpl.tpp.

References maxHist_.

◆ verbose()

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::verbose ( ) const

protected

Verbosity level, allowed values 0, 1, or 2.

Definition at line 568 of file AmIteratorTmpl.h.

References verbose_.

Referenced by computeError(), and computeError().

◆ errorType()

template<typename Iterator, typename T>

std::string Pscf::AmIteratorTmpl< Iterator, T >::errorType ( ) const

protected

Get error type string.

Definition at line 575 of file AmIteratorTmpl.h.

References errorType_.

Referenced by computeError().

◆ residual()

template<typename Iterator, typename T>

T const & Pscf::AmIteratorTmpl< Iterator, T >::residual ( ) const

protected

Get the current residual vector by const reference.

Definition at line 589 of file AmIteratorTmpl.h.

◆ state()

template<typename Iterator, typename T>

T const & Pscf::AmIteratorTmpl< Iterator, T >::state ( ) const

protected

Return the current state vector by const reference.

Definition at line 582 of file AmIteratorTmpl.h.

◆ totalItr()

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::totalItr ( )

protected

Return the total number of iterations needed to converge.

Definition at line 603 of file AmIteratorTmpl.h.

◆ timerTotal()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerTotal ( )

protected

Get total time.

Definition at line 652 of file AmIteratorTmpl.h.

◆ timerMDE()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerMDE ( )

protected

Get time spent solving the modified diffusion equation (MDE).

Definition at line 610 of file AmIteratorTmpl.h.

◆ timerAM()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerAM ( )

protected

Get total time for AM algorithm, excluding MDE solution.

Definition at line 617 of file AmIteratorTmpl.h.

◆ timerResid()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerResid ( )

protected

Get time spent computing residual.

Definition at line 624 of file AmIteratorTmpl.h.

◆ timerError()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerError ( )

protected

Get time evaluating scalar error.

Definition at line 631 of file AmIteratorTmpl.h.

◆ timerCoeff()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerCoeff ( )

protected

Get time spent evaluating Anderson mixing coefficients.

Definition at line 638 of file AmIteratorTmpl.h.

◆ timerOmega()

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::timerOmega ( )

protected

Get time spent updating w states.

Definition at line 645 of file AmIteratorTmpl.h.

◆ read()

template<typename Iterator, typename T>

template<typename Type>

ScalarParam< Type > & Util::ParamComposite::read	(	std::istream &	in,
		const char *	label,
		Type &	value )

protected

Add and read a new required ScalarParam < Type > object.

This is equivalent to ScalarParam<Type>(in, label, value, true).

Parameters

in	input stream for reading
label	Label string
value	reference to new ScalarParam< Type >

Definition at line 305 of file ParamComposite.h.

Referenced by readParameters().

◆ readOptional()

template<typename Iterator, typename T>

template<typename Type>

ScalarParam< Type > & Util::ParamComposite::readOptional	(	std::istream &	in,
		const char *	label,
		Type &	value )

inlineprotected

Add and read a new optional ScalarParam < Type > object.

This is equivalent to ScalarParam<Type>(in, label, value, false).

Parameters

in	input stream for reading
label	Label string
value	reference to new ScalarParam< Type >

Definition at line 319 of file ParamComposite.h.

Referenced by readErrorType(), and readMixingParameters().

Member Data Documentation

◆ epsilon_

template<typename Iterator, typename T>

double Pscf::AmIteratorTmpl< Iterator, T >::epsilon_

protected

Error tolerance.

Definition at line 93 of file AmIteratorTmpl.h.

Referenced by AmIteratorTmpl(), and readParameters().

◆ maxItr_

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::maxItr_

protected

Maximum number of iterations to attempt.

Definition at line 98 of file AmIteratorTmpl.h.

Referenced by AmIteratorTmpl(), and solve().

◆ maxHist_

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::maxHist_

protected

Maximum number of basis vectors in AM algorithm.

Definition at line 103 of file AmIteratorTmpl.h.

Referenced by allocateAM(), AmIteratorTmpl(), and computeLambda().

◆ verbose_

template<typename Iterator, typename T>

int Pscf::AmIteratorTmpl< Iterator, T >::verbose_

protected

Verbosity level.

Definition at line 108 of file AmIteratorTmpl.h.

Referenced by AmIteratorTmpl(), and verbose().

◆ errorType_

template<typename Iterator, typename T>

std::string Pscf::AmIteratorTmpl< Iterator, T >::errorType_

protected

Type of error criterion used to test convergence.

Definition at line 113 of file AmIteratorTmpl.h.

Referenced by AmIteratorTmpl(), computeError(), errorType(), isValidErrorType(), and readErrorType().

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AmIteratorTmpl()

◆ ~AmIteratorTmpl()

Member Function Documentation

◆ readParameters()

◆ solve()

◆ outputTimers()

◆ clearTimers()

◆ readErrorType()

◆ isValidErrorType()

◆ readMixingParameters()

◆ allocateAM()

◆ isAllocatedAM()

◆ setup()

◆ clear()

◆ computeError() [1/2]

◆ computeError() [2/2]

◆ lambdaRampFactor()

◆ computeLambda()

◆ verbose()

◆ errorType()

◆ residual()

◆ state()

◆ totalItr()

◆ timerTotal()

◆ timerMDE()

◆ timerAM()

◆ timerResid()

◆ timerError()

◆ timerCoeff()

◆ timerOmega()

◆ read()

◆ readOptional()

Member Data Documentation

◆ epsilon_

◆ maxItr_

◆ maxHist_

◆ verbose_

◆ errorType_