da_fpi.h File Reference

Damped fixed-point iteration, the shared driver of the decomposition algorithms. More...

#include <cmath>
#include <cstddef>
#include <functional>
#include <limits>
#include <utility>
#include <vector>
#include "line/num/number.h"
#include "line/util/error.h"

Include dependency graph for da_fpi.h:

Go to the source code of this file.

Classes
struct	line::da::FpiOptions
	Options mirroring the fields MATLAB reads off the options struct. More...
struct	line::da::FpiResult< T >

Namespaces
namespace	line
namespace	line::da

Functions
template<class T>
FpiResult< T >	line::da::da_fpi (const std::function< std::pair< std::vector< T >, std::vector< T > >(const std::vector< T > &, std::size_t)> &iterfun, const std::vector< T > &x0, const FpiOptions &options=FpiOptions())
	Damped fixed-point iteration, the shared driver of the decomposition algorithms.

Detailed Description

Damped fixed-point iteration, the shared driver of the decomposition algorithms.

Templated port of matlab/src/api/da/da_fpi.m. The iteration is x_{k+1} = (1 - omega) x_ref + omega f(x_k, k) stopping when the configured norm of the increment falls below iter_tol, or after iter_max steps. MATLAB passes the iteration function as a handle returning both the new iterate and the reference point it should be damped against; the port takes a std::function with the same contract, so a caller whose reference differs from its input (as in the Erlang fixed point) is expressible without special-casing.

THE INCREMENT NORM FOLLOWS MATLAB'S max(), which OMITS NaN and answers NaN only when every entry is one. The first form of this port skipped NaN entries but left delta at its initial 0, so an all-NaN increment – a diverged iterate – reported CONVERGENCE, where MATLAB's NaN < iter_tol is false and the loop continues to iter_max. Corrected here; a caller that wants to stop on a divergence asks for it with nanstop.

A tolerance-driven loop is inexact by construction, whatever the arithmetic: the answer is the fixed point only to within iter_tol. The static_assert records that, so nobody instantiates it at exact arithmetic expecting an exact fixed point.

Definition in file da_fpi.h.