Documentation

This class represents an "evaluation" object that will be created by a instance of HCL_Functional object to implement the value, gradient, and Hessian of the functional at a point. That is, if the HCL_Functional represents , the the evaluation object represents the triple . The purpose of having an evaluation object is to deal with the common situation in which the functional value and derivatives share some intermediate calculations. A typical implementation of such a functional involves defining an evaluation object whose constructor performs these intermediate calculations. The Value method then completes the computation of the functional value, while the Gradient and Hessian methods complete the calculation of the derivatives.

Note that if one is defining a functional for which there are no (significant) common computations shared by , , and , then need not define an evaluation object explicitly. Instead, the concrete class derived from HCL_Functional can create an instance of HCL_FunctionalDefaultEval. For more details, see the documentation for HCL_Functional, and also the Technical Report referenced at the end of this documentation.

There is also a special mechanism for implementing the Hessian operator. The method Hessian must create an instance of HCL_LinearOp to represent . In many cases, this operator can be implemented using existing HCL classes (such as the matrix operator classes). However, when this is not the case, one can use the default class HCL_FunctionalDefaultHessian as follows. In the class derived from HCL_EvaluateFunctional, the virtual protected methods HessianImage and HessianInvImage (if desired) are overridden to implement the action of the Hessian operator and its inverse. The method Hessian is not overriddent in the derived class, for then the default implementation will create an instance of HCL_FunctionalDefaultHessian (which will contain a pointer to the evaluation object and can then invoke HessianImage and HessianInvImage as needed).

When an optimization (or other) algorithm is implemented, the functional value, gradient, and Hessian should be accessed through the ValueRef, GradientRef, and HessianRef methods. These are methods implemented in the base class (i.e. they do not need to be redefined in a derived class). The ValueRef method invokes Value to get the function value, stores it, and sets a flag to indicate that the value has already been computed. On subsequent calls, ValueRef merely returns the stored value. GradientRef and HessianRef work in a similar fashion; note that these method manage the storage of the gradient and Hessian, so the calling program does not need to allocate storage.

Here is a summary of the primary methods of the class HCL_EvaluateFunctional:

• Domain Returns a reference to the domain of the underlying functional.
• Value Computes the value of the functional at the point at which this object was created. Must be implemented by the creator of a concrete class.
• ValueRef Calls Value, if necessary, to compute the functional value, saves it, and returns it. Implemented in the base class.
• Gradient Computes the gradient of the functional at the point at which this object was created. Must be implemented by the creator of a concrete class.
• GradientRef Calls Gradient, if necessary, to compute the functional gradient, saves it, and returns a reference to it. Implemented in the base class.
• Hessian Computes the Hessian of the functional at the point at which this object was created. Must be implemented by the creator of a concrete class.
• HessianRef Calls Hessian, if necessary, to compute the functional Hessian, saves it, and returns a reference to it. Implemented in the base class.

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.