roboptim::Function Class Referenceabstract

Define an abstract mathematical function ( $C^0$). More...

#include <roboptim/core/function.hh>

+ Inheritance diagram for roboptim::Function:

Public Types

typedef double value_type
 Values type. More...
 
typedef std::size_t size_type
 Size type. More...
 
typedef ublas::vector< value_typevector_t
 Basic vector type. More...
 
typedef ublas::matrix< value_typematrix_t
 Basic matrix type. More...
 
typedef vector_t result_t
 Type of a function evaluation result. More...
 
typedef vector_t argument_t
 Type of a function evaluation argument. More...
 

Public Member Functions

bool isValidResult (const result_t &result) const throw ()
 Check the given result size is valid. More...
 
size_type inputSize () const throw ()
 Return the input size (i.e. argument's vector size). More...
 
size_type outputSize () const throw ()
 Return the output size (i.e. result's vector size). More...
 
virtual ~Function () throw ()
 Trivial destructor. More...
 
result_t operator() (const argument_t &argument) const throw ()
 Evaluate the function at a specified point. More...
 
void operator() (result_t &result, const argument_t &argument) const throw ()
 Evaluate the function at a specified point. More...
 
const std::string & getName () const throw ()
 Get function name. More...
 
virtual std::ostream & print (std::ostream &) const throw ()
 Display the function on the specified output stream. More...
 

Static Public Member Functions

static const value_type infinity () throw ()
 Get the value that symbolizes positive infinity. More...
 

Protected Member Functions

 Function (size_type inputSize, size_type outputSize=1, std::string name=std::string()) throw ()
 Concrete class constructor should call this constructor. More...
 
virtual void impl_compute (result_t &result, const argument_t &argument) const =0 throw ()
 Function evaluation. More...
 

Interval

typedef std::pair< value_type,
value_type
interval_t
 Interval type (lower, upper). Use negative or positive infinity to respectively disable the lower or upper bound. More...
 
typedef std::vector< interval_tintervals_t
 Vector of intervals. More...
 
static interval_t makeInterval (value_type l, value_type u) throw ()
 Construct an interval from a lower and upper bound. More...
 
static interval_t makeInfiniteInterval () throw ()
 Construct an infinite interval. More...
 
static interval_t makeLowerInterval (value_type l) throw ()
 Construct an interval from a lower bound. More...
 
static interval_t makeUpperInterval (value_type u) throw ()
 Construct an interval from an upper bound. More...
 
static double getLowerBound (const interval_t &interval) throw ()
 Get the lower bound of an interval. More...
 
static double getUpperBound (const interval_t &interval) throw ()
 Get the upper bound of an interval. More...
 

Discrete interval

typedef boost::tuple
< value_type, value_type,
value_type
discreteInterval_t
 Types representing a discrete interval. A discrete interval is a triplet of values: More...
 
static discreteInterval_t makeDiscreteInterval (value_type min, value_type max, value_type step)
 Construct a discrete interval. More...
 
static discreteInterval_t makeDiscreteInterval (interval_t interval, value_type step)
 Construct a discrete interval. More...
 
static double getLowerBound (const discreteInterval_t &interval) throw ()
 Get the lower bound of a discrete interval. More...
 
static double getUpperBound (const discreteInterval_t &interval) throw ()
 Get the upper bound of a discrete interval. More...
 
static double getStep (const discreteInterval_t &interval) throw ()
 Get the upper step of a discrete interval. More...
 
template<typename F >
static void foreach (const discreteInterval_t interval, F functor)
 Iterate on an interval. More...
 
template<typename F >
static void foreach (const interval_t interval, const size_type n, F functor)
 Iterate on an interval. More...
 

Detailed Description

Define an abstract mathematical function ( $C^0$).

A function is an object that can be evaluated for a given point.

\[ f : x \rightarrow f(x) \]

$x \in \mathbb{R}^n$, $f(x) \in \mathbb{R}^m$ where $n$ is the input size and $m$ is the output size.

Functions are pure immutable objects: evaluating a function twice at a given point must give the same result.

Examples:
visualization-gnuplot-function.cc.

Member Typedef Documentation

Type of a function evaluation argument.

Types representing a discrete interval. A discrete interval is a triplet of values:

  • lower bound,
  • upper bound,
  • step.

Interval type (lower, upper). Use negative or positive infinity to respectively disable the lower or upper bound.

Vector of intervals.

typedef ublas::matrix<value_type> roboptim::Function::matrix_t

Basic matrix type.

This basic matrix type is used each time a two dimensional matrix of values is needed.

Attention
It is good practice in RobOptim to rely on this type when a matrix of values is needed instead of relying on a particular implementation.
Examples:
numeric-linear-function.cc, and numeric-quadratic-function.cc.

Type of a function evaluation result.

typedef std::size_t roboptim::Function::size_type

Size type.

This type is used to represent sizes, indexes, etc.

Values type.

Represents the numerical type (i.e. float, double, int...) used for computations.

typedef ublas::vector<value_type> roboptim::Function::vector_t

Basic vector type.

This basic vector type is used each time a vector of values is required.

Attention
It is good practice in RobOptim to rely on this type when a vector of values is needed instead of relying on a particular implementation.
Examples:
constant-function.cc, identity-function.cc, numeric-linear-function.cc, numeric-quadratic-function.cc, and problem-cc.cc.

Constructor & Destructor Documentation

roboptim::Function::~Function ( )
throw (
)
virtual

Trivial destructor.

roboptim::Function::Function ( size_type  inputSize,
size_type  outputSize = 1,
std::string  name = std::string () 
)
throw (
)
protected

Concrete class constructor should call this constructor.

Parameters
inputSizefunction arity
outputSizeresult size
namefunction's name

Member Function Documentation

template<typename F >
static void roboptim::Function::foreach ( const discreteInterval_t  interval,
functor 
)
inlinestatic

Iterate on an interval.

Call the functor to each discretization point of the discrete interval.

Parameters
intervalinterval on which the method iterates
functorunary function that will be applied
Template Parameters
Ffunctor type (has to satisfy the STL unary function concept)
template<typename F >
static void roboptim::Function::foreach ( const interval_t  interval,
const size_type  n,
functor 
)
inlinestatic

Iterate on an interval.

Call the functor regularly n times on an interval.

Parameters
intervalinterval on which the method iterates
nnumber of discretization points
functorunary function that will be applied
Template Parameters
Ffunctor type (has to satisfy the STL unary function concept)
static double roboptim::Function::getLowerBound ( const interval_t interval)
throw (
)
inlinestatic

Get the lower bound of an interval.

Parameters
intervalaccessed interval
Returns
lower bound of the interval
static double roboptim::Function::getLowerBound ( const discreteInterval_t interval)
throw (
)
inlinestatic

Get the lower bound of a discrete interval.

Parameters
intervalaccessed discrete interval
Returns
lower bound of the discrete interval
const std::string& roboptim::Function::getName ( ) const
throw (
)
inline
static double roboptim::Function::getStep ( const discreteInterval_t interval)
throw (
)
inlinestatic

Get the upper step of a discrete interval.

Parameters
intervalaccessed discrete interval
Returns
upper step of the discrete interval
static double roboptim::Function::getUpperBound ( const interval_t interval)
throw (
)
inlinestatic

Get the upper bound of an interval.

Parameters
intervalaccessed interval
Returns
upper bound of the interval
static double roboptim::Function::getUpperBound ( const discreteInterval_t interval)
throw (
)
inlinestatic

Get the upper bound of a discrete interval.

Parameters
intervalaccessed discrete interval
Returns
upper bound of the discrete interval
virtual void roboptim::Function::impl_compute ( result_t result,
const argument_t argument 
) const
throw (
)
protectedpure virtual

Function evaluation.

Evaluate the function, has to be implemented in concrete classes.

Warning
Do not call this function directly, call operator()(result_t&, const argument_t&) const throw () instead.
Parameters
resultresult will be stored in this vector
argumentpoint at which the function will be evaluated

Implemented in roboptim::NTimesDerivableFunction< 2 >, roboptim::FiniteDifferenceGradient< FdgPolicy >, roboptim::NumericQuadraticFunction, roboptim::NumericLinearFunction, roboptim::ConstantFunction, and roboptim::IdentityFunction.

static const value_type roboptim::Function::infinity ( )
throw (
)
inlinestatic

Get the value that symbolizes positive infinity.

Returns
representation of positive infinity in the value type

Referenced by makeInfiniteInterval(), makeLowerInterval(), makeUpperInterval(), and roboptim::Problem< F, CLIST >::print().

size_type roboptim::Function::inputSize ( ) const
throw (
)
inline
bool roboptim::Function::isValidResult ( const result_t result) const
throw (
)
inline

Check the given result size is valid.

Parameters
resultresult that will be checked
Returns
true if valid, false if not
static discreteInterval_t roboptim::Function::makeDiscreteInterval ( value_type  min,
value_type  max,
value_type  step 
)
inlinestatic

Construct a discrete interval.

Parameters
minmiminum value of the interval
maxmaxinum value of the interval
stepdiscretization step
static discreteInterval_t roboptim::Function::makeDiscreteInterval ( interval_t  interval,
value_type  step 
)
inlinestatic

Construct a discrete interval.

Parameters
intervalcontinuous interval
stepdiscretization step
static interval_t roboptim::Function::makeInfiniteInterval ( )
throw (
)
inlinestatic

Construct an infinite interval.

Returns
interval representing $[-\infty, +\infty]$

References infinity().

Referenced by roboptim::Problem< F, CLIST >::Problem().

static interval_t roboptim::Function::makeInterval ( value_type  l,
value_type  u 
)
throw (
)
inlinestatic

Construct an interval from a lower and upper bound.

Parameters
llower bound
uupper bound
Returns
interval representing $[l, u]$
static interval_t roboptim::Function::makeLowerInterval ( value_type  l)
throw (
)
inlinestatic

Construct an interval from a lower bound.

Parameters
llower bound
Returns
interval representing $[l, +\infty]$

References infinity().

static interval_t roboptim::Function::makeUpperInterval ( value_type  u)
throw (
)
inlinestatic

Construct an interval from an upper bound.

Parameters
uupper bound
Returns
interval representing $[-\infty, u]$

References infinity().

result_t roboptim::Function::operator() ( const argument_t argument) const
throw (
)
inline

Evaluate the function at a specified point.

The program will abort if the argument does not have the expected size.

Parameters
argumentpoint at which the function will be evaluated
Returns
computed result
void roboptim::Function::operator() ( result_t result,
const argument_t argument 
) const
throw (
)
inline

Evaluate the function at a specified point.

The program will abort if the argument does not have the expected size.

Parameters
resultresult will be stored in this vector
argumentpoint at which the function will be evaluated

References RoboptimCoreDout.

std::ostream & roboptim::Function::print ( std::ostream &  o) const
throw (
)
virtual