Module Functionals
Changes made in the current development cycle can be
found in the changelog.
A module that represents various function-like classes.
Review Status
- Reviewed By:
- tcornwel
- Date Reviewed:
- 1996/02/13
Etymology
The term Functional was chosen to roughly follow the usage in
Barton and Nackman's Scientific and Engineering C++.
Functional classes map a Domain object into a Range object, rather like a
mathematical function. They use operator(),
so they look much like single argument C++ functions.
Synopsis
Functionals and their derived classes map an input
Domain object into an output Range object using the
operator().
Often the input and output types are numeric, but it can be of any type.
class Offspring : public Functional<List<Parents>, List<Children> > {
public:
List<Children> operator()(List<Parents>);
};
would be a legal Functional.
The Functions and their derived classes map, again using the
operator(), numeric value(s) into a numeric value. Since they are
numeric, the Domain and Range base type can be of type
AutoDiff<T> (where T is numeric base type) or one
of its derivations, in which case the value and its derivatives will be
calculated.
In the current version the Domain and
Range are the same for Functions
The basic classes are:
- Functional<Domain, Range>
-
A base class that maps a Domain object into a Range
object using the Range operator(const Domain &). All
information necessary to convert the Domain into a
Range will be available in the class
or in the input information. No variable class state (parameters)
are available.
- FunctionParam<T>
- A helper base class that acts as a container for parameters
(state) used in Function classes. The class contains
a list of parameters, and a list of flags associated with the parameters.
Methods to set and obtain the parameters (using operator[])
and their flags (using methods mask()) are available. The flags
can e.g. be used to indicate to Fitting routines if a certain
parameter has to be updated ('fitted') or not.
The FunctionParam class does not assume anything about the uses of the
class, but leaves that to the final users. This means that a lot of
copying between intermediate and final users is not necessary
(like between a Gaussian fitter with fixed parameters
and the Fitting routines: the Gaussian fitter just sets a flag to False, and
let the Fitting worry about what to do internally).
- Function<T>
- Base class for function objects with zero or more parameters (i.e.
Functionals with state).
All parameters should be of the same type T as the
Function<T>. Function objects are specifically geared
towards use in the Fitting classes, but
can be used anywhere where the value (and/or derivatives) of functions
are needed.
The Function<T> class is derived from Functional
and contains a FunctionParam<T> object.
The parameters act as state for the function
(e.g. a width for a Gaussian). A function object is called using the
T operator(const T&) (ndim=1), or the
T operator(const Vector<T>&) (all values of ndim), or
T operator(const T&, const T&) (for ndim=2 only).
If the template argument is AutoDiff<T>, the parameters and the
returned value will be AutoDiff<T>; the arguments of the
operator() will be of type T. The returned value
of the function will be the function value at x (and the
derivatives w.r.t. the non-masked parameters) Using AutoDiffA<T>
the derivatives can be calculated w.r.t. parameters and/or arguments, see
AutoDiff and
FunctionTraits for details.
A Function1D is provided for 1-dimensional function objects
Actual functional classes:
- e.g. Gaussian1D<T>
- An actual function object will be derived from
Function<T>. The minimum functionality of a Function
object will be support for the operator() methods (through a
single, hidden, eval() method); for the manipulation of the
associated parameters (using operator[index] and
mask(index)) and some administrative aids (ndim(),
nparameters() and the like.
In most cases it is advantageous to have a special parameter handling
class (e.g. Gaussian1DParam), to separate the (template
independent) parameter handling from the possible specialization of
the eval() method, and to more easily incorporate
special parameter handling (e.g. using flux rather than amplitude
of a Gaussian). All of this is transparent to the end-user.
Combinatory Function objects are provided to easily combine and create
function objects:
- CompoundFunction
- creates
a new, compound, function object from one or more other function objects
(including compounds...). The new function will have the sum of the
parameters of the input functions as the new parameters (i.e the compound
function created from a 1-dimensional Gaussian (with 3 parameters) and a
third-order polynomial (with 4 parameters) will have 7 parameters).
- CombiFunction
- creates
a (linear) combination of a number of input functions. The number of
parameters of the newly created function will be equal to the number of
input functions (i.e. the combi
function created from a 1-dimensional Gaussian (with 3 parameters) and a
third-order polynomial (with 4 parameters) will have 2 parameters). The
function will be param0*gauss(x) + param1*poly(x)
- FunctionWrapper
- will take
a global function (or by the use of the STL function adapters
mem_fun* also member functions) of any dimension, and with
any number of parameters. The function is assumed to be called as
f(x, p), and is wrapped like
FunctionWrapper(&func, param&, ndim) (see example).
Example
A function to find a bracketed root by bisection could be written
as follows:
template <class Domain, class Range>
Domain findRoot(const Functional<Domain,Range> &func, Domain left,
Domain right, Domain tol) {
Range fr = func(right);
Range fl = func(left);
Range sign = fr > 0 ? 1 : -1 ;
AlwaysAssertExit(fl*fr < 0.0 && right > left);
while (right - left > tol) {
Domain mid = (left + right) / 2;
Range fmid = func(mid);
if (sign*fmid > 0.0) right = mid;
else left = mid;
};
return (left + right)/2;
}
Since Function1D is derived from Functional, the
above function will also work with classes derived from Function1D. To
behave sensibly, the Domain and Range types should be real, i.e.,
Float or Double.
To calculate the value of a polynomial
2 + 4x<sup>2</sup> + 6x<sup>4</sup>
at x=5.1:
Polynomial<Double> pol(4);
pol[0] = 2; pol[2] = 4; pol[4] = 6;
cout << "Polynomial value at 5.1: " << pol(5.1) << endl;
Create a simple function (1-dimensional) with 2 parameters (A and B):
Double myf(const Double x, const Vector<Double> p) {
return p[0]*sin(p[1]*x); }
make it into a function object for initial parameters 2 and pi:
Vector<Double> p(2);
p[0] = 2; p[1] = C::pi;
FunctionWrapper<Double> f0(myf, p, 2);
Make the first parameter 3:
f0[0] = 3;
(for the global function you have to change p[0]).
Calculate the value of the function:
cout << "The value " << f0(3) << " should be 1.5 times the value " <<
myf(3) << endl;
A function object could be created as:
template<class T> class objf : public Function<T> {
public:
objf() : Function<T>(2) {}; // 2 parameters
objf(const objf<T> &other) : Function<T>(other) {};
virtual ~objf() {};
// The actual method called for the evaluation operator():
virtual T eval(typename Function<T>::FunctionArg x) const {
return param_p[0] * sin(param_p[1] * x[0]); };
// Return a copy of function (used for combination e.g.)
virtual Function<T> *clone() const {
return new objf<T>(*this); };
};
Which can be called as:
objf<Double> f1;
f1[0] = 2; f1[1] = C::pi;
cout << "The value " << myf(3) << " should be equal to the value " <<
f1(3) << endl;
Motivation
The immediate motivations for this module were:
- To represent functions which are used in linear and non-linear least
squares fitting
To Do
- It could be convenient to have a letter/envelope class, and to
define ``function arithmetic.''
- ArraySampledFunctional -- Index into an array using the longest axis (full description)
- Chebyshev -- A function class that defines a Chebyshev polynomial (full description)
- ChebyshevEnums -- Define enums for Chebyshev classes (full description)
- ChebyshevParam -- Parameter handling for Chebyshev polynomial parameters (full description)
- ChebyshevParamModeImpl -- A ChebyshevParam with the get/setMode implementation (full description)
- ChebyshevParamModeImpl_PS -- Partial specialization of ChebyshevParamModeImpl for AutoDiff (full description)
- ChebyshevParamModeImpl_PSA -- Partial specialization of ChebyshevParamModeImpl for AutoDiff (full description)
- CombiFunction -- Form a linear combination of function objects. (full description)
- CombiFunction_PS -- Partial specialization of CombiFunction for AutoDiff (full description)
- CombiParam -- Parameters for a linear combination of function objects. (full description)
- CompiledFunction -- Form a linear combination of function objects. (full description)
- CompiledParam -- Parameters for a compiled string function object. (full description)
- CompoundFunction -- Sum of a collection of Functions which behaves as one Function object. (full description)
- CompoundFunction_PS -- Partial AutoDiff specialization of CompoundFunction (full description)
- CompoundParam -- Parameters for sum of parameterized Functions (full description)
- DiracDFunction -- A one dimensional Dirac delta function (full description)
- DiracDParam -- A one dimensional Dirac delta function (full description)
- EclecticFunctionFactory -- (full description)
- EvenPolynomial -- A one dimensional odd polynomial class (full description)
- EvenPolynomialParam -- Parameter handling for even polynomials (full description)
- EvenPolynomial_PS -- Partial specialization of EvenPolynomial for AutoDiff (full description)
- FieldNotFoundError -- (full description)
- FuncExprData -- Data and enumerations for functional expressions (full description)
- FuncExpression -- An expression executable as function (full description)
- Function -- Numerical functional interface class (full description)
- Function1D -- Numerical functional interface class for 1 dimension (full description)
- FunctionFactory -- (full description)
- FunctionFactoryError -- (full description)
- FunctionHolder -- A holder for Functions to enable record conversions (full description)
- FunctionMarshallable -- (full description)
- FunctionOrder -- Container of function description details (full description)
- FunctionParam -- Container of function parameters with masking flags (full description)
- FunctionTraits -- Function data types for parameters and arguments (full description)
- FunctionTraits_P -- FunctionTraits specialization for AutoDiff (full description)
- FunctionTraits_PA -- FunctionTraits specialization for AutoDiffA (full description)
- FunctionTraits_PX -- FunctionTraits specialization for AutoDiffX (full description)
- FunctionWrapper -- Construct nD function objects from C++ functions (full description)
- FunctionalProxy -- (full description)
- GNoiseFunction -- A one dimensional normal distribution (full description)
- GNoiseParam -- A one dimensional normal distribution (full description)
- Gaussian1D -- A one dimensional Gaussian class. (full description)
- Gaussian1DParam -- Parameter handling for one dimensional Gaussian class. (full description)
- Gaussian1D_PS -- Partial specialization of Gaussian1D for AutoDiff (full description)
- Gaussian2D -- A two dimensional Gaussian class. (full description)
- Gaussian2DParam -- Parameter handling for 2 dimensional Gaussian class (full description)
- Gaussian2D_PS -- Partial specialization of Gaussian2D for AutoDiff (full description)
- Gaussian3D -- A three dimensional Gaussian class. (full description)
- Gaussian3DParam -- Parameter handling for 3 dimensional Gaussian class (full description)
- Gaussian3D_PS -- Partial specialization of Gaussian3D for AutoDiff (full description)
- GaussianND -- A Multi-dimensional Gaussian functional. (full description)
- GaussianNDParam -- A Multi-dimensional Gaussian parameter handling. (full description)
- HyperPlane -- A hyper plane function. (full description)
- HyperPlaneParam -- Parameter handling for a hyper plane function. (full description)
- HyperPlane_PS -- Partial specialization of HyperPlane for AutoDiff (full description)
- Interpolate1D -- Interpolate in one dimension (full description)
- InvalidSerializationError -- (full description)
- KaiserBFunction -- A one dimensional Kaiser-Bessel function (full description)
- KaiserBParam -- A one dimensional Kaiser-Bessel function (full description)
- MarshButterworthBandpass -- A Butterworth function class that supports serialization (full description)
- MarshallableChebyshev -- A Chebyshev function class that supports serialization (full description)
- OddPolynomial -- A one dimensional odd polynomial class (full description)
- OddPolynomialParam -- Parameter handling for odd polynomials (full description)
- OddPolynomial_PS -- Partial specialization of OddPolynomial for AutoDiff (full description)
- Output -- Global functions (full description)
- Output -- Global functions (full description)
- Output -- Global functions (full description)
- Polynomial -- A one dimensional polynomial class (full description)
- PolynomialParam -- Parameter handling for one-dimensional polynomials (full description)
- Polynomial_PS -- Partial specialization of Polynomial for AutoDiff (full description)
- SPolynomial -- A one dimensional scaled polynomial class (full description)
- SPolynomialParam -- Parameter handling for scaled 1-D polynomials (full description)
- SampledFunctional -- A base class for indexing into arbitrary data types (full description)
- ScalarSampledFunctional -- A unified interface for indexing into Vectors or Blocks (full description)
- SerialHelper -- (full description)
- SimButterworthBandpass -- a class for evaluating a Butterworth filter transfer function. (full description)
- SincFunction -- A one dimensional sin(x)/x (full description)
- SincParam -- A one dimensional sin(x)/x (full description)
- Sinusoid1D -- A one dimensional Sinusoid class. (full description)
- Sinusoid1DParam -- Parameter handling for one dimensional Sinusoid class (full description)
- Sinusoid1D_PS -- Partial specialization of Sinusoid1D for AutoDiff (full description)
- SpecificFunctionFactory -- (full description)
- UnaryFunction -- A one dimensional unary function (full description)
- UnaryParam -- Parameter handling for one dimensional unary function (full description)
- UnrecognizedFunctionError -- (full description)
- WrapperBase -- Aid in constructing function objects from C++ functions (full description)
- WrapperData -- Aid in constructing function objects from C++ functions (full description)
- WrapperData_FF -- Specialization for calls with no arguments and no parameters (full description)
- WrapperData_FT -- Specialization for calls with no arguments and parameter (full description)
- WrapperData_FV -- Specialization for calls with no arguments and parameters (full description)
- WrapperData_TF -- Specialization for calls with argument and no parameters (full description)
- WrapperData_TT -- Specialization for calls with argument and parameter (full description)
- WrapperData_TV -- Specialization for calls with argument and parameters (full description)
- WrapperData_VF -- Specialization for calls with argument and no parameters (full description)
- WrapperData_VT -- Specialization for calls with argument and parameter (full description)
- WrapperData_VV -- Specialization for calls with argument and parameters (full description)
- WrapperParam -- Parameter handling for wrapped function objects (full description)
- execute -- Execute function (full description)
- output -- Output function (full description)
- output -- Output function (full description)