NICE_Optimization/Plotter.h

/*
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB.  If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.

---
Copyright (C) 2009, Esther-Sabrina Platzer <esther.platzer@uni-jena.de>
Matthias Wacker <matthias.wacker@mti.uni-jena.de>
*/

	/// @class Plotter
	/// Class interface for cost function plotting.
	///
	/// @author Esther-Sabrina Platzer, Matthias Wacker
	/// @date 2009-07-07

#ifndef _PLOTTER_H_
#define _PLOTTER_H_

#include "core/optimization/blackbox/SimpleOptProblem.h"
#include "AdaptiveDirectionRandomSearchOptimizer.h"

namespace OPTIMIZATION
{
  
  class Plotter
  {
    public:
      ///
      /// defaultConstructor
      ///
      Plotter();
          
      ///
      ///	Copy constructor
      ///	@param plotter plotter to copy
      ///
      Plotter(const Plotter &plotter);

          ///
      /// Assignment operator
      /// @param pkitter plotter to assign
      Plotter& operator=(const Plotter &plotter);


      ///
      ///	Destructor.
          ///	
      ~Plotter();
      
    
      ///
      /// Set optimization problem
      ///
      void setOptProblem(const SimpleOptProblem& optprob);

      
      ///
      /// Performs a 1d evaluation of the costfunction defined in the optimization problem.
      /// @param paramnum parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from lower border of parameter value
      /// @param to upper border of parameter value
      /// @param stepwidth sampling rate for costfunction evaluation
      /// @param path path to the result file
      ///
      void plot1D(int paramnum, const float from, const float to, const float stepwidth, const char* path);
      
      
      ///
      /// Performs a 2d evaluation of the costfunction defined in the optimization problem.
      /// @param paramnum1 first parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from1 lower border of parameter value for parameter 1
      /// @param to1 upper border of parameter value for parameter 1
      /// @param stepwidth1 sampling rate for costfunction evaluation of parameter 1
      /// @param paramnum2 second parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from2 lower border of parameter value for parameter 2
      /// @param to2 upper border of parameter value for parameter2
      /// @param stepwidth2 sampling rate for costfunction evaluation of parameter 2
      /// @param path path to the result file
      ///
      void plot2D(int paramnum1, const float from1, const float to1, const float stepwidth1, int paramnum2, const float from2, const float to2, const float stepwidth2, const char* path);
      
      
      ///
      /// Performs a 3d evaluation of the costfunction defined in the optimization problem. Note, that the first to parameters will vary while the third one stays fixed for the generation of one evaluation cycle. Afterwards a new plot file will be generated with a new initialization of parameter 3 and again parameter 1 and 2 will be varied within their ranges. This function will result in a fixed number of plot files giving the behavior of the first two parameters over time for a varied third one. The files will be named given the path and a evaluation number corresponding to the parameter value of parameter 1 will be added to the path name. 
      /// @param paramnum1 first parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from1 lower border of parameter value for parameter 1
      /// @param to1 upper border of parameter value for parameter 1
      /// @param stepwidth1 sampling rate for costfunction evaluation of parameter 1
      /// @param paramnum2 second parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from2 lower border of parameter value for parameter 2
      /// @param to2 upper border of parameter value for parameter 2
      /// @param stepwidth2 sampling rate for costfunction evaluation of parameter 2
      /// @param paramnum3 third parameter to evaluate (will be checked to lie in the range of the dimension of the opt. problem)
      /// @param from3 lower border of parameter value for parameter 3
      /// @param to3 upper border of parameter value for parameter 3
      /// @param stepwidth3 sampling rate for costfunction evaluation of parameter 3
      /// @param path path to the result file
      ///
      void plot3D(int paramnum1, const float from1, const float to1, const float stepwidth1, int paramnum2, const float from2, const float to2, const float stepwidth2, int paramnum3, const float from3, const float to3, const float stepwidth3, const char* path);

      ///
      /// Setting the bound interpretation status: if absolute= true, the bounds (from,to) will be interpreted as absolute values and the evaluation goes from from till to; if absolute= false, the bounds will be interpreted relative to the current parameter values, meaning the the evaluation goes from start= actualval + from till end= actualval + to. Default is true.
      /// @param absolute bound interpretation status
      ///
      void setBoundInterpretationStatus(bool absolute);

      /// Get the bound interpretation status
      /// @retval true, if bounds are interpreted as absolute bounds (start= from, end=to)
      /// @retval false, if bounds are interpreted relative to the actual parameter value (start= actualval + from, end= actualval + to)	
      ///
      bool getBoundInterpretationStatus();

    protected:

      //! Flag giving the status of the bound interpretation: if true, the bounds (from,to) will be interpreted as absolute values and the evaluation goes from from till to; if false, the bounds will be interpreted relative to the current parameter values, meaning the the evaluation goes from start= actualval + from till end= actualval + to. Default is true.
      bool m_absoluteBounds;

      //! Costfunction
      CostFunction* m_pCostfunc;
      
      //! Optproblem pointer
      const SimpleOptProblem* m_pOptprob;
  }; //class
} //namespace

#endif