-- 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 <tt>bindings-levmar</tt> which this package depends on. See:
--   <a>http://www.ics.forth.gr/~lourakis/levmar/</a>.
--   
--   A note regarding the license:
--   
--   This library depends on <tt>bindings-levmar</tt> 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 <tt>bindings-levmar</tt>.
@package levmar
@version 1.1


-- | For additional documentation see the documentation of the levmar C
--   library which this library is based on:
--   <a>http://www.ics.forth.gr/~lourakis/levmar/</a>
module Numeric.LevMar

-- | A functional relation describing measurements represented as a
--   function from a vector of parameters to a vector of expected
--   measurements.
--   
--   <ul>
--   <li>Ensure that the length of the parameters vector equals the length
--   of the initial parameters vector in <a>levmar</a>.</li>
--   <li>Ensure that the length of the ouput vector equals the length of
--   the samples vector in <a>levmar</a>.</li>
--   </ul>
type Model r = Vector r -> Vector r

-- | The jacobian of the <a>Model</a> function. Expressed as a function
--   from a vector of parameters to a matrix which for each expected
--   measurement describes the partial derivatives of the parameters.
--   
--   See:
--   <a>http://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant</a>
--   
--   <ul>
--   <li>Ensure that the length of the parameter vector equals the length
--   of the initial parameter vector in <a>levmar</a>.</li>
--   <li>Ensure that the output matrix has the dimension
--   <tt>n&gt;&lt;m</tt> where <tt>n</tt> is the number of samples and
--   <tt>m</tt> is the number of parameters.</li>
--   </ul>
type Jacobian r = Vector r -> Matrix r

-- | The Levenberg-Marquardt algorithm is overloaded to work on
--   <a>Double</a> and <a>Float</a>.
class LevMarable r
levmar :: LevMarable r => Model r -> Maybe (Jacobian r) -> Vector r -> Vector r -> Int -> Options r -> Constraints r -> Either LevMarError (Vector r, Info r, Matrix r)

-- | Minimization options
data Options r
Opts :: !r -> !r -> !r -> !r -> !r -> Options r

-- | Scale factor for initial <i>mu</i>.
optScaleInitMu :: Options r -> !r

-- | Stopping thresholds for <tt>||J^T e||_inf</tt>.
optStopNormInfJacTe :: Options r -> !r

-- | Stopping thresholds for <tt>||Dp||_2</tt>.
optStopNorm2Dp :: Options r -> !r

-- | Stopping thresholds for <tt>||e||_2</tt>.
optStopNorm2E :: Options r -> !r

-- | Step used in the difference approximation to the Jacobian. If
--   <tt>optDelta&lt;0</tt>, 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

-- | Ensure that these vectors have the same length as the number of
--   parameters.
data Constraints r
Constraints :: !Maybe (Vector r) -> !Maybe (Vector r) -> !Maybe (Vector r) -> !Maybe (LinearConstraints r) -> Constraints r

-- | Optional lower bounds
lowerBounds :: Constraints r -> !Maybe (Vector r)

-- | Optional upper bounds
upperBounds :: Constraints r -> !Maybe (Vector r)

-- | Optional weights
weights :: Constraints r -> !Maybe (Vector r)

-- | Optional linear constraints
linearConstraints :: Constraints r -> !Maybe (LinearConstraints r)

-- | Linear constraints consisting of a constraints matrix,
--   <tt>k&gt;&lt;m</tt> and a right hand constraints vector, of length
--   <tt>k</tt> where <tt>m</tt> is the number of parameters and <tt>k</tt>
--   is the number of constraints.
type LinearConstraints r = (Matrix r, Vector r)

-- | Information regarding the minimization.
data Info r
Info :: !r -> !r -> !r -> !r -> !r -> !Int -> !StopReason -> !Int -> !Int -> !Int -> Info r

-- | <tt>||e||_2</tt> at initial parameters.
infNorm2initE :: Info r -> !r

-- | <tt>||e||_2</tt> at estimated parameters.
infNorm2E :: Info r -> !r

-- | <tt>||J^T e||_inf</tt> at estimated parameters.
infNormInfJacTe :: Info r -> !r

-- | <tt>||Dp||_2</tt> at estimated parameters.
infNorm2Dp :: Info r -> !r

-- | <tt>mu/max[J^T J]_ii ]</tt> at estimated parameters.
infMuDivMax :: Info r -> !r

-- | Number of iterations.
infNumIter :: Info r -> !Int

-- | Reason for terminating.
infStopReason :: Info r -> !StopReason

-- | Number of function evaluations.
infNumFuncEvals :: Info r -> !Int

-- | Number of jacobian evaluations.
infNumJacobEvals :: Info r -> !Int

-- | Number of linear systems solved, i.e. attempts for reducing error.
infNumLinSysSolved :: Info r -> !Int

-- | Reason for terminating.
data StopReason

-- | Stopped because of small gradient <tt>J^T e</tt>.
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 <a>optScaleInitMu</a>.
SingularMatrix :: StopReason

-- | Stopped because no further error reduction is possible. Restart with
--   increased <a>optScaleInitMu</a>.
SmallestError :: StopReason

-- | Stopped because of small <tt>||e||_2</tt>.
SmallNorm2E :: StopReason

-- | Stopped because model function returned invalid values (i.e. NaN or
--   Inf). This is a user error.
InvalidValues :: StopReason
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 <tt>malloc</tt> 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 Typeable1 Options
instance Typeable1 Constraints
instance Typeable StopReason
instance Typeable1 Info
instance Typeable LevMarError
instance Read r => Read (Options r)
instance Show r => Show (Options r)
instance (Show r, Element r) => Show (Constraints r)
instance Read StopReason
instance Show StopReason
instance Enum StopReason
instance Read r => Read (Info r)
instance Show r => Show (Info r)
instance Read LevMarError
instance Show LevMarError
instance Exception LevMarError
instance Monoid (Constraints r)
instance LevMarable Double
instance LevMarable Float