levmar-0.2.1: An implementation of the Levenberg-Marquardt algorithmSource codeContentsIndex
LevMar.Intermediate.Fitting.AD
StabilityExperimental
Maintainervandijk.roel@gmail.com, v.dijk.bas@gmail.com
Contents
Model.
Levenberg-Marquardt algorithm.
Minimization options.
Output
Description

A levmar variant specialised for curve-fitting that uses Automatic Differentiation to automatically compute the Jacobian.

For additional documentation see the documentation of the levmar C library which this library is based on: http://www.ics.forth.gr/~lourakis/levmar/

Synopsis
type Model r a = [r] -> a -> r
type SimpleModel r = Model r r
type Jacobian r a = [r] -> a -> [r]
type SimpleJacobian r = Jacobian r r
jacobianOf :: (HasBasis r, Basis r ~ (), VectorSpace (Scalar r)) => Model (r :~> r) a -> Jacobian r a
class LevMarable r
levmar :: forall r a. (HasBasis r, Basis r ~ (), VectorSpace (Scalar r), LevMarable r) => Model (r :~> r) a -> [r] -> [(a, r)] -> Integer -> Options r -> Maybe [r] -> Maybe [r] -> Maybe (LinearConstraints r) -> Maybe [r] -> Either LevMarError ([r], Info r, CovarMatrix r)
type LinearConstraints r = ([[r]], [r])
data Options r = Opts {
optScaleInitMu :: r
optStopNormInfJacTe :: r
optStopNorm2Dp :: r
optStopNorm2E :: r
optDelta :: r
}
defaultOpts :: Fractional r => Options r
data Info r = Info {
infNorm2initE :: r
infNorm2E :: r
infNormInfJacTe :: r
infNorm2Dp :: r
infMuDivMax :: r
infNumIter :: Integer
infStopReason :: StopReason
infNumFuncEvals :: Integer
infNumJacobEvals :: Integer
infNumLinSysSolved :: Integer
}
data StopReason
= SmallGradient
| SmallDp
| MaxIterations
| SingularMatrix
| SmallestError
| SmallNorm2E
| InvalidValues
type CovarMatrix r = [[r]]
data LevMarError
= LevMarError
| LapackError
| FailedBoxCheck
| MemoryAllocationFailure
| ConstraintMatrixRowsGtCols
| ConstraintMatrixNotFullRowRank
| TooFewMeasurements
Model.
type Model r a = [r] -> a -> rSource

A functional relation describing measurements represented as a function from a list of parameters and an x-value to an expected measurement.

  • Ensure that the length of the parameters list equals the lenght of the initial parameters list in levmar.

For example, the quadratic function f(x) = a*x^2 + b*x + c can be written as:

quad :: Num r => Model r r
quad [a, b, c] x = a*x^2 + b*x + c
type SimpleModel r = Model r rSource
This type synonym expresses that usually the a in Model r a equals the type of the parameters.
type Jacobian r a = [r] -> a -> [r]Source

The jacobian of the Model function. Expressed as a function from a list of parameters and an x-value to the partial derivatives of the parameters.

See: http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant

  • Ensure that the length of the parameters list equals the lenght of the initial parameters list in levmar.
  • Ensure that the length of the output parameter derivatives list equals the length of the input parameters list.

For example, the jacobian of the above quad model can be written as:

quadJacob :: Num r => Jacobian N3 r r
quadJacob [_, _, _] x = [ x^2   -- with respect to a
                        , x     -- with respect to b
                        , 1     -- with respect to c
                        ]

Notice you don't have to differentiate for x.

type SimpleJacobian r = Jacobian r rSource
This type synonym expresses that usually the a in Jacobian r a equals the type of the parameters.
jacobianOf :: (HasBasis r, Basis r ~ (), VectorSpace (Scalar r)) => Model (r :~> r) a -> Jacobian r aSource
Compute the Jacobian of the Model using Automatic Differentiation.
Levenberg-Marquardt algorithm.
class LevMarable r Source
The Levenberg-Marquardt algorithm is overloaded to work on Double and Float.
show/hide Instances
levmarSource
:: forall r a . (HasBasis r, Basis r ~ (), VectorSpace (Scalar r), LevMarable r)
=> Model (r :~> r) aModel. Note that ':~>' is overloaded for all the numeric classes.
-> [r]Initial parameters
-> [(a, r)]Samples
-> IntegerMaximum iterations
-> Options rMinimization options
-> Maybe [r]Optional lower bounds
-> Maybe [r]Optional upper bounds
-> Maybe (LinearConstraints r)Optional linear constraints
-> Maybe [r]Optional weights
-> Either LevMarError ([r], Info r, CovarMatrix r)

The Levenberg-Marquardt algorithm specialised for curve-fitting that automatically computes the Jacobian using automatic differentiation of the model function.

Warning: Don't apply levmar to Models that apply methods of the Eq and Ord classes to the parameters. These methods are undefined for ':~>'!!!

type LinearConstraints r = ([[r]], [r])Source
Linear constraints consisting of a constraints matrix, kxm and a right hand constraints vector, kx1 where m is the number of parameters and k is the number of constraints.
Minimization options.
data Options r Source
Minimization options
Constructors
Opts
optScaleInitMu :: rScale factor for initial mu.
optStopNormInfJacTe :: rStopping thresholds for ||J^T e||_inf.
optStopNorm2Dp :: rStopping thresholds for ||Dp||_2.
optStopNorm2E :: rStopping thresholds for ||e||_2.
optDelta :: rStep used in the difference approximation to the Jacobian. If optDelta<0, the Jacobian is approximated with central differences which are more accurate (but slower!) compared to the forward differences employed by default.
show/hide Instances
Show r => Show (Options r)
defaultOpts :: Fractional r => Options rSource
Default minimization options
Output
data Info r Source
Information regarding the minimization.
Constructors
Info
infNorm2initE :: r||e||_2 at initial parameters.
infNorm2E :: r||e||_2 at estimated parameters.
infNormInfJacTe :: r||J^T e||_inf at estimated parameters.
infNorm2Dp :: r||Dp||_2 at estimated parameters.
infMuDivMax :: rmu/max[J^T J]_ii ] at estimated parameters.
infNumIter :: IntegerNumber of iterations.
infStopReason :: StopReasonReason for terminating.
infNumFuncEvals :: IntegerNumber of function evaluations.
infNumJacobEvals :: IntegerNumber of jacobian evaluations.
infNumLinSysSolved :: IntegerNumber of linear systems solved, i.e. attempts for reducing error.
show/hide Instances
Show r => Show (Info r)
data StopReason Source
Reason for terminating.
Constructors
SmallGradientStopped because of small gradient J^T e.
SmallDpStopped because of small Dp.
MaxIterationsStopped because maximum iterations was reached.
SingularMatrixStopped because of singular matrix. Restart from current estimated parameters with increased optScaleInitMu.
SmallestErrorStopped because no further error reduction is possible. Restart with increased optScaleInitMu.
SmallNorm2EStopped because of small ||e||_2.
InvalidValuesStopped because model function returned invalid values (i.e. NaN or Inf). This is a user error.
show/hide Instances
type CovarMatrix r = [[r]]Source
Covariance matrix corresponding to LS solution.
data LevMarError Source
Constructors
LevMarErrorGeneric error (not one of the others)
LapackErrorA call to a lapack subroutine failed in the underlying C levmar library.
FailedBoxCheckAt least one lower bound exceeds the upper one.
MemoryAllocationFailureA call to malloc failed in the underlying C levmar library.
ConstraintMatrixRowsGtColsThe matrix of constraints cannot have more rows than columns.
ConstraintMatrixNotFullRowRankConstraints matrix is not of full row rank.
TooFewMeasurementsCannot solve a problem with fewer measurements than unknowns. In case linear constraints are provided, this error is also returned when the number of measurements is smaller than the number of unknowns minus the number of equality constraints.
show/hide Instances
Produced by Haddock version 2.4.2