LowpassNeuron.H

Go to the documentation of this file.

/*!@file ModelNeuron/LowpassNeuron.H a very simple and abstract kind of neuron */

// //////////////////////////////////////////////////////////////////// //
// The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2001 by the //
// University of Southern California (USC) and the iLab at USC.         //
// See http://iLab.usc.edu for information about this project.          //
// //////////////////////////////////////////////////////////////////// //
// Major portions of the iLab Neuromorphic Vision Toolkit are protected //
// under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
// in Visual Environments, and Applications'' by Christof Koch and      //
// Laurent Itti, California Institute of Technology, 2001 (patent       //
// pending; application number 09/912,225 filed July 23, 2001; see      //
// http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
// //////////////////////////////////////////////////////////////////// //
// This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit 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.     //
//                                                                      //
// The iLab Neuromorphic Vision C++ Toolkit 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 the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
// to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
// Boston, MA 02111-1307 USA.                                           //
// //////////////////////////////////////////////////////////////////// //
//
// Primary maintainer for this file: David Berg <dberg@usc.edu>
// $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/ModelNeuron/LowpassNeuron.H $

#ifndef MODELNEURON_LOWPASSNEURON_H_DEFINED
#define MODELNEURON_LOWPASSNEURON_H_DEFINED

#include "ModelNeuron/SimUnit.H"
#include "ModelNeuron/LowPass.H"

// ######################################################################
// abstract neural model made from simple first order linear dynamic systems 
//
// the underlying currents are represented by :
//
// dc/dt = (I_p - c)/t_p + (c - I_n)/t_n 
//
// where c is the state variable, I_p are the possitive (excitatory) inputs and 
// I_n are the negative (inhibitory) inputs. t_p and t_n are the excitatory
// and inhibitory decay factors. 
//
// the state of the system is then given by :
//
// tau * dg/dt = -g + c + H 
//
// ######################################################################
template <class RateFunc = RateFunctions::EmptyFunction, class IntType = LowPassExpEuler>
class LowpassNeuronImpl: public SimUnit
{
public:  
  //! Constructor with default params
  LowpassNeuronImpl(const double& tau_ef,     // excite time constant msecs
                    const double& tau_es,     // excite time constant msecs
                    const double& tau_if,     // inhibit time constant msecs
                    const double& tau_is,     // inhibit time constant msecs
                    const double& tau_s,     // system time constant msecs
                    const double& gain,      // ration of excitatory to inhibitory gain
                    const double& h,         // system steady state
                    const SimTime& timestep, // simulaton timestep
                    const std::string& name = "LowpassNeuron", 
                    const std::string& units = "pA");
  
  //! Constructor with default params
  LowpassNeuronImpl(const double& tau_ef,     // excite time constant msecs
                    const double& tau_es,     // excite time constant msecs
                    const double& tau_if,     // inhibit time constant msecs
                    const double& tau_is,     // inhibit time constant msecs
                    const double& tau_s,      // system time constant msecs
                    const double& gain,      // ration of excitatory to inhibitory gain
                    const double& h,         // system steady state
                    const double& param1,    // param 1 for the rate function
                    const SimTime& timestep, // simulaton timestep
                    const std::string& name = "LowpassNeuron", 
                    const std::string& units = "pA");
  
  //! Constructor with default params
  LowpassNeuronImpl(const double& tau_ef,     // excite time constant msecs
                    const double& tau_es,     // excite time constant msecs
                    const double& tau_if,     // inhibit time constant msecs
                    const double& tau_is,     // inhibit time constant msecs
                    const double& tau_s,      // system time constant msecs
                    const double& gain,      //ration of excitatory to inhibitory gain
                    const double& h,         // system steady state
                    const double& param1,    //param 1 for the rate function
                    const double& param2,    //param 2 for the rate function
                    const SimTime& timestep, //simulaton timestep
                    const std::string& name = "LowpassNeuron", 
                    const std::string& units = "pA");
  
  //! destructor
  ~LowpassNeuronImpl() { };
  
  //! get the display output
  const double getDisplayOutput() const;
  
private:
  //! integrate a time step using exponential euler
  const double doIntegrate(const SimTime& dt, const double& ine, const double& inh);
  
  //!initialize or reset internal variables
  void doInit();
  
  //! clone this object
  LowpassNeuronImpl<RateFunc,IntType>* doClone() const;
  
  IntType itsEf, itsEs, itsIf, itsIs, itsG;  //5 temporal filters to construct a neuron
  double itsEsf, itsEss, itsIsf, itsIss, itsGs;//state variables
  double itsGain;             //inhibit to excite ratio
  RateFunc firingRate;       // our firing rate functor
};

// ######################################################################
// typedefs
// ######################################################################
typedef 
LowpassNeuronImpl<RateFunctions::EmptyFunction, LowPassExpEuler> LowpassNeuron;
typedef 
LowpassNeuronImpl<RateFunctions::RectifyFunction, LowPassExpEuler> LowpassNeuronRectify;
typedef 
LowpassNeuronImpl<RateFunctions::FullRectifyFunction, LowPassExpEuler> LowpassNeuronFullRectify;
typedef 
LowpassNeuronImpl<RateFunctions::StepFunction, LowPassExpEuler> LowpassNeuronStep;
typedef 
LowpassNeuronImpl<RateFunctions::MaxRectFunction, LowPassExpEuler> LowpassNeuronMaxRect;
typedef 
LowpassNeuronImpl<RateFunctions::LogThreshFunction, LowPassExpEuler> LowpassNeuronLog;
typedef 
LowpassNeuronImpl<RateFunctions::SigmoidFunction, LowPassExpEuler> LowpassNeuronSigmoid;

// ######################################################################
// register our objects
// ######################################################################
namespace 
{
  typedef SimUnit::Factory LPNFactory;
  typedef SimUnit::Creator LPNCreator;
  //define creation functions
  struct RegisterLowpassNeuron
  {
    RegisterLowpassNeuron()
    {
      const double tauef = 10.0;
      const double taues = 150.0;
      const double tauif = 15.0;
      const double tauis = 150.0;
      const double taus = 15.0;
      const double gain = 1;
      
      const SimTime time = SimTime::MSECS(1.0);
      
      LPNFactory::instance().add("LowpassNeuron", 
                                 LPNCreator::make<LowpassNeuron>(tauef, taues, tauif, tauis, 
                                                                 taus, gain, -0.5, time));
      LPNFactory::instance().add("LowpassNeuronRectify", 
                                 LPNCreator::make<LowpassNeuronRectify>(tauef, taues, tauif, tauis, 
                                                                        taus, gain, -0.5, 0.0, time));
      LPNFactory::instance().add("LowpassNeuronFullRectify", 
                                 LPNCreator::make<LowpassNeuronFullRectify>(tauef, taues, tauif, 
                                                                            tauis, taus, gain, 0.0, time));
      LPNFactory::instance().add("LowpassNeuronStep", 
                                 LPNCreator::make<LowpassNeuronStep>(tauef, taues, tauif, 
                                                                     tauis, taus, gain, -0.5, 0.0, 1.0, time));
      LPNFactory::instance().add("LowpassNeuronMaxRect", 
                                 LPNCreator::make<LowpassNeuronMaxRect>(tauef, taues, tauif, 
                                                                        tauis, taus, gain, -0.5, 0.0, 1.0, time));
      LPNFactory::instance().add("LowpassNeuronLog", 
                                 LPNCreator::make<LowpassNeuronLog>(tauef, taues, tauif, 
                                                                    tauis, taus, gain, 0.0, 0.1, time));
      LPNFactory::instance().add("LowpassNeuronSigmoid",
                                 LPNCreator::make<LowpassNeuronSigmoid>(tauef, taues, tauif, 
                                                                        tauis, taus, gain, -0.5, 0.55,12.0, time));
    }
  };
  static RegisterLowpassNeuron registerlpn;  
}

// ######################################################################
// ##### implementation for LowpassNeuronImpl
// ######################################################################
// default case rate function takes 0 params
// ######################################################################
template <class RateFunc, class IntType> inline
LowpassNeuronImpl<RateFunc,IntType>::LowpassNeuronImpl(const double& tauef, 
                                                       const double& taues, 
                                                       const double& tauif, 
                                                       const double& tauis, 
                                                       const double& taus, 
                                                       const double& gain, 
                                                       const double& h,
                                                       const SimTime& timestep,
                                                       const std::string& name, 
                                                       const std::string& units) : 
  SimUnit(timestep, IntType::RateType, name+RateFunc::name(), units), 
  itsEf(timestep.msecs(), 0.0, tauef), itsEs(timestep.msecs(), 0.0, taues), 
  itsIf(timestep.msecs(), 0.0, tauif), itsIs(timestep.msecs(), 0.0, tauis), 
  itsG(timestep.msecs(), h, taus), itsEsf(0.0), itsEss(0.0), itsIsf(0.0), itsIss(0.0), 
  itsGs(h), itsGain(gain), firingRate() { };

// ######################################################################
// default case rate function takes 1 params
// ######################################################################
template <class RateFunc, class IntType> inline
LowpassNeuronImpl<RateFunc,IntType>::LowpassNeuronImpl(const double& tauef, 
                                                       const double& taues, 
                                                       const double& tauif, 
                                                       const double& tauis, 
                                                       const double& taus, 
                                                       const double& gain, 
                                                       const double& h,
                                                       const double& param1,
                                                       const SimTime& timestep,
                                                       const std::string& name, 
                                                       const std::string& units) : 
  SimUnit(timestep, IntType::RateType, name+RateFunc::name(), units), 
  itsEf(timestep.msecs(), 0.0, tauef), itsEs(timestep.msecs(), 0.0, taues), 
  itsIf(timestep.msecs(), 0.0, tauif), itsIs(timestep.msecs(), 0.0, tauis), 
  itsG(timestep.msecs(), h, taus), itsEsf(0.0), itsEss(0.0), itsIsf(0.0), itsIss(0.0), 
  itsGs(h), itsGain(gain), firingRate(param1) { };

// ######################################################################
// default case rate function takes 2 params
// ######################################################################
template <class RateFunc, class IntType> inline
LowpassNeuronImpl<RateFunc,IntType>::LowpassNeuronImpl(const double& tauef,
                                                       const double& taues,  
                                                       const double& tauif,
                                                       const double& tauis,  
                                                       const double& taus, 
                                                       const double& gain, 
                                                       const double& h,
                                                       const double& param1,
                                                       const double& param2,
                                                       const SimTime& timestep,
                                                       const std::string& name, 
                                                       const std::string& units) : 
  SimUnit(timestep, IntType::RateType, name+RateFunc::name(), units), 
  itsEf(timestep.msecs(), 0.0, tauef), itsEs(timestep.msecs(), 0.0, taues), 
  itsIf(timestep.msecs(), 0.0, tauif), itsIs(timestep.msecs(), 0.0, tauis), 
  itsG(timestep.msecs(), h, taus), itsEsf(0.0), itsEss(0.0), itsIsf(0.0), itsIss(0.0), 
  itsGs(h), itsGain(gain), firingRate(param1, param2) { };


// ######################################################################
template <class RateFunc, class IntType> inline 
const double LowpassNeuronImpl<RateFunc,IntType>::getDisplayOutput() const
{
  return itsGs;
}

// ######################################################################
template <class RateFunc, class IntType> inline
const double LowpassNeuronImpl<RateFunc,IntType>::doIntegrate(const SimTime& dt, 
                                                              const double& ine,
                                                              const double& inh)
{
  //update our excitatory synapses
  itsEf.update(ine, itsEsf); //fast
  itsEs.update(ine, itsEss); //slow
  
  //update our inhibitory synapses
  itsIf.update(inh, itsIsf); //fast
  itsIs.update(inh, itsIss); //slow

  //excitatory drives go up if the system state is less than one, and inhibitory
  //go down if greater than -1, this helps keep the system stable. between those
  //ranges.
  
  //relationship between system state and drive
  //only excites if < 1, else inhibit
  const double exc_point = 1.0 - itsGs;                               
  //only inhibits if > 1, else excite
  const double inh_point = itsGs + 1.0;                               
  //nonlinear relationhip, excite < rest, 0 at rest, and excite > rest, inhbit > 1
  const double exc_slow = (itsGs - itsG.H)*(itsGs - itsG.H)*exc_point;

  //excitatory and inhibitory drives
  const double exc_drive = itsEsf*exc_point + itsEss*exc_slow;  //itsEsf and itsEss will be pos
  const double inh_drive = itsIsf*inh_point + itsIss*inh_point; //itsIsf and itsIss will be neg
  
  //system drive with weighted inhibition
  const double drive = exc_drive + itsGain*inh_drive;
  
  //update system dynamics and return rate
  itsG.update(drive, itsGs); 
  return firingRate(itsGs);
}

// ######################################################################
template <class RateFunc, class IntType> inline
void LowpassNeuronImpl<RateFunc,IntType>::doInit()
{
  itsEss = 0.0;
  itsEsf = 0.0;
  itsIss = 0.0;
  itsIsf = 0.0;
  itsGs = itsG.H;
}

// ######################################################################
template <class RateFunc, class IntType> inline 
LowpassNeuronImpl<RateFunc,IntType>* LowpassNeuronImpl<RateFunc,IntType>::doClone() const
{
  return new LowpassNeuronImpl<RateFunc,IntType>(*this);
}

#endif
// ######################################################################
/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */