casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
CompoundFunction.h
Go to the documentation of this file.
00001 //# CompoundFunction.h: Sum of a collection of Functions
00002 //# Copyright (C) 2001,2002,2005
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //#
00027 //# $Id: CompoundFunction.h 21024 2011-03-01 11:46:18Z gervandiepen $
00028 
00029 #ifndef SCIMATH_COMPOUNDFUNCTION_H
00030 #define SCIMATH_COMPOUNDFUNCTION_H
00031 
00032 //# Includes
00033 #include <casa/aips.h>
00034 #include <scimath/Functionals/CompoundParam.h>
00035 #include <scimath/Functionals/Function.h>
00036 #include <scimath/Mathematics/AutoDiff.h>
00037 #include <scimath/Mathematics/AutoDiffMath.h>
00038 
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 //# Forward declarations
00042 
00043 // <summary>
00044 // Sum of a collection of Functions which behaves as one Function object.
00045 // </summary>
00046 
00047 // <use visibility=export>
00048 
00049 // <reviewed reviewer="tcornwel" date="1996/02/22" tests="tCompoundFunction" 
00050 // demos="">
00051 // </reviewed>
00052 
00053 // <prerequisite>
00054 //   <li> <linkto class="Function">Function</linkto> class
00055 // </prerequisite>
00056 //
00057 // <synopsis>
00058 // This class takes an arbitrary number of Function objects, and generates
00059 // a new, single function object. The parameters of the compound object
00060 // are the union of all the parameters in the input objects.
00061 //
00062 // When CompoundFunction is evaluated, the result is the sum of 
00063 // all the individual function values.
00064 //
00065 // Member functions are added with the <src>addFunction()</src> method.
00066 //
00067 // In general the interaction with the function parameters should be through
00068 // the overall function parameters (i.e. through the parameters of the
00069 // <src>CompoundFunction</src>). If for any reason you want to set the
00070 // parameters of an individual function (see e.g. the example in the
00071 // <linkto class=Fit2D>Fit2D</linkto>), call <src>consolidate()</src> before
00072 // abd after the actual setting.
00073 //
00074 // <note role=tip>
00075 // Check <linkto class=CompoundFunction>CombiFunction</linkto> class
00076 // for a simple linear combination of function objects </note>
00077 // </synopsis>
00078 //
00079 // <example>
00080 // Suppose for some reason we wanted the sum of <src>x^2</src> plus a gaussian.
00081 // We could form it as follows:
00082 // <srcblock>
00083 //    Polynomial<Float> x2(2);
00084 //    x[2] = 1.0;                                        // x^2
00085 //    Gaussian1D<Float> gauss(1.0, 0.0, 1.0);          // e^{-x^2}
00086 //    CompoundParam<Float> sum;                        // sum == 0.0
00087 //    sum.addFunction(x2);                               // sum == x^2
00088 //    sum.addFunction(gauss);                            // sum == x^2+e^{-x^2}
00089 //    sum(2.0);                                          // == 4 + e^-4
00090 //    CompoundParam[0] = 2.0;                          // sum ==2x^2+e^{-x^2}
00091 //    sum(2.0);                                          // == 8 + e^-4
00092 // </srcblock>
00093 // </example>
00094 
00095 // <templating arg=T>
00096 //  <li> T should have standard numerical operators and exp() function. Current
00097 //      implementation only tested for real types.
00098 //  <li> To obtain derivatives, the derivatives should be defined.
00099 // </templating>
00100 
00101 // <thrown>
00102 // <li> AipsError if dimensions of functions added different
00103 // </thrown>
00104 
00105 // <motivation>
00106 // This class was created to allow a non-linear least squares fitter to fit a 
00107 // (potentially) arbitrary number of functions (typically Gaussians).
00108 // </motivation>
00109 //
00110 // <todo asof="2001/10/22">
00111 //   <li> Nothing I know of
00112 // </todo>
00113 
00114 template <class T> class CompoundFunction : public CompoundParam<T>
00115 {
00116 public:
00117   //# Constructors
00118   // The default constructor -- no functions, no parameters, nothing, the
00119   // function operator returns a 0.
00120   CompoundFunction() : CompoundParam<T>() {}
00121   // Make this object a (deep) copy of other. If parameters have been set
00122   // without an intervening calculation, a <src>consolidate()</src> could
00123   // be necessary on <em>other</em> first.
00124   // <group>
00125   CompoundFunction(const CompoundFunction<T> &other) :
00126     CompoundParam<T>(other) {}
00127   CompoundFunction(const CompoundFunction<T> &other, Bool) :
00128     CompoundParam<T>(other, True) {}
00129   template <class W>
00130     CompoundFunction(const CompoundFunction<W> &other) :
00131     CompoundParam<T>(other) {}
00132   template <class W>
00133     CompoundFunction(const CompoundFunction<W> &other, Bool) :
00134     CompoundParam<T>(other, True) {}
00135   // </group>
00136   // Make this object a (deep) copy of other.
00137   CompoundFunction<T> &operator=(const CompoundFunction<T> &other) {
00138     other.fromParam_p();
00139     CompoundParam<T>::operator=(other); return *this; }
00140   
00141   // Destructor
00142   virtual ~CompoundFunction() {}
00143   
00144   //# Operators
00145   // Evaluate the function at <src>x</src>.
00146   virtual T eval(typename Function<T>::FunctionArg x) const;
00147   
00148   //# Member functions
00149   // Consolidate the parameter settings. This could be necessary if
00150   // parameters have been set, and a copy constructor called. This is
00151   // necessary before and after the setting of <em>local</em> parameters; i.e.
00152   // the parameters of the individual functions.
00153   CompoundFunction<T> &consolidate() { fromParam_p();
00154     toParam_p(); return *this; }
00155   // Return a copy of this object from the heap. The caller is responsible for
00156   // deleting the pointer.
00157   // <group>
00158   virtual Function<T> *clone() const { fromParam_p();
00159     return new CompoundFunction<T>(*this); }
00160   virtual Function<typename FunctionTraits<T>::DiffType> *cloneAD() const {
00161     return new CompoundFunction<typename FunctionTraits<T>::DiffType>(*this); }
00162   virtual Function<typename FunctionTraits<T>::BaseType> *cloneNonAD() const {
00163     return new CompoundFunction<typename FunctionTraits<T>::BaseType>
00164       (*this, True); }
00165   // </group>
00166   
00167 private:
00168   //# Member functions
00169   // Copy the local parameters from general block
00170   void fromParam_p() const;
00171   // Make the general block from local parameters
00172   void toParam_p();
00173 
00174   //# Make members of parent classes known.
00175 protected:
00176   using CompoundParam<T>::parset_p;
00177   using CompoundParam<T>::param_p;
00178   using CompoundParam<T>::funpar_p;
00179   using CompoundParam<T>::locpar_p;
00180   using CompoundParam<T>::paroff_p;
00181   using CompoundParam<T>::functionPtr_p;
00182 public:
00183   using CompoundParam<T>::nparameters;
00184   using CompoundParam<T>::nFunctions;
00185   using CompoundParam<T>::function;
00186 };
00187 
00188 #define CompoundFunction_PS CompoundFunction
00189 
00190 // <summary> Partial <src>AutoDiff</src> specialization of CompoundFunction
00191 // </summary>
00192 
00193 // <synopsis>
00194 // <note role=warning> The name <src>CompoundFunction_PS</src> is only
00195 // for cxx2html documentation problems. Use
00196 // <src>CompoundFunction</src> in your code.</note>
00197 // </synopsis>
00198 
00199 template <class T> class CompoundFunction_PS<AutoDiff<T> > :
00200 public CompoundParam<AutoDiff<T> >
00201 {
00202  public:
00203   //# Constructors
00204   // The default constructor -- no functions, no parameters, nothing, the
00205   // function operator returns a 0.
00206   CompoundFunction_PS() : CompoundParam<AutoDiff<T> >() {}
00207   // Make this object a (deep) copy of other. If parameters have been set
00208   // without an intervening calculation, a <src>consolidate()</src> could
00209   // be necessary on <em>other</em> first.
00210   // <group>
00211   CompoundFunction_PS(const CompoundFunction_PS<AutoDiff<T> > &other) :
00212     CompoundParam<AutoDiff<T> >(other) {}
00213   template <class W>
00214     CompoundFunction_PS(const CompoundFunction_PS<W> &other) :
00215     CompoundParam<AutoDiff<T> >(other) {}
00216   // </group>
00217   // Make this object a (deep) copy of other.
00218   CompoundFunction_PS<AutoDiff<T> > &
00219     operator=(const CompoundFunction_PS<AutoDiff<T> > &other) {
00220     fromParam_p();
00221     CompoundParam<AutoDiff<T> >::operator=(other); return *this; }
00222 
00223   // Destructor
00224   virtual ~CompoundFunction_PS() {}
00225 
00226   //# Operators
00227   // Evaluate the function and its derivatives at <src>x</src> <em>wrt</em>
00228   // to the coefficients.
00229   virtual AutoDiff<T>
00230     eval(typename Function<AutoDiff<T> >::FunctionArg x) const;
00231   
00232   //# Member functions
00233 // Add a function to the sum. All functions must have the same 
00234   // <src>ndim()</src> as the first one. Returns the (zero relative) number 
00235   // of the function just added.
00236   uInt addFunction(const Function<AutoDiff<T> > &newFunction);
00237   // Consolidate the parameter settings. This could be necessary if
00238   // parameters have been set, and a copy constructor called. This is
00239   // necessary before and after the setting of <em>local</em> parameters; i.e.
00240   // the parameters of the individual functions.
00241   CompoundFunction_PS<AutoDiff<T> > &consolidate() { fromParam_p();
00242     toParam_p(); return *this; }
00243   // Return a copy of this object from the heap. The caller is responsible for
00244   // deleting the pointer.
00245   // <group>
00246   virtual Function<AutoDiff<T> > *clone() const { fromParam_p();
00247     return new CompoundFunction<AutoDiff<T> >(*this); }
00248   virtual Function<typename FunctionTraits<AutoDiff<T> >::DiffType>
00249     *cloneAD() const {
00250     return new CompoundFunction<typename FunctionTraits<AutoDiff<T> >::DiffType>
00251       (*this); }
00252   virtual Function<typename FunctionTraits<AutoDiff<T> >::BaseType>
00253     *cloneNonAD() const {
00254     return new CompoundFunction<typename FunctionTraits<AutoDiff<T> >::BaseType>
00255       (*this, True); }
00256   // </group>
00257 
00258 private:
00259   //# Member functions
00260   // Copy the local parameters to/from general block
00261   void fromParam_p() const;
00262   // Make the general block from local parameters
00263   void toParam_p();
00264 
00265   //# Make members of parent classes known.
00266 protected:
00267   using CompoundParam<AutoDiff<T> >::parset_p;
00268   using CompoundParam<AutoDiff<T> >::param_p;
00269   using CompoundParam<AutoDiff<T> >::funpar_p;
00270   using CompoundParam<AutoDiff<T> >::locpar_p;
00271   using CompoundParam<AutoDiff<T> >::paroff_p;
00272   using CompoundParam<AutoDiff<T> >::functionPtr_p;
00273 public:
00274   using CompoundParam<AutoDiff<T> >::nparameters;
00275   using CompoundParam<AutoDiff<T> >::nFunctions;
00276   using CompoundParam<AutoDiff<T> >::function;
00277 };
00278 
00279 #undef CompoundFunction_PS
00280 
00281 
00282 } //# NAMESPACE CASA - END
00283 
00284 #ifndef CASACORE_NO_AUTO_TEMPLATES
00285 #include <scimath/Functionals/CompoundFunction.tcc>
00286 #include <scimath/Functionals/Compound2Function.tcc>
00287 #endif //# CASACORE_NO_AUTO_TEMPLATES
00288 #endif