NICE_Optimization/GradientDescentOptimizer.h

//////////////////////////////////////////////////////////////////////
//
//	GradientDescentOptimizer.h: interface of the optimizer GradientDescent.
//
//	Written by: Matthias Wacker
//  edited by Johannes Ruehle, 2012-10-11
//////////////////////////////////////////////////////////////////////

#ifndef _GRADIENT_DESCENT_OPTIMIZER_
#define _GRADIENT_DESCENT_OPTIMIZER_

#include <cmath>
#include "optimization/DerivativeBasedOptimizer.h"

///
///	Class GradientDescentOptimizer
///
///  HowToUse:
///	
///	  * use setStepSize to specify the initial stepsize to compute the numerical gradient
///	  * use setParameters() to set the start point
///	  * call init()
///	  * call optimize()
///	  
///	   
///	  
///  Implemented Abort criteria:
///	  		
///	* maximum number of iterations
///	* time limit
///	* parameter bounds
///	* function value tolerance
/// 	* parameter tolerance
///	* gradient tolerance
///  
///	Additional return reason:
///
///	* ERROR_COMPUTATION_UNSTABLE
///
/// GradientDescent supports the 'scales' feature
class GradientDescentOptimizer : public DerivativeBasedOptimizer
{
	public:

		typedef  DerivativeBasedOptimizer SuperClass;

		///
		///	Constructor.
		///	\param loger : OptLogBase * to existing log class
		///
		GradientDescentOptimizer(OptLogBase *loger=NULL);

		///
		///	Copy constructor
		///	\param opt .. optimizer to copy
		///
		GradientDescentOptimizer( const GradientDescentOptimizer &opt);

	        ///
		///	Destructor.
		///
		~GradientDescentOptimizer();


		///
		///	\brief Set the initial step size
		///	The initial stepsize is used to give the optimizer an initial value for the order of 
		///	magnitude to start with.
		///	(e.g. step 100000 in x direction or 0.01 ?)
		///	\param stepSize with the step size for the i-th dimension in the i-th position.
		///
		void setStepSize(const optimization::matrix_type & stepSize);

		///
		///	Get the actual step size
		///	\return vector<double> with the actual step sizes
		///
		inline const optimization::matrix_type & getStepSize(){return m_stepSize;};


		///
		///	do internal initializations		
		///
		void init();


		///
		///	start the optimization
		///	\return the return status that can be found in the corresponding enumeration
		///
		int optimize();

		inline void setStepLength(double stepLength){m_stepLength=stepLength;}

        inline void setMinimalGradientMagnitude(double minGradientMag){m_MinimalGradientMagnitude=minGradientMag;}
	private:

		///
		///	step size vector
		///
		optimization::matrix_type m_stepSize;
		
		///
		/// .. steplength
		///
		double m_stepLength;

        ///
        ///	Minimal threshold for the L2-Norm of the gradient, so that the gradient descent
        /// is aborted.
        ///
        double m_MinimalGradientMagnitude;
		
};

#endif