HMath.API.Convergence¶

Description

Uniform iteration reports retain the best current estimate on an exhausted budget. Input/domain failures use Either; successful execution need not mean numerical convergence. Residuals are finite nonnegative absolute measures.

On this page¶

API	Purpose
StopReason	Stagnation is opt-in and uses an exact-equality caller predicate; it does not reinterpret a small update as proof of a small residual.
ResidualSatisfied	Declaration and type contract below.
IterationLimit	Declaration and type contract below.
Stagnation	Declaration and type contract below.
Convergence	Iteration report retaining the estimate and residual even on a budget/stagnation stop.
Convergence	Declaration and type contract below.
estimate	Best current estimate, retained even when the iteration budget is exhausted.
iterationCount	Number of completed updates; the initial estimate is iteration zero.
finalResidual	Finite nonnegative absolute residual at the returned estimate.
stopReason	ResidualSatisfied,IterationLimit,or Stagnation; successful execution does not itself imply convergence.
IterationOptions	Caller-controlled iteration count and absolute/relative stopping tolerances, validated by iterateUntil.
IterationOptions	Declaration and type contract below.
maximumIterations	Nonnegative maximum number of updates permitted by iterateUntil.
absoluteTolerance	Finite nonnegative absolute stopping threshold.
relativeTolerance	Finite nonnegative tolerance scaled by the initial residual.
defaultIterationOptions	Default iteration budget 1000, absolute tolerance 1e-12, relative tolerance 1e-10.
iterateUntil	Stop at residual <= atol + rtol * initialResidual.
requireConvergence	Given operation name then convergence report, return its estimate only for ResidualSatisfied.
resultMaybe	Explicitly discard error details for callers retaining a Maybe interface.
fromMaybeError	Given error value then Maybe result, convert Nothing to Left error and Just x to Right x.
Converged	Read-only successful view.

Documentation

StopReason

data StopReason Source #

Stagnation is opt-in and uses an exact-equality caller predicate; it does not reinterpret a small update as proof of a small residual.

Constructors

ResidualSatisfied
IterationLimit
Stagnation

Instances

Instances details

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

Convergence

data Convergence a Source #

Iteration report retaining the estimate and residual even on a budget/stagnation stop. Inspect stopReason before assuming convergence.

Constructors

Convergence

Fields

estimate :: a
Best current estimate, retained even when the iteration budget is exhausted.
iterationCount :: !Int
Number of completed updates; the initial estimate is iteration zero.
finalResidual :: !Double
Finite nonnegative absolute residual at the returned estimate.
stopReason :: !StopReason
ResidualSatisfied,IterationLimit,or Stagnation; successful execution does not itself imply convergence.

Instances

Instances details

Functor Convergence Source #
Instance details Defined in HMath.API.Convergence Methods fmap :: (a -> b) -> Convergence a -> Convergence b # (<$) :: a -> Convergence b -> Convergence a #
Foldable Convergence Source #
Instance details Defined in HMath.API.Convergence Methods fold :: Monoid m => Convergence m -> m # foldMap :: Monoid m => (a -> m) -> Convergence a -> m # foldMap' :: Monoid m => (a -> m) -> Convergence a -> m # foldr :: (a -> b -> b) -> b -> Convergence a -> b # foldr' :: (a -> b -> b) -> b -> Convergence a -> b # foldl :: (b -> a -> b) -> b -> Convergence a -> b # foldl' :: (b -> a -> b) -> b -> Convergence a -> b # foldr1 :: (a -> a -> a) -> Convergence a -> a # foldl1 :: (a -> a -> a) -> Convergence a -> a # toList :: Convergence a -> [a] # null :: Convergence a -> Bool # length :: Convergence a -> Int # elem :: Eq a => a -> Convergence a -> Bool # maximum :: Ord a => Convergence a -> a # minimum :: Ord a => Convergence a -> a # sum :: Num a => Convergence a -> a # product :: Num a => Convergence a -> a #
Traversable Convergence Source #
Instance details Defined in HMath.API.Convergence Methods traverse :: Applicative f => (a -> f b) -> Convergence a -> f (Convergence b) # sequenceA :: Applicative f => Convergence (f a) -> f (Convergence a) # mapM :: Monad m => (a -> m b) -> Convergence a -> m (Convergence b) # sequence :: Monad m => Convergence (m a) -> m (Convergence a) #
Show a => Show (Convergence a) Source #
Instance details Defined in HMath.API.Convergence Methods showsPrec :: Int -> Convergence a -> ShowS # show :: Convergence a -> String # showList :: [Convergence a] -> ShowS #
Eq a => Eq (Convergence a) Source #
Instance details Defined in HMath.API.Convergence Methods (==) :: Convergence a -> Convergence a -> Bool # (/=) :: Convergence a -> Convergence a -> Bool #

IterationOptions

data IterationOptions Source #

Caller-controlled iteration count and absolute/relative stopping tolerances, validated by iterateUntil.

Constructors

IterationOptions
Fields maximumIterations :: !Int Nonnegative maximum number of updates permitted by iterateUntil. absoluteTolerance :: !Double Finite nonnegative absolute stopping threshold. relativeTolerance :: !Double Finite nonnegative tolerance scaled by the initial residual.

Instances

Instances details

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

defaultIterationOptions

defaultIterationOptions :: IterationOptions Source #

Default iteration budget 1000, absolute tolerance 1e-12, relative tolerance 1e-10. Use record updates to configure a solver; iterateUntil validates nonnegative finite tolerances.

iterateUntil

iterateUntil :: IterationOptions -> (a -> Either MathError a) -> (a -> Either MathError Double) -> (a -> a -> Bool) -> a -> Either MathError (Convergence a) Source #

Stop at residual <= atol + rtol * initialResidual. Comparisons are scaled to avoid overflow in that sum. The initial value is tested at iteration zero.

requireConvergence

requireConvergence :: String -> Convergence a -> Either MathError a Source #

Given operation name then convergence report, return its estimate only for ResidualSatisfied. IterationLimit or Stagnation becomes Left (NonConvergence name iterationCount), preserving the distinction between execution and convergence.

resultMaybe

resultMaybe :: Either e a -> Maybe a Source #

Explicitly discard error details for callers retaining a Maybe interface.

fromMaybeError

fromMaybeError :: e -> Maybe a -> Either e a Source #

Given error value then Maybe result, convert Nothing to Left error and Just x to Right x. Example: fromMaybeError "missing" (Just 3) == Right 3.

Converged

pattern Converged :: a -> Convergence a Source #

Read-only successful view. The report still retains its residual and count.