HMath.Root¶

Description

Checked Double root solvers. Absolute residual and mixed absolute/relative step tolerances are separate. A small step alone never certifies a root. All function and derivative calls count against the evaluation budget. Sign-changing isolation finds simple roots; exact polynomial Sturm isolation additionally finds even/repeated roots with multiplicity. Callback functions must be deterministic and total on points visited by the chosen method.

On this page¶

API	Purpose
RootOptions	Root-solver iterationevaluation budgets and residualstep tolerances, initialized with defaultRootOptions.
RootOptions	Declaration and type contract below.
rootMaxIterations	Maximum scalar-root iteration count.
rootMaxEvaluations	Maximum scalar function/derivative evaluation budget.
rootTolerance	Requested finite positive residual tolerance.
rootStepTolerance	Requested finite positive parameter-step tolerance.
defaultRootOptions	Default root-solving limits: 200 iterations, 4000 evaluations, residual tolerance 1e-10 and step tolerance 1e-12.
RootResult	Scalar root estimate with residual,optional certified bracket error bound,and work counts.
RootResult	Declaration and type contract below.
rootValue	Returned scalar root estimate.
rootResidual	Absolute function residual at rootValue.
rootErrorBound	Optional bracket-based absolute root error bound; Nothing when the method cannot certify one.
rootIterations	Completed scalar-root iterations.
rootEvaluations	Recorded function/derivative evaluation count.
Bracket	Validated scalar bracketing state used by checked bracketed root solvers; construct through the bracketing API.
bracket	Validate finite a<b and endpoint roots or opposite signs; construction never assumes a discontinuity is a root.
BracketMethod	Bracket-preserving root strategy such as bisection,Brent,Ridder,or regula falsi variants.
Bisection	Declaration and type contract below.
RegulaFalsi	Declaration and type contract below.
Illinois	Declaration and type contract below.
Brent	Declaration and type contract below.
Ridder	Declaration and type contract below.
solveBracket	Brackets are re-evaluated with the supplied function, preventing stale or mismatched endpoint caches from certifying a different function's root.
bracketScan	Evaluate a uniform finite grid under the evaluation budget and return every endpoint/sign-change bracket.
isolateIntervals	Refine sign-change scan brackets and deduplicate endpoint roots.
DerivativeMethod	Derivative-based scalar-root strategy, including Newton,Halley,and Householder methods with their required derivatives.
Newton	Declaration and type contract below.
Halley	Declaration and type contract below.
Householder3	Declaration and type contract below.
solveDerivative	Derivatives [f', f'', f'''] are required through order 1, 2, or 3.
secant	Unbracketed two-point secant iteration; zero slopes, stagnation, and exhausted budgets fail explicitly.
steffensen	Derivative-free Steffensen root update using f(x+f(x)); termination checks the original residual.
FixedPointMethod	Fixed-point acceleration strategy, selecting Picard,Aitken,or Steffensen iteration.
Picard	Declaration and type contract below.
Aitken	Declaration and type contract below.
SteffensenFixed	Declaration and type contract below.
fixedPoint	Picard iteration, non-restarted Aitken sequence acceleration, or restarted Steffensen acceleration.
anderson	Anderson mixing with depth m and Tikhonov regularization.
SystemMethod	Multivariate root strategy, selecting checked Newton or Broyden updates.
MultivariateNewton	Declaration and type contract below.
NewtonTrustRegion	Declaration and type contract below.
Broyden	Declaration and type contract below.
SystemRootResult	Returned multivariate root vector with residual norm and iteration/evaluation counts.
SystemRootResult	Declaration and type contract below.
systemRoot	Returned multivariate root parameter vector.
systemResidual	Norm of the residual function at systemRoot.
systemIterations	Completed nonlinear-system iterations.
systemEvaluations	Recorded system function/evaluation count.
solveSystem	Solve a square analytic-Jacobian system using Newton, trust-radius Newton, or rank-one Broyden updates.
polynomialRoots	Reuse the checked Aberth-Ehrlich simultaneous complex solver for an ascending-coefficient polynomial.
realPolynomialRoots	Use exact square-free factorization and Sturm isolation; return rational intervals and integer multiplicities.

Documentation

RootOptions

data RootOptions Source #

Root-solver iterationevaluation budgets and residualstep tolerances, initialized with defaultRootOptions.

Constructors

RootOptions
Fields rootMaxIterations :: Int Maximum scalar-root iteration count. rootMaxEvaluations :: Int Maximum scalar function/derivative evaluation budget. rootTolerance :: Double Requested finite positive residual tolerance. rootStepTolerance :: Double Requested finite positive parameter-step tolerance.

Instances

Instances details

Show RootOptions Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> RootOptions -> ShowS # show :: RootOptions -> String # showList :: [RootOptions] -> ShowS #
Eq RootOptions Source #
Instance details Defined in HMath.Root Methods (==) :: RootOptions -> RootOptions -> Bool # (/=) :: RootOptions -> RootOptions -> Bool #

defaultRootOptions

defaultRootOptions :: RootOptions Source #

Default root-solving limits: 200 iterations, 4000 evaluations, residual tolerance 1e-10 and step tolerance 1e-12. Solvers validate options and report their own convergence diagnostics.

RootResult

data RootResult Source #

Scalar root estimate with residual,optional certified bracket error bound,and work counts.

Constructors

RootResult
Fields rootValue :: Double Returned scalar root estimate. rootResidual :: Double Absolute function residual at rootValue. rootErrorBound :: Maybe Double Optional bracket-based absolute root error bound; Nothing when the method cannot certify one. rootIterations :: Int Completed scalar-root iterations. rootEvaluations :: Int Recorded function/derivative evaluation count.

Instances

Instances details

Show RootResult Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> RootResult -> ShowS # show :: RootResult -> String # showList :: [RootResult] -> ShowS #
Eq RootResult Source #
Instance details Defined in HMath.Root Methods (==) :: RootResult -> RootResult -> Bool # (/=) :: RootResult -> RootResult -> Bool #

Bracket

data Bracket Source #

Validated scalar bracketing state used by checked bracketed root solvers; construct through the bracketing API.

Instances

Instances details

Show Bracket Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> Bracket -> ShowS # show :: Bracket -> String # showList :: [Bracket] -> ShowS #
Eq Bracket Source #
Instance details Defined in HMath.Root Methods (==) :: Bracket -> Bracket -> Bool # (/=) :: Bracket -> Bracket -> Bool #

bracket

bracket :: (Double -> Double) -> Double -> Double -> Either MathError Bracket Source #

Validate finite a<b and endpoint roots or opposite signs; construction never assumes a discontinuity is a root.

BracketMethod

data BracketMethod Source #

Bracket-preserving root strategy such as bisection,Brent,Ridder,or regula falsi variants.

Constructors

Bisection
RegulaFalsi
Illinois
Brent
Ridder

Instances

Instances details

Show BracketMethod Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> BracketMethod -> ShowS # show :: BracketMethod -> String # showList :: [BracketMethod] -> ShowS #
Eq BracketMethod Source #
Instance details Defined in HMath.Root Methods (==) :: BracketMethod -> BracketMethod -> Bool # (/=) :: BracketMethod -> BracketMethod -> Bool #

solveBracket

solveBracket :: BracketMethod -> RootOptions -> (Double -> Double) -> Bracket -> Either MathError RootResult Source #

Brackets are re-evaluated with the supplied function, preventing stale or mismatched endpoint caches from certifying a different function's root.

bracketScan

bracketScan :: RootOptions -> (Double -> Double) -> Double -> Double -> Int -> Either MathError [Bracket] Source #

Evaluate a uniform finite grid under the evaluation budget and return every endpoint/sign-change bracket.

isolateIntervals

isolateIntervals :: RootOptions -> (Double -> Double) -> Double -> Double -> Int -> Either MathError [RootResult] Source #

Refine sign-change scan brackets and deduplicate endpoint roots. Even roots require polynomial isolation.

DerivativeMethod

data DerivativeMethod Source #

Derivative-based scalar-root strategy, including Newton,Halley,and Householder methods with their required derivatives.

Constructors

Newton
Halley
Householder3

Instances

Instances details

Show DerivativeMethod Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> DerivativeMethod -> ShowS # show :: DerivativeMethod -> String # showList :: [DerivativeMethod] -> ShowS #
Eq DerivativeMethod Source #
Instance details Defined in HMath.Root Methods (==) :: DerivativeMethod -> DerivativeMethod -> Bool # (/=) :: DerivativeMethod -> DerivativeMethod -> Bool #

solveDerivative

solveDerivative :: DerivativeMethod -> RootOptions -> (Double -> Double) -> [Double -> Double] -> Double -> Either MathError RootResult Source #

Derivatives [f', f'', f'''] are required through order 1, 2, or 3. Householder3 is the order-four rational Householder update.

secant

secant :: RootOptions -> (Double -> Double) -> Double -> Double -> Either MathError RootResult Source #

Unbracketed two-point secant iteration; zero slopes, stagnation, and exhausted budgets fail explicitly.

steffensen

steffensen :: RootOptions -> (Double -> Double) -> Double -> Either MathError RootResult Source #

Derivative-free Steffensen root update using f(x+f(x)); termination checks the original residual.

FixedPointMethod

data FixedPointMethod Source #

Fixed-point acceleration strategy, selecting Picard,Aitken,or Steffensen iteration.

Constructors

Picard
Aitken
SteffensenFixed

Instances

Instances details

Show FixedPointMethod Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> FixedPointMethod -> ShowS # show :: FixedPointMethod -> String # showList :: [FixedPointMethod] -> ShowS #
Eq FixedPointMethod Source #
Instance details Defined in HMath.Root Methods (==) :: FixedPointMethod -> FixedPointMethod -> Bool # (/=) :: FixedPointMethod -> FixedPointMethod -> Bool #

fixedPoint

fixedPoint :: FixedPointMethod -> RootOptions -> (Double -> Double) -> Double -> Either MathError RootResult Source #

Picard iteration, non-restarted Aitken sequence acceleration, or restarted Steffensen acceleration.

anderson

anderson :: Int -> Double -> RootOptions -> ([Double] -> [Double]) -> [Double] -> Either MathError SystemRootResult Source #

Anderson mixing with depth m and Tikhonov regularization. Residuals are g(x)-x. Solving the constrained residual Gram system is a bounded reference implementation; it does not pretend to use a low-storage QR update.

SystemMethod

data SystemMethod Source #

Multivariate root strategy, selecting checked Newton or Broyden updates.

Constructors

MultivariateNewton
NewtonTrustRegion Double
Broyden

Instances

Instances details

Show SystemMethod Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> SystemMethod -> ShowS # show :: SystemMethod -> String # showList :: [SystemMethod] -> ShowS #
Eq SystemMethod Source #
Instance details Defined in HMath.Root Methods (==) :: SystemMethod -> SystemMethod -> Bool # (/=) :: SystemMethod -> SystemMethod -> Bool #

SystemRootResult

data SystemRootResult Source #

Returned multivariate root vector with residual norm and iteration/evaluation counts.

Constructors

SystemRootResult
Fields systemRoot :: [Double] Returned multivariate root parameter vector. systemResidual :: Double Norm of the residual function at systemRoot. systemIterations :: Int Completed nonlinear-system iterations. systemEvaluations :: Int Recorded system function/evaluation count.

Instances

Instances details

Show SystemRootResult Source #
Instance details Defined in HMath.Root Methods showsPrec :: Int -> SystemRootResult -> ShowS # show :: SystemRootResult -> String # showList :: [SystemRootResult] -> ShowS #
Eq SystemRootResult Source #
Instance details Defined in HMath.Root Methods (==) :: SystemRootResult -> SystemRootResult -> Bool # (/=) :: SystemRootResult -> SystemRootResult -> Bool #

solveSystem

solveSystem :: SystemMethod -> RootOptions -> ([Double] -> [Double]) -> ([Double] -> [[Double]]) -> [Double] -> Either MathError SystemRootResult Source #

Solve a square analytic-Jacobian system using Newton, trust-radius Newton, or rank-one Broyden updates.

polynomialRoots

polynomialRoots :: RootOptions -> Polynomial (Complex Double) -> Either MathError [Complex Double] Source #

Reuse the checked Aberth-Ehrlich simultaneous complex solver for an ascending-coefficient polynomial.

realPolynomialRoots

realPolynomialRoots :: Int -> Rational -> Polynomial Rational -> Either MathError [(Rational, Rational, Int)] Source #

Use exact square-free factorization and Sturm isolation; return rational intervals and integer multiplicities.