-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | An implementation of the Levenberg-Marquardt algorithm -- -- The Levenberg-Marquardt algorithm is an iterative technique that finds -- a local minimum of a function that is expressed as the sum of squares -- of nonlinear functions. It has become a standard technique for -- nonlinear least-squares problems and can be thought of as a -- combination of steepest descent and the Gauss-Newton method. When the -- current solution is far from the correct one, the algorithm behaves -- like a steepest descent method: slow, but guaranteed to converge. When -- the current solution is close to the correct solution, it becomes a -- Gauss-Newton method. -- -- Optional box- and linear constraints can be given. Both single and -- double precision floating point types are supported. -- -- The actual algorithm is implemented in a C library which is bundled -- with bindings-levmar which this package depends on. See: -- http://www.ics.forth.gr/~lourakis/levmar/. -- -- All modules are self-contained; i.e. each module re-exports all the -- things you need to work with it. -- -- Also see the levmar-safe package which adds extra type-safety -- on top of this package. -- -- A note regarding the license: -- -- This library depends on bindings-levmar which is bundled together with -- a C library which falls under the GPL. Please be aware of this when -- distributing programs linked with this library. For details see the -- description and license of bindings-levmar. @package levmar @version 0.3 -- | For additional documentation see the documentation of the levmar C -- library which this library is based on: -- http://www.ics.forth.gr/~lourakis/levmar/ module Numeric.LevMar -- | A functional relation describing measurements represented as a -- function from a list of parameters to a list of expected measurements. -- -- -- -- For example: -- -- 
--   hatfldc :: Model Double
--   hatfldc [p0, p1, p2, p3] = [ p0 - 1.0
--                              , p0 - sqrt p1
--                              , p1 - sqrt p2
--                              , p3 - 1.0
--                              ]
--
type Model r = [r] -> [r] -- | The jacobian of the Model function. Expressed as a function -- from a list of parameters to a list of lists which for each expected -- measurement describes the partial derivatives of the parameters. -- -- See: -- http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant -- -- -- -- For example the jacobian of the above hatfldc model is: -- -- 
--   hatfldc_jac :: Jacobian Double
--   hatfldc_jac _ p1 p2 _ = [ [1.0,  0.0,           0.0,           0.0]
--                           , [1.0, -0.5 / sqrt p1, 0.0,           0.0]
--                           , [0.0,  1.0,          -0.5 / sqrt p2, 0.0]
--                           , [0.0,  0.0,           0.0,           1.0]
--                           ]
--
type Jacobian r = [r] -> [[r]] -- | The Levenberg-Marquardt algorithm is overloaded to work on -- Double and Float. class LevMarable r levmar :: LevMarable r => Model r -> Maybe (Jacobian r) -> [r] -> [r] -> Integer -> Options r -> Constraints r -> Either LevMarError ([r], Info r, CovarMatrix r) -- | 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. type LinearConstraints r = ([[r]], [r]) -- | Minimization options data Options r Opts :: r -> r -> r -> r -> r -> Options r -- | Scale factor for initial mu. optScaleInitMu :: Options r -> r -- | Stopping thresholds for ||J^T e||_inf. optStopNormInfJacTe :: Options r -> r -- | Stopping thresholds for ||Dp||_2. optStopNorm2Dp :: Options r -> r -- | Stopping thresholds for ||e||_2. optStopNorm2E :: Options r -> r -- | Step 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. optDelta :: Options r -> r -- | Default minimization options defaultOpts :: Fractional r => Options r data Constraints r Constraints :: Maybe [r] -> Maybe [r] -> Maybe [r] -> Maybe (LinearConstraints r) -> Constraints r -- | Optional lower bounds lowerBounds :: Constraints r -> Maybe [r] -- | Optional upper bounds upperBounds :: Constraints r -> Maybe [r] -- | Optional weights weights :: Constraints r -> Maybe [r] -- | Optional linear constraints linearConstraints :: Constraints r -> Maybe (LinearConstraints r) -- | Constraints where all fields are Nothing. noConstraints :: Constraints r -- | Information regarding the minimization. data Info r Info :: r -> r -> r -> r -> r -> Integer -> StopReason -> Integer -> Integer -> Integer -> Info r -- | ||e||_2 at initial parameters. infNorm2initE :: Info r -> r -- | ||e||_2 at estimated parameters. infNorm2E :: Info r -> r -- | ||J^T e||_inf at estimated parameters. infNormInfJacTe :: Info r -> r -- | ||Dp||_2 at estimated parameters. infNorm2Dp :: Info r -> r -- | mu/max[J^T J]_ii ] at estimated parameters. infMuDivMax :: Info r -> r -- | Number of iterations. infNumIter :: Info r -> Integer -- | Reason for terminating. infStopReason :: Info r -> StopReason -- | Number of function evaluations. infNumFuncEvals :: Info r -> Integer -- | Number of jacobian evaluations. infNumJacobEvals :: Info r -> Integer -- | Number of linear systems solved, i.e. attempts for reducing error. infNumLinSysSolved :: Info r -> Integer -- | Reason for terminating. data StopReason -- | Stopped because of small gradient J^T e. SmallGradient :: StopReason -- | Stopped because of small Dp. SmallDp :: StopReason -- | Stopped because maximum iterations was reached. MaxIterations :: StopReason -- | Stopped because of singular matrix. Restart from current estimated -- parameters with increased optScaleInitMu. SingularMatrix :: StopReason -- | Stopped because no further error reduction is possible. Restart with -- increased optScaleInitMu. SmallestError :: StopReason -- | Stopped because of small ||e||_2. SmallNorm2E :: StopReason -- | Stopped because model function returned invalid values (i.e. NaN or -- Inf). This is a user error. InvalidValues :: StopReason -- | Covariance matrix corresponding to LS solution. type CovarMatrix r = [[r]] data LevMarError -- | Generic error (not one of the others) LevMarError :: LevMarError -- | A call to a lapack subroutine failed in the underlying C levmar -- library. LapackError :: LevMarError -- | At least one lower bound exceeds the upper one. FailedBoxCheck :: LevMarError -- | A call to malloc failed in the underlying C levmar library. MemoryAllocationFailure :: LevMarError -- | The matrix of constraints cannot have more rows than columns. ConstraintMatrixRowsGtCols :: LevMarError -- | Constraints matrix is not of full row rank. ConstraintMatrixNotFullRowRank :: LevMarError -- | Cannot 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. TooFewMeasurements :: LevMarError instance Typeable LevMarError instance Show LevMarError instance Read StopReason instance Show StopReason instance Enum StopReason instance Read r => Read (Info r) instance Show r => Show (Info r) instance Read r => Read (Options r) instance Show r => Show (Options r) instance Exception LevMarError instance LevMarable Double instance LevMarable Float -- | This module provides the Levenberg-Marquardt algorithm specialised for -- curve-fitting. -- -- For additional documentation see the documentation of the levmar C -- library which this library is based on: -- http://www.ics.forth.gr/~lourakis/levmar/ module Numeric.LevMar.Fitting -- | A functional relation describing measurements represented as a -- function from a list of parameters and an x-value to an expected -- measurement. -- -- -- -- 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 Model r a = [r] -> (a -> r) -- | This type synonym expresses that usually the a in -- Model r a equals the type of the parameters. type SimpleModel r = Model r r -- | 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 -- -- -- -- 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 Jacobian r a = [r] -> (a -> [r]) -- | This type synonym expresses that usually the a in -- Jacobian r a equals the type of the parameters. type SimpleJacobian r = Jacobian r r -- | The Levenberg-Marquardt algorithm is overloaded to work on -- Double and Float. class LevMarable r -- | The Levenberg-Marquardt algorithm specialised for curve-fitting. levmar :: LevMarable r => Model r a -> Maybe (Jacobian r a) -> [r] -> [(a, r)] -> Integer -> Options r -> Constraints r -> Either LevMarError ([r], Info r, CovarMatrix r) -- | 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. type LinearConstraints r = ([[r]], [r]) -- | Minimization options data Options r Opts :: r -> r -> r -> r -> r -> Options r -- | Scale factor for initial mu. optScaleInitMu :: Options r -> r -- | Stopping thresholds for ||J^T e||_inf. optStopNormInfJacTe :: Options r -> r -- | Stopping thresholds for ||Dp||_2. optStopNorm2Dp :: Options r -> r -- | Stopping thresholds for ||e||_2. optStopNorm2E :: Options r -> r -- | Step 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. optDelta :: Options r -> r -- | Default minimization options defaultOpts :: Fractional r => Options r -- | Information regarding the minimization. data Info r Info :: r -> r -> r -> r -> r -> Integer -> StopReason -> Integer -> Integer -> Integer -> Info r -- | ||e||_2 at initial parameters. infNorm2initE :: Info r -> r -- | ||e||_2 at estimated parameters. infNorm2E :: Info r -> r -- | ||J^T e||_inf at estimated parameters. infNormInfJacTe :: Info r -> r -- | ||Dp||_2 at estimated parameters. infNorm2Dp :: Info r -> r -- | mu/max[J^T J]_ii ] at estimated parameters. infMuDivMax :: Info r -> r -- | Number of iterations. infNumIter :: Info r -> Integer -- | Reason for terminating. infStopReason :: Info r -> StopReason -- | Number of function evaluations. infNumFuncEvals :: Info r -> Integer -- | Number of jacobian evaluations. infNumJacobEvals :: Info r -> Integer -- | Number of linear systems solved, i.e. attempts for reducing error. infNumLinSysSolved :: Info r -> Integer -- | Reason for terminating. data StopReason -- | Stopped because of small gradient J^T e. SmallGradient :: StopReason -- | Stopped because of small Dp. SmallDp :: StopReason -- | Stopped because maximum iterations was reached. MaxIterations :: StopReason -- | Stopped because of singular matrix. Restart from current estimated -- parameters with increased optScaleInitMu. SingularMatrix :: StopReason -- | Stopped because no further error reduction is possible. Restart with -- increased optScaleInitMu. SmallestError :: StopReason -- | Stopped because of small ||e||_2. SmallNorm2E :: StopReason -- | Stopped because model function returned invalid values (i.e. NaN or -- Inf). This is a user error. InvalidValues :: StopReason -- | Covariance matrix corresponding to LS solution. type CovarMatrix r = [[r]] data LevMarError -- | Generic error (not one of the others) LevMarError :: LevMarError -- | A call to a lapack subroutine failed in the underlying C levmar -- library. LapackError :: LevMarError -- | At least one lower bound exceeds the upper one. FailedBoxCheck :: LevMarError -- | A call to malloc failed in the underlying C levmar library. MemoryAllocationFailure :: LevMarError -- | The matrix of constraints cannot have more rows than columns. ConstraintMatrixRowsGtCols :: LevMarError -- | Constraints matrix is not of full row rank. ConstraintMatrixNotFullRowRank :: LevMarError -- | Cannot 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. TooFewMeasurements :: LevMarError