You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@commons.apache.org by lu...@apache.org on 2015/07/27 21:43:58 UTC
svn commit: r959804 -
/websites/production/commons/content/proper/commons-math/userguide/leastsquares.html
Author: luc
Date: Mon Jul 27 19:43:57 2015
New Revision: 959804
Log:
new chapter in the userguide
Added:
websites/production/commons/content/proper/commons-math/userguide/leastsquares.html (with props)
Added: websites/production/commons/content/proper/commons-math/userguide/leastsquares.html
==============================================================================
--- websites/production/commons/content/proper/commons-math/userguide/leastsquares.html (added)
+++ websites/production/commons/content/proper/commons-math/userguide/leastsquares.html Mon Jul 27 19:43:57 2015
@@ -0,0 +1,762 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 27 July 2015
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20150727" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Math – The Commons Math User Guide - Least squares</title>
+
+ <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
+ <link rel="stylesheet" href="../css/site.css" type="text/css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+ <script type="text/javascript" src="../js/jquery.min.js"></script>
+ <script type="text/javascript" src="../js/bootstrap.min.js"></script>
+ <script type="text/javascript" src="../js/prettify.min.js"></script>
+ <script type="text/javascript" src="../js/site.js"></script>
+
+
+<script src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
+<link rel="stylesheet" type="text/css" href="../css/prettify.css" media="all"/>
+ </head>
+
+ <body class="composite">
+ <a href="http://commons.apache.org/" id="bannerLeft" title="Apache Commons logo">
+ <img class="logo-left" src="../images/commons-logo.png" alt="Apache Commons logo"/>
+ </a>
+ <a href="../index.html" id="bannerRight">
+ <img class="logo-right" src="../images/math.gif" alt="Commons Math"/>
+ </a>
+ <div class="clear"></div>
+
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container-fluid">
+ <a class="brand" href="http://commons.apache.org/proper/commons-math/">Apache Commons Math ™</a>
+ <ul class="nav">
+
+ <li id="publishDate">Last Published: 27 July 2015</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 3.6-SNAPSHOT</li>
+ </ul>
+ <div class="pull-right"> <ul class="nav">
+ <li>
+ <a href="http://www.apachecon.com/" class="externalLink" title="ApacheCon">
+ ApacheCon</a>
+ </li>
+ <li>
+ <a href="http://www.apache.org" class="externalLink" title="Apache">
+ Apache</a>
+ </li>
+ <li>
+ <a href="../../../" title="Commons">
+ Commons</a>
+ </li>
+ </ul>
+</div>
+ </div>
+ </div>
+ </div>
+
+ <div class="container-fluid">
+ <table class="layout-table">
+ <tr>
+ <td class="sidebar">
+ <div class="well sidebar-nav">
+ <ul class="nav nav-list">
+ <li class="nav-header">Math</li>
+ <li class="none">
+ <a href="../index.html" title="Overview">
+ Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/download_math.cgi" title="Downloads">
+ Downloads</a>
+ </li>
+ <li class="none">
+ <a href="../apidocs/index.html" title="Latest API docs (development)">
+ Latest API docs (development)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.5/index.html" title="Javadoc (3.5 release)">
+ Javadoc (3.5 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.4.1/index.html" title="Javadoc (3.4.1 release)">
+ Javadoc (3.4.1 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.4/index.html" title="Javadoc (3.4 release)">
+ Javadoc (3.4 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.3/index.html" title="Javadoc (3.3 release)">
+ Javadoc (3.3 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.2/index.html" title="Javadoc (3.2 release)">
+ Javadoc (3.2 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.1.1/index.html" title="Javadoc (3.1.1 release)">
+ Javadoc (3.1.1 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.1/index.html" title="Javadoc (3.1 release)">
+ Javadoc (3.1 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-3.0/index.html" title="Javadoc (3.0 release)">
+ Javadoc (3.0 release)</a>
+ </li>
+ <li class="none">
+ <a href="../../../math/javadocs/api-2.2/index.html" title="Javadoc (2.2 release)">
+ Javadoc (2.2 release)</a>
+ </li>
+ <li class="none">
+ <a href="../issue-tracking.html" title="Issue Tracking">
+ Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="http://git-wip-us.apache.org/repos/asf/commons-math.git" class="externalLink" title="Source Repository (current)">
+ Source Repository (current)</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/commons/Math" class="externalLink" title="Wiki">
+ Wiki</a>
+ </li>
+ <li class="none">
+ <a href="../developers.html" title="Developers Guide">
+ Developers Guide</a>
+ </li>
+ <li class="none">
+ <a href="../proposal.html" title="Proposal">
+ Proposal</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-book"></i>User Guide</li>
+ <li class="none">
+ <a href="../userguide/index.html" title="Contents">
+ Contents</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/overview.html" title="Overview">
+ Overview</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/stat.html" title="Statistics">
+ Statistics</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/random.html" title="Data Generation">
+ Data Generation</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/linear.html" title="Linear Algebra">
+ Linear Algebra</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/analysis.html" title="Numerical Analysis">
+ Numerical Analysis</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/special.html" title="Special Functions">
+ Special Functions</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/utilities.html" title="Utilities">
+ Utilities</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/complex.html" title="Complex Numbers">
+ Complex Numbers</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/distribution.html" title="Distributions">
+ Distributions</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/fraction.html" title="Fractions">
+ Fractions</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/transform.html" title="Transform Methods">
+ Transform Methods</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/geometry.html" title="Geometry">
+ Geometry</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/optimization.html" title="Optimization">
+ Optimization</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/fitting.html" title="Curve Fitting">
+ Curve Fitting</a>
+ </li>
+ <li class="none active">
+ <a href="../userguide/leastsquares.html" title="Least Squares">
+ Least Squares</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/ode.html" title="Ordinary Differential Equations">
+ Ordinary Differential Equations</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/genetics.html" title="Genetic Algorithms">
+ Genetic Algorithms</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/filter.html" title="Filters">
+ Filters</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/ml.html" title="Machine Learning">
+ Machine Learning</a>
+ </li>
+ <li class="none">
+ <a href="../userguide/exceptions.html" title="Exceptions">
+ Exceptions</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header"><i class="icon-info-sign"></i>Project Documentation</li>
+ <li class="collapsed">
+ <a href="../project-info.html" title="Project Information">
+ Project Information</a>
+ </li>
+ <li class="collapsed">
+ <a href="../project-reports.html" title="Project Reports">
+ Project Reports</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">Commons</li>
+ <li class="none">
+ <a href="../../../" title="Home">
+ Home</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/licenses/" class="externalLink" title="License">
+ License</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../components.html" title="Components">
+ Components</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../sandbox/index.html" title="Sandbox">
+ Sandbox</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../../dormant/index.html" title="Dormant">
+ Dormant</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">General Information</li>
+ <li class="none">
+ <a href="../security.html" title="Security">
+ Security</a>
+ </li>
+ <li class="none">
+ <a href="../../../volunteering.html" title="Volunteering">
+ Volunteering</a>
+ </li>
+ <li class="none">
+ <a href="../../../patches.html" title="Contributing Patches">
+ Contributing Patches</a>
+ </li>
+ <li class="none">
+ <a href="../../../building.html" title="Building Components">
+ Building Components</a>
+ </li>
+ <li class="none">
+ <a href="../../../commons-parent-pom.html" title="Commons Parent Pom">
+ Commons Parent Pom</a>
+ </li>
+ <li class="none">
+ <a href="../../../build-plugin/index.html" title="Commons Build Plugin">
+ Commons Build Plugin</a>
+ </li>
+ <li class="none">
+ <a href="../../../releases/index.html" title="Releasing Components">
+ Releasing Components</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/commons/FrontPage" class="externalLink" title="Wiki">
+ Wiki</a>
+ </li>
+ </ul>
+ <ul class="nav nav-list">
+ <li class="nav-header">ASF</li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How the ASF works">
+ How the ASF works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">
+ Get Involved</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/dev/" class="externalLink" title="Developer Resources">
+ Developer Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">
+ Sponsorship</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">
+ Thanks</a>
+ </li>
+ </ul>
+ </div>
+ <div id="poweredBy">
+ <a href="http://www.apache.org/events/current-event.html" title="ApacheCon" class="builtBy">
+ <img class="builtBy" alt="ApacheCon" src="http://www.apache.org/events/current-event-125x125.png" />
+ </a>
+ <a href="http://maven.apache.org/" title="Maven" class="builtBy">
+ <img class="builtBy" alt="Maven" src="http://maven.apache.org/images/logos/maven-feather.png" />
+ </a>
+ </div>
+ </td>
+ <td class="content">
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License. -->
+
+
+ <div class="section">
+<h2><a name="a14_Least_squares"></a>14 Least squares</h2>
+
+<div class="section">
+<h3><a name="a14.1_Overview"></a>14.1 Overview</h3>
+
+<p>
+ The least squares package fits a parametric model to a set of observed
+ values by minimizing a cost function with a specific form.
+ The fitting basically consists in finding the values
+ for some parameters p<sub>k</sub> such that a cost function
+ J = sum(w<sub>i</sub>(target<sub>i</sub> - model<sub>i</sub>)<sup>2</sup>) is
+ minimized. The various (target<sub>i</sub> - model<sub>i</sub>(p<sub>k</sub>))
+ terms are called residuals. They represent the deviation between a set of
+ target values target<sub>i</sub> and theoretical values computed from
+ models model<sub>i</sub> depending on free parameters p<sub>k</sub>.
+ The w<sub>i</sub> factors are weights. One classical use case is when the
+ target values are experimental observations or measurements.
+ </p>
+
+<p>
+ Two engines devoted to least-squares problems are available. The first one is
+ based on the <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/GaussNewtonOptimizer.html">
+ Gauss-Newton</a> method. The second one is the <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LevenbergMarquardtOptimizer.html">
+ Levenberg-Marquardt</a> method.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.2_LeastSquaresBuilder_and_LeastSquaresFactory"></a>14.2 LeastSquaresBuilder and LeastSquaresFactory</h3>
+
+
+<p>
+ In order to solve a least-squares fitting problem, the user must provide the following elements:
+ </p>
+<ul>
+
+<li>a mean to evaluate all the components of the model for a given set of parameters:
+ model<sub>i</sub> = f<sub>i</sub>(p<sub>1</sub>, p<sub>2</sub>, ... p<sub>k</sub>),
+ this is code</li>
+
+<li>the target (or observed) components: target<sub>i</sub>, this is data</li>
+
+<li>the start values for all p<sub>k</sub> parameters: s<sub>k</sub>, this is data</li>
+
+<li>optionally a validator for the p<sub>k</sub> parameters, this is code</li>
+
+<li>optionally the weight for sample point i: w<sub>i</sub>, this is data and defaults to 1.0 if not provided</li>
+
+<li>a maximum number of iterations, this is data</li>
+
+<li>a maximum number of evaluations, this is data</li>
+
+<li>a convergence criterion, this is code</li>
+ </ul>
+
+
+<p>
+ The elements of the list above can be provided as an implementation of the
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.html">
+ LeastSquaresProblem</a> interface. However, this is cumbersome to do directly, so some helper
+ classes are available. The first helper is a mutable builder:
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresBuilder.html">
+ LeastSquaresBuilder</a>. The second helper is an utility factory:
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresFactory.html">
+ LeastSquaresFactory</a>.
+ </p>
+
+<p>
+ The builder class is better suited when setting the various elements of the least squares
+ problem is done progressively in different places in the user code. In this case, the user
+ would create first an empty builder andconfigure it progressively by calling its methods
+ (<tt>start</tt>, <tt>target</tt>, <tt>model</tt>, ...). Once the configuration
+ is complete, calling the <tt>build</tt> method would create the least squares problem.
+ </p>
+
+<p>
+ The factory utility is better suited when the various elements of the least squares
+ problem are all known at one place and the problem can be built in just one sweep, calling
+ to one of the static <tt>LeastSquaresFactory.create</tt> method.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.3_Model_Function"></a>14.3 Model Function</h3>
+
+<p>
+ The model function is used by the least squares engine to evaluate the model components
+ model<sub>i</sub> given some test parameters p<sub>k</sub>. It is therefore a multivariate
+ function (it depends on the various p<sub>k</sub>) and it is vector-valued (it has several
+ components model<sub>i</sub>). There must be exactly one component model<sub>i</sub> for
+ each target (or observed) component target<sub>i</sub>, otherwise some residuals to be
+ squared and summed could not be computed. In order for the problem to be well defined, the
+ number of parameters p<sub>k</sub> must be less than the number of components model<sub>i</sub>.
+ Failing to ensure this may lead to the engine throwing an exception as the underlying linear
+ algebra operations may encounter singular matrices. It is not unusual to have a large number
+ of components (several thousands) and only a dozen parameters. There are no limitations on these
+ numbers, though.
+ </p>
+
+<p>
+ As the least squares engine needs to create Jacobians matrices for the model function, both
+ its value and its derivatives <i>with respect to the p<sub>k</sub> parameters</i> must
+ be available. There are two ways to provide this:
+ </p>
+<ul>
+
+<li>provide one
+ <a href="../apidocs/org/apache/commons/math3/analysis/MultivariateVectorFunction.html">MultivariateVectorFunction</a>
+ instance for computing the components values and one
+ <a href="../apidocs/org/apache/commons/math3/analysis/MultivariateMatrixFunction.html">MultivariateMatrixFunction</a>
+ instance for computing the components derivatives (i.e. the Jacobian matrix) with
+ respect to the parameters,</li>
+
+<li>or provide one
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
+ instance for computing both the components values and their derivatives simultaneously.</li>
+ </ul>
+ The first alternative is best suited for models which are not computationally intensive
+ as it allows more modularized code with one method for each type of computation. The second
+ alternative is best suited for models which are computationally intensive and evaluating
+ both the values and derivatives in one sweep saves a lot of work.
+
+
+<p>
+ The <tt>point</tt> parameter of the <tt>value</tt> methods in the
+ <a href="../apidocs/org/apache/commons/math3/analysis/MultivariateVectorFunction.html">MultivariateVectorFunction</a>,
+ <a href="../apidocs/org/apache/commons/math3/analysis/MultivariateMatrixFunction.html">MultivariateMatrixFunction</a>,
+ or <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
+ interfaces will contain the parameters p<sub>k</sub>. The values will be the model components
+ model<sub>i</sub> and the derivatives will be the derivatives of the model components
+ with respect to the parameters dmodel<sub>i</sub>/dp<sub>k</sub>.
+ </p>
+
+<p>
+ There are no requirements on how to compute value and derivatives. The
+ <a href="../apidocs/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.html">
+ DerivativeStructure</a> class may be useful to compute analytically derivatives in
+ difficult cases, but this class is not mandated by the API which only expects the derivatives
+ as a Jacobian matrix containing primitive double entries.
+ </p>
+
+<p>
+ One non-obvious feature provided by both the builder and the factory is lazy evaluation. This feature
+ allows to defer calls to the model functions until they are really needed by the engine. This
+ can save some calls for engines that evaluate the value and the Jacobians in different loops
+ (this is the case for Levenberg-Marquardt). However, lazy evaluation is possible <i>only</i>
+ if the model functions are themselves separated, i.e. it can be used only with the first
+ alternative above. Setting up the <tt>lazyEvaluation</tt> flag to <tt>true</tt> in the builder
+ or factory and setting up the model function as one
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/MultivariateJacobianFunction.html">MultivariateJacobianFunction</a>
+ instance at the same time will trigger an illegal state exception telling that the model function
+ misses required functionality.
+ </p>
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.4_Parameters_Validation"></a>14.4 Parameters Validation</h3>
+
+<p>
+ In some cases, the model function requires parameters to lie within a specific domain. For example
+ a parameter may be used in a square root and needs to be positive, or another parameter represents
+ the sine of an angle and should be within -1 and +1, or several parameters may need to remain in
+ the unit circle and the sum of their squares must be smaller than 1. The least square solvers available
+ in Apache Commons Math currently don't allow to set up constraints on the parameters. This is a
+ known missing feature. There are two ways to circumvent this.
+ </p>
+
+<p>
+ Both ways are achieved by setting up a
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/ParameterValidator.html">ParameterValidator</a>
+ instance. The input of the value and jacobian model functions will always be the output of
+ the parameter validator if one exists.
+ </p>
+
+<p>
+ One way to constrain parameters is to use a continuous mapping between the parameters that the
+ least squares solver will handle and the real parameters of the mathematical model. Using mapping
+ functions like <tt>logit</tt> and <tt>sigmoid</tt>, one can map a finite range to the
+ infinite real line. Using mapping functions based on <tt>log</tt> and <tt>exp</tt>, one
+ can map a semi-infinite range to the infinite real line. It is possible to use such a mapping so
+ that the engine will always see unbounded parameters, whereas on the other side of the mapping the
+ mathematical model will always see parameters mapped correctly to the expected range. Care must be
+ taken with derivatives as one must remember that the parameters have been mapped. Care must also
+ be taken with convergence status. This may be tricky.
+ </p>
+
+<p>
+ Another way to constrain parameters is to simply truncate the parameters back to the domain when
+ one search point escapes from it and not care about derivatives. This works <i>only</i> if the
+ solution is expected to be inside the domain and not at the boundary, as points out of the domain
+ will only be temporary test points with a cost function higher than the real solution and will soon
+ be dropped by the underlying engine. As a rule of thumb, these conditions are met only when the
+ domain boundaries correspond to unrealistic values that will never be achieved (null distances,
+ negative masses, ...) but they will not be met when the domain boundaries are more operational
+ limits (a maximum weight that can be handled by a device, a minimum temperature that can be
+ sustained by an instrument, ...).
+ </p>
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.5_Tuning"></a>14.5 Tuning</h3>
+
+<p>
+ Among the elements to be provided to the least squares problem builder or factory
+ are some tuning parameters for the solver.
+ </p>
+
+<p>
+ The maximum number of iterations refers to the engine algorithm main loop, whereas the
+ maximum number of iterations refers to the number of calls to the model method. Some
+ algorithms (like Levenberg-Marquardt) have two embedded loops, with iteration number
+ being incremented at outer loop level, but a new evaluation being done at each inner
+ loop. In this case, the number of evaluations will be greater than the number of iterations.
+ Other algorithms (like Gauss-Newton) have only one level of loops. In this case, the
+ number of evaluations will equal to the number of iterations. In any case, the maximum
+ numbers are really only intended as safeguard to prevent infinite loops, so the exact
+ value of the limit is not important so it is common to select some almost arbitrary number
+ much larger than the expected number of evaluations and use it for both
+ <tt>maxIterations</tt> and <tt>maxEvaluations</tt>. As an example, if the least
+ squares solver usually finds a solution in 50 iterations, setting a maximum value to 1000
+ is probably safe and prevents infinite loops. If the least squares solver needs several
+ hundreds of evaluations, it would probably be safer to set the maximum value to 10000 or
+ even 1000000 to avoid failures in slightly more demanding cases. Very fine tuning of
+ these maximum numbers is often worthless, they are only intended as safeguards.
+ </p>
+
+<p>
+ Convergence checking is delegated to a dedicated interface from the <tt>optim</tt>
+ package: <a href="../apidocs/org/apache/commons/math3/optim/ConvergenceChecker.html">
+ ConvergenceChecker</a>, parameterized with either the specific
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
+ class used for least squares problems or the general
+ <a href="../apidocs/org/apache/commons/math3/optim/PointVectorValuePair.html">PointVectorValuePair</a>.
+ Each time convergence is checked, both the previous
+ and the current evaluations of the least squares problem are provided, so the checker can
+ compare them and decide whereas convergence has been reached or not. The predefined convergence
+ checker implementations that can be useful for least squares fitting are:
+ </p>
+<ul>
+
+<li><a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/EvaluationRmsChecker.html">EvaluationRmsChecker</a>,
+ which uses only the normalized cost (square-root of the sum of squared of the residuals,
+ divided by the number of measurements),</li>
+
+<li><a href="../apidocs/org/apache/commons/math3/optim/SimpleVectorValueChecker.html">SimpleVectorValueChecker</a>,
+ which uses the model components themselves (<i>not</i> the residuals),</li>
+
+<li><a href="../apidocs/org/apache/commons/math3/optim/SimplePointChecker.html">SimplePointChecker<PointVectorValuePair></a>,
+ which uses the parameters.</li>
+ </ul>
+ Of course, users can also provide their own implementation of the
+ <a href="../apidocs/org/apache/commons/math3/optim/ConvergenceChecker.html">ConvergenceChecker</a>
+ interface.
+
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.6_Optimization_Engine"></a>14.6 Optimization Engine</h3>
+
+<p>
+ Once the least squares problem has been created, using either the builder or the factory,
+ it is passed to an optimization engine for solving. Two engines devoted to least-squares
+ problems are available. The first one is
+ based on the <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/GaussNewtonOptimizer.html">
+ Gauss-Newton</a> method. The second one is the <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LevenbergMarquardtOptimizer.html">
+ Levenberg-Marquardt</a> method. For both increased readability and in order to leverage
+ possible future changes in the configuration, it is recommended to use the fluent-style API to
+ build and configure the optimizers. This means creating a first temporary version of the optimizer
+ with a default parameterless constructor, and then to set up the various configuration parameters
+ using the available <tt>withXxx</tt> methods that all return a new optimizer instance. Only the
+ final fully configured instance is used. As an example, setting up a Levenberg-Marquardt with
+ all configuration set to default except the cost relative tolerance and parameter relative tolerance
+ would be done as follows:
+ </p>
+
+<div class="source">
+<pre>
+ LeastSquaresOptimizer optimizer = new LevenbergMarquardtOptimizer().
+ withCostRelativeTolerance(1.0e-12).
+ withParameterRelativeTolerance(1.0e-12);
+ </pre></div>
+
+
+<p>
+ As another example, setting up a Gauss-Newton optimizer and forcing the decomposition to SVD (the
+ default is QR decomposition) would be done as follows:
+ </p>
+
+<div class="source">
+<pre>
+ LeastSquaresOptimizer optimizer = new GaussNewtonOptimizer().
+ withwithDecomposition(GaussNewtonOptimizer.Decomposition.QR);
+ </pre></div>
+
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.7_Solving"></a>14.7 Solving</h3>
+
+<p>
+ Solving the least squares problem is done by calling the <tt>optimize</tt> method of the
+ optimizer and passing the least squares problem as the single parameter:
+ </p>
+
+<div class="source">
+<pre>
+ LeastSquaresOptimizer.Optimum optimum = optimizer.optimize(leastSquaresProblem);
+ </pre></div>
+
+
+<p>
+ The <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresOptimizer.Optimum.html">
+ LeastSquaresOptimizer.Optimum</a> class is a specialized
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
+ with additional methods te retrieve the number of evaluations and number of iterations performed.
+ The most important methods are inherited from the
+ <a href="../apidocs/org/apache/commons/math3/fitting/leastsquares/LeastSquaresProblem.Evaluation.html">Evaluation</a>
+ class and correspond to the point (i.e. the parameters), cost, Jacobian, RMS, covariance ...
+ </p>
+ </div>
+
+
+<div class="section">
+<h3><a name="a14.8_Example"></a>14.8 Example</h3>
+
+<p>
+ The following simple example shows how to find the center of a circle of known radius to
+ to best fit observed 2D points. It is a simplified version of one of the JUnit test cases.
+ In the complete test case, both the circle center and its radius are fitted, here the
+ radius is fixed.
+ </p>
+
+<div class="source">
+<pre>
+ final double radius = 70.0;
+ final Vector2D[] observedPoints = new Vector2D[] {
+ new Vector2D( 30.0, 68.0),
+ new Vector2D( 50.0, -6.0),
+ new Vector2D(110.0, -20.0),
+ new Vector2D( 35.0, 15.0),
+ new Vector2D( 45.0, 97.0)
+ };
+
+ // the model function components are the distances to current estimated center,
+ // they should be as close as possible to the specified radius
+ MultivariateJacobianFunction distancesToCurrentCenter = new MultivariateJacobianFunction() {
+ public Pair<RealVector, RealMatrix> value(final RealVector point) {
+
+ Vector2D center = new Vector2D(point.getEntry(0), point.getEntry(1));
+
+ RealVector value = new ArrayRealVector(observedPoints.length);
+ RealMatrix jacobian = new Array2DRowRealMatrix(observedPoints.length, 2);
+
+ for (int i = 0; i < observedPoints.length; ++i) {
+ Vector2D o = observedPoints[i];
+ double modelI = Vector2D.distance(o, center);
+ value.setEntry(i, modelI);
+ // derivative with respect to p0 = x center
+ jacobian.setEntry(i, 0, (center.getX() - o.getX()) / modelI);
+ // derivative with respect to p1 = y center
+ jacobian.setEntry(i, 1, (center.getX() - o.getX()) / modelI);
+ }
+
+ return new Pair<RealVector, RealMatrix>(value, jacobian);
+
+ }
+ };
+
+ // the target is to have all points at the specified radius from the center
+ double[] prescribedDistances = new double[observedPoints.length];
+ Arrays.fill(prescribedDistances, radius);
+
+ // least squares problem to solve : modeled radius should be close to target radius
+ LeastSquaresProblem problem = new LeastSquaresBuilder().
+ start(new double[] { 100.0, 50.0 }).
+ model(distancesToCurrentCenter).
+ target(prescribedDistances).
+ lazyEvaluation(false).
+ maxEvaluations(1000).
+ maxIterations(1000).
+ build();
+ LeastSquaresOptimizer.Optimum optimum = new LevenbergMarquardtOptimizer().optimize(problem);
+ Vector2D fittedCenter = new Vector2D(optimum.getPoint().getEntry(0), optimum.getPoint().getEntry(1));
+ System.out.println("fitted center: " + fittedCenter.getX() + " " + fittedCenter.getY());
+ System.out.println("RMS: " + optimum.getRMS());
+ System.out.println("evaluations: " + optimum.getEvaluations());
+ System.out.println("iterations: " + optimum.getIterations());
+ </pre></div>
+ </div>
+
+ </div>
+
+
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="footer">
+ <p>Copyright © 2003-2015
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ All Rights Reserved.</p>
+
+<div class="center">Apache Commons, Apache Commons Math, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div>
+ </div>
+ </body>
+
+</html>
Propchange: websites/production/commons/content/proper/commons-math/userguide/leastsquares.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: websites/production/commons/content/proper/commons-math/userguide/leastsquares.html
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision