dlr::optimization::OptimizerLineSearch< Functor > Class Template Reference

OptimizerLineSearch implements the line search algorithm described in [1]. More...

#include <optimizerLineSearch.h>

Inheritance diagram for dlr::optimization::OptimizerLineSearch< Functor >:

[legend]Collaboration diagram for dlr::optimization::OptimizerLineSearch< Functor >:


Public Types
typedef Functor::argument_type	argument_type
	This is the Type of the objective function argument.
typedef Functor::result_type	result_type
	This is the Type of the objective function return value.
Public Member Functions
	OptimizerLineSearch ()
	Default constructor sets parameters to reasonable values for functions which take values and arguments in the "normal" range of 0 to 100 or so.
	OptimizerLineSearch (const Functor &functor)
	Constructor which specifies the specific Functor instance to use.
	OptimizerLineSearch (const Functor &functor, const argument_type &startPoint, const argument_type &startGradient, const result_type &startValue)
	Overloading of constructor.
	OptimizerLineSearch (const OptimizerLineSearch &source)
	Copy constructor.
virtual	~OptimizerLineSearch ()
	Destructor.
size_t	getNumberOfFunctionCalls ()
	If a valid minimization result is available, this method returns the number of function calls required to produce that result.
virtual void	setStartPoint (const argument_type &startPoint)
	Sets part of the initial conditions for the minimization.
virtual void	setStartPoint (const argument_type &startPoint, const result_type &startValue, const argument_type &startGradient)
	Sets part of the initial conditions for the minimization.
virtual void	setInitialStep (const argument_type &initialStep)
	Sets part of the initial conditions for the minimization.
void	setParameters (double argumentTolerance=1.0e-7, double alpha=1.0e-4, double maximumStepMagnitude=100.0)
	Sets the line search parameters.
OptimizerLineSearch &	operator= (const OptimizerLineSearch &source)
	Assignment operator.
Functor	objectiveFunction ()
	This method returns a copy of the Functor instance used for optimization.
result_type	optimalValue ()
	This method finds the optimum of the current Functor, if necessary, and returns the Functor value at that point.
argument_type	optimum ()
	This method finds the optimum of the current Functor, if necessary, and returns the Functor argument which produces that optimum.
void	setObjectiveFunction (const Functor &functor)
	This method specifies the Functor instance to use for the optimization.
Protected Member Functions
void	checkState ()
	This protected member function verifies that all necessary values have been set prior to running the optimization.
std::pair< typename Functor::argument_type, typename Functor::result_type >	run ()
	Perform the minimization.
virtual void	setOptimum (const typename Functor::argument_type &optimum, const typename Functor::result_type &optimalValue, bool needsFurtherOptimization)
	This protected member function provides a way for subclasses to communicate intermediate optimization results outside of the normal "return value of this->run()" method.
Protected Attributes
double	m_alpha
double	m_argumentTolerance
size_t	m_functionCallCount
argument_type	m_initialStep
double	m_initialStepMagnitude
double	m_maximumStepMagnitude
argument_type	m_startGradient
argument_type	m_startPoint
result_type	m_startValue
Functor	m_functor
	m_functor->operator()() should compute the objective function.
bool	m_needsOptimization
	Set to false if m_optimum contains a valid optimum, true otherwise.
argument_type	m_optimum
	Caches the result of the most recent optimization.
result_type	m_optimalValue
	Caches the result of the most recent optimization.

Detailed Description

template<class Functor>
class dlr::optimization::OptimizerLineSearch< Functor >

OptimizerLineSearch implements the line search algorithm described in [1].

It takes as input an n dimensional point, the value of the function and gradient at that point, a direction, and an input quantity that limits the length of the steps. It uses these to find a new point within the length requested and along the direction specified at which the function has significantly decreased, and returns that n-dimensional point.

WARNING: The line search algorithm is not really an optimization. If you want to find the minimum function value along a line in parameter space, this is _not_ the class you're looking for.

[1] W. H. Press et al., Numerical Recipes in C The Art of Scientific Computing, Cambridge University Press, 1988.

Definition at line 43 of file optimizerLineSearch.h.

Member Typedef Documentation

template<class Functor>

typedef Functor::argument_type dlr::optimization::OptimizerLineSearch< Functor >::argument_type

This is the Type of the objective function argument.

Reimplemented from dlr::optimization::Optimizer< Functor >.

Definition at line 48 of file optimizerLineSearch.h.

template<class Functor>

typedef Functor::result_type dlr::optimization::OptimizerLineSearch< Functor >::result_type

This is the Type of the objective function return value.

Reimplemented from dlr::optimization::Optimizer< Functor >.

Definition at line 49 of file optimizerLineSearch.h.

Constructor & Destructor Documentation

template<class Functor>

dlr::optimization::OptimizerLineSearch< Functor >::OptimizerLineSearch ( ) [inline]

Default constructor sets parameters to reasonable values for functions which take values and arguments in the "normal" range of 0 to 100 or so.

Definition at line 245 of file optimizerLineSearch.h.

References dlr::optimization::OptimizerLineSearch< Functor >::setParameters().

template<class Functor>

dlr::optimization::OptimizerLineSearch< Functor >::OptimizerLineSearch ( const Functor & functor ) [inline, explicit]

Constructor which specifies the specific Functor instance to use.

Using this constructor exclusively avoids the danger of calling optimalValue() or optimum() before a Functor instance has been specified.

Parameters:

functor

A copy of this argument will be stored internally for use in optimization.

Definition at line 262 of file optimizerLineSearch.h.

References dlr::optimization::OptimizerLineSearch< Functor >::setParameters().

template<class Functor>

dlr::optimization::OptimizerLineSearch< Functor >::OptimizerLineSearch	(	const Functor &	functor,
		const argument_type &	startPoint,
		const argument_type &	startGradient,
		const result_type &	startValue
	)

Overloading of constructor.

Parameters:

	functor	A copy of this argument will be stored internally for use in optimization.
	startPoint	The initial search point on the function.
	startGradient	The initial gradient at startPoint.
	startValue	The function value at startPoint.

template<class Functor>

dlr::optimization::OptimizerLineSearch< Functor >::OptimizerLineSearch ( const OptimizerLineSearch< Functor > & source ) [inline]

Copy constructor.

Parameters:

source

The OptimizerLineSearch instance to be copied.

Definition at line 279 of file optimizerLineSearch.h.

References dlr::optimization::copyArgumentType(), dlr::optimization::OptimizerLineSearch< Functor >::m_initialStep, dlr::optimization::OptimizerLineSearch< Functor >::m_startGradient, and dlr::optimization::OptimizerLineSearch< Functor >::m_startPoint.

template<class Functor>

dlr::optimization::OptimizerLineSearch< Functor >::~OptimizerLineSearch ( ) [inline, virtual]

Destructor.

Definition at line 298 of file optimizerLineSearch.h.

Member Function Documentation

template<class Functor>

size_t dlr::optimization::OptimizerLineSearch< Functor >::getNumberOfFunctionCalls ( ) [inline]

If a valid minimization result is available, this method returns the number of function calls required to produce that result.

If no valid minimization result is available, the return value is 0.

Returns:: The number of function calls spent in the last minimization, or 0.

Definition at line 108 of file optimizerLineSearch.h.

References dlr::optimization::OptimizerLineSearch< Functor >::m_functionCallCount.

template<class Functor>

void dlr::optimization::OptimizerLineSearch< Functor >::setStartPoint ( const argument_type & startPoint ) [inline, virtual]

Sets part of the initial conditions for the minimization.

Search will start at this location in parameter space. The member function setInitialStep() must also be called before the line search can be run.

Parameters:

startPoint

Indicates a point in the parameter space of the objective function.

Definition at line 305 of file optimizerLineSearch.h.

References dlr::optimization::copyArgumentType(), dlr::optimization::OptimizerLineSearch< Functor >::m_functionCallCount, dlr::optimization::Optimizer< Functor >::m_functor, dlr::optimization::Optimizer< Functor >::m_needsOptimization, dlr::optimization::OptimizerLineSearch< Functor >::m_startGradient, and dlr::optimization::OptimizerLineSearch< Functor >::m_startValue.

template<class Functor>

void dlr::optimization::OptimizerLineSearch< Functor >::setStartPoint	(	const argument_type &	startPoint,
		const result_type &	startValue,
		const argument_type &	startGradient
	)			`[inline, virtual]`

Sets part of the initial conditions for the minimization.

Search will start at this location in parameter space. Use this function to avoid recomputing the function value and gradient at this point. The member function setInitialStep() must also be called before the line search can be run.

Parameters:

	startPoint	Indicates a point in the parameter space of the objective function.
	startValue	The value of the objective function, when evaluated at startPoint.
	startGradient	The gradient of the objective function, when evaluated at startPoint.

Definition at line 329 of file optimizerLineSearch.h.

template<class Functor>

void dlr::optimization::OptimizerLineSearch< Functor >::setInitialStep ( const argument_type & initialStep ) [inline, virtual]

Sets part of the initial conditions for the minimization.

This specifies both the initial search step and the direction of search in parameter space. The member function setStartPoint() must also be called before the line search can be run.

Parameters:

initialStep

Indicates the direction in space where the objective function will be going.

Definition at line 349 of file optimizerLineSearch.h.

References dlr::optimization::copyArgumentType(), DLR_THROW3, dlr::optimization::dotArgumentType(), dlr::optimization::OptimizerLineSearch< Functor >::m_functionCallCount, dlr::optimization::OptimizerLineSearch< Functor >::m_initialStepMagnitude, dlr::optimization::Optimizer< Functor >::m_needsOptimization, and dlr::numeric::sqrt().

template<class Functor>

void dlr::optimization::OptimizerLineSearch< Functor >::setParameters	(	double	argumentTolerance = `1.0e-7`,
		double	alpha = `1.0e-4`,
		double	maximumStepMagnitude = `100.0`
	)			`[inline]`

Sets the line search parameters.

Default values are reasonable for functions which take values and arguments in the "normal" range of 0 to 100 or so.

Parameters:

	argumentTolerance	Iteration will terminate when a minimization step moves, along every axis, a distance less than a threshold which is linearly related to this factor.
	alpha	Iteration will terminate when the function value has decreased by an amount which is linearly related to this factor.
	maximumStepMagnitude	Sets the maximum size of the initial step of the line search.

Definition at line 375 of file optimizerLineSearch.h.

References dlr::optimization::OptimizerLineSearch< Functor >::m_alpha, dlr::optimization::OptimizerLineSearch< Functor >::m_argumentTolerance, dlr::optimization::OptimizerLineSearch< Functor >::m_functionCallCount, dlr::optimization::OptimizerLineSearch< Functor >::m_maximumStepMagnitude, and dlr::optimization::Optimizer< Functor >::m_needsOptimization.

Referenced by dlr::optimization::OptimizerLineSearch< Functor >::OptimizerLineSearch().

template<class Functor>

OptimizerLineSearch< Functor > & dlr::optimization::OptimizerLineSearch< Functor >::operator= ( const OptimizerLineSearch< Functor > & source ) [inline]

Assignment operator.

Parameters:

source

The OptimizerLineSearch instance to be copied.

Returns:: Reference to *this.

Definition at line 394 of file optimizerLineSearch.h.

template<class Functor>

void dlr::optimization::OptimizerLineSearch< Functor >::checkState ( ) [inline, protected]

This protected member function verifies that all necessary values have been set prior to running the optimization.

If anything is missing or inconsistent, it throws an exception.

Definition at line 189 of file optimizerLineSearch.h.

Referenced by dlr::optimization::OptimizerLineSearch< Functor >::run().

template<class Functor>

std::pair< typename Functor::argument_type, typename Functor::result_type > dlr::optimization::OptimizerLineSearch< Functor >::run ( ) [inline, protected, virtual]

Perform the minimization.

This overrides Optimizer<Functor>::run().

Returns:: A std::pair of the vector parameter which brings the specified Functor to a point of sufficient decrease, and the corresponding Functor value.

Implements dlr::optimization::Optimizer< Functor >.

Definition at line 416 of file optimizerLineSearch.h.

template<class Functor>

Functor dlr::optimization::Optimizer< Functor >::objectiveFunction ( ) [inline, inherited]

This method returns a copy of the Functor instance used for optimization.

Returns:: A Functor instance.

Definition at line 91 of file optimizer.h.

References dlr::optimization::Optimizer< Functor >::m_functor.

template<class Functor>

Optimizer< Functor >::result_type dlr::optimization::Optimizer< Functor >::optimalValue ( ) [inline, inherited]

This method finds the optimum of the current Functor, if necessary, and returns the Functor value at that point.

Note that you must have specified an objective function (Functor) before calling this method.

Returns:: The Functor value at it's optimum.

Definition at line 282 of file optimizer.h.

References dlr::optimization::Optimizer< Functor >::m_needsOptimization, dlr::optimization::Optimizer< Functor >::m_optimalValue, dlr::optimization::Optimizer< Functor >::run(), and dlr::optimization::Optimizer< Functor >::setOptimum().

template<class Functor>

Optimizer< Functor >::argument_type dlr::optimization::Optimizer< Functor >::optimum ( ) [inline, inherited]

This method finds the optimum of the current Functor, if necessary, and returns the Functor argument which produces that optimum.

Note that you must have specified an objective function (Functor) before calling this method.

Returns:: The Functor arguments which produce the optimal value.

Definition at line 297 of file optimizer.h.

References dlr::optimization::Optimizer< Functor >::m_needsOptimization, dlr::optimization::Optimizer< Functor >::m_optimum, dlr::optimization::Optimizer< Functor >::run(), and dlr::optimization::Optimizer< Functor >::setOptimum().

template<class Functor>

void dlr::optimization::Optimizer< Functor >::setObjectiveFunction ( const Functor & functor ) [inline, inherited]

This method specifies the Functor instance to use for the optimization.

If this function is overridden by the base class, it should normally either call Optimizer::setObjectiveFunction(), or explicitly set the member variable m_needsOptimization to true.

Parameters:

functor

A copy of this argument will be stored internally for use in optimization.

Definition at line 311 of file optimizer.h.

References dlr::optimization::Optimizer< Functor >::m_functor, and dlr::optimization::Optimizer< Functor >::m_needsOptimization.

template<class Functor>

virtual void dlr::optimization::Optimizer< Functor >::setOptimum	(	const typename Functor::argument_type &	optimum,
		const typename Functor::result_type &	optimalValue,
		bool	needsFurtherOptimization
	)			`[inline, protected, virtual, inherited]`

This protected member function provides a way for subclasses to communicate intermediate optimization results outside of the normal "return value of this->run()" method.

Parameters:

	optimum	This argument will be saved as the current optimum.
	optimalValue	This argument will be saved as the function value a the current optimum.
	needsFurtherOptimization	This argument indicates whether or not further refinement is necessary.

Definition at line 172 of file optimizer.h.

References dlr::optimization::Optimizer< Functor >::m_needsOptimization, dlr::optimization::Optimizer< Functor >::m_optimalValue, and dlr::optimization::Optimizer< Functor >::m_optimum.

Referenced by dlr::optimization::Optimizer< Functor >::optimalValue(), and dlr::optimization::Optimizer< Functor >::optimum().