dneuron.h

a useful spiking neural networks simulator

		/// Modify the delay with the specified step size.
	void addDelay(ntime_t delta_d)  { ndelay += delta_d; }

		/// The event handler delivers a pulse to the destination (post-synaptic) neuron.
	virtual void activate(tscheduler &scheduler, ntime_t current_time)
	{
		if( getDeb() )
			std::cout << std::setw(9) << std::setiosflags(std::ios::fixed) << std::setprecision(debug_precision) << current_time << " " << dest->getName() << 
				" Pulse Arrived from " << src->getName() << " (delay=" << ndelay << ", w=" << weight << ")" << std::endl;
		dest->pulseArrive( scheduler, current_time, weight );
	}

		/// Obtains the pointer to the queue object of this event.
	virtual tqueue *queue() const { return dest->queue(); }
};


//////////////////////////////////////////////////////////////////////////
/// The message synapse class.
/// This class of synapses has an effect for the destination (post-synaptic) neuron
/// to deliver a message.  THe effect of the message can be arbitrarily specified.

template <bool debug>
class tsynapse_message : public tsynapse_base, public debugflag<debug>
{
protected:
	tneuron_base *src;
	tneuron_base *dest;
	message_base *mess;

public:
		/// Construct a synapse with the specified source, destination, delay and a pointer to a message.
		/// The pointer to the message will be deleted at the destrucion of this synapse.
	tsynapse_message(tneuron_base &isrc, tneuron_base &idest, real idelay, message_base *imess)
		: tsynapse_base(idelay), src(&isrc), dest(&idest), mess(imess) { }
		/// Construct a synapse with the specified destination, delay and a pointer to a message.
		/// Source neuron will be specified after the construction via setSrc() method.
		/// The pointer to the message will be deleted at the destrucion of this synapse.
	tsynapse_message(tneuron_base &idest, real idelay, message_base *imess)
		: tsynapse_base(idelay), src(NULL), dest(&idest), mess(imess) { }
		/// Destructor deletes the message.
	virtual ~tsynapse_message() { delete mess; }

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

		/// 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; }

		/// The event handler delivers a message to the destination (post-synaptic) neuron.
	virtual void activate(tscheduler &scheduler, ntime_t current_time)
	{
		if( getDeb() )
			std::cout << std::setw(9) << std::setiosflags(std::ios::fixed) << std::setprecision(debug_precision) << current_time << " " << dest->getName() << 
			" Pulse Arrived from " << src->getName() << std::endl;
		dest->pulseArrive( scheduler, current_time, mess );
	}
};


//////////////////////////////////////////////////////////////////////////
/// The "fatigue" synapse class.
/// This class of synapses delivers a pulse to the destination (post-synaptic) neuron,
/// whose strength decays on bursting (by lack of energy) and recovers gradually.
/// This is a sample for constructing more complex synapse class.

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

		/// The time of half-value period of the synapse weight decrease.
	static const ntime_t recover_hv_period = 2000;
		/// The ratio of the decay of the weight caused by one pulse deliver.
	static const real    fire_ratio = 0.002;

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

		/// 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; }
		/// Modify the delay with the specified step size.
	void addDelay(ntime_t delta_d)  { ndelay += delta_d; }

		/// The event handler delivers a pulse to the destination (post-synaptic) neuron.
		/// Then the last firing time is recorded to process the fatigueness.
	virtual void activate(tscheduler &scheduler, ntime_t current_time)
	{
		real this_weight = weight + (last_weight - weight) * exp( (current_time - last_fire) * (-M_LN2 / recover_hv_period) );
		if( getDeb() )
			std::cout << std::setw(9) << std::setiosflags(std::ios::fixed) << std::setprecision(debug_precision) << current_time << " " << dest->getName() << 
			" Pulse Arrived from " << src->getName() << "(" << this_weight * fire_ratio << "/" << weight << ")" << std::endl;
		dest->pulseArrive( scheduler, current_time, this_weight * fire_ratio );
		last_fire = current_time;
		last_weight = this_weight * (1.0 - fire_ratio);
	}

	virtual const char *getClassName() const { return "tsynapse_fatigue"; };
};

/// @}

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

/// \addtogroup Neurons
/// @{

//////////////////////////////////////////////////////////////////////////
/// The class defines a leaky integrate-and-fire neuron with threshold change, 
/// which receives only immediate pulses.
/// A neuron itself behaves as an action of an event.  When the next firing
/// is predicted, the action is scheduled at the predicted firing time (called `loopback').
/// When activated at a certain simulation time, the neuron re-calculates its state
/// and process firing if necessary.

template <bool debug>
class tneuron : public tneuron_base, public taction, public debugflag<debug>
{
protected:

	real sig_level;
	ntime_t last_simulate;
	ntime_t last_fire;
	std::vector<tsynapse_base *> synapses;

	void fire(tscheduler &scheduler, ntime_t current_time);

	static const ntime_t def_sig_hv_period = 2.0;
	static const ntime_t def_thr_hv_period = 0.5;
	static const real def_min_threshold    = 1.0;
	static const real def_max_threshold    = 11.0;

		/// Signal half-value period.
	ntime_t sig_hv_period;
		/// Threshold half-value period.
	ntime_t thr_hv_period;
		/// Minimum threshold level.
	real min_threshold;
		/// Maximum threshold level just after one firing.
	real max_threshold;
		/// The converge level (resting potential) of this neuron.
	static const real sig_converge_level = 0.0;

		/// Signal decaying coefficient is calculated from the signal half-value period.
	real coeff_sigdecay;
		/// Threshold decaying coefficient is calculated from the threshold half-value period.
	real coeff_thrdecay;

		/// This function simulates time elapse up to the specified time.
	void simulateElapse( ntime_t current_time )
	{
		sig_level = sig_converge_level +
					( ( sig_level - sig_converge_level ) 
					  * exp( (current_time - last_simulate) * coeff_sigdecay ) );
		last_simulate = current_time;
	}
		/// Schedule the next firing.
	virtual void scheduleFire( tscheduler &scheduler, ntime_t current_time, bool resched = true );

public:
		/// Construct a neuron with the specified name, signal half-value period,
		/// threshold half-value period, minimum threshold and maximum threshold.
	tneuron(std::string iname = "", 
					 ntime_t isig_hv_period = def_sig_hv_period, 
					 ntime_t ithr_hv_period = def_thr_hv_period,
					 real imin_threshold = def_min_threshold,
					 real imax_threshold = def_max_threshold );
	virtual ~tneuron();

		/// Calculates the current signal level.
	virtual real getCurrentSigLevel(ntime_t current_time)
		{ simulateElapse( current_time ); return sig_level; }

		/// Calculates the current threshold level.
	virtual real getCurrentThrLevel(ntime_t current_time) 
		{
			return min_threshold + 
				   ( (max_threshold - min_threshold) 
					 * exp( (current_time - last_fire) * coeff_thrdecay ) );
		}

		/// Processes the pulse arrival.
	virtual void pulseArrive(
					tscheduler &scheduler, 
					ntime_t current_time, 
					real pulse_level)
		{ totalpulse++; simulateElapse( current_time ); sig_level += pulse_level; scheduleFire( scheduler, current_time ); }

		/// Add an synapse whose destination (post-synapse) is this neuron.
	virtual void addSynapse(tsynapse_base *s) 
		{ synapses.push_back(s); s->setSrc(*this); }
		/// Remove an synapse from this neuron.
	virtual void eraseSynapse(tsynapse_base *s) 
		{ remove( synapses.begin(), synapses.end(), s); }

		/// Get the time of the last firing.
	virtual ntime_t getLastFire() const { return last_fire; }
		/// Get the time of the last simulation.
	virtual ntime_t getLastSimulate() const { return last_simulate; }

		/// When activated as an event, it re-calculates its state and check firing.
	virtual void activate(tscheduler &scheduler, ntime_t current_time)
		{ 
		if( getDeb() )
			std::cout << std::setw(9) << std::setiosflags(std::ios::fixed) << std::setprecision(debug_precision) << current_time << " " << getName() << 
				" Pulse arrived (loopback)" << std::endl;
		simulateElapse(current_time); scheduleFire(scheduler, current_time, false); };

		/// Get the class name.
	virtual const char *getClassName() const { return "tneuron"; };

		/// Get the pointer to the queue object.
	virtual tqueue *queue() const { return &_queue; }

		/// Get the vector of synapses.
	const std::vector<tsynapse_base *> &getSynapses() { return synapses; }
};

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

//////////////////////////////////////////////////////////////////////////
/// This class extends the tneuron class with a constant external input.

template <bool debug>
class tneuron_ext_const : public tneuron<debug>
{
protected:
	static const real def_ext_input            = 0.0;
	real ext_input;
	real sig_converge_level;

		/// This function simulates time elapse up to the specified time.
		/// Note that this function is non-virtual to speed-up the simulation.
	void simulateElapse( ntime_t current_time )
	{
		sig_level = sig_converge_level +
					( ( sig_level - sig_converge_level ) 
					  * exp( (current_time - last_simulate) * coeff_sigdecay ) );
		last_simulate = current_time;
	}
		/// Schedule the next firing.
	virtual void scheduleFire( tscheduler &scheduler, ntime_t current_time, bool resched = true );

public:
		/// Construct a neuron with the specified name, signal half-value period,
		/// threshold half-value period, minimum threshold, maximum threshold, and
		/// the weight of the external input.
	tneuron_ext_const(std::string iname = "", 
					 ntime_t isig_hv_period = def_sig_hv_period, 
					 ntime_t ithr_hv_period = def_thr_hv_period,
					 real imin_threshold = def_min_threshold,
					 real imax_threshold = def_max_threshold,
					 real iext_input = def_ext_input ) 
		: tneuron<debug>( iname, isig_hv_period, ithr_hv_period, imin_threshold, imax_threshold ),
		  ext_input(iext_input), sig_converge_level(iext_input / coeff_sigdecay) { }
	virtual ~tneuron_ext_const() { }	

		/// Calculates the current signal level.
	virtual real getCurrentSigLevel(ntime_t current_time)
		{ simulateElapse( current_time ); return sig_level; }

		/// Get the weight of the external input.
	real getExtInput() { return ext_input; }
		/// Get the weight of the external input for logging.
	virtual real getCurrentExtInput(ntime_t /*current_time*/) { return ext_input; }
		/// Change the weight of the external input at the specified time.
	void setExtInput(tscheduler &scheduler, ntime_t current_time, real val) 
		{ simulateElapse( current_time ); ext_input = val; sig_converge_level = ext_input / coeff_sigdecay; scheduleFire( scheduler, current_time ); }
		/// Get the converge level (resting potential of this neuron).
	real getConvergeLevel() { return sig_converge_level; }
		/// Change the weight of the external input at the specified time, so that the converge level 
		/// (resting potential of this neuron) becomes the specified value..