Convergence Namespace Reference

Items related to checking the convergence of numerical algorithms. More...

Namespaces
namespace	OptionTags
	Option tags related to the convergence of iterative algorithms.
namespace	Tags
	Tags related to the convergence of iterative algorithms.

Classes
struct	Criteria
	Criteria that determine an iterative algorithm has converged. More...
struct	HasConverged
	Signals convergence or termination of the algorithm. More...

Enumerations
enum class	Reason {   NumIterations , MaxIterations , AbsoluteResidual , RelativeResidual ,   Error }
	The reason the algorithm has converged or terminated. More...

Functions
bool	operator== (const Criteria &lhs, const Criteria &rhs)
bool	operator!= (const Criteria &lhs, const Criteria &rhs)
std::optional< Reason >	criteria_match (const Criteria &criteria, size_t iteration_id, double residual_magnitude, double initial_residual_magnitude)
	Determine whether the criteria are met.
std::ostream &	operator<< (std::ostream &os, const Reason &reason)

Detailed Description

Items related to checking the convergence of numerical algorithms.

Enumeration Type Documentation

Reason

enum class Convergence::Reason

strong

The reason the algorithm has converged or terminated.

See also

Convergence::Criteria

Enumerator
NumIterations	Reached the target number of iterations.
MaxIterations	Reached the maximum number of iterations. Can be interpreted as an error condition.
AbsoluteResidual	Residual converged below absolute tolerance.
RelativeResidual	Residual converged below relative tolerance.
Error	An error occurred during the algorithm.

Function Documentation

criteria_match()

std::optional< Reason > Convergence::criteria_match	(	const Criteria &	criteria,
		size_t	iteration_id,
		double	residual_magnitude,
		double	initial_residual_magnitude )

Determine whether the criteria are met.

Note

This function assumes the iteration_id is that of the latest completed step and that it is zero-indexed, where zero indicates the initial state of the algorithm. Therefore, the MaxIteration criterion will match if the iteration_id is equal or higher. For example, a MaxIteration of 0 means the algorithm should run no iterations, so it matches if the iteration_id is 0 or higher since that's the initial state before any steps have been performed. A MaxIteration of 1 matches if the iteration_id is 1 or higher since one iteration is complete. At this point, also the residual_magnitude reflects the state of the algorithm after completion of the first iteration. The initial_residual_magnitude always refers to the state before the first iteration has begun, i.e. where the iteration_id is zero.

Returns: A Convergence::Reason if the criteria are met, or std::nullopt otherwise. The possible convergence reasons are:

• Convergence::Reason::AbsoluteResidual if the residual_magnitude meets the convergence criteria's absolute_residual.
• Convergence::Reason::RelativeResidual if residual_magnitude / initial_residual_magnitude meets the convergence criteria's relative_residual.
• Convergence::Reason::MaxIterations if the iteration_id is the convergence_criteria's max_iterations or higher. This is often interpreted as an error because the algorithm did not converge in the alloted number of iterations.