MathRoot Namespace Reference

Root finding algorithms for scalar functions. More...

Data Structures
struct	AllRootsResult
	Result for all roots finder including null intervals. More...
struct	MultipleBrentValueWrapper
	Brent wrapper that adapts a Value-only function for offset root finding. More...
struct	MultipleConfig
	Configuration for multiple root finding. More...
struct	MultipleDerivativeValueWrapper
	Wrapper exposing a function derivative through the Value() contract required by Brent. More...
struct	MultipleGetRootValueFn
	Evaluates original (non-offset) function value at a root point via Value interface. More...
struct	MultipleGetValueFn
	Returns the sampled value at a given index from a math_Vector. More...
struct	MultipleNoExtraHandler
	No-op interval handler for functions without derivative. More...
struct	MultipleResult
	Result for multiple root finding. Contains all found roots sorted in ascending order. More...
struct	MultipleSampleValueFn
	Samples a Value-only function and stores f(x)-offset into a math_Vector. More...
struct	NullInterval
	Represents an interval where the function is null (within tolerance). More...
struct	TrigResult
	Result for trigonometric equation solver. More...

Functions
template<typename Func >
MultipleResult	FindMultipleRoots (Func &theFunc, double theA, double theB, int theNbSamples, double theEpsX, double theEpsF, double theOffset=0.0)
	Helper function to find multiple roots with offset.
template<typename Func >
AllRootsResult	FindAllRootsWithIntervals (Func &theFunc, const math_Vector &theSamples, double theEpsX=1.0e-10, double theEpsF=1.0e-10, double theEpsNul=1.0e-10)
	Find all roots of a function using sampling and refinement.
template<typename Func >
AllRootsResult	FindAllRootsWithIntervals (Func &theFunc, double theA, double theB, int theNbSamples, double theEpsX=1.0e-10, double theEpsF=1.0e-10, double theEpsNul=1.0e-10)
	Find all roots using uniform sampling.
template<typename Function >
MathUtils::ScalarResult	Bisection (Function &theFunc, double theLower, double theUpper, const MathUtils::Config &theConfig=MathUtils::Config())
	Bisection method for root finding. Simple and robust, guaranteed to converge if a valid bracket is provided. Converges linearly, halving the interval at each step.
template<typename Function >
MathUtils::ScalarResult	BisectionNewton (Function &theFunc, double theLower, double theUpper, const MathUtils::Config &theConfig=MathUtils::Config())
	Hybrid bisection-Newton method. Combines the robustness of bisection with the speed of Newton's method. Uses Newton step when it stays within bracket, otherwise bisects.
template<typename Function >
MathUtils::ScalarResult	Brent (Function &theFunc, double theLower, double theUpper, const MathUtils::Config &theConfig=MathUtils::Config())
	Brent's method for root finding. Combines bisection, secant, and inverse quadratic interpolation. Guaranteed to converge if a valid bracket is provided.
template<typename Function >
MultipleResult	FindAllRoots (Function &theFunc, double theLower, double theUpper, const MultipleConfig &theConfig=MultipleConfig())
	Finds all real roots of a function within the range [theLower, theUpper]. Uses uniform sampling to detect sign changes, then refines each root using Brent's method.
template<typename Function >
MultipleResult	FindAllRootsWithDerivative (Function &theFunc, double theLower, double theUpper, const MultipleConfig &theConfig=MultipleConfig())
	Finds all real roots of a function with derivative within range [theLower, theUpper]. Can also detect extrema where function touches zero without crossing.
template<typename Function >
MultipleResult	FindAllRoots (Function &theFunc, double theLower, double theUpper, int theNbSamples)
	Convenience alias using default configuration.
void	SortRoots (MultipleResult &theResult)
	In-place insertion sort of roots and corresponding values by ascending root value.
void	AddRoot (MultipleResult &theResult, double theEpsX, double theRoot, double theValue)
	Helper to add a root if it is not a duplicate of an already found root.
double	EffectiveXTolerance (double theLower, double theUpper, double theXTolerance)
	Compute the minimal X tolerance compatible with the established multi-root behavior.
template<typename Function >
bool	EvaluateValue (Function &theFunc, double theX, double &theValue)
	Evaluate the original function value.
template<typename Function >
bool	EvaluateShiftedValue (Function &theFunc, double theX, double theOffset, double &theValue)
	Evaluate the function value shifted by the requested offset.
template<typename Function >
bool	EvaluateShiftedValues (Function &theFunc, double theX, double theOffset, double &theValue, double &theDerivative)
	Evaluate the function value and derivative, then shift the value by the requested offset.
template<typename Function >
bool	RefineBracketedRoot (Function &theFunc, double theOffset, double theX1, double theY1, double theX2, double theY2, double theTolerance, double theEpsX, MultipleResult &theResult)
	Refine a bracketed sign change using the same Brent/Newton sequence as math_FunctionRoots.
template<typename Function >
MultipleResult	FindAllRootsWithDerivativeImpl (Function &theFunc, double theLower, double theUpper, const MultipleConfig &theConfig)
	Derivative-aware implementation mirroring the proven math_FunctionRoots heuristics while operating on the modern callable-based MathRoot API.
template<typename SampleFn , typename GetValueFn , typename BrentWrapperT , typename GetRootValueFn , typename IntervalExtraFn >
MultipleResult	FindAllRootsImpl (double theLower, double theUpper, const MultipleConfig &theConfig, SampleFn theSampleFn, GetValueFn theGetValue, BrentWrapperT &theBrentWrapper, GetRootValueFn theGetRootValue, IntervalExtraFn theIntervalExtra)
	Core implementation for finding all roots in an interval. Shared logic for both Value-only and Values (with derivative) interfaces.
template<typename Function >
MathUtils::ScalarResult	Newton (Function &theFunc, double theGuess, const MathUtils::Config &theConfig=MathUtils::Config())
	Newton-Raphson root finding algorithm. Finds x such that f(x) = 0 using Newton's method with derivative.
template<typename Function >
MathUtils::ScalarResult	NewtonBounded (Function &theFunc, double theGuess, double theLower, double theUpper, const MathUtils::Config &theConfig=MathUtils::Config())
	Newton-Raphson with bounds checking. Falls back to bisection step if Newton step goes outside bounds. More robust than pure Newton for ill-conditioned problems.
template<typename Function >
MathUtils::ScalarResult	Secant (Function &theFunc, double theX0, double theX1, const MathUtils::Config &theConfig=MathUtils::Config())
	Secant method for root finding. Does not require derivative, uses finite difference approximation. Converges superlinearly (order ~1.618, the golden ratio).
template<typename Function >
MathUtils::ScalarResult	SecantAuto (Function &theFunc, double theX0, const MathUtils::Config &theConfig=MathUtils::Config())
	Secant method with automatic initial points. Creates second point by small perturbation of the initial guess.
TrigResult	Trigonometric (double theA, double theB, double theC, double theD, double theE, double theInfBound=0.0, double theSupBound=THE_2PI, double theEps=1.5e-12)
	Solve trigonometric equation: a*cos^2(x) + 2*b*cos(x)*sin(x) + c*cos(x) + d*sin(x) + e = 0.
TrigResult	TrigonometricLinear (double theD, double theE, double theInfBound=0.0, double theSupBound=THE_2PI)
	Solve linear trigonometric equation: d*sin(x) + e = 0.
TrigResult	TrigonometricCDE (double theC, double theD, double theE, double theInfBound=0.0, double theSupBound=THE_2PI)
	Solve trigonometric equation: c*cos(x) + d*sin(x) + e = 0.

Detailed Description

Root finding algorithms for scalar functions.

Function Documentation

AddRoot()

void MathRoot::AddRoot ( MultipleResult & theResult, double theEpsX, double theRoot, double theValue )

inline

Helper to add a root if it is not a duplicate of an already found root.

Bisection()

template<typename Function >

MathUtils::ScalarResult MathRoot::Bisection	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Bisection method for root finding. Simple and robust, guaranteed to converge if a valid bracket is provided. Converges linearly, halving the interval at each step.

Algorithm:

1. Start with bracket [a, b] where f(a) * f(b) < 0
2. Compute midpoint m = (a + b) / 2
3. If f(m) has same sign as f(a), set a = m, else set b = m
4. Repeat until convergence

Template Parameters

Function

type with Value(double theX, double& theF) method

Parameters

theFunc	function to find root of
theLower	lower bound of bracket
theUpper	upper bound of bracket
theConfig	solver configuration

Returns

result containing root location and convergence status

BisectionNewton()

template<typename Function >

MathUtils::ScalarResult MathRoot::BisectionNewton	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Hybrid bisection-Newton method. Combines the robustness of bisection with the speed of Newton's method. Uses Newton step when it stays within bracket, otherwise bisects.

Template Parameters

Function

type with Values(double theX, double& theF, double& theDf) method

Parameters

theFunc	function with value and derivative
theLower	lower bound of bracket
theUpper	upper bound of bracket
theConfig	solver configuration

Returns

result containing root location and convergence status

Brent()

template<typename Function >

MathUtils::ScalarResult MathRoot::Brent	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Brent's method for root finding. Combines bisection, secant, and inverse quadratic interpolation. Guaranteed to converge if a valid bracket is provided.

Algorithm:

1. Start with bracket [a, b] where f(a) * f(b) < 0
2. At each step, try inverse quadratic interpolation
3. If interpolation step is rejected, use bisection
4. Acceptance criteria ensure superlinear convergence when possible

Template Parameters

Function

type with Value(double theX, double& theF) method

Parameters

theFunc	function to find root of
theLower	lower bound of bracket (f(theLower) and f(theUpper) must have opposite signs)
theUpper	upper bound of bracket
theConfig	solver configuration

Returns

result containing root location and convergence status

EffectiveXTolerance()

double MathRoot::EffectiveXTolerance ( double theLower, double theUpper, double theXTolerance )

inline

Compute the minimal X tolerance compatible with the established multi-root behavior.

EvaluateShiftedValue()

template<typename Function >

bool MathRoot::EvaluateShiftedValue	(	Function &	theFunc,
		double	theX,
		double	theOffset,
		double &	theValue )

Evaluate the function value shifted by the requested offset.

Template Parameters

Function

type with Value(double theX, double& theF) method

EvaluateShiftedValues()

template<typename Function >

bool MathRoot::EvaluateShiftedValues	(	Function &	theFunc,
		double	theX,
		double	theOffset,
		double &	theValue,
		double &	theDerivative )

Evaluate the function value and derivative, then shift the value by the requested offset.

Template Parameters

Function

type with Values(double theX, double& theF, double& theDF) method

EvaluateValue()

template<typename Function >

bool MathRoot::EvaluateValue	(	Function &	theFunc,
		double	theX,
		double &	theValue )

Evaluate the original function value.

Template Parameters

Function

type with Value(double theX, double& theF) method

FindAllRoots() [1/2]

template<typename Function >

MultipleResult MathRoot::FindAllRoots	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MultipleConfig &	theConfig = MultipleConfig() )

Finds all real roots of a function within the range [theLower, theUpper]. Uses uniform sampling to detect sign changes, then refines each root using Brent's method.

Algorithm:

1. Sample function at NbSamples uniform points
2. Detect all sign changes and zero crossings
3. For each bracket, apply Brent's method to find precise root
4. Check for extrema that might touch zero

Template Parameters

Function

type with Value(double theX, double& theF) method

Parameters

theFunc	function object to find roots of
theLower	lower bound of search interval
theUpper	upper bound of search interval
theConfig	configuration parameters

Returns

result containing all found roots

FindAllRoots() [2/2]

template<typename Function >

MultipleResult MathRoot::FindAllRoots	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		int	theNbSamples )

Convenience alias using default configuration.

Template Parameters

Function

type with Value(double, double&) method

Parameters

theFunc	function to find roots of
theLower	lower bound
theUpper	upper bound
theNbSamples	number of sample points

Returns

result with all found roots

FindAllRootsImpl()

template<typename SampleFn , typename GetValueFn , typename BrentWrapperT , typename GetRootValueFn , typename IntervalExtraFn >

MultipleResult MathRoot::FindAllRootsImpl	(	double	theLower,
		double	theUpper,
		const MultipleConfig &	theConfig,
		SampleFn	theSampleFn,
		GetValueFn	theGetValue,
		BrentWrapperT &	theBrentWrapper,
		GetRootValueFn	theGetRootValue,
		IntervalExtraFn	theIntervalExtra )

Core implementation for finding all roots in an interval. Shared logic for both Value-only and Values (with derivative) interfaces.

Template Parameters

SampleFn	callable (int theIndex, double theX) -> bool
GetValueFn	callable (int theIndex) -> double, returns f(x)-offset at sample
BrentWrapperT	type with Value(double, double&) for Brent root finding
GetRootValueFn	callable (double theX) -> double, returns original f(x)
IntervalExtraFn	callable (int, x0, x1, f0, f1, result, epsX) -> void

FindAllRootsWithDerivative()

template<typename Function >

MultipleResult MathRoot::FindAllRootsWithDerivative	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MultipleConfig &	theConfig = MultipleConfig() )

Finds all real roots of a function with derivative within range [theLower, theUpper]. Can also detect extrema where function touches zero without crossing.

This version uses derivative information for better extrema detection.

Template Parameters

Function

type with Values(double theX, double& theF, double& theDF) method

Parameters

theFunc	function object with derivative
theLower	lower bound of search interval
theUpper	upper bound of search interval
theConfig	configuration parameters

Returns

result containing all found roots

FindAllRootsWithDerivativeImpl()

template<typename Function >

MultipleResult MathRoot::FindAllRootsWithDerivativeImpl	(	Function &	theFunc,
		double	theLower,
		double	theUpper,
		const MultipleConfig &	theConfig )

Derivative-aware implementation mirroring the proven math_FunctionRoots heuristics while operating on the modern callable-based MathRoot API.

Template Parameters

Function

type with Value() and Values() methods

FindAllRootsWithIntervals() [1/2]

template<typename Func >

AllRootsResult MathRoot::FindAllRootsWithIntervals	(	Func &	theFunc,
		const math_Vector &	theSamples,
		double	theEpsX = 1.0e-10,
		double	theEpsF = 1.0e-10,
		double	theEpsNul = 1.0e-10 )

Find all roots of a function using sampling and refinement.

Uses a sample of the function to find:

1. Null intervals: where |F(x)| <= EpsNul for consecutive sample points
2. Isolated roots: single points where F(x) = 0

The algorithm:

1. Evaluates F at sample points
2. Identifies null intervals where |F| <= EpsNul for 2+ consecutive points
3. Refines interval boundaries using root finding
4. Finds isolated roots between null intervals using MultipleRoots

Template Parameters

Func	function type with: bool Value(double, double&) bool Values(double, double&, double&) for derivative

Parameters

theFunc	function with derivative to analyze
theSamples	sample points array
theEpsX	tolerance for root x-value
theEpsF	tolerance for function value at root
theEpsNul	tolerance for null interval detection

Returns

AllRootsResult with roots and null intervals

FindAllRootsWithIntervals() [2/2]

template<typename Func >

AllRootsResult MathRoot::FindAllRootsWithIntervals	(	Func &	theFunc,
		double	theA,
		double	theB,
		int	theNbSamples,
		double	theEpsX = 1.0e-10,
		double	theEpsF = 1.0e-10,
		double	theEpsNul = 1.0e-10 )

Find all roots using uniform sampling.

Template Parameters

Func	function type with Value and Values methods

Parameters

theFunc	function with derivative
theA	interval start
theB	interval end
theNbSamples	number of sample points
theEpsX	tolerance for root x-value
theEpsF	tolerance for function value
theEpsNul	tolerance for null interval detection

Returns

AllRootsResult with roots and null intervals

FindMultipleRoots()

template<typename Func >

MultipleResult MathRoot::FindMultipleRoots	(	Func &	theFunc,
		double	theA,
		double	theB,
		int	theNbSamples,
		double	theEpsX,
		double	theEpsF,
		double	theOffset = 0.0 )

Helper function to find multiple roots with offset.

Template Parameters

Func	function type

Parameters

theFunc	function to analyze
theA	interval start
theB	interval end
theNbSamples	number of sample points
theEpsX	tolerance for root x-value
theEpsF	tolerance for function value
theOffset	offset value (find roots of f(x) - offset = 0)

Returns

MultipleResult with found roots

Newton()

template<typename Function >

MathUtils::ScalarResult MathRoot::Newton	(	Function &	theFunc,
		double	theGuess,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Newton-Raphson root finding algorithm. Finds x such that f(x) = 0 using Newton's method with derivative.

Algorithm: x_{n+1} = x_n - f(x_n) / f'(x_n)

Requires a function providing both value and derivative. Converges quadratically near the root for simple roots.

Template Parameters

Function

type with Values(double theX, double& theF, double& theDf) method returning bool (true if evaluation succeeded)

Parameters

theFunc	function object providing value and derivative
theGuess	initial guess for the root
theConfig	solver configuration (tolerances, max iterations)

Returns

result containing root location and convergence status

NewtonBounded()

template<typename Function >

MathUtils::ScalarResult MathRoot::NewtonBounded	(	Function &	theFunc,
		double	theGuess,
		double	theLower,
		double	theUpper,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Newton-Raphson with bounds checking. Falls back to bisection step if Newton step goes outside bounds. More robust than pure Newton for ill-conditioned problems.

Template Parameters

Function

type with Values(double theX, double& theF, double& theDf) method

Parameters

theFunc	function object providing value and derivative
theGuess	initial guess for the root
theLower	lower bound of search interval
theUpper	upper bound of search interval
theConfig	solver configuration

Returns

result containing root location and convergence status

RefineBracketedRoot()

template<typename Function >

bool MathRoot::RefineBracketedRoot	(	Function &	theFunc,
		double	theOffset,
		double	theX1,
		double	theY1,
		double	theX2,
		double	theY2,
		double	theTolerance,
		double	theEpsX,
		MultipleResult &	theResult )

Refine a bracketed sign change using the same Brent/Newton sequence as math_FunctionRoots.

Template Parameters

Function

type with Value() and Values() methods

Secant()

template<typename Function >

MathUtils::ScalarResult MathRoot::Secant	(	Function &	theFunc,
		double	theX0,
		double	theX1,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Secant method for root finding. Does not require derivative, uses finite difference approximation. Converges superlinearly (order ~1.618, the golden ratio).

Algorithm:

1. Start with two initial points x0, x1
2. Approximate derivative: f'(x) ~ (f(x1) - f(x0)) / (x1 - x0)
3. Newton-like update: x2 = x1 - f(x1) * (x1 - x0) / (f(x1) - f(x0))
4. Repeat with x0 = x1, x1 = x2

Template Parameters

Function

type with Value(double theX, double& theF) method

Parameters

theFunc	function object providing only value
theX0	first initial point
theX1	second initial point (different from theX0)
theConfig	solver configuration

Returns

result containing root location and convergence status

SecantAuto()

template<typename Function >

MathUtils::ScalarResult MathRoot::SecantAuto	(	Function &	theFunc,
		double	theX0,
		const MathUtils::Config &	theConfig = MathUtils::Config() )

Secant method with automatic initial points. Creates second point by small perturbation of the initial guess.

Template Parameters

Function

type with Value(double theX, double& theF) method

Parameters

theFunc	function object providing only value
theX0	initial guess
theConfig	solver configuration

Returns

result containing root location and convergence status

SortRoots()

void MathRoot::SortRoots ( MultipleResult & theResult )

inline

In-place insertion sort of roots and corresponding values by ascending root value.

Trigonometric()

TrigResult MathRoot::Trigonometric ( double theA, double theB, double theC, double theD, double theE, double theInfBound = 0.0, double theSupBound = THE_2PI, double theEps = 1.5e-12 )

inline

Solve trigonometric equation: a*cos^2(x) + 2*b*cos(x)*sin(x) + c*cos(x) + d*sin(x) + e = 0.

Uses half-angle substitution t = tan(x/2) to convert to polynomial:

• cos(x) = (1-t^2)/(1+t^2)
• sin(x) = 2t/(1+t^2)

Resulting polynomial is of degree 4, 3, or 2 depending on coefficients. Roots are filtered to lie within [theInfBound, theSupBound].

Parameters

theA	coefficient of cos^2(x)
theB	coefficient of cos(x)*sin(x) (equation uses 2*b)
theC	coefficient of cos(x)
theD	coefficient of sin(x)
theE	constant term
theInfBound	lower bound for roots (default 0)
theSupBound	upper bound for roots (default 2*PI)
theEps	tolerance for coefficient comparison

Returns

TrigResult containing roots in specified interval

TrigonometricCDE()

TrigResult MathRoot::TrigonometricCDE ( double theC, double theD, double theE, double theInfBound = 0.0, double theSupBound = THE_2PI )

inline

Solve trigonometric equation: c*cos(x) + d*sin(x) + e = 0.

Parameters

theC	coefficient of cos(x)
theD	coefficient of sin(x)
theE	constant term
theInfBound	lower bound for roots
theSupBound	upper bound for roots

Returns

TrigResult containing roots

TrigonometricLinear()

TrigResult MathRoot::TrigonometricLinear ( double theD, double theE, double theInfBound = 0.0, double theSupBound = THE_2PI )

inline

Solve linear trigonometric equation: d*sin(x) + e = 0.

Parameters

theD	coefficient of sin(x)
theE	constant term
theInfBound	lower bound for roots
theSupBound	upper bound for roots

Returns

TrigResult containing roots