commons-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From l..@apache.org
Subject svn commit: r959804 - /websites/production/commons/content/proper/commons-math/userguide/leastsquares.html
Date Mon, 27 Jul 2015 19:43:58 GMT
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 &#x2013; 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 &trade;</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&lt;PointVectorValuePair&gt;</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&lt;RealVector, RealMatrix&gt; 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 &lt; 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&lt;RealVector, RealMatrix&gt;(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(&quot;fitted center: &quot; + fittedCenter.getX() + &quot;
&quot; + fittedCenter.getY());
+  System.out.println(&quot;RMS: &quot;           + optimum.getRMS());
+  System.out.println(&quot;evaluations: &quot;   + optimum.getEvaluations());
+  System.out.println(&quot;iterations: &quot;    + optimum.getIterations());
+        </pre></div>
+      </div>
+
+     </div>
+  
+
+					</td>
+				</tr>
+			</table>
+		</div>
+
+		<div class="footer">
+			<p>Copyright &copy;                    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



Mime
View raw message