DiFfRG::BisectionRootFinderTarget Class Reference

Bisection search which converges a target value rather than the search variable. More...

#include <root_finding.hh>

Public Member Functions
	BisectionRootFinderTarget (FUN f, const double abs_tol=1e-4, const int max_iter=1000)
void	set_abs_tol (const double abs_tol)
void	set_max_iter (const uint max_iter)
void	set_x_min (const double x_min)
void	set_x_max (const double x_max)
void	set_bounds (const double x_min, const double x_max)
void	set_next_x (const std::function< double(double, double)> &next_x)
void	set_x_collapse_tol (const double x_collapse_tol)
	Width of the x-bracket below which the search gives up. Zero (the default) selects an automatic, magnitude-scaled multiple of the machine epsilon.
uint	get_iter () const
double	get_target () const
	Target value belonging to the point returned by search(). NaN before search() ran.
bool	converged () const
	Whether the last search() met the target tolerance. False if it stopped early because the bracket collapsed or the iteration limit was reached.
double	search ()

Protected Types
using	FUN = std::function<bool(const double, double &)>

Protected Attributes
FUN	f
double	abs_tol
uint	max_iter
uint	iter
double	x_min = std::numeric_limits<double>::quiet_NaN()
double	x_max = std::numeric_limits<double>::quiet_NaN()
double	x_collapse_tol = 0.
double	target = std::numeric_limits<double>::quiet_NaN()
bool	m_converged = false
std::function< double(double, double)>	next_x

Detailed Description

Bisection search which converges a target value rather than the search variable.

The bracketing logic is identical to BisectionRootFinder: the callback returns true if the tested point lies at or above the root (tightening the upper bound) and false if it lies below (tightening the lower bound). The difference is the stopping criterion. Instead of shrinking the interval in x until it falls below abs_tol, the callback additionally writes a target value through its double & out-parameter, and the search stops once two consecutive successful evaluations produce target values differing by less than abs_tol.

This is the right tool when the quantity of interest is not x itself but an observable computed at x, whose sensitivity to x is not known a priori.

BisectionRootFinderTarget search(
    [&](const double x, double &target) -> bool {
      config.set_double("/physical/m2A", x);
      return run_at(x, target); // writes the observable into target
    },
    tol, 100);
search.set_bounds(lower, upper);
const double x      = search.search();
const double target = search.get_target();

Failed evaluations need not write anything meaningful into the target; only successful ones are compared. If the bracket collapses to machine precision, or max_iter is exhausted, before the criterion is met, the search stops, warns, and returns the last successful point with converged() reporting false. Only a search without any successful evaluation throws.

Note that the criterion fires early if the target happens to be insensitive to x over part of the bracket, since two neighbouring successes then look converged. In that case tighten abs_tol or install a next_x which does not bisect.

Two deliberate differences to BisectionRootFinder: the iteration counter is advanced before the callback runs, so get_iter() inside the callback names the step being taken, and the bounds are NaN-initialised so that a forgotten set_bounds throws instead of reading garbage.

Member Typedef Documentation

FUN

using DiFfRG::BisectionRootFinderTarget::FUN = std::function<bool(const double, double &)>

protected

Constructor & Destructor Documentation

BisectionRootFinderTarget()

DiFfRG::BisectionRootFinderTarget::BisectionRootFinderTarget ( FUN f, const double abs_tol = 1e-4, const int max_iter = 1000 )

inline

Member Function Documentation

converged()

bool DiFfRG::BisectionRootFinderTarget::converged ( ) const

inline

Whether the last search() met the target tolerance. False if it stopped early because the bracket collapsed or the iteration limit was reached.

get_iter()

uint DiFfRG::BisectionRootFinderTarget::get_iter ( ) const

inline

get_target()

double DiFfRG::BisectionRootFinderTarget::get_target ( ) const

inline

Target value belonging to the point returned by search(). NaN before search() ran.

search()

double DiFfRG::BisectionRootFinderTarget::search ( )

inline

set_abs_tol()

void DiFfRG::BisectionRootFinderTarget::set_abs_tol ( const double abs_tol )

inline

set_bounds()

void DiFfRG::BisectionRootFinderTarget::set_bounds ( const double x_min, const double x_max )

inline

set_max_iter()

void DiFfRG::BisectionRootFinderTarget::set_max_iter ( const uint max_iter )

inline

set_next_x()

void DiFfRG::BisectionRootFinderTarget::set_next_x ( const std::function< double(double, double)> & next_x )

inline

set_x_collapse_tol()

void DiFfRG::BisectionRootFinderTarget::set_x_collapse_tol ( const double x_collapse_tol )

inline

Width of the x-bracket below which the search gives up. Zero (the default) selects an automatic, magnitude-scaled multiple of the machine epsilon.

set_x_max()

void DiFfRG::BisectionRootFinderTarget::set_x_max ( const double x_max )

inline

set_x_min()

void DiFfRG::BisectionRootFinderTarget::set_x_min ( const double x_min )

inline

Member Data Documentation

abs_tol

double DiFfRG::BisectionRootFinderTarget::abs_tol

protected

f

FUN DiFfRG::BisectionRootFinderTarget::f

protected

iter

uint DiFfRG::BisectionRootFinderTarget::iter

protected

m_converged

bool DiFfRG::BisectionRootFinderTarget::m_converged = false

protected

max_iter

uint DiFfRG::BisectionRootFinderTarget::max_iter

protected

next_x

std::function<double(double, double)> DiFfRG::BisectionRootFinderTarget::next_x

protected

Initial value:

= [](const double x_min, const double x_max) {
      return (x_min + x_max) / 2.;
    }

target

double DiFfRG::BisectionRootFinderTarget::target = std::numeric_limits<double>::quiet_NaN()

protected

x_collapse_tol

double DiFfRG::BisectionRootFinderTarget::x_collapse_tol = 0.

protected

x_max

double DiFfRG::BisectionRootFinderTarget::x_max = std::numeric_limits<double>::quiet_NaN()

protected

x_min

double DiFfRG::BisectionRootFinderTarget::x_min = std::numeric_limits<double>::quiet_NaN()

protected

---

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

• /home/runner/work/DiFfRG_current/DiFfRG_current/DiFfRG/include/DiFfRG/common/root_finding.hh