dneuron.h

a useful spiking neural networks simulator

/** 
 * @file  dneuron.h
 * @brief Neuron/Synapse class in discrete-event NN simulation
 *
 * @author Makino, Takaki <[e-mail]>
 * @date 2003-05-01
 * @version $Id: dneuron.h,v 1.6 2003/05/08 07:24:56 t Exp $
 *
 *  Copyright (C) 2003 Makino, Takaki. 
 *
 *  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, 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., 675 Mass Ave, Cambridge, MA 02139, USA.  
 */

#ifndef __dneuron_h
#define __dneuron_h

#include <vector>
#include <map>
#include <string>
#include <algorithm>
#include <math.h>
#include <queue>
#include <iostream>
#include <iomanip>

#include "dsched.h"
#include "func.h"

namespace punnets_common {

const int debug_precision = 5;

typedef unsigned long long u_int64_t;

/// \addtogroup totalvars Variables for Statistics
/// @{

/// This variable counts the total number of firing of the neurons.
extern u_int64_t totalfire;

/// This variable counts the total pulse arrivals to any of the neurons.
extern u_int64_t totalpulse;

/// This variable counts the total number of partitions.
extern u_int64_t totalpartition;

/// This variable counts the number of partitions without Newton-Raphson search.
/// Each element contains the number of 0th, 1st, 2nd. and delta partitions, respectively.
extern u_int64_t totalpartition_nonewton[4];

/// This variable counts the number of partitions with Newton-Raphson search.
/// Each element contains the number of 0th, 1st, 2nd. and delta partitions, respectively.

extern u_int64_t totalpartition_newton[4];

/// This variable counts the number of peak searches.
/// Each element contains the number of searches with peak below threshold (no crossing), 
/// peak above threshold (crossing), no peak (not convex), respectively.

extern u_int64_t totalpeaksearch[3];

/// This variable counts the total number of peak enclosings.  One peak search contains several enclosings.
extern u_int64_t totalpeakenclosing;

/// This variable counts the total number of re-scheduling.
extern u_int64_t totalrescheduled;

/// This variable counts the total filtering caused by maximum gradient check.
extern u_int64_t totalfiltered_maxgrad;

/// This variable counts the total filtering caused by nearby incontinuity.
extern u_int64_t totalfiltered_incontinuity;

/// This variable counts the total filtering caused by nearby next pulse.
extern u_int64_t totalfiltered_nextpulse;

/// @}

//const bool global_debug = true;
//const bool force_global_debug = true;

/// This variable specifies the minimum error value.
const real epsilon = 1e-10;

class tsynapse_base;


/////////////////////////////////////////////////////////////////////////
/// An interface for selective debugging messages.
///
/// This interface class provides getDeb() and setDeb() members.
/// neuron and synapse classes are designed to produce debug messages
/// only if getDeb() is true. 

template <bool d>
class debugflag;

/// This instantiation of the class is used for punnets_nodebug namespace.
/// it provides always false value to the getDeb(), so that the debugging code
/// is optimized out.

template <> class debugflag<false> 
{ 
public: 
		/// Get debugging condition, which is always false.
	bool getDeb() const { return false; } 
		/// Set debugging condition, which always fails.
	void setDeb(bool) { std::cout << "No Debug" << std::endl; } 
};

/// This instantiation of the class is used for punnets namespace.

template <> class debugflag<true> 
{ 
protected: 
		/// The debugging condition.
	bool debug;  
public: 
		/// Constructor initialized the debugging condition to false.
	debugflag() { debug = false; } 
		/// Get debugging condition.
	bool getDeb() const { return debug; } 
		/// Set debugging condition.
	void setDeb(bool b) { debug = b; } 
};

/// \addtogroup Neurons 
/// @{

/////////////////////////////////////////////////////////////////////////
/// The base class of a neuron.
///
/// This abstract base class provides several interfaces for neuron access.

class tneuron_base
{
protected:
		/// The name of this neuron.  Used in debugging and logging.
	std::string name;
		/// The event queue of this neuron. 
	mutable tqueue _queue;

public:
		/// Construct a neuron with the name iname.
	tneuron_base(std::string iname = "")
		: name(iname) { }
	virtual ~tneuron_base() { }
		/// Returns the name of this neuron.
	const std::string &getName() const { return name; }
	
		/// These methods handle pulse arrivals of the neuron.
		/// The pulse may be a real number (immediate value), message, or a function to be added.
		/// The latter two has a default handler that does nothing. A derived class should redefine these methods.
	virtual void pulseArrive(
					tscheduler &scheduler, 
					ntime_t current_time, 
					real pulse_level) = 0;
	virtual void pulseArrive(
					tscheduler &/*scheduler*/, 
					ntime_t /*current_time*/, 
					message_base * /*mess*/) { }
	virtual void pulseArrive(
					tscheduler &/*scheduler*/, 
					ntime_t /*current_time*/, 
					func_base * /*func*/) { }

		/// Add a synapse input (this neuron becomes postsynaptic). A derived class should redefine this method.
	virtual void addSynapse(tsynapse_base *) { }

		/// This function probes the current signal level of the neuron. A derived class should redefine this method. 
	virtual real getCurrentSigLevel(ntime_t /*current_time*/) { return 0.0; };
		/// This function probes the current threshold level of the neuron. A derived class should redefine this method.
	virtual real getCurrentThrLevel(ntime_t /*current_time*/) { return 0.0; };
		/// This function probes the current external input level of the neuron. A derived class should redefine this method.
	virtual real getCurrentExtInput(ntime_t /*current_time*/) { return 0.0; }

		/// This function returns the last time that the neuron fired.  Used in STDP and such.
	virtual ntime_t getLastFire() const { return 0; }
		/// This function returns the last time that the neuron has been simulated.
	virtual ntime_t getLastSimulate() const { return 0; }
		/// This function returns the type of the last simulation (0th/1st/2nd and so on).
	virtual int getLastSimulateType() const { return 0; }

		/// Obtains the pointer to the queue object of this neuron.
	virtual tqueue *queue() const { return &_queue; }

		/// Obtains the class name of this neuron.
	virtual const char *getClassName() const { return "tneuron_base"; };
};

/// @}

/*************************************************************************/

/// \addtogroup Synapses
/// @{

/////////////////////////////////////////////////////////////////////////
/// The base class of a synapse.
///
/// This abstract base class provides several interfaces for a synapse.
/// A synapse itself behaves as an action of an event; i.e. when activated at a certain
/// simulation time, a synapse updates the destination (post-synaptic) neuron.

class tsynapse_base : public taction
{
protected:
		/// synaptic delay.
	ntime_t ndelay;

public:
		/// Construct a synapse with the specified delay.
	tsynapse_base(ntime_t idelay) : taction(), ndelay(idelay) { }
		/// Get the delay length.
	ntime_t getDelay() const { return ndelay; }
		/// Get the weight of the synapse. A derived class should redefine this method. 
	virtual real getWeight()   const { return 0; }

		/// Set the source neuron (presynaptic) of this synapse.  A derived class should redefine this method. 
	virtual void setSrc(tneuron_base &) { }
		/// Get the source neuron (pre-synaptic).   A derived class should redefine this method. 
	virtual tneuron_base &getSrc() const { throw "ERROR"; }
		/// Get the destination neuron (post-synaptic).   A derived class should redefine this method. 
	virtual tneuron_base &getDest() const { throw "ERROR"; }

		/// The event handler.  When the source (pre-synaptic) neuron fires,
		/// this function is called after the synaptic delay.  A derived
		/// class should redefine this method to update the destination (post-synaptic)
		/// neuron.
	virtual void activate(tscheduler &scheduler, ntime_t current_time) = 0;

		/// Obtains the class name of this neuron.
	virtual const char *getClassName() const { return "tsynapse_base"; };
};
/// @}

//////////////////////////////////////////////////////////////////////////
} // namespace punnets_common
//////////////////////////////////////////////////////////////////////////
namespace punnets_private {
//////////////////////////////////////////////////////////////////////////
using namespace punnets_common;

/// \addtogroup Synapses
/// @{

//////////////////////////////////////////////////////////////////////////
/// The default synapse class.
/// This class of synapses has an effect for the destination (post-synaptic) neuron
/// to update its potential immediately with a constant amount of the weight.

template <bool debug>
class tsynapse : public tsynapse_base, public debugflag<debug>
{
protected:
	tneuron_base *src;
	tneuron_base *dest;
	real weight;

public:
		/// Construct a synapse with the specified source, destination, delay and weight.
	tsynapse(tneuron_base &isrc, tneuron_base &idest, ntime_t idelay, real iweight)
		: tsynapse_base(idelay), src(&isrc), dest(&idest), weight(iweight) { }
		/// Construct a synapse with the specified destination, delay and weight.
		/// Source neuron will be specified after the construction via setSrc() method.
	tsynapse(tneuron_base &idest, ntime_t idelay, real iweight)
		: tsynapse_base(idelay), src(NULL), dest(&idest), weight(iweight) { }
	virtual ~tsynapse() { }

		/// Specify the source neuron.
	virtual void setSrc(tneuron_base &isrc) { src = &isrc; }

		/// Get the weight value of this synapse.
	virtual real getWeight()   const { return weight; }
		/// Get the source neuron (pre-synaptic). 
	virtual tneuron_base &getSrc() const { if( src == NULL ) throw "ERROR"; return *src; }
		/// Get the destination neuron (post-synaptic). 
	virtual tneuron_base &getDest() const { return *dest; }

		/// Modify the weight value with the specified step size.
	void addWeight(real delta_w)    { weight += delta_w; }