casa::Function< T, U > Class Template Reference
[Functionals]

#include <Function.h>

Inheritance diagram for casa::Function< T, U >:

[legend]Collaboration diagram for casa::Function< T, U >:

[legend]List of all members.

Detailed Description

template<class T, class U = T>
class casa::Function< T, U >

Numerical functional interface class.

Intended use:

Part of API

Review Status

Reviewed By:: tcornwel
Date Reviewed:: 1996/02/22
Test programs:: tGaussian2D

Prerequisite

Synopsis

A Function is used for classes which map a scalar or n-dimensional Vector of type T into a T. The object also has zero or more parameters which can be masked if necessary, and be used in the Fitting module, and, implicitly, in the AutoDiff differentiation module.

The parameter interface is provided by the FunctionParam class.

A Function can have a name() which can be used in generic interfaces.

The function calls implemented are:

operator()()
operator()(const T &x)
operator()(const Vector<T> &x)
operator()(Function::FunctionArg x)
operator()(const T &x, const T &y) (for 2D)
operator()(const T &x, const T &y, const T &z) (for 3D)

The T in the above is the Function::ArgType as derived from the FunctionTraits class. These calls are (in debug mode) tested for the correct number of arguments, after which they call a T eval(FunctionArg x) const = 0 to be implemented in derived classes. The derived class should also implement an uInt ndim() const = 0. The derived class can access the nth parameter with the [n] operator, and the corresponding mask with mask(n) method. The variables are referenced with x[i].

Example

A complete implementation of say an A.sin(2pi.f.x) with parameters amplitude(A) and frequency(f) and variable time(x) could be:

      //# Sinusoid.h
      \#include <casa/aips.h>
      \#include <scimath/Functionals/Function.h>
      \#include <casa/BasicSL/Constants.h>
      \#include <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); };
      };

The following will calculate the value and the derivative for A=2; f=3; x=0.1;

        // 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;

A shorter version, where all parameter handling is done at user level could be:

      //# Sinusoid.h
      \#include <casa/aips.h>
      \#include <scimath/Functionals/Function.h>
      \#include <casa/BasicSL/Constants.h>
      \#include <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; };
      };

The following will calculate the value and the derivative for A=2; f=3; x=0.1;

        // 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;

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.

Template Type Argument Requirements (T)

Besides the requirements set by the Functional base class, it must be possible to form a Vector<T>.

To Do

At some point, we may want to implement a letter-envelope class, implement function arithmetic, etc.
use maybe Poolstack for static Vector

Definition at line 199 of file Function.h.

Public Types

typedef FunctionTraits< T
>::ArgType ArgType

typedef const ArgType * FunctionArg

Public Member Functions

virtual ~Function ()

Destructor.

virtual uInt ndim () const=0

Returns the number of dimensions of function.

uInt nparameters () const

Returns the number of parameters.

virtual U eval (FunctionArg x) const =0

Evaluate the function object.

virtual const String & name () const

Specify the name associated with the function (default will be unknown).

virtual Bool hasMode () const

return True if the implementing function supports a mode.

ostream & print (ostream &os) const

Print the function (i.e.

Function ()

Constructors.

Function (const uInt n)

Function (const Vector< T > &in)

Function (const FunctionParam< T > &other)

template<class W, class X>

Function (const Function< W, X > &other)

Function (const Function< T, U > &other)

T & operator[] (const uInt n)

Manipulate the nth parameter (0-based) with no index check.

const T & operator[] (const uInt n) const

virtual U operator() () const

Evaluate this function object at xor at x, y.

virtual U operator() (const ArgType &x) const

virtual U operator() (const Vector< ArgType > &x) const

virtual U operator() (FunctionArg x) const

virtual U operator() (const ArgType &x, const ArgType &y) const

virtual U operator() (const ArgType &x, const ArgType &y, const ArgType &z) const

Bool & mask (const uInt n)

Manipulate the mask associated with the nth parameter (e.g.

const Bool & mask (const uInt n) const

const FunctionParam< T > & parameters () const

Return the parameter interface.

FunctionParam< T > & parameters ()

const Vector< ArgType > & argp () const

Get arg_p and parset_p.

const Bool parsetp () const

void lockParam ()

Compiler cannot always find the correct 'const' version of parameter access.

void unlockParam ()

virtual void setMode (const RecordInterface &mode)

get/set the function mode.

virtual void getMode (RecordInterface &mode) const

virtual Function< T, U > * clone () const=0

Return a copy of this object from the heap.

virtual Function< typename
FunctionTraits< T >::DiffType > * cloneAD () const

virtual Function< typename
FunctionTraits< T >::BaseType > * cloneNonAD () const

Protected Attributes

FunctionParam< T > param_p

The parameters and masks.

Vector< ArgType > arg_p

Aid for non-contiguous argument storage.

Bool parset_p

Indicate parameter written.

Bool locked_p

Indicate that parameters are expected to be locked from changing.