casacore
Loading...
Searching...
No Matches
Function.h
Go to the documentation of this file.
1//# Function.h: Numerical functional interface class
2//# Copyright (C) 2001,2002,2003,2004,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: 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
28#ifndef SCIMATH_FUNCTION_H
29#define SCIMATH_FUNCTION_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/Vector.h>
34#include <casacore/casa/BasicMath/Functional.h>
35#include <casacore/casa/Utilities/Assert.h>
36#include <casacore/scimath/Functionals/FunctionParam.h>
37#include <casacore/scimath/Functionals/FunctionTraits.h>
38
39//# Forward declarations
40#include <casacore/casa/iosfwd.h>
41
42namespace casacore { //# NAMESPACE CASACORE - BEGIN
43
44//# Forward declarations
45class String;
46class RecordInterface;
47
48// <summary> Numerical functional interface class
49// </summary>
50
51// <use visibility=export>
52
53// <reviewed reviewer="tcornwel" date="1996/02/22" tests="tGaussian2D"
54// demos="">
55// </reviewed>
56
57// <prerequisite>
58// <li> <linkto class="Functional">Functional</linkto>
59// <li> <linkto class="FunctionParam">FunctionParam</linkto>
60// </prerequisite>
61//
62// <synopsis>
63// A <src>Function</src> is used for classes which map a
64// scalar or n-dimensional Vector of type <src>T</src> into a <src>T</src>.
65// The object also has zero or more parameters which can be masked
66// if necessary, and be used in the <src>Fitting</src> module, and, implicitly,
67// in the <linkto class=AutoDiff>AutoDiff</linkto> differentiation module.
68//
69// The parameter interface is provided by the
70// <linkto class="FunctionParam"><src>FunctionParam</src></linkto> class.
71//
72// A Function can have a <src>name()</src> which can be used in generic
73// interfaces.
74//
75// The function calls implemented are:
76// <ul>
77// <li> <src>operator()()</src>
78// <li> <src>operator()(const T &x)</src>
79// <li> <src>operator()(const Vector<T> &x)</src>
80// <li> <src>operator()(Function::FunctionArg x)</src>
81// <li> <src>operator()(const T &x, const T &y)</src> (for 2D)
82// <li> <src>operator()(const T &x, const T &y, const T &z)</src> (for 3D)
83// </ul>
84// The <src>T</src> in the above is the <src>Function::ArgType</src>
85// as derived from the <linkto class="FunctionTraits">FunctionTraits</linkto>
86// class.
87// These calls are (in debug mode) tested for the correct number of arguments,
88// after which they call a <src>T eval(FunctionArg x) const = 0</src> to
89// be implemented in derived classes. The derived class should also implement
90// an <src>uInt ndim() const = 0</src>. The derived class can access the
91// nth parameter with the <src>[n]</src> operator, and the corresponding
92// mask with <src>mask(n)</src> method.
93// The variables are referenced with <src>x[i]</src>.
94//
95// </synopsis>
96
97// <example>
98// A complete implementation of say an <src>A.sin(2pi.f.x)</src> with
99// parameters amplitude(<em>A</em>) and frequency(<em>f</em>) and variable
100// time(<em>x</em>) could be:
101// <srcblock>
102// //# Sinusoid.h
103// #include <casacore/casa/aips.h>
104// #include <casacore/scimath/Functionals/Function.h>
105// #include <casacore/casa/BasicSL/Constants.h>
106// #include <casacore/casa/BasicMath/Math.h>
107// // The sinusoid class
108// template<class T> class Sinusoid : public Function<T> {
109// public:
110// // For easy reference of the parameters
111// enum { AMPL=0, FREQ };
112// // Constructors. Defaults are A=1, f=1
113// Sinusoid() : Function<T>(2) {
114// param_p[AMPL] = T(1.0); param_p[FREQ] = T(1.0); }
115// explicit Sinusoid(const T &ampl) : Function<T>(2) {
116// param_p[AMPL] = ampl; param_p[FREQ] = T(1.0); }
117// Sinusoid(const T &ampl, const T &freq) : Function<T>(2) {
118// param_p[AMPL] = ampl; param_p[FREQ] = freq; }
119// Sinusoid(const Sinusoid &other) : Function<T>(2) {
120// param_p[AMPL] = other.param_p[AMPL];
121// param_p[FREQ] = other.parameter[FREQ]; }
122// Sinusoid<T> &operator=(const Sinusoid<T> &other) {
123// if (this != &other) param_p = other.param_p;
124// return *this; }
125// virtual ~Sinusoid() {}
126// // Dimensionality
127// virtual uInt ndim() const { return 2; }
128// // Evaluate
129// virtual T eval(Function<T>::FunctionArg x) const {
130// return param_p[AMPL]*sin(T(C::_2pi)*param_p[FREQ]*x[0]); }
131// // Copy it
132// virtual Function<T> *clone() const { return new Sinusoid<T>(param_p); }
133// };
134// </srcblock>
135// The following will calculate the value and the derivative for
136// <src>A=2; f=3; x=0.1;</src>
137// <srcblock>
138// // The function objects for value, and for value + derivative
139// Sinusoid<Double> soid1(2.0, 3.0);
140// typedef AutoDiff<Double> Adif;
141// Sinusoid<Adif> soid2(Adif(2,2,0), Adif(3,2,1));
142// cout << "Value: " << soid1(0.1) << endl;
143// cout << "(val, deriv): " << soid2(Adif(0.1)) << endl;
144// </srcblock>
145//
146// A shorter version, where all parameter handling is done at user level
147// could be:
148// <srcblock>
149// //# Sinusoid.h
150// #include <casacore/casa/aips.h>
151// #include <casacore/scimath/Functionals/Function.h>
152// #include <casacore/casa/BasicSL/Constants.h>
153// #include <casacore/casa/BasicMath/Math.h>
154// template<class T> class Sinusoid : public Function<T> {
155// public:
156// enum { AMPL=0, FREQ };
157// Sinusoid() : Function<T>(2){param_p[AMPL] T(1);param_p[FREQ]=T(1);}
158// virtual ~Sinusoid() {}
159// virtual uInt ndim() const { return 2; }
160// virtual T eval(Function<T>::FunctionArg x) const {
161// return param_p[AMPL]*sin(T(C::_2pi)*param_p[FREQ]*x[0]); }
162// virtual Function<T> *clone() const { return new Sinusoid<T>param_p; }
163// };
164// </srcblock>
165// The following will calculate the value and the derivative for
166// <src>A=2; f=3; x=0.1;</src>
167// <srcblock>
168// // The function objects for value, and for value + derivative
169// typedef AutoDiff<Double> Adif;
170// typedef Function<Double> FD;
171// typedef Function<AutoDiff<Double> > FAdif
172// Sinusoid<Double> soid1;
173// Sinusoid<Adif> soid2;
174// soid1[FD::AMPL] = 2; soid1[FD::FREQ] = 3;
175// soid2[FAdif::AMPL] = Adif(2,2,0);
176// soid2[FAdif::FREQ] = Adif(3,2,1);
177// cout << "Value: " << soid1(0.1) << endl;
178// cout << "(val, deriv): " << soid2(Adif(0.1)) << endl;
179// </srcblock>
180// </example>
181
182// <motivation>
183// A function of more than one variable was required for a function which
184// represents the sky brightness. Adjustable parameters were required for
185// non-linear least squares fitting.
186// </motivation>
187//
188// <templating arg=T>
189// <li> Besides the requirements set by the
190// <linkto class="Functional">Functional</linkto> base class, it must be
191// possible to form a <src>Vector<T></src>.
192// </templating>
193//
194// <todo asof="2005/01/20">
195// <li> At some point, we may want to implement a letter-envelope class,
196// implement function arithmetic, etc.
197// <li> use maybe Poolstack for static Vector
198// </todo>
199
200 template<class T, class U=T> class Function :
201 public Functional<typename FunctionTraits<T>::ArgType, U>,
202 public Functional<Vector<typename FunctionTraits<T>::ArgType>, U> {
203
204 public:
205 //# Typedefs
207 typedef const ArgType* FunctionArg;
208
209 //# Constructors
210 // Constructors
211 // <group>
213 explicit Function(const uInt n) : param_p(n), arg_p(0), parset_p(False),
214 locked_p(False) {}
215 explicit Function(const Vector<T> &in) : param_p(in), arg_p(0),
217 Function(const FunctionParam<T> &other) : param_p(other), arg_p(0),
219 template <class W, class X>
220 Function(const Function<W,X> &other) : param_p(other.parameters()),
221 arg_p(0), parset_p(other.parsetp()), locked_p(False) {}
222 // </group>
223
224 // Destructor
225 virtual ~Function() {}
226
227 // Returns the number of dimensions of function
228 virtual uInt ndim() const = 0;
229 // Returns the number of parameters
230 uInt nparameters() const { return param_p.nelements(); }
231
232 // Evaluate the function object
233 virtual U eval(FunctionArg x) const = 0;
234
235 //# Operators
236 // Manipulate the nth parameter (0-based) with no index check
237 // <group>
238 T &operator[](const uInt n) { parset_p |= !locked_p;
239 return param_p[n]; }
240 const T &operator[](const uInt n) const { return param_p[n]; }
241 // </group>
242 // Evaluate this function object at <src>x</src>or at <src>x, y</src>.
243 // The length of <src>x</src> must be greater than or equal to
244 // <src>ndim()</src>.
245 // <group>
246 virtual U operator()() const {
247 DebugAssert(ndim()==0, AipsError); return eval(FunctionArg(0)); }
248 virtual U operator()(const ArgType &x) const {
249 DebugAssert(ndim()<=1, AipsError); return eval(&x); }
250 virtual U operator()(const Vector<ArgType> &x) const;
251 virtual U operator()(FunctionArg x) const { return eval(x); }
252 virtual U operator()(const ArgType &x, const ArgType &y) const;
253 virtual U operator()(const ArgType &x, const ArgType &y,
254 const ArgType &z) const;
255 // </group>
256
257 //# Member functions
258 // Specify the name associated with the function (default will be
259 // <src>unknown</src>)
260 virtual const String &name() const;
261 // Manipulate the mask associated with the nth parameter
262 // (e.g. to indicate whether the parameter is adjustable or
263 // nonadjustable).
264 // Note: no index check.
265 // <group>
266 Bool &mask(const uInt n) { parset_p |= !locked_p;
267 return param_p.mask(n); }
268 const Bool &mask(const uInt n) const { return param_p.mask(n); }
269 // </group>
270 // Return the parameter interface
271 // <group>
272 const FunctionParam<T> &parameters() const { return param_p; }
274 // </group>
275 // Get <src>arg_p</src> and <src>parset_p</src>. Necessary for reasons
276 // of protection in the copying of non-conforming Functions.
277 // <group>
278 const Vector<ArgType> &argp() const { return arg_p; }
279 Bool parsetp() const { return parset_p; }
280 // </group>
281 // Compiler cannot always find the correct 'const' version of parameter
282 // access. In cases where this would lead to excessive overheads in
283 // moving parameters around (like in <src>CompoundFunction</src>) the
284 // parameter changing can be set to be locked, and no changes are
285 // assumed.
286 // <group>
287 void lockParam() { locked_p = True; }
289 // </group>
290
291 // get/set the function mode. These provide an interface to
292 // function-specific configuration or state that controls how the
293 // function calculates its values but otherwise does not qualify as
294 // a parameter. Some part of the state, for example, might have a
295 // type different from that of T. The state is passed as fields of a
296 // record, mode--the names, types and values of which are specific to
297 // the implementing function and should be documented in the implementing
298 // class. It is recommended that all possible inputs passed to this
299 // function via setMode() be considered optional such that if the
300 // record omits a legal field, that part of the state is left unchanged.
301 // Fields not recognized by the implementing class should be ignored.
302 // An exception should be thrown if a recognized field contains illegal
303 // data. The default implementations for both getMode() and setMode()
304 // ignore the input record.
305 // <group>
306 virtual void setMode(const RecordInterface& mode);
307 virtual void getMode(RecordInterface& mode) const;
308 // </group>
309
310 // return True if the implementing function supports a mode. The default
311 // implementation returns False.
312 virtual Bool hasMode() const;
313
314 // Print the function (i.e. the parameters)
315 ostream &print(ostream &os) const { return param_p.print(os); }
316 // Return a copy of this object from the heap. The caller is responsible
317 // for deleting this pointer. The <src>cloneAD</src> will return a clone
318 // with an <src>AutoDef<T></src>; the <src>cloneNonAD</src> a clone
319 // with <src><T></src>. An <src>AipsError</src> will be thrown if the
320 // <src>cloneAD()</src> or <src>cloneNonAD()</src> is not implemented
321 // for a specific function.
322 // <group>
323 virtual Function<T,U> *clone() const = 0;
326 *cloneNonAD() const;
327 // </group>
328
329protected:
330 //# Data
331 // The parameters and masks
333 // Aid for non-contiguous argument storage
335 // Indicate parameter written
336 mutable Bool parset_p;
337 // Indicate that parameters are expected to be locked from changing
338 mutable Bool locked_p;
339};
340
341//# Global functions
342// <summary> Global functions </summary>
343// <group name=Output>
344// Output declaration
345template<class T, class U>
346ostream &operator<<(ostream &os, const Function<T,U> &fun);
347// </group>
349//# Inlines
350template<class T, class U>
351inline ostream &operator<<(ostream &os, const Function<T,U> &fun) {
352 return fun.print(os); }
353
354} //# NAMESPACE CASACORE - END
355
356#ifndef CASACORE_NO_AUTO_TEMPLATES
357#include <casacore/scimath/Functionals/Function.tcc>
358#endif //# CASACORE_NO_AUTO_TEMPLATES
359#endif
#define DebugAssert(expr, exception)
Definition Assert.h:185
T ArgType
Type for arguments.
FunctionParam< T > param_p
The parameters and masks.
Definition Function.h:332
FunctionTraits< T >::ArgType ArgType
Definition Function.h:206
virtual void setMode(const RecordInterface &mode)
get/set the function mode.
const T & operator[](const uInt n) const
Definition Function.h:240
virtual U operator()(const ArgType &x, const ArgType &y) const
Function(const Vector< T > &in)
Definition Function.h:215
virtual U operator()(const ArgType &x) const
Definition Function.h:248
FunctionParam< T > & parameters()
Definition Function.h:273
virtual Function< T, U > * clone() const =0
Return a copy of this object from the heap.
Function()
Constructors.
Definition Function.h:212
virtual void getMode(RecordInterface &mode) const
virtual U operator()() const
Evaluate this function object at xor at x, y.
Definition Function.h:246
virtual Function< typename FunctionTraits< T >::BaseType > * cloneNonAD() const
Bool & mask(const uInt n)
Manipulate the mask associated with the nth parameter (e.g.
Definition Function.h:266
const Bool & mask(const uInt n) const
Definition Function.h:268
virtual U operator()(FunctionArg x) const
Definition Function.h:251
const FunctionParam< T > & parameters() const
Return the parameter interface.
Definition Function.h:272
void lockParam()
Compiler cannot always find the correct 'const' version of parameter access.
Definition Function.h:287
Function(const Function< W, X > &other)
Definition Function.h:220
T & operator[](const uInt n)
Manipulate the nth parameter (0-based) with no index check.
Definition Function.h:238
virtual uInt ndim() const =0
Returns the number of dimensions of function.
virtual Bool hasMode() const
return True if the implementing function supports a mode.
virtual ~Function()
Destructor.
Definition Function.h:225
virtual const String & name() const
Specify the name associated with the function (default will be unknown)
virtual U operator()(const ArgType &x, const ArgType &y, const ArgType &z) const
Function(const uInt n)
Definition Function.h:213
Vector< ArgType > arg_p
Aid for non-contiguous argument storage.
Definition Function.h:334
ostream & print(ostream &os) const
Print the function (i.e.
Definition Function.h:315
virtual U operator()(const Vector< ArgType > &x) const
const Vector< ArgType > & argp() const
Get arg_p and parset_p.
Definition Function.h:278
Bool parset_p
Indicate parameter written.
Definition Function.h:336
Function(const FunctionParam< T > &other)
Definition Function.h:217
virtual U eval(FunctionArg x) const =0
Evaluate the function object.
uInt nparameters() const
Returns the number of parameters.
Definition Function.h:230
Bool locked_p
Indicate that parameters are expected to be locked from changing.
Definition Function.h:338
const ArgType * FunctionArg
Definition Function.h:207
Bool parsetp() const
Definition Function.h:279
virtual Function< typename FunctionTraits< T >::DiffType > * cloneAD() const
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43
ostream & operator<<(ostream &os, const Function< T, U > &fun)
Output declaration.