HCL_Op

class HCL_Op_d : public HCL_Base

HCL_Op_d is the base class for (presumably nonlinear) operators

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_Op_d is the base class for (presumably nonlinear) operators. Such an operator maps one vector space into another, say
The primary methods of this class are:
Domain Returns a reference to the domain of the operator. This is used primarily for error-checking.
Range Returns a reference to the range of the operator. This is used primarily for error-checking.
Image Computes the action of the operator on a vector. Here is an example illustrating the use of Domain, Range, and Image:
   void fcn( HCL_Op_d & F,HCL_Vector_d & x,HCL_Vector_d & y )
   {
      if( x.Space() != F.Domain() || y.Space() != F.Range() )
         // Error condition
      .
      .
      .
      F.Image( x,y ); // y <-- F(x)
      .
      .
      .
   }
ImageAdd Adds the image of the operator to the output vector.
Deriv Creates the derivative of the operator at a point. This derivative is a linear operator and this method constructs it as an HCL_LinearOp_d.
SecondDeriv Creates the second derivative of the operator at a point. This derivative is a bilinear operator and this method constructs it as an HCL_BiLinearOp_d.
Evaluate Creates an "evaluation object" which knows the image and derivatives of the operator at a given point. The purpose of the evaluation object is to accommodate the common situation in which the computation of the image and derivatives involve some common intermediate calculations. The implementor of the operator can put these intermediate calculations in the evaluation object, so that they need only be done once at each point. The implementor of optimization algorithms should respect this by using Evaluate to get the image and/or derivatives instead of using Image, Deriv, and/or SecondDeriv.
In addition to the above methods, HCL_Op_d has a number of protected virtual functions that allow the user to avoid writing a distinct evaluation class if desired. If these methods, which include DerivImage, SecondDerivImage, and others, are over-ridden in a derived class, then the default Evaluate method can be used, which creates an instance of HCL_OpDefaultEval_d.
Defining operators is expected to be one of the main activities of users of HCL, since the many optimization problems involve operators in the definition of the objective function or constraints. As the last paragraph suggests, there are a number of ways to implement operators. These are described in detail in the report
"Implementing operators in HCL", Technical Report 99-22, Department of Computational and Applied Mathematics, Rice University, Houston, TX 77251-1892.
downloadable from the HCL home page.

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

DerivImage computes the image of the derivative on dx, yielding dy. Default implementation returns an error message and exits. To use the default Evaluate method in a derived class, you must either (1) override the default implementation of Deriv1, or, failing that, (2) override the default implementation of this method and its relatives with code that actually implements the linear map defined by the derivative. In either case the evaluation object will then be an instance of HCL_OpDefaultEval_d.

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

DerivAdjImage computes the image of the adjoint of the derivative on dy, yielding dx. Default implementation returns an error message and exits. To use the default Evaluate method in a derived class, you must either (1) override the default implementation of Deriv1, or, failing that, (2) override the default implementation of this method and its relatives with code that actually implements the linear map defined by the derivative. In either case the evaluation object will then be an instance of HCL_OpDefaultEval_d.

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

DerivInvImage computes the image of the inverse of the derivative on dy, yielding dx. Default implementation returns an error message and exits. To use the default Evaluate method in a derived class, you must either (1) override the default implementation of Deriv1, or, failing that, (2) override the default implementation of this method and its relatives with code that actually implements the linear map defined by the derivative. In either case the evaluation object will then be an instance of HCL_OpDefaultEval_d.

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

DerivInvAdjImage computes the image of the inverse of the adjoint of the derivative on dx, yielding dy. Default implementation returns an error message and exits. To use the default Evaluate method in a derived class, you must either (1) override the default implementation of Deriv1, or, failing that, (2) override the default implementation of this method and its relatives with code that actually implements the linear map defined by the derivative. In either case the evaluation object will then be an instance of HCL_OpDefaultEval_d.

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

Image1 computes the image of the operator on x, yielding y. Default implementation returns an error message and exits. The default implementation of Evaluate uses this method, so you must either override it or override Evaluate to obtain a working child class.

virtual HCL_LinearOp_d* Deriv1( const HCL_Vector_d & x ) const

Deriv1 computes the derivative of the operator at x. Default implementation returns a null value. The default implementation of Evaluate calls this method, and returns its value if not null. If the return value is null, it uses the HCL_OpDefaultDeriv class to construct a derivative implementation; this construction in turn uses the DerivImage, DerivAdjImage, etc. methods. Therefore to obtain a working operator class, with an implemented derivative, you must either (1) override Evaluate, (2) override Deriv1 (this method), or (3) override DerivImage, DerivAdjImage, etc.

virtual void SecondDerivImage( const HCL_Vector_d & x, const HCL_Vector_d & dx1, const HCL_Vector_d & dx2, HCL_Vector_d & dy ) const

Writing

, this method computes

. If this method and the related protected image methods are implemented, then the default Evaluate method can be used. The evaluation method will then be an instance of HCL_OpDefaultEval_d. Note that either the pair SecondDerivImage, SecondDerivPartialAdjImage or the method SecondDeriv1 must be implemented to enable the use of the default second derivative construction.

virtual void SecondDerivPartialAdjImage(const HCL_Vector_d & x, const HCL_Vector_d & dx1, const HCL_Vector_d & dy, HCL_Vector_d & dx2 ) const

This method computes

virtual HCL_BiLinearOp_d* SecondDeriv1( const HCL_Vector_d & x ) const

SecondDeriv1 computes the second derivative of the operator at x. Its default implementation returns NULL. If the default implementation is overridden to return a legal HCL_BiLinearOp_d object, then that object is returned by the SecondDeriv method of the default evaluation class HCL_OpDefaultEval_d. Otherwise, this method returns a second derivative object that calls the methods SecondDerivImage, SecondDerivPartialAdjImage, which must then be implemented to provide a working second derivative.

virtual HCL_VectorSpace_d& Domain() const

Domain space access. Returns a reference to the HCL_VectorSpace_d which forms the domain of the operator. Note that, in the current design, the domain of an operator must be an entire vector space, although many nonlinear operators 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 HCL_VectorSpace_d& Range() const

Range space access. Returns a reference to the range of the operator, which is an HCL_VectorSpace_d. 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 greatest a such that x + a*dir lies in the domain. By default (i.e. unless this virtual function is overridden in a derived class), the domain is assumed to be the whole space, and MaxStep returns 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 operators are not defined on an entire vector space, but rather only on a subset.

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

Image computes the action of the operator on x, giving y. It does this by creating an evaluation object via Evaluate, extracting the image, and deleting the evaluation object. This method is defined in this (the base) class, so it need not be redefined in concrete derived classes.

virtual void ImageAdd( const HCL_Vector_d & x, HCL_Vector_d & y, double a=1.0, double b=1.0 ) const

ImageAdd computes

. (Note that the scalars a and b are optional and default to 1.0.) It does this by creating an evaluation object via Evaluate, extracting the image, and deleting the evaluation object. This method is defined in this (the base) class, so it need not be redefined in concrete derived classes. However greater efficiency may be obtained in some cases by overriding the default implementation, through ``loop fusion''.

virtual void ImageAdd( const HCL_Vector_d & x, const HCL_Vector_d & z, HCL_Vector_d & y, double a=1.0, double b=1.0 ) const

ImageAdd computes

virtual HCL_LinearOp_d* Deriv( const HCL_Vector_d & x ) const

Deriv computes the derivative, as an HCL_LinearOp_d, of the operator at x. It does this by creating an evaluation object via Evaluate, extracting the derivative, and deleting the evaluation object. This method is defined in this (the base) class, so it need not be redefined in concrete derived classes.

virtual HCL_BiLinearOp_d* SecondDeriv( const HCL_Vector_d & x ) const

SecondDeriv computes the second derivative of the operator at a point. It does this by creating an evaluation object, using Evaluate, getting the second derivative, and deleting the evaluation object. The method is implemented in this (the base) class, so it need not be redefined for derived classes.

virtual HCL_EvaluateOp_d* Evaluate( const HCL_Vector_d & x ) const

Evaluate creates an evaluation object which knows how to compute the image, first derivative, and second derivative, along with all relevant adjoints, at a point. The purpose of the evaluation object is to accommodate the common situation in which the computation of the image and derivatives involve some common intermediate calculations. See the class documentation for more information on evaluation objects. The default implementation uses the Image1 method and either the Deriv1 and SecondDeriv1 methods, or DerivImage, DerivAdjImage,...,SecondDerivImage,...These return null values or exit with an error message in their default implementations, so for each level of functionality (image alone, image plus first derivative,...) some combination of these methods must be overriden in any derived class. Alternatively, the user may override the default Evaluate method and provide standalone classes for the derivatives.

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

Check analytic derivative. This method computes the relative difference between the directional derivative as computed from the analytic derivative 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 derivative is correctly implemented and the function is sufficiently smooth, 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 implemente in this class.

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

CheckDerivAdj calls CheckDeriv to test the correctness of the derivative, and then calls the HCL_LinearOp_d method CheckAdj to test the correctness of its adjoint. This method is implemented in this class.

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

Check analytic second derivative. This method computes the relative difference between the second directional derivative as computed from the analytic derivative 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 derivative is correctly implemented and the function is sufficiently smooth, 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 CheckSecondDerivAdj( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) const

CheckSecondDerivAdj calls CheckSecondDeriv to test the correctness of the second derivative, and then calls the HCL_LinearOp_d method CheckAdj to test the correctness of the three related adjoints. This method is implemented in this class.

Direct child classes:: HCL_LNLOp_d
HCL_OpProductDomain_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 HCL_VectorSpace_d&	Range () const Range space access
virtual double	MaxStep ( const HCL_Vector_d & x, const HCL_Vector_d &dir) const MaxStep computes the greatest a such that x + a*dir lies in the domain
virtual void	Image ( const HCL_Vector_d & x, HCL_Vector_d & y ) const Image computes the action of the operator on x, giving y
virtual void	ImageAdd ( const HCL_Vector_d & x, HCL_Vector_d & y, double a=1.0, double b=1.0 ) const ImageAdd computes
virtual void	ImageAdd ( const HCL_Vector_d & x, const HCL_Vector_d & z, HCL_Vector_d & y, double a=1.0, double b=1.0 ) const ImageAdd computes
virtual HCL_LinearOp_d*	Deriv ( const HCL_Vector_d & x ) const Deriv computes the derivative, as an HCL_LinearOp_d, of the operator at x
virtual HCL_BiLinearOp_d*	SecondDeriv ( const HCL_Vector_d & x ) const SecondDeriv computes the second derivative of the operator at a point
virtual HCL_EvaluateOp_d*	Evaluate ( const HCL_Vector_d & x ) const Evaluate creates an evaluation object which knows how to compute the image, first derivative, and second derivative, along with all relevant adjoints, at a point
int	CheckDeriv ( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) const Check analytic derivative
int	CheckDerivAdj ( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) const CheckDerivAdj calls CheckDeriv to test the correctness of the derivative, and then calls the HCL_LinearOp_d method CheckAdj to test the correctness of its adjoint
int	CheckSecondDeriv ( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) const Check analytic second derivative
int	CheckSecondDerivAdj ( const HCL_Vector_d &, const HCL_Vector_d &, ostream & str, int n=10, double hmin=0.1, double hmax=1.0 ) const CheckSecondDerivAdj calls CheckSecondDeriv to test the correctness of the second derivative, and then calls the HCL_LinearOp_d method CheckAdj to test the correctness of the three related adjoints

virtual void	DerivImage ( const HCL_Vector_d & x, const HCL_Vector_d & dx, HCL_Vector_d & dy ) const DerivImage computes the image of the derivative on dx, yielding dy
virtual void	DerivAdjImage ( const HCL_Vector_d & x, const HCL_Vector_d & dy, HCL_Vector_d & dx ) const DerivAdjImage computes the image of the adjoint of the derivative on dy, yielding dx
virtual void	DerivInvImage ( const HCL_Vector_d & x, const HCL_Vector_d & dy, HCL_Vector_d & dx ) const DerivInvImage computes the image of the inverse of the derivative on dy, yielding dx
virtual void	DerivInvAdjImage ( const HCL_Vector_d & x, const HCL_Vector_d & dx, HCL_Vector_d & dy ) const DerivInvAdjImage computes the image of the inverse of the adjoint of the derivative on dx, yielding dy
virtual void	Image1 ( const HCL_Vector_d & x, HCL_Vector_d & y ) const Image1 computes the image of the operator on x, yielding y
virtual HCL_LinearOp_d*	Deriv1 ( const HCL_Vector_d & x ) const Deriv1 computes the derivative of the operator at x
virtual void	SecondDerivImage ( const HCL_Vector_d & x, const HCL_Vector_d & dx1, const HCL_Vector_d & dx2, HCL_Vector_d & dy ) const Writing , this method computes
virtual void	SecondDerivPartialAdjImage (const HCL_Vector_d & x, const HCL_Vector_d & dx1, const HCL_Vector_d & dy, HCL_Vector_d & dx2 ) const This method computes
virtual HCL_BiLinearOp_d*	SecondDeriv1 ( const HCL_Vector_d & x ) const SecondDeriv1 computes the second derivative of the operator at x

class HCL_Op_d : public HCL_Base

Inheritance:

Public Methods

Protected Methods

Inherited from HCL_Base:

Public Methods

Documentation