casacore
Loading...
Searching...
No Matches
Chebyshev.h
Go to the documentation of this file.
1//# Chebyshev.h A function class that defines a Chebyshev polynomial
2//# Copyright (C) 2000,2001,2002,2003,2005
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: casa-feedback@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//#! ========================================================================
27
28#ifndef SCIMATH_CHEBYSHEV_H
29#define SCIMATH_CHEBYSHEV_H
30
31#include <casacore/casa/aips.h>
32#include <casacore/scimath/Functionals/ChebyshevParam.h>
33#include <casacore/scimath/Functionals/Function1D.h>
34#include <casacore/scimath/Mathematics/AutoDiff.h>
35#include <casacore/scimath/Mathematics/AutoDiffMath.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40
41// <summary> A function class that defines a Chebyshev polynomial
42// </summary>
43
44// <use visibility=export>
45
46// <reviewed reviewer="wbrouw" date="2001/11/12" tests="tChebyshev" demos="">
47// </reviewed>
48
49// <prerequisite>
50// <li> <linkto class=Function>Function</linkto>
51// </prerequisite>
52//
53// <etymology>
54// This class is named after Chebyshev Type I polynomials
55// </etymology>
56//
57// <synopsis>
58// This class allows one to form and evaluate a function as a
59// Chebyshev series, a linear combination of so-called Chebyshev
60// polynomials.
61//
62// This class's implementation is split into two parts:
63// the parent class <linkto class="ChebyshevParam">ChebyshevParam&lt;T&gt;</linkto>,
64// which manages the function's parameters, and this class, which handles
65// how the function is evaluated. Thus, be sure to also consult
66// <linkto class="ChebyshevParam">ChebyshevParam&lt;T&gt;</linkto> for
67// the full interface of this function.
68//
69// <ANCHOR NAME="Chebyshev:about">
70// <H3>About Chebyshev Polynomials</H3></ANCHOR>
71//
72// Chebyshev polynomials are a special type of ultraspheric polynomials
73// that are useful in such contexts as numerical analysis and circuit
74// design. They form an orthogobnal set.
75// A (type I) Chebyshev polynomial, T_n, is generated via the
76// equation:
77// <srcblock>
78// T_n(x) = cos n(arccos x)
79// </srcblock>
80// Through clever use of trigometric identities, one can express T_n
81// as a real polynomial expression of the form
82// <srcblock>
83// n
84// T_n(x) = SUM C_i t^i
85// i=0
86// </srcblock>
87// The low order polynomials look like this:
88// <srcblock>
89// T_0 = 1
90// T_1 = x
91// T_2 = 2x^2 - 1
92// T_3 = 4x^3 - 3x
93// T_4 = 8x^4 - 8x^2 + 1
94// T_5 = 16x^5 - 20x^3 + 5x
95// </srcblock>
96// Higher order polynomials satisfy the recurrance relation,
97// <srcblock>
98// T_(n+1) = 2xT_(n) - T_(n-1).
99// </srcblock>
100//
101// A common use of Chebyshev polynomials is in approximating
102// functions. In particular, any function that is approximated by
103// a power series,
104// <srcblock>
105// f(x) ~ SUM P_i x^i,
106// </srcblock>
107// over the interval [-1, 1] can be approximated by a linear
108// combination of Chebyshev polynomials:
109// <srcblock>
110// f(x) ~ SUM C_i T_i(x),
111// </srcblock>
112// where C_i is the set of so-called Chebyshev coefficients.
113//
114// Approximating a function with Chebyshev polynomials has some
115// important advantages. For one, if the function is well approximated
116// by a converging power series, one can obtain an equally accurate
117// estimate using fewer terms of the corresponding Chebyshev series.
118// More important, though, is the property over the interval [-1, 1],
119// each polynomial has a domain of [-1, 1]; thus, the series is nicely
120// bounded. And because of this bounded property, approximations
121// calculated from a Chebyshev series are less susceptible to machine
122// rounding errors than the equivalent power series.
123//
124// <ANCHOR NAME="Chebyshev:using">
125// <H3>Using the Chebyshev Function class</H3></ANCHOR>
126//
127// With a simple change of variable, it is possible to approximate a
128// continuous function over any restricted interval using a
129// Chebyshev series. This documention refers to this interval as the
130// <em>Chebyshev interval</em> (set with the
131// <linkto class="ChebyshevParam">setInterval()</linkto> function). The
132// other important input parameters, of course, include the
133// coefficients of the polynomials.
134//
135// Like all Functions, the Chebyshev series is evaluated via the
136// function operator, <src>operator()</src>. If the input value is
137// within the range set by
138// <linkto class="ChebyshevParam">setInterval()</linkto>, it is
139// transformed to the range [-1, 1] via,
140// <srcblock>
141// y = x - (min + max)/2) / ((max - min)/2)
142// </srcblock>
143// The series is then evaluated with the coefficients set either at
144// construction or via setCoefficients(). The value that is returned
145// when the input value is outside the Chebyshev interval depends on
146// the out-of-interval mode (set via
147// <linkto class="ChebyshevParam">setOutOfIntervalMode()</linkto>). The
148// default mode is to return a default value which can be set via
149// <linkto class="ChebyshevParam">setDefault()</linkto>. The supported
150// modes are identified by the
151// enumeration OutOfIntervalMode; see the
152// <linkto class="ChebyshevParam">documentation for ChebyshevParam</linkto>
153// for a detailed description of these modes. In practice, though, it is
154// expected that this class will be configured for the interval of interest.
155//
156// The derivative of a Chebyshev series with respect to the independent
157// variable (i.e. the argument <src>x</src>) is easily calculated analytically
158// and can be expressed as another Chebyshev series; this is what the
159// <src>derivative()</src> function returns. However, the more general way to
160// obtain derivatives is via the <linkto class="AutoDiff">AutoDiff</linkto>
161// templated type.
162//
163// </synopsis>
164//
165// <example>
166// In this example, a 2nd order Chebyshev polynomial series is
167// created.
168// <srcblock>
169// // set coeffs to desired values
170// Vector<Double> coeffs(3, 1);
171//
172// // configure the function
173// Chebyshev<Double> cheb;
174// cheb.setInterval(-0.8, 7.2);
175// cheb.setDefault(1.0);
176// cheb.setCoefficients(coeffs);
177//
178// // evaluate the function as necessary
179// Double z = cheb(-0.5); // -0.5 is within range, z = 0.78625
180// z = cheb(4.2); // 4.2 is within range, z = 0.375
181// z = cheb(-3); // -3 is out of the interval, z = 1
182// </srcblock>
183//
184// The next example illustrates how to use the
185// <linkto class="AutoDiff">AutoDiff</linkto> class to simultaneously
186// calculate derivatives. Here, we replace the Double type with
187// AutoDiff<Double>.
188// <srcblock>
189// Chebyshev<AutoDiffA<Double> > cheb;
190// cheb.setDefault(AutoDiffA<Double>(1));
191// cheb.setInterval(AutoDiffA<Double>(-0.8), AutoDiffA<Double>(7.2));
192//
193// // we'll track derivatives with respect to x and each of our
194// // coefficients; for a second-order series, this makes 4
195// // derivatives total. x will be the first variable; the
196// // coefficients will the 2nd-4th variables
197// cheb.setCoefficient(0, AutoDiffA<Double>(3.1, 4, 1)); // c0 = 3.1
198// cheb.setCoefficient(1, AutoDiffA<Double>(2.4, 4, 2)); // c1 = 2.4
199// cheb.setCoefficient(2, AutoDiffA<Double>(0.5, 4, 3)); // c2 = 0.5
200//
201// // now evaluate the function
202// AutoDiffA<Double> x(1.2, 4, 0); // x = 1.2
203// AutoDiffA<Double> y = cheb(x); // y = 1.65
204// Double dydx = y.derivative(0); // dy/dx = 0.35
205// Double dydc1 = y.derivative(2); // dy/dc1 = -0.5
206// </srcblock>
207// </example>
208//
209// <motivation>
210// This class was created to support systematic errors in the simulator tool.
211// It can be used by Jones matrix classes to vary gains in a predictable way,
212// mimicing natural processes of the atmosphere or instrumental effects.
213// </motivation>
214
215// <templating arg=T>
216// <li> T should have standard numerical operators. Current
217// implementation only tested for real types (and their AutoDiffs).
218// </templating>
219
220// <thrown>
221// <li> Assertion in debug mode if attempt is made to address incorrect
222// coefficients
223// </thrown>
224//
225// <todo asof="2001/08/22">
226// <li> It would be helpful to be able to convert to and from the
227// Polynomial<T> type; this would be supported via a function,
228// Polynomial<T> polynomial(), and constructor,
229// Chebyshev(Polynomial<T>)
230// </todo>
231
232template<class T>
234public:
235
236 //# Constructors
237 // create a zero-th order Chebyshev polynomial with the first coefficient
238 // equal to zero. The bounded domain is [T(-1), T(1)]. The
239 // OutOfDomainMode is CONSTANT, and the default value is T(0).
241
242 // create an n-th order Chebyshev polynomial with the coefficients
243 // equal to zero. The bounded domain is [T(-1), T(1)]. The
244 // OutOfDomainMode is CONSTANT, and the default value is T(0).
245 explicit Chebyshev(const uInt n) : ChebyshevParamModeImpl<T>(n) {}
246
247 // create a zero-th order Chebyshev polynomical with the first coefficient
248 // equal to one.
249 // min is the minimum value of its Chebyshev interval, and
250 // max is the maximum value.
251 // mode sets the behavior of the function outside the Chebyshev interval
252 // (see setOutOfIntervalMode() and OutOfIntervalMode enumeration
253 // definition for details).
254 // defval is the value returned when the function is evaluated outside
255 // the Chebyshev interval and mode=CONSTANT.
256 Chebyshev(const T &min, const T &max,
257 const typename ChebyshevEnums::
258 OutOfIntervalMode mode=ChebyshevEnums::CONSTANT,
259 const T &defval=T(0)) :
260 ChebyshevParamModeImpl<T>(min, max, mode, defval) {}
261
262 // create a fully specified Chebyshev polynomial.
263 // coeffs holds the coefficients of the Chebyshev polynomial (see
264 // setCoefficients() for details).
265 // min is the minimum value of its canonical range, and
266 // max is the maximum value.
267 // mode sets the behavior of the function outside the Chebyshev interval
268 // (see setOutOfIntervalMode() and OutOfIntervalMode enumeration
269 // definition for details).
270 // defval is the value returned when the function is evaluated outside
271 // the canonical range and mode=CONSTANT.
272 Chebyshev(const Vector<T> &coeffs, const T &min, const T &max,
273 const typename ChebyshevEnums::
274 OutOfIntervalMode mode=ChebyshevEnums::CONSTANT,
275 const T &defval=T(0)) :
276 ChebyshevParamModeImpl<T>(coeffs, min, max, mode, defval) {}
277
278 // create a fully specified Chebyshev polynomial.
279 // config is a record that contains the non-coefficient data
280 // that configures this class.
281 // The fields recognized by this class are those documented for the
282 // <linkto class="ChebyshevParam">ChebyshevPara::setMode()</linkto>
283 // function.
284 // <group>
287 Chebyshev(const Vector<T> &coeffs, const RecordInterface& mode) :
288 ChebyshevParamModeImpl<T>(coeffs, mode) { }
289 // </group>
290
291 // create a deep copy of another Chebyshev polynomial
292 // <group>
293 Chebyshev(const Chebyshev &other) : ChebyshevParamModeImpl<T>(other) {}
294 // </group>
295
296 // make this instance a (deep) copy of another Chebyshev polynomial
298 ChebyshevParam<T>::operator=(other); return *this; }
299
300 // Destructor
301 virtual ~Chebyshev() {}
302
303 //# Operators
304 // Evaluate the Chebyshev at <src>x</src>.
305 virtual T eval(const typename FunctionTraits<T>::ArgType *x) const;
306
307 //# Member functions
308 // Return the Chebyshev polynomial which is the derivative of this one
309 // (with respect to the argument <src>x</src>).
311
312 // Create a new copy of this object. The caller is responsible
313 // for deleting the pointer.
314 // <group>
315 virtual Function<T> *clone() const { return new Chebyshev<T>(*this); }
316 // </group>
317
318};
319
320
321} //# NAMESPACE CASACORE - END
322
323#ifndef CASACORE_NO_AUTO_TEMPLATES
324#include <casacore/scimath/Functionals/Chebyshev.tcc>
325#endif //# CASACORE_NO_AUTO_TEMPLATES
326#endif
A ChebyshevParam with the get/setMode implementation.
uInt order() const
return the order of this polynomial.
ChebyshevParam< T > & operator=(const ChebyshevParam< T > &other)
make a (deep) copy of another Chebyshev polynomial
Chebyshev()
create a zero-th order Chebyshev polynomial with the first coefficient equal to zero.
Definition Chebyshev.h:240
Chebyshev(const uInt n)
create an n-th order Chebyshev polynomial with the coefficients equal to zero.
Definition Chebyshev.h:245
virtual ~Chebyshev()
Destructor.
Definition Chebyshev.h:301
Chebyshev(const T &min, const T &max, const typename ChebyshevEnums::OutOfIntervalMode mode=ChebyshevEnums::CONSTANT, const T &defval=T(0))
create a zero-th order Chebyshev polynomical with the first coefficient equal to one.
Definition Chebyshev.h:256
Chebyshev< T > derivative() const
Return the Chebyshev polynomial which is the derivative of this one (with respect to the argument x).
Chebyshev< T > & operator=(const Chebyshev< T > &other)
make this instance a (deep) copy of another Chebyshev polynomial
Definition Chebyshev.h:297
Chebyshev(const Vector< T > &coeffs, const RecordInterface &mode)
Definition Chebyshev.h:287
Chebyshev(const Vector< T > &coeffs, const T &min, const T &max, const typename ChebyshevEnums::OutOfIntervalMode mode=ChebyshevEnums::CONSTANT, const T &defval=T(0))
create a fully specified Chebyshev polynomial.
Definition Chebyshev.h:272
Chebyshev(const Chebyshev &other)
create a deep copy of another Chebyshev polynomial
Definition Chebyshev.h:293
virtual Function< T > * clone() const
Create a new copy of this object.
Definition Chebyshev.h:315
virtual T eval(const typename FunctionTraits< T >::ArgType *x) const
Evaluate the Chebyshev at x.
Chebyshev(uInt order, const RecordInterface &mode)
create a fully specified Chebyshev polynomial.
Definition Chebyshev.h:285
T ArgType
Type for arguments.
this file contains all the compiler specific defines
Definition mainpage.dox:28
LatticeExprNode max(const LatticeExprNode &left, const LatticeExprNode &right)
unsigned int uInt
Definition aipstype.h:49
LatticeExprNode min(const LatticeExprNode &left, const LatticeExprNode &right)