Numerical functional interface class. More...

#include <SpectralElement.h>

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

Public Types
typedef FunctionTraits< T > ::ArgType	ArgType

typedef const ArgType *	FunctionArg

Public Member Functions
	Function ()
	Constructors. More...

	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)

virtual	~Function ()
	Destructor. More...

virtual uInt	ndim () const =0
	Returns the number of dimensions of function. More...

uInt	nparameters () const
	Returns the number of parameters. More...

virtual U	eval (FunctionArg x) const =0
	Evaluate the function object. More...

T &	operator[] (const uInt n)
	Manipulate the nth parameter (0-based) with no index check. More...

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

virtual U	operator() () const
	Evaluate this function object at `x`or at `x, y`. More...

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

virtual const String &	name () const
	Specify the name associated with the function (default will be `unknown`) More...

Bool &	mask (const uInt n)
	Manipulate the mask associated with the nth parameter (e.g. More...

const Bool &	mask (const uInt n) const

const FunctionParam< T > &	parameters () const
	Return the parameter interface. More...

FunctionParam< T > &	parameters ()

const Vector< ArgType > &	argp () const
	Get `arg_p` and `parset_p`. More...

Bool	parsetp () const

void	lockParam ()
	Compiler cannot always find the correct 'const' version of parameter access. More...

void	unlockParam ()

virtual void	setMode (const RecordInterface &mode)
	get/set the function mode. More...

virtual void	getMode (RecordInterface &mode) const

virtual Bool	hasMode () const
	return True if the implementing function supports a mode. More...

ostream &	print (ostream &os) const
	Print the function (i.e. More...

virtual Function< T, U > *	clone () const =0
	Return a copy of this object from the heap. More...

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

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

Public Member Functions inherited from casacore::Functional< FunctionTraits< T >::ArgType, U >
virtual	~Functional ()
	Destructor. More...

virtual U	operator() (const FunctionTraits< T >::ArgType &x) const =0
	Map a Domain `x` into a Range `y` value. More...

Public Member Functions inherited from casacore::Functional< Vector< FunctionTraits< T >::ArgType >, U >
virtual	~Functional ()
	Destructor. More...

virtual U	operator() (const Vector< FunctionTraits< T >::ArgType > &x) const =0
	Map a Domain `x` into a Range `y` value. More...

Protected Attributes
FunctionParam< T >	param_p
	The parameters and masks. More...

Vector< ArgType >	arg_p
	Aid for non-contiguous argument storage. More...

Bool	parset_p
	Indicate parameter written. More...

Bool	locked_p
	Indicate that parameters are expected to be locked from changing. More...

Detailed Description

template<class T, class U>
class casacore::Function< T, U >

Numerical functional interface class.

Intended use:

Public interface

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 <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); }
};

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

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 38 of file SpectralElement.h.

Member Typedef Documentation

template<class T, class U>

typedef FunctionTraits<T>::ArgType casacore::Function< T, U >::ArgType

Definition at line 206 of file Function.h.

template<class T, class U>

typedef const ArgType* casacore::Function< T, U >::FunctionArg

Definition at line 207 of file Function.h.

Constructor & Destructor Documentation

template<class T, class U>

casacore::Function< T, U >::Function ( )

inline

Constructors.

Definition at line 212 of file Function.h.

template<class T, class U>

casacore::Function< T, U >::Function ( const uInt n )

inlineexplicit

Definition at line 213 of file Function.h.

template<class T, class U>

casacore::Function< T, U >::Function ( const Vector< T > & in )

inlineexplicit

Definition at line 215 of file Function.h.

template<class T, class U>

casacore::Function< T, U >::Function ( const FunctionParam< T > & other )

inline

Definition at line 217 of file Function.h.

template<class T, class U>

template<class W , class X >

casacore::Function< T, U >::Function ( const Function< W, X > & other )

inline

Definition at line 220 of file Function.h.

template<class T, class U>

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

inline

Definition at line 222 of file Function.h.

template<class T, class U>

virtual casacore::Function< T, U >::~Function ( )

inlinevirtual

Destructor.

Definition at line 233 of file Function.h.

Member Function Documentation

template<class T, class U>

const Vector<ArgType>& casacore::Function< T, U >::argp ( ) const

inline

Get arg_p and parset_p.

Necessary for reasons of protection in the copying of non-conforming Functions.

Definition at line 286 of file Function.h.

template<class T, class U>

virtual Function<T,U>* casacore::Function< T, U >::clone ( ) const

pure virtual

Return a copy of this object from the heap.

The caller is responsible for deleting this pointer. The cloneAD will return a clone with an AutoDef<T>; the cloneNonAD a clone with <T>. An AipsError will be thrown if the cloneAD() or cloneNonAD() is not implemented for a specific function.

template<class T, class U>

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

virtual

Reimplemented in casacore::Gaussian2D_PS< AutoDiff< T > >, casacore::Gaussian3D_PS< AutoDiff< T > >, casacore::Lorentzian1D_PS< AutoDiff< T > >, casacore::Gaussian1D_PS< AutoDiff< T > >, casacore::CompoundFunction_PS< AutoDiff< T > >, casacore::Sinusoid1D_PS< AutoDiff< T > >, casacore::Gaussian2D< T >, casacore::Gaussian2D< casacore::Double >, casacore::CombiFunction_PS< AutoDiff< T > >, casacore::HyperPlane_PS< AutoDiff< T > >, casacore::ConstantND_PS< AutoDiff< T > >, casacore::PoissonFunction_PS< AutoDiff< T > >, casacore::Polynomial_PS< AutoDiff< T > >, casacore::Gaussian3D< T >, casacore::OddPolynomial_PS< AutoDiff< T > >, casacore::EvenPolynomial_PS< AutoDiff< T > >, casacore::PowerLogarithmicPolynomial_PS< AutoDiff< T > >, casacore::Lorentzian1D< T >, casacore::Gaussian1D< T >, casacore::CompiledFunction< T >, casacore::CompoundFunction< T >, casacore::Sinusoid1D< T >, casacore::CompoundFunction< casacore::AutoDiff< Double > >, casacore::CombiFunction< T >, casacore::HyperPlane< T >, casacore::ConstantND< T >, casacore::SincFunction< T >, casacore::UnaryFunction< T >, casacore::DiracDFunction< T >, casacore::Polynomial< T >, casacore::Polynomial< Double >, casacore::Polynomial< casacore::casacore::AutoDiff< casacore::Float > >, casacore::KaiserBFunction< T >, casacore::PoissonFunction< T >, casacore::OddPolynomial< T >, casacore::EvenPolynomial< T >, casacore::SPolynomial< T >, and casacore::PowerLogarithmicPolynomial< T >.

template<class T, class U>

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

virtual

template<class T, class U>

virtual U casacore::Function< T, U >::eval ( FunctionArg x ) const

pure virtual

Evaluate the function object.

Referenced by casacore::Function< Type >::operator()().

template<class T, class U>

virtual void casacore::Function< T, U >::getMode ( RecordInterface & mode ) const

virtual

Reimplemented in casacore::ChebyshevParamModeImpl_PSA< AutoDiffA< T > >, casacore::ChebyshevParamModeImpl_PS< AutoDiff< T > >, casacore::ChebyshevParamModeImpl< T >, and casacore::SimButterworthBandpass< T >.

template<class T, class U>

virtual Bool casacore::Function< T, U >::hasMode ( ) const

virtual

return True if the implementing function supports a mode.

The default implementation returns False.

Reimplemented in casacore::ChebyshevParamModeImpl< T >, and casacore::SimButterworthBandpass< T >.

template<class T, class U>

void casacore::Function< T, U >::lockParam ( )

inline

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 CompoundFunction) the parameter changing can be set to be locked, and no changes are assumed.

Definition at line 295 of file Function.h.

template<class T, class U>

Bool& casacore::Function< T, U >::mask ( const uInt n )

inline

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

to indicate whether the parameter is adjustable or nonadjustable). Note: no index check.

Definition at line 274 of file Function.h.

template<class T, class U>

const Bool& casacore::Function< T, U >::mask ( const uInt n ) const

inline

Definition at line 276 of file Function.h.

template<class T, class U>

virtual const String& casacore::Function< T, U >::name ( ) const

virtual

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

template<class T, class U>

virtual uInt casacore::Function< T, U >::ndim ( ) const

pure virtual

Returns the number of dimensions of function.

Referenced by casacore::Function< Type >::operator()().

template<class T, class U>

uInt casacore::Function< T, U >::nparameters ( ) const

inline

Returns the number of parameters.

Definition at line 238 of file Function.h.

Referenced by casacore::PowerLogarithmicPolynomialParam< AutoDiff< T > >::coefficient(), casacore::ChebyshevParam< AutoDiffA< T > >::getCoefficient(), casacore::ChebyshevParam< AutoDiffA< T > >::nCoefficients(), and casacore::PowerLogarithmicPolynomialParam< AutoDiff< T > >::setCoefficient().

template<class T, class U>

virtual U casacore::Function< T, U >::operator() ( ) const

inlinevirtual

Evaluate this function object at xor at x, y.

The length of x must be greater than or equal to ndim().

Definition at line 254 of file Function.h.

template<class T, class U>

virtual U casacore::Function< T, U >::operator() ( const ArgType & x ) const

inlinevirtual

Definition at line 256 of file Function.h.

template<class T, class U>

virtual U casacore::Function< T, U >::operator() ( const Vector< ArgType > & x ) const

virtual

template<class T, class U>

virtual U casacore::Function< T, U >::operator() ( FunctionArg x ) const

inlinevirtual

Definition at line 259 of file Function.h.

template<class T, class U>

virtual U casacore::Function< T, U >::operator()	(	const ArgType &	x,
		const ArgType &	y
	)		const

virtual

template<class T, class U>

virtual U casacore::Function< T, U >::operator()	(	const ArgType &	x,
		const ArgType &	y,
		const ArgType &	z
	)		const

virtual

template<class T, class U>

T& casacore::Function< T, U >::operator[] ( const uInt n )

inline

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

Definition at line 246 of file Function.h.

template<class T, class U>

const T& casacore::Function< T, U >::operator[] ( const uInt n ) const

inline

Definition at line 248 of file Function.h.

template<class T, class U>

const FunctionParam<T>& casacore::Function< T, U >::parameters ( ) const

inline

Return the parameter interface.

Definition at line 280 of file Function.h.

template<class T, class U>

FunctionParam<T>& casacore::Function< T, U >::parameters ( )

inline

Definition at line 281 of file Function.h.

template<class T, class U>

Bool casacore::Function< T, U >::parsetp ( ) const

inline

Definition at line 287 of file Function.h.

template<class T, class U>

ostream& casacore::Function< T, U >::print ( ostream & os ) const

inline

Print the function (i.e.

the parameters)

Definition at line 323 of file Function.h.

template<class T, class U>

virtual void casacore::Function< T, U >::setMode ( const RecordInterface & mode )

virtual

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.

Reimplemented in casacore::ChebyshevParamModeImpl_PSA< AutoDiffA< T > >, casacore::ChebyshevParamModeImpl_PS< AutoDiff< T > >, casacore::ChebyshevParamModeImpl< T >, and casacore::SimButterworthBandpass< T >.

template<class T, class U>

void casacore::Function< T, U >::unlockParam ( )

inline

Definition at line 296 of file Function.h.