casacore
Fitting.h
Go to the documentation of this file.
1 //# Fitting.h: Module for various forms of mathematical fitting
2 //# Copyright (C) 1995,1999-2002,2004
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 #ifndef SCIMATH_FITTING_H
28 #define SCIMATH_FITTING_H
29 
30 #include <casacore/casa/aips.h>
31 #include <casacore/scimath/Fitting/LSQFit.h>
32 #include <casacore/scimath/Fitting/LinearFit.h>
33 #include <casacore/scimath/Fitting/LinearFitSVD.h>
34 #include <casacore/scimath/Fitting/NonLinearFit.h>
35 #include <casacore/scimath/Fitting/NonLinearFitLM.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <module>
40 //
41 // <summary>
42 // Module for various forms of mathematical fitting.
43 // </summary>
44 //
45 // <prerequisite>
46 // <li> Basic principles can be found in
47 // <a href="../notes/224.html">Note 224</a>.
48 // </prerequisite>
49 //
50 // <reviewed reviewer="Neil Killeen" date="2000/06/01"
51 // demos="dLSQFit,dConstraints">
52 // </reviewed>
53 //
54 // <synopsis>
55 //
56 // The Fitting module holds various classes and functions related
57 // to fitting models to data. Currently only least-squares fits
58 // are handled.
59 //
60 // <H3>Least-Squares Fits</H3>
61 //
62 // We are given N data points, which
63 // we will fit to a function with M adjustable parameters.
64 // N should normally be greater than M, and at least M non-dependent relations
65 // between the parameters should be given. In cases where there are less than
66 // M independent points, Singular-Value-Deconvolution methods are available.
67 // Each condition equation can be given an
68 // (estimated) standard deviation, which is comparable to the statistical
69 // weight, which is often used in place of the standard deviation.
70 //
71 // The best fit is assumed to be the one which minimises the 'chi-squared'.
72 //
73 // In the (rather common) case that individual errors are not known for
74 // the individual data points, one can <em>assume</em> that the
75 // individual errors are unity, calculate the best fit function, and then
76 // <em>estimate</em> the errors (assuming they are all identical) by
77 // inverting the <em>normal equations</em>.
78 // Of course, in this case we do not have an independent estimate of
79 // chi<sup>2</sup>.
80 //
81 // The methods used in the Fitting module are described in
82 // <a href="../notes/224.html">Note 224</a>.
83 // The methods (both standard and
84 // SVD) are based on a Cholesky decomposition of the normal equations.
85 //
86 // General background can also be found in <EM>Numerical Recipes</EM> by
87 // Press <EM>et al.</EM>.
88 //
89 // <H3>Linear Least-Squares Fits</H3>
90 //
91 // The <em>linear least squares</em> solution assumes that the fit function
92 // is a linear combination of M linear condition equations.
93 // It is important to note that <em>linear</em> refers to the dependence on
94 // the parameters; the condition equations may be very non-linear in the
95 // dependent arguments.
96 //
97 // The linear least squares problem is solved by explicitly
98 // forming and inverting the normal equations.
99 // If the normal equations are close to
100 // singular, the <em>singular value decomposition</em> (SVD) method may be
101 // used. <em>Numerical Recipes</em> suggests the SVD be always used, however
102 // this advice is not universally accepted.
103 //
104 // <H3>Linear Least-Squares Fits with Known Linear Constraints</H3>
105 //
106 // Sometimes there are not enough independent observations, <EM>i.e.</EM>, the
107 // number of data points <I>N</I> is less than the number of adjustable
108 // parameters <I>M</I>. In this case the least-squares problem cannot be
109 // solved unless additional ``constraints'' on the adjustable parameters can
110 // be introduced. Under other circumstances, we may want to introduce
111 // constraints on the adjustable
112 // parameters to add additional information, <EM>e.g.</EM>, the sum of angles
113 // of a triangle. In more complex cases, the forms of the constraints
114 // are unknown. Here we confine ourselves to
115 // least-squares fit problems in which the forms of constraints are known.
116 //
117 // If the forms of constraint equations are known, the least-squares
118 // problem can be solved. (In the case where not
119 // enough independent observations are available, a minimum number of
120 // sufficient constraint equations have to be provided. The singular value
121 // decomposition method can be used to calculate the minimum number of
122 // orthogonal constraints needed).
123 //
124 // <H3>Nonlinear Least-Squares Fits</H3>
125 //
126 // We now consider the situation where the fitted function
127 // depends <EM>nonlinearly</EM> on the set of
128 // <I>M</I> adjustable parameters.
129 // But with nonlinear dependences the minimisation of chi<sup>2</sup> cannot
130 // proceed as in the linear case.
131 // However, we can <EM>linearise</EM> the problem, find an
132 // approximate solution, and then iteratively seek the minimising solution.
133 // The iteration stops when e.g. the adjusted parameters do not change
134 // anymore. In general it is very difficult to find a general solution that
135 // finds a global minimum, and the solution has to be matched with the problem.
136 // The Levenberg-Marquardt algorithm is a general non-linear fitting method
137 // which can produce correct results in many cases. It has been included, but
138 // always be aware of possible problems with non-linear solutions.
139 //
140 // <H3>What Is Available?</H3>
141 //
142 // The basic classes are <linkto class=LSQFit>LSQFit</linkto> and
143 // <linkto class=LSQaips>LSQaips</linkto>.
144 // They provide the basic framework for normal equation generation, solving
145 // the normal equations and iterating in the case of non-linear equations.
146 //
147 // The <em>LSQFit</em> class uses a native C++ interface (pointers and
148 // iterators). They handle real data and complex data.
149 // The <em>LSQaips</em> class offers the functionality of <em>LSQFit</em>,
150 // but with an additional Casacore Array interface.<br>
151 //
152 // Functionality is
153 // <ol>
154 // <li> Fit a linear combination of functions to data points, and, optionally,
155 // use supplied constraint conditions on the adjustable parameters.
156 // <li> Fit a nonlinear function to data points. The adjustable parameters
157 // are parameters inside the function.
158 // <li> Repetitively perform a linear fit for every line of pixels parallel
159 // to any axis in a Lattice.
160 // <li> Solve (as opposed to fit to a set of data), a set of equations
161 // </ol>
162 //
163 // In addition to the basic Least Squares routines in the <src>LSQFit</src> and
164 // <src>LSQaips</src> classes, this module contains also a set of direct
165 // data fitters:
166 // <ul>
167 // <li> <src>Fit2D</src>
168 // <li> <src>LinearFit</src>
169 // <li> <src>LinearFitSVD</src>
170 // <li> <src>NonLinearFit</src>
171 // <li> <src>NonLinearFitLM</src>
172 // </ul>
173 // Furthermore class <src>LatticeFit</src> can do fitting on lattices.
174 //
175 // Note that the basic functions have <em>LSQ</em> in their title; the
176 // one-step fitting functions <em>Fit</em>.
177 //
178 // The above fitting problems can usually be solved by directly
179 // calling the <src>fit()</src> member function provided by one of the
180 // <src>Fit</src> classes above, or by
181 // gradually building the normal equation matrix and solving the
182 // normal equations (<src>solve()</src>).
183 //
184 // A Distributed Object interface to the classes is available
185 // (<src>DOfitting</src>) for use in the <I>Glish</I> <src>dfit</src>
186 // object, available through the <src>fitting.g</src> script.
187 //
188 // </synopsis>
189 //
190 // <motivation>
191 // This module was motivated by baseline subtraction/continuum fitting in the
192 // first instance.
193 // </motivation>
194 //
195 // <todo asof="2004/09/22">
196 // <li> extend the Fit interface classes to cater for building the
197 // normal equations in parts.
198 // </todo>
199 //
200 // </module>
201 //
202 
203 } //# NAMESPACE CASACORE - END
204 
205 #endif
206 
207 
this file contains all the compiler specific defines
Definition: mainpage.dox:28