/***************************************************************************
 *   Copyright (C) 2005 by Robot Group Leipzig                             *
 *    martius@informatik.uni-leipzig.de                                    *
 *    fhesse@informatik.uni-leipzig.de                                     *
 *    der@informatik.uni-leipzig.de                                        *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program 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 General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************
 *                                                                         *
 *  DESCRIPTION                                                            *
 *                                                                         *
 *   $Log: abstractmodel.h,v $
 *   Revision 1.6  2008/05/30 11:57:12  martius
 *   do processing of inputs in learning function if network is not
 *    activated with this input before (was a very probable mistake)
 *
 *   Revision 1.5  2008/04/17 14:54:44  martius
 *   randomGen added, which is a random generator with long period and an
 *    internal state. Each Agent has an instance and passed it to the controller
 *    and the wiring. This is good for
 *   a) repeatability on agent basis,
 *   b) parallel execution as done in ode_robots
 *
 *   Revision 1.4  2008/02/08 13:38:05  der
 *   abstract model is inspectable
 *
 *   Revision 1.3  2007/02/20 15:41:05  martius
 *   big model stuff, elman and co
 *
 *   Revision 1.2  2006/07/27 15:27:20  martius
 *   processing should be called before learning
 *
 *   Revision 1.1  2006/07/20 17:14:34  martius
 *   removed std namespace from matrix.h
 *   storable interface
 *   abstract model and invertablemodel as superclasses for networks
 *
 *
 *                                                                 *
 ***************************************************************************/
#ifndef __ABSTRACTMODEL_H
#define __ABSTRACTMODEL_H

#include "matrix.h"
#include "configurable.h"
#include "storeable.h"
#include "inspectable.h"
#include "randomgenerator.h"

/// abstract class (interface) for a model that can be used by a controller
class AbstractModel : public Configurable, public Storeable, public Inspectable {
 public: 
  AbstractModel() {};
  AbstractModel(const std::string& name, const std::string& revision)
    : Configurable(name, revision) {}
  virtual ~AbstractModel(){};

  /** initialisation of the network with the given number of input and output units
      @param inputDim length of input vector
      @param outputDim length of output vector
      @param unit_map if 0 the parametes are choosen randomly. 
             Otherwise the model is initialised to represent a unit_map 
	     with the given response strength.
      @param randGen pointer to random generator, if 0 an new one is used
   */
  virtual void init(unsigned int inputDim, unsigned  int outputDim, 
		    double unit_map = 0.0, RandGen* randGen = 0) = 0;

  /** passive processing of the input
     (this function is not constant since a recurrent network 
     for example might change internal states
  */
  virtual const matrix::Matrix process (const matrix::Matrix& input) = 0;

  /* performs learning and returns the network output before learning.
     Neural networks process the input before. (no need to call process before)
     \param learnRateFactor can be given to modify eps for this learning step.
  */
  virtual const matrix::Matrix learn (const matrix::Matrix& input, 
				      const matrix::Matrix& nom_output, 
				      double learnRateFactor = 1) = 0;

  /// damps the weights and the biases by multiplying (1-damping)
  virtual void damp(double damping) = 0;

  /// returns the number of input neurons
  virtual unsigned int getInputDim() const = 0;
  /// returns the number of output neurons
  virtual unsigned int getOutputDim() const = 0;

};


#endif
