eigen/unsupported/Eigen/NonLinearOptimization

141 lines
5.8 KiB
Plaintext
Raw Normal View History

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2009 Thomas Capricelli <orzel@freehackers.org>
//
// This Source Code Form is subject to the terms of the Mozilla
// Public License v. 2.0. If a copy of the MPL was not distributed
// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
2009-11-09 13:45:27 +08:00
#ifndef EIGEN_NONLINEAROPTIMIZATION_MODULE
#define EIGEN_NONLINEAROPTIMIZATION_MODULE
2010-01-28 06:43:15 +08:00
#include <vector>
#include <Eigen/Core>
#include <Eigen/Jacobi>
2010-01-05 05:45:33 +08:00
#include <Eigen/QR>
#include <unsupported/Eigen/NumericalDiff>
/**
2009-11-09 10:07:36 +08:00
* \defgroup NonLinearOptimization_Module Non linear optimization module
2009-09-28 08:42:19 +08:00
*
2009-11-09 11:52:47 +08:00
* \code
* #include <unsupported/Eigen/NonLinearOptimization>
* \endcode
*
2009-11-09 11:21:45 +08:00
* This module provides implementation of two important algorithms in non linear
* optimization. In both cases, we consider a system of non linear functions. Of
* course, this should work, and even work very well if those functions are
* actually linear. But if this is so, you should probably better use other
* methods more fitted to this special case.
*
2018-07-12 17:56:18 +08:00
* One algorithm allows to find a least-squares solution of such a system
* (Levenberg-Marquardt algorithm) and the second one is used to find
2009-11-09 11:21:45 +08:00
* a zero for the system (Powell hybrid "dogleg" method).
*
2009-11-09 11:52:47 +08:00
* This code is a port of minpack (http://en.wikipedia.org/wiki/MINPACK).
2018-06-07 20:43:02 +08:00
* Minpack is a very famous, old, robust and well renowned package, written in
2009-11-09 11:52:47 +08:00
* fortran. Those implementations have been carefully tuned, tested, and used
* for several decades.
*
2010-01-28 06:43:15 +08:00
* The original fortran code was automatically translated using f2c (http://en.wikipedia.org/wiki/F2c) in C,
2009-11-09 11:52:47 +08:00
* then c++, and then cleaned by several different authors.
* The last one of those cleanings being our starting point :
* http://devernay.free.fr/hacks/cminpack.html
2009-11-09 11:21:45 +08:00
*
* Finally, we ported this code to Eigen, creating classes and API
* coherent with Eigen. When possible, we switched to Eigen
2009-11-11 04:33:36 +08:00
* implementation, such as most linear algebra (vectors, matrices, stable norms).
2009-11-09 11:21:45 +08:00
*
* Doing so, we were very careful to check the tests we setup at the very
2009-11-11 04:33:36 +08:00
* beginning, which ensure that the same results are found.
2009-11-09 11:21:45 +08:00
*
2009-11-09 11:52:47 +08:00
* \section Tests Tests
*
2009-11-11 04:33:36 +08:00
* The tests are placed in the file unsupported/test/NonLinear.cpp.
2009-11-09 11:52:47 +08:00
*
* There are two kinds of tests : those that come from examples bundled with cminpack.
* They guaranty we get the same results as the original algorithms (value for 'x',
* for the number of evaluations of the function, and for the number of evaluations
2018-07-12 17:56:18 +08:00
* of the Jacobian if ever).
2009-11-09 11:52:47 +08:00
*
* Other tests were added by myself at the very beginning of the
2018-07-12 17:56:18 +08:00
* process and check the results for Levenberg-Marquardt using the reference data
2009-11-09 11:52:47 +08:00
* on http://www.itl.nist.gov/div898/strd/nls/nls_main.shtml. Since then i've
2018-06-07 20:43:02 +08:00
* carefully checked that the same results were obtained when modifying the
2009-11-09 11:52:47 +08:00
* code. Please note that we do not always get the exact same decimals as they do,
* but this is ok : they use 128bits float, and we do the tests using the C type 'double',
* which is 64 bits on most platforms (x86 and amd64, at least).
2018-07-12 17:56:18 +08:00
* I've performed those tests on several other implementations of Levenberg-Marquardt, and
2009-11-11 04:33:36 +08:00
* (c)minpack performs VERY well compared to those, both in accuracy and speed.
2009-11-09 11:52:47 +08:00
*
2009-11-11 04:33:36 +08:00
* The documentation for running the tests is on the wiki
* http://eigen.tuxfamily.org/index.php?title=Tests
2009-11-09 11:52:47 +08:00
*
2018-07-12 17:56:18 +08:00
* \section API API: overview of methods
2009-11-09 11:52:47 +08:00
*
2018-07-12 17:56:18 +08:00
* Both algorithms needs a functor computing the Jacobian. It can be computed by
* hand, using auto-differentiation (see \ref AutoDiff_Module), or using numerical
* differences (see \ref NumericalDiff_Module). For instance:
*\code
* MyFunc func;
* NumericalDiff<MyFunc> func_with_num_diff(func);
* LevenbergMarquardt<NumericalDiff<MyFunc> > lm(func_with_num_diff);
* \endcode
* For HybridNonLinearSolver, the method solveNumericalDiff() does the above wrapping for
* you.
2009-11-09 11:52:47 +08:00
*
* The methods LevenbergMarquardt.lmder1()/lmdif1()/lmstr1() and
* HybridNonLinearSolver.hybrj1()/hybrd1() are specific methods from the original
2009-11-11 04:33:36 +08:00
* minpack package that you probably should NOT use until you are porting a code that
2018-07-12 17:56:18 +08:00
* was previously using minpack. They just define a 'simple' API with default values
2009-11-09 11:52:47 +08:00
* for some parameters.
*
2018-07-12 17:56:18 +08:00
* All algorithms are provided using two APIs :
2009-11-11 04:33:36 +08:00
* - one where the user inits the algorithm, and uses '*OneStep()' as much as he wants :
2009-11-09 11:52:47 +08:00
* this way the caller have control over the steps
2009-11-11 04:33:36 +08:00
* - one where the user just calls a method (optimize() or solve()) which will
* handle the loop: init + loop until a stop condition is met. Those are provided for
* convenience.
2009-11-09 11:52:47 +08:00
*
2010-01-27 15:14:50 +08:00
* As an example, the method LevenbergMarquardt::minimize() is
2018-07-12 17:56:18 +08:00
* implemented as follow:
2009-09-28 08:42:19 +08:00
* \code
2010-01-27 15:14:50 +08:00
* Status LevenbergMarquardt<FunctorType,Scalar>::minimize(FVectorType &x, const int mode)
2009-11-09 11:52:47 +08:00
* {
2010-01-27 15:14:50 +08:00
* Status status = minimizeInit(x, mode);
* do {
* status = minimizeOneStep(x, mode);
* } while (status==Running);
2009-11-09 11:52:47 +08:00
* return status;
* }
2009-09-28 08:42:19 +08:00
* \endcode
2009-11-09 11:52:47 +08:00
*
2010-01-27 15:14:50 +08:00
* \section examples Examples
*
* The easiest way to understand how to use this module is by looking at the many examples in the file
* unsupported/test/NonLinearOptimization.cpp.
*/
2009-11-09 11:21:45 +08:00
#ifndef EIGEN_PARSED_BY_DOXYGEN
#include "src/NonLinearOptimization/qrsolv.h"
#include "src/NonLinearOptimization/r1updt.h"
#include "src/NonLinearOptimization/r1mpyq.h"
#include "src/NonLinearOptimization/rwupdt.h"
#include "src/NonLinearOptimization/fdjac1.h"
#include "src/NonLinearOptimization/lmpar.h"
#include "src/NonLinearOptimization/dogleg.h"
#include "src/NonLinearOptimization/covar.h"
#include "src/NonLinearOptimization/chkder.h"
2009-11-09 11:21:45 +08:00
#endif
#include "src/NonLinearOptimization/HybridNonLinearSolver.h"
#include "src/NonLinearOptimization/LevenbergMarquardt.h"
2009-11-09 13:45:27 +08:00
#endif // EIGEN_NONLINEAROPTIMIZATION_MODULE