Loading...
Searching...
No Matches
Function.h
Go to the documentation of this file.
//# Function.h: Numerical functional interface class
//# Copyright (C) 2001,2002,2003,2004,2005
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef SCIMATH_FUNCTION_H
#define SCIMATH_FUNCTION_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/BasicMath/Functional.h>
#include <casacore/casa/Utilities/Assert.h>
#include <casacore/scimath/Functionals/FunctionParam.h>
#include <casacore/scimath/Functionals/FunctionTraits.h>
//# Forward declarations
#include <casacore/casa/iosfwd.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward declarations
class String;
class RecordInterface;
// <summary> Numerical functional interface class
// </summary>
// <use visibility=export>
// <reviewed reviewer="tcornwel" date="1996/02/22" tests="tGaussian2D"
// demos="">
// </reviewed>
// <prerequisite>
// <li> <linkto class="Functional">Functional</linkto>
// <li> <linkto class="FunctionParam">FunctionParam</linkto>
// </prerequisite>
//
// <synopsis>
// A <src>Function</src> is used for classes which map a
// scalar or n-dimensional Vector of type <src>T</src> into a <src>T</src>.
// The object also has zero or more parameters which can be masked
// if necessary, and be used in the <src>Fitting</src> module, and, implicitly,
// in the <linkto class=AutoDiff>AutoDiff</linkto> differentiation module.
//
// The parameter interface is provided by the
// <linkto class="FunctionParam"><src>FunctionParam</src></linkto> class.
//
// A Function can have a <src>name()</src> which can be used in generic
// interfaces.
//
// The function calls implemented are:
// <ul>
// <li> <src>operator()()</src>
// <li> <src>operator()(const T &x)</src>
// <li> <src>operator()(const Vector<T> &x)</src>
// <li> <src>operator()(Function::FunctionArg x)</src>
// <li> <src>operator()(const T &x, const T &y)</src> (for 2D)
// <li> <src>operator()(const T &x, const T &y, const T &z)</src> (for 3D)
// </ul>
// The <src>T</src> in the above is the <src>Function::ArgType</src>
// as derived from the <linkto class="FunctionTraits">FunctionTraits</linkto>
// class.
// These calls are (in debug mode) tested for the correct number of arguments,
// after which they call a <src>T eval(FunctionArg x) const = 0</src> to
// be implemented in derived classes. The derived class should also implement
// an <src>uInt ndim() const = 0</src>. The derived class can access the
// nth parameter with the <src>[n]</src> operator, and the corresponding
// mask with <src>mask(n)</src> method.
// The variables are referenced with <src>x[i]</src>.
//
// </synopsis>
// <example>
// A complete implementation of say an <src>A.sin(2pi.f.x)</src> with
// parameters amplitude(<em>A</em>) and frequency(<em>f</em>) and variable
// time(<em>x</em>) could be:
// <srcblock>
// //# Sinusoid.h
// #include <casacore/casa/aips.h>
// #include <casacore/scimath/Functionals/Function.h>
// #include <casacore/casa/BasicSL/Constants.h>
// #include <casacore/casa/BasicMath/Math.h>
// // The sinusoid class
// template<class T> class Sinusoid : public Function<T> {
// public:
// // For easy reference of the parameters
// enum { AMPL=0, FREQ };
// // Constructors. Defaults are A=1, f=1
// Sinusoid() : Function<T>(2) {
// param_p[AMPL] = T(1.0); param_p[FREQ] = T(1.0); }
// explicit Sinusoid(const T &ampl) : Function<T>(2) {
// param_p[AMPL] = ampl; param_p[FREQ] = T(1.0); }
// Sinusoid(const T &ampl, const T &freq) : Function<T>(2) {
// param_p[AMPL] = ampl; param_p[FREQ] = freq; }
// Sinusoid(const Sinusoid &other) : Function<T>(2) {
// param_p[AMPL] = other.param_p[AMPL];
// param_p[FREQ] = other.parameter[FREQ]; }
// Sinusoid<T> &operator=(const Sinusoid<T> &other) {
// if (this != &other) param_p = other.param_p;
// return *this; }
// virtual ~Sinusoid() {}
// // Dimensionality
// virtual uInt ndim() const { return 2; }
// // Evaluate
// virtual T eval(Function<T>::FunctionArg x) const {
// return param_p[AMPL]*sin(T(C::_2pi)*param_p[FREQ]*x[0]); }
// // Copy it
// virtual Function<T> *clone() const { return new Sinusoid<T>(param_p); }
// };
// </srcblock>
// The following will calculate the value and the derivative for
// <src>A=2; f=3; x=0.1;</src>
// <srcblock>
// // The function objects for value, and for value + derivative
// Sinusoid<Double> soid1(2.0, 3.0);
// typedef AutoDiff<Double> Adif;
// Sinusoid<Adif> soid2(Adif(2,2,0), Adif(3,2,1));
// cout << "Value: " << soid1(0.1) << endl;
// cout << "(val, deriv): " << soid2(Adif(0.1)) << endl;
// </srcblock>
//
// A shorter version, where all parameter handling is done at user level
// could be:
// <srcblock>
// //# Sinusoid.h
// #include <casacore/casa/aips.h>
// #include <casacore/scimath/Functionals/Function.h>
// #include <casacore/casa/BasicSL/Constants.h>
// #include <casacore/casa/BasicMath/Math.h>
// template<class T> class Sinusoid : public Function<T> {
// public:
// enum { AMPL=0, FREQ };
// Sinusoid() : Function<T>(2){param_p[AMPL] T(1);param_p[FREQ]=T(1);}
// virtual ~Sinusoid() {}
// virtual uInt ndim() const { return 2; }
// virtual T eval(Function<T>::FunctionArg x) const {
// return param_p[AMPL]*sin(T(C::_2pi)*param_p[FREQ]*x[0]); }
// virtual Function<T> *clone() const { return new Sinusoid<T>param_p; }
// };
// </srcblock>
// The following will calculate the value and the derivative for
// <src>A=2; f=3; x=0.1;</src>
// <srcblock>
// // The function objects for value, and for value + derivative
// typedef AutoDiff<Double> Adif;
// typedef Function<Double> FD;
// typedef Function<AutoDiff<Double> > FAdif
// Sinusoid<Double> soid1;
// Sinusoid<Adif> soid2;
// soid1[FD::AMPL] = 2; soid1[FD::FREQ] = 3;
// soid2[FAdif::AMPL] = Adif(2,2,0);
// soid2[FAdif::FREQ] = Adif(3,2,1);
// cout << "Value: " << soid1(0.1) << endl;
// cout << "(val, deriv): " << soid2(Adif(0.1)) << endl;
// </srcblock>
// </example>
// <motivation>
// A function of more than one variable was required for a function which
// represents the sky brightness. Adjustable parameters were required for
// non-linear least squares fitting.
// </motivation>
//
// <templating arg=T>
// <li> Besides the requirements set by the
// <linkto class="Functional">Functional</linkto> base class, it must be
// possible to form a <src>Vector<T></src>.
// </templating>
//
// <todo asof="2005/01/20">
// <li> At some point, we may want to implement a letter-envelope class,
// implement function arithmetic, etc.
// <li> use maybe Poolstack for static Vector
// </todo>
template<class T, class U=T> class Function :
public Functional<typename FunctionTraits<T>::ArgType, U>,
public Functional<Vector<typename FunctionTraits<T>::ArgType>, U> {
public:
//# Typedefs
typedef typename FunctionTraits<T>::ArgType ArgType;
typedef const ArgType* FunctionArg;
//# Constructors
// Constructors
// <group>
Function() : param_p(), arg_p(0), parset_p(False), locked_p(False) {}
explicit Function(const uInt n) : param_p(n), arg_p(0), parset_p(False),
locked_p(False) {}
explicit Function(const Vector<T> &in) : param_p(in), arg_p(0),
parset_p(False), locked_p(False) {}
Function(const FunctionParam<T> &other) : param_p(other), arg_p(0),
parset_p(False), locked_p(False) {}
template <class W, class X>
Function(const Function<W,X> &other) : param_p(other.parameters()),
arg_p(0), parset_p(other.parsetp()), locked_p(False) {}
// </group>
// Destructor
virtual ~Function() {}
// Returns the number of dimensions of function
virtual uInt ndim() const = 0;
// Returns the number of parameters
uInt nparameters() const { return param_p.nelements(); }
// Evaluate the function object
virtual U eval(FunctionArg x) const = 0;
//# Operators
// Manipulate the nth parameter (0-based) with no index check
// <group>
T &operator[](const uInt n) { parset_p |= !locked_p;
return param_p[n]; }
const T &operator[](const uInt n) const { return param_p[n]; }
// </group>
// Evaluate this function object at <src>x</src>or at <src>x, y</src>.
// The length of <src>x</src> must be greater than or equal to
// <src>ndim()</src>.
// <group>
virtual U operator()() const {
DebugAssert(ndim()==0, AipsError); return eval(FunctionArg(0)); }
virtual U operator()(const ArgType &x) const {
DebugAssert(ndim()<=1, AipsError); return eval(&x); }
virtual U operator()(const Vector<ArgType> &x) const;
virtual U operator()(FunctionArg x) const { return eval(x); }
virtual U operator()(const ArgType &x, const ArgType &y) const;
virtual U operator()(const ArgType &x, const ArgType &y,
const ArgType &z) const;
// </group>
//# Member functions
// Specify the name associated with the function (default will be
// <src>unknown</src>)
virtual const String &name() const;
// Manipulate the mask associated with the nth parameter
// (e.g. to indicate whether the parameter is adjustable or
// nonadjustable).
// Note: no index check.
// <group>
Bool &mask(const uInt n) { parset_p |= !locked_p;
return param_p.mask(n); }
const Bool &mask(const uInt n) const { return param_p.mask(n); }
// </group>
// Return the parameter interface
// <group>
const FunctionParam<T> &parameters() const { return param_p; }
FunctionParam<T> &parameters() { parset_p = True; return param_p; }
// </group>
// Get <src>arg_p</src> and <src>parset_p</src>. Necessary for reasons
// of protection in the copying of non-conforming Functions.
// <group>
const Vector<ArgType> &argp() const { return arg_p; }
Bool parsetp() const { return parset_p; }
// </group>
// Compiler cannot always find the correct 'const' version of parameter
// access. In cases where this would lead to excessive overheads in
// moving parameters around (like in <src>CompoundFunction</src>) the
// parameter changing can be set to be locked, and no changes are
// assumed.
// <group>
void lockParam() { locked_p = True; }
void unlockParam() { locked_p = False; }
// </group>
// get/set the function mode. These provide an interface to
// function-specific configuration or state that controls how the
// function calculates its values but otherwise does not qualify as
// a parameter. Some part of the state, for example, might have a
// type different from that of T. The state is passed as fields of a
// record, mode--the names, types and values of which are specific to
// the implementing function and should be documented in the implementing
// class. It is recommended that all possible inputs passed to this
// function via setMode() be considered optional such that if the
// record omits a legal field, that part of the state is left unchanged.
// Fields not recognized by the implementing class should be ignored.
// An exception should be thrown if a recognized field contains illegal
// data. The default implementations for both getMode() and setMode()
// ignore the input record.
// <group>
virtual void setMode(const RecordInterface& mode);
virtual void getMode(RecordInterface& mode) const;
// </group>
// return True if the implementing function supports a mode. The default
// implementation returns False.
virtual Bool hasMode() const;
// Print the function (i.e. the parameters)
ostream &print(ostream &os) const { return param_p.print(os); }
// Return a copy of this object from the heap. The caller is responsible
// for deleting this pointer. The <src>cloneAD</src> will return a clone
// with an <src>AutoDef<T></src>; the <src>cloneNonAD</src> a clone
// with <src><T></src>. An <src>AipsError</src> will be thrown if the
// <src>cloneAD()</src> or <src>cloneNonAD()</src> is not implemented
// for a specific function.
// <group>
virtual Function<T,U> *clone() const = 0;
virtual Function<typename FunctionTraits<T>::DiffType> *cloneAD() const;
virtual Function<typename FunctionTraits<T>::BaseType>
*cloneNonAD() const;
// </group>
protected:
//# Data
// The parameters and masks
FunctionParam<T> param_p;
// Aid for non-contiguous argument storage
mutable Vector<ArgType> arg_p;
// Indicate parameter written
mutable Bool parset_p;
// Indicate that parameters are expected to be locked from changing
mutable Bool locked_p;
};
//# Global functions
// <summary> Global functions </summary>
// <group name=Output>
// Output declaration
template<class T, class U>
ostream &operator<<(ostream &os, const Function<T,U> &fun);
// </group>
//# Inlines
template<class T, class U>
inline ostream &operator<<(ostream &os, const Function<T,U> &fun) {
return fun.print(os); }
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/scimath/Functionals/Function.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
DebugAssert
#define DebugAssert(expr, exception)
Definition Assert.h:183
casacore::AipsError
Definition Error.h:133
casacore::FunctionParam
Definition FunctionParam.h:85
casacore::FunctionTraits::ArgType
T ArgType
Type for arguments.
Definition FunctionTraits.h:148
casacore::Function
Definition Function.h:200
casacore::Function::param_p
FunctionParam< T > param_p
The parameters and masks.
Definition Function.h:330
casacore::Function::ArgType
FunctionTraits< T >::ArgType ArgType
Definition Function.h:204
casacore::Function::setMode
virtual void setMode(const RecordInterface &mode)
get/set the function mode.
casacore::Function::operator[]
const T & operator[](const uInt n) const
Definition Function.h:238
casacore::Function::operator()
virtual U operator()(const ArgType &x, const ArgType &y) const
casacore::Function::Function
Function(const Vector< T > &in)
Definition Function.h:213
casacore::Function::operator()
virtual U operator()(const ArgType &x) const
Definition Function.h:246
casacore::Function::parameters
FunctionParam< T > & parameters()
Definition Function.h:271
casacore::Function::clone
virtual Function< T, U > * clone() const =0
Return a copy of this object from the heap.
casacore::Function::Function
Function()
Constructors.
Definition Function.h:210
casacore::Function::getMode
virtual void getMode(RecordInterface &mode) const
casacore::Function::operator()
virtual U operator()() const
Evaluate this function object at xor at x, y.
Definition Function.h:244
casacore::Function::cloneNonAD
virtual Function< typename FunctionTraits< T >::BaseType > * cloneNonAD() const
casacore::Function::unlockParam
void unlockParam()
Definition Function.h:286
casacore::Function::mask
Bool & mask(const uInt n)
Manipulate the mask associated with the nth parameter (e.g.
Definition Function.h:264
casacore::Function::mask
const Bool & mask(const uInt n) const
Definition Function.h:266
casacore::Function::operator()
virtual U operator()(FunctionArg x) const
Definition Function.h:249
casacore::Function::parameters
const FunctionParam< T > & parameters() const
Return the parameter interface.
Definition Function.h:270
casacore::Function::lockParam
void lockParam()
Compiler cannot always find the correct 'const' version of parameter access.
Definition Function.h:285
casacore::Function::Function
Function(const Function< W, X > &other)
Definition Function.h:218
casacore::Function::operator[]
T & operator[](const uInt n)
Manipulate the nth parameter (0-based) with no index check.
Definition Function.h:236
casacore::Function::ndim
virtual uInt ndim() const =0
Returns the number of dimensions of function.
casacore::Function::hasMode
virtual Bool hasMode() const
return True if the implementing function supports a mode.
casacore::Function::~Function
virtual ~Function()
Destructor.
Definition Function.h:223
casacore::Function::name
virtual const String & name() const
Specify the name associated with the function (default will be unknown).
casacore::Function::operator()
virtual U operator()(const ArgType &x, const ArgType &y, const ArgType &z) const
casacore::Function::Function
Function(const uInt n)
Definition Function.h:211
casacore::Function::arg_p
Vector< ArgType > arg_p
Aid for non-contiguous argument storage.
Definition Function.h:332
casacore::Function::print
ostream & print(ostream &os) const
Print the function (i.e.
Definition Function.h:313
casacore::Function::operator()
virtual U operator()(const Vector< ArgType > &x) const
casacore::Function::argp
const Vector< ArgType > & argp() const
Get arg_p and parset_p.
Definition Function.h:276
casacore::Function::parset_p
Bool parset_p
Indicate parameter written.
Definition Function.h:334
casacore::Function::Function
Function(const FunctionParam< T > &other)
Definition Function.h:215
casacore::Function::eval
virtual U eval(FunctionArg x) const =0
Evaluate the function object.
casacore::Function::nparameters
uInt nparameters() const
Returns the number of parameters.
Definition Function.h:228
casacore::Function::locked_p
Bool locked_p
Indicate that parameters are expected to be locked from changing.
Definition Function.h:336
casacore::Function::FunctionArg
const ArgType * FunctionArg
Definition Function.h:205
casacore::Function::parsetp
Bool parsetp() const
Definition Function.h:277
casacore::Function::cloneAD
virtual Function< typename FunctionTraits< T >::DiffType > * cloneAD() const
casacore::Functional
Definition Functional.h:120
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::Vector
Definition Vector.h:82
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::operator<<
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::RecordInterface
RecordInterface()
The default constructor creates an empty record with a variable structure.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::True
const Bool True
Definition aipstype.h:41
casacore::Function_global_functions_Output
Global functions .
Definition Function.h:343
casacore::Function_global_functions_Output::operator<<
ostream & operator<<(ostream &os, const Function< T, U > &fun)
Output declaration.