HCL_Functional

class HCL_Functional_d : public HCL_Base

HCL_Functional is the base class for all real-valued functions

Inheritance:

Public Methods
Protected Methods

Inherited from HCL_Base:

Public Methods
void IncCount() const
void DecCount() const
int Count() const
virtual ostream& Write(ostream &) const

Documentation

HCL_Functional is the base class for all real-valued functions. The purpose of this class is to represent objective functions in optimization problems.
The primary methods of this class are
Domain Returns a reference to the domain of the functional, which is a vector space. This is used primarily for error-checking; for example:
   if( x.Space() != f.Domain() )
      // Error condition
Value Returns the value of the functional at a point. Example:
   double fx = f.Value( x );
Gradient Computes the gradient of the functional at a point. Example:
   HCL_Vector_d * g = f.Domain().Member(); // Get a vector to hold the gradient
   f.Gradient( x,*g ); // Fill *g with the gradient of f at x
Hessian Computes the Hessian of the functional at a point. Example:
   HCL_LinearOp_d * L = f.Hessian( x ); // Get the Hessian operator at x.
Evaluate Returns an "evaluation object", that is, an object of class HCL_EvaluateFunctional_d, which knows the value, gradient, and Hessian of the functional at given point. Typically, this method should be used to compute the value, gradient, and/or Hessian of the functional, rather than Value, Gradient, and/or Hessian. For example, implementors of optimization algorithms should use Evaluate unless it is known that only one of the value, gradient, Hessian will be used at a given point. Otherwise, the optimization algorithm is failing to take advantage of possible efficiencies that may be built into a given functional class.
There are several ways to implements functionals; the various options are described in detail, with examples, in the Technical Report referenced at the end of this documentation. In brief, the basic issue is that a functional class must have a corresponding evaluation class (derived from HCL_EvaluateFunctional). The two basic options are:

Define a single class, derived from HCL_Functional, and use the default evaluation class HCL_FunctionalDefaultEval. This is done automatically if the virtual function Evaluate is not overridden in the derived functional class. However, the implementor of the derived class must then override the protected methods Value1, Gradient1, and HessianImage (and HessianInvImage, if desired) or Hessian1. This is the method of choice if there is no efficiency to be gained by sharing intermediate computations among the value, gradient, and Hessian.
Define a class derived from HCL_Functional and another class derived from HCL_EvaluateFunctional. Override the virtual function Evaluate in HCL_Evaluate to create an instance of the evaluation class. This is the method of choice if there is significant gain in sharing intermediate computations among the value, gradient, and Hessian. The user-defined evaluation class provides a place to store these intermediate calculations.
For more information about functional and evaluation classes, see "Implementing functionals in HCL", Technical Report 99-24, Department of Computational and Applied Mathematics, Rice University, PO Box 1892, Houston, TX 77251-1892. This report is available on the HCL home page.

virtual double Value1( const HCL_Vector_d & x ) const

Value1 computes the value of the functional at x. Default implementation returns an error message and exits. The protected methods Value1, Gradient1, and Hessian1 or HessianImage, HessianInvImage must be implemented in a derived class if the implementor wishes to use HCL_FunctionalDefaultEval for the evaluation object.

virtual void Gradient1( const HCL_Vector_d & x, HCL_Vector_d & y ) const

Gradient1 computes the gradient of the functional at x and stores it in y. Default implementation returns an error message and exits. The protected methods Value1, Gradient1, and Hessian1 or HessianImage, HessianInvImage must be implemented in a derived class if the implementor wishes to use HCL_FunctionalDefaultEval for the evaluation object.

virtual void HessianImage( const HCL_Vector_d & x, const HCL_Vector_d & dx, HCL_Vector_d & dy ) const

HessianImage computes the action of the Hessian of the functional (at x) on the input dx, giving dy. Default implementation returns an error message and exits. To obtain the functionality of this method in a derived class, only one of Hessian1 and the pair HessianImage, HessianInvImage should be implemented. The protected methods Value1, Gradient1, and Hessian1 or HessianImage, HessianInvImage must be implemented in a derived class if the implementor wishes to use HCL_FunctionalDefaultEval for the evaluation object.

virtual void HessianInvImage( const HCL_Vector_d & x, const HCL_Vector_d & dy, HCL_Vector_d & dx ) const

HessianInvImage computes the action of the inverse Hessian of the functional (at x) on the input dy, giving dx. Default implementation returns an error message and exits. Note that if the inverse Hessian is never to be used, this method can be implemented as an error. To obtain the functionality of this method in a derived class, you must override this default implementation. Only one of Hessian1 and the pair HessianImage, HessianInvImage should be implemented. The protected methods Value1, Gradient1, and Hessian1 or HessianImage, HessianInvImage must be implemented in a derived class if the implementor wishes to use HCL_FunctionalDefaultEval for the evaluation object.

virtual HCL_LinearOp_d* Hessian1( const HCL_Vector_d & x ) const

Hessian1 creates an instance of HCL_LinearOp to represent the Hessian of the functional at x, and returns a pointer to it. Note that the calling program must delete it using HCL_delete when it is no longer needed. Only one of Hessian1 and the pair HessianImage, HessianInvImage should be implemented. The protected methods Value1, Gradient1, and Hessian1 or HessianImage, HessianInvImage must be implemented in a derived class if the implementor wishes to use HCL_FunctionalDefaultEval for the evaluation object.

virtual HCL_VectorSpace_d& Domain() const

Domain space access. Returns a reference to the HCL_VectorSpace_d which forms the domain of the functional. Note that, in the current design, the domain of a functional must be an entire vector space, although many nonlinear functionals are only defined on an open subset of a vector space. This is a flaw in the design of HCL which may be corrected in some future version of the software. A partial work-around to this problem is provided by the MaxStep method. Pure virtual: must be implemented in any derived instantiable class.

virtual double MaxStep( const HCL_Vector_d & x, const HCL_Vector_d & dir) const

MaxStep computes the largest value of a such that x+a*dir lies in the domain of definition of the functional. By default (i.e. unless this virtual function is implemented in a derived class), the domain is assumed to be the whole space, and MaxStep return the largest floating point number. This method is used in some of the optimization algorithms and provides a partial solution to the problem that many functionals are not defined on an entire vector space, but rather only on a subset.

virtual HCL_EvaluateFunctional_d* Evaluate( const HCL_Vector_d & x ) const

Evaluate creates an "evaluation" object, which knows how to compute the function value, gradient,and Hessian at the given x. The purpose of using Evaluate (rather than Value, Gradient, and Hessian) is for efficiency; many functionals are such that the evaluation of the functional and its derivatives require common intermediate calculations. The evaluation object mechanism gives the functional class implementor a place to store these intermediate results so that they do not have to be re-computed if the the gradient is requested at some point after the value, for example. The implementor of an optimization algorithm should respect this by using Evaluate to get a value, gradient, and/or Hessian rather than using Value, Gradient, and/or Hessian. Note as explained in the class documentation, if there is no advantage in having an evaluation object, then the implementor can simply not override Evaluate in the derived class, in which case the default implementation will create an instance of HCL_FunctionalDefaultEval. In this case, the implementor must override the virtual protected methods Value1, Gradient1, and either Hessian1 or HessianImage, HessianInvImage.

virtual double Value( const HCL_Vector_d & x ) const

Value evaluates the function at x. It does so by creating an evaluation object with the Evaluate method, getting the value from it, deleting the evaluation object, and returning the value. Value is defined in this (the base) class, so it need not be redefined in a derived class.

virtual void Gradient( const HCL_Vector_d & x, HCL_Vector_d & g ) const

Gradient computes the gradient at x. It does so by creating an evaluation object with the Evaluate method, getting the gradient from it, and deleting the evaluation object. Gradient is defined in this (the base) class, so it need not be redefined in a derived class.

virtual HCL_LinearOp_d* Hessian( const HCL_Vector_d & x ) const

Hessian computes the gradient at x. It does so by creating an evaluation object with the Evaluate method, getting the Hessian from it, and deleting the evaluation object. Hessian is defined in this (the base) class, so it need not be redefined in a derived class.

void Scan( const HCL_Vector_d & x, const HCL_Vector_d & dx, int N, double hmin, double hmax, char * fname = NULL )

Scan computes the value of the function at N points. The points are equally spaced and lie on the line segment from x+hmin*dx to x+hmax*dx. The results are written to the file fname (if provided) and to the screen. This method is implemented in this class.

int CheckGrad( const HCL_Vector_d & x, const HCL_Vector_d & y, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 )

Check analytic gradient. This method computes the relative difference between the directional derivative as computed from the analytic gradient and the same estimated by a central difference formula. This is done at n equally-spaced points on the line segment [x+hmin*y,x+hmax*y]. The parameters hmin, hmax, and n are optional and default to 0.1, 1.0, and 10, respectively. If the analytic gradient is correctly implemented and the function is three times continuously differentiable, then these errors will lie on a parabola when plotted against the step size. The results are sent to the output stream str. This method is implemented in this class.

int CheckHess( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 )

Check analytic Hessian. This method computes the relative difference between the second directional derivative as computed from the analytic Hessian and the same estimated by a central difference formula. This is done at n equally-spaced points on the line segment [x+hmin*y,x+hmax*y]. The parameters hmin, hmax, and n are optional and default to 0.1, 1.0, and 10, respectively. If the analytic Hessian is correctly implemented and the function is four times continuously differentiable, then these errors will lie on a parabola when plotted against the step size. The results are sent to the output stream str. This method is implemented in this class.

Direct child classes:: HCL_QuadFunctional_d
HCL_LinCombFcnl_d
HCL_LeastSquaresFcnl_d
HCL_LeastSquaresFcnlGN_d
HCL_BigMFcnl_d
HCL_ALFcnl_d
HCL_RestrictedFunctional_d
HCL_FunctionalProductDomain_d

alphabetic index hierarchy of classes

this page has been generated automatically by doc++

(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de

virtual HCL_VectorSpace_d&	Domain () const Domain space access
virtual double	MaxStep ( const HCL_Vector_d & x, const HCL_Vector_d & dir) const MaxStep computes the largest value of a such that *x+adir** lies in the domain of definition of the functional
virtual HCL_EvaluateFunctional_d*	Evaluate ( const HCL_Vector_d & x ) const Evaluate creates an "evaluation" object, which knows how to compute the function value, gradient,and Hessian at the given x
virtual double	Value ( const HCL_Vector_d & x ) const Value evaluates the function at x
virtual void	Gradient ( const HCL_Vector_d & x, HCL_Vector_d & g ) const Gradient computes the gradient at x
virtual HCL_LinearOp_d*	Hessian ( const HCL_Vector_d & x ) const Hessian computes the gradient at x
void	Scan ( const HCL_Vector_d & x, const HCL_Vector_d & dx, int N, double hmin, double hmax, char * fname = NULL ) Scan computes the value of the function at N points
int	CheckGrad ( const HCL_Vector_d & x, const HCL_Vector_d & y, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) Check analytic gradient
int	CheckHess ( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) Check analytic Hessian

virtual double	Value1 ( const HCL_Vector_d & x ) const Value1 computes the value of the functional at x
virtual void	Gradient1 ( const HCL_Vector_d & x, HCL_Vector_d & y ) const Gradient1 computes the gradient of the functional at x and stores it in y
virtual void	HessianImage ( const HCL_Vector_d & x, const HCL_Vector_d & dx, HCL_Vector_d & dy ) const HessianImage computes the action of the Hessian of the functional (at x) on the input dx, giving dy
virtual void	HessianInvImage ( const HCL_Vector_d & x, const HCL_Vector_d & dy, HCL_Vector_d & dx ) const HessianInvImage computes the action of the inverse Hessian of the functional (at x) on the input dy, giving dx
virtual HCL_LinearOp_d*	Hessian1 ( const HCL_Vector_d & x ) const Hessian1 creates an instance of HCL_LinearOp to represent the Hessian of the functional at x, and returns a pointer to it

class HCL_Functional_d : public HCL_Base

Inheritance:

Public Methods

Protected Methods

Inherited from HCL_Base:

Public Methods

Documentation