stdp_nn_pre_centered_synapse.h

Go to the documentation of this file.

/*
 *  stdp_nn_pre_centered_synapse.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST 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.
 *
 *  NEST 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 NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef STDP_NN_PRE_CENTERED_SYNAPSE_H
#define STDP_NN_PRE_CENTERED_SYNAPSE_H
 
// C++ includes:
#include <cmath>
 
// Includes from nestkernel:
#include "common_synapse_properties.h"
#include "connection.h"
#include "connector_model.h"
#include "event.h"
 
 
namespace nest
{
 
/* BeginUserDocs: synapse, chemical, functional, stdp
 
Short description
+++++++++++++++++
 
Synapse type for spike-timing dependent plasticity with
presynaptic-centered nearest-neighbour spike pairing scheme
 
Description
+++++++++++
 
``stdp_nn_pre_centered_synapse`` is a connector to create synapses with spike
time dependent plasticity with the ``presynaptic``-centered nearest-neighbour
spike pairing scheme, as described in :footcite:p:`Izhikevich2003b`.
 
Each presynaptic spike is taken into account in the STDP weight change rule
with the nearest preceding postsynaptic one and the nearest succeeding
postsynaptic one (instead of pairing with all spikes, like in ``stdp_synapse``).
So, when a presynaptic spike occurs, it is accounted in the depression rule
with the nearest preceding postsynaptic one; and when a postsynaptic spike
occurs, it is accounted in the facilitation rule with all preceding
presynaptic spikes that were not earlier than the previous postsynaptic
spike. For a clear illustration of this scheme see fig. 7B in :footcite:p:`Morrison2008`.
 
The pairs exactly coinciding (so that ``presynaptic_spike == postsynaptic_spike
+ dendritic_delay``), leading to zero ``delta_t``, are discarded. In this case the
concerned pre/postsynaptic spike is paired with the second latest preceding
post/presynaptic one (for example, ``pre=={10 ms; 20 ms}`` and ``post=={20 ms}`` will
result in a potentiation pair 20-to-10).
 
The implementation involves two additional variables - presynaptic and
postsynaptic traces :footcite:p:`Morrison2008`. The presynaptic trace decays exponentially over
time with the time constant ``tau_plus``, increases by 1 on a pre-spike
occurrence, and is reset to 0 on a post-spike occurrence. The postsynaptic
trace (implemented on the postsynaptic neuron side) decays with the time
constant ``tau_minus`` and increases to 1 on a post-spike occurrence.
 
.. warning::
 
   This synaptic plasticity rule does not take
   :ref:`precise spike timing <sim_precise_spike_times>` into
   account. When calculating the weight update, the precise spike time part
   of the timestamp is ignored.
 
Parameters
++++++++++
 
========= =======  ======================================================
 tau_plus  ms      Time constant of STDP window, potentiation
                   (tau_minus defined in postsynaptic neuron)
 lambda    real    Step size
 alpha     real    Asymmetry parameter (scales depressing increments as
                   alpha*lambda)
 mu_plus   real    Weight dependence exponent, potentiation
 mu_minus  real    Weight dependence exponent, depression
 Wmax      real    Maximum allowed weight
========= =======  ======================================================
 
Transmits
+++++++++
 
SpikeEvent
 
References
++++++++++
 
.. footbibliography::
 
See also
++++++++
 
stdp_synapse, stdp_nn_symm_synapse
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: stdp_nn_pre_centered_synapse
 
EndUserDocs */
 
// connections are templates of target identifier type (used for pointer /
// target index addressing) derived from generic connection template
 
void register_stdp_nn_pre_centered_synapse( const std::string& name );
 
template < typename targetidentifierT >
class stdp_nn_pre_centered_synapse : public Connection< targetidentifierT >
{
 
public:
  typedef CommonSynapseProperties CommonPropertiesType;
  typedef Connection< targetidentifierT > ConnectionBase;
 
  static constexpr ConnectionModelProperties properties = ConnectionModelProperties::HAS_DELAY
    | ConnectionModelProperties::IS_PRIMARY | ConnectionModelProperties::SUPPORTS_HPC
    | ConnectionModelProperties::SUPPORTS_LBL;
 
  stdp_nn_pre_centered_synapse();
 
 
  stdp_nn_pre_centered_synapse( const stdp_nn_pre_centered_synapse& ) = default;
  stdp_nn_pre_centered_synapse& operator=( const stdp_nn_pre_centered_synapse& ) = default;
 
  // Explicitly declare all methods inherited from the dependent base
  // ConnectionBase. This avoids explicit name prefixes in all places these
  // functions are used. Since ConnectionBase depends on the template parameter,
  // they are not automatically found in the base class.
  using ConnectionBase::get_delay;
  using ConnectionBase::get_delay_steps;
  using ConnectionBase::get_rport;
  using ConnectionBase::get_target;
 
  void get_status( Dictionary& d ) const;
 
  void set_status( const Dictionary& d, ConnectorModel& cm );
 
  bool send( Event& e, size_t t, const CommonSynapseProperties& cp );
 
  class ConnTestDummyNode : public ConnTestDummyNodeBase
  {
  public:
    // Ensure proper overriding of overloaded virtual functions.
    // Return values from functions are ignored.
    using ConnTestDummyNodeBase::handles_test_event;
    size_t
    handles_test_event( SpikeEvent&, size_t ) override
    {
      return invalid_port;
    }
  };
 
  void
  check_connection( Node& s, Node& t, size_t receptor_type, const CommonPropertiesType& )
  {
    ConnTestDummyNode dummy_target;
 
    ConnectionBase::check_connection_( dummy_target, s, t, receptor_type );
 
    t.register_stdp_connection( t_lastspike_ - get_delay(), get_delay() );
  }
 
  void
  set_weight( double w )
  {
    weight_ = w;
  }
 
private:
  double
  facilitate_( double w, double kplus )
  {
    double norm_w = ( w / Wmax_ ) + ( lambda_ * std::pow( 1.0 - ( w / Wmax_ ), mu_plus_ ) * kplus );
    return norm_w < 1.0 ? norm_w * Wmax_ : Wmax_;
  }
 
  double
  depress_( double w, double kminus )
  {
    double norm_w = ( w / Wmax_ ) - ( alpha_ * lambda_ * std::pow( w / Wmax_, mu_minus_ ) * kminus );
    return norm_w > 0.0 ? norm_w * Wmax_ : 0.0;
  }
 
  // data members of each connection
  double weight_;
  double tau_plus_;
  double lambda_;
  double alpha_;
  double mu_plus_;
  double mu_minus_;
  double Wmax_;
  double Kplus_;
 
  double t_lastspike_;
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties stdp_nn_pre_centered_synapse< targetidentifierT >::properties;
 
template < typename targetidentifierT >
inline bool
stdp_nn_pre_centered_synapse< targetidentifierT >::send( Event& e, size_t t, const CommonSynapseProperties& )
{
  // synapse STDP depressing/facilitation dynamics
  double t_spike = e.get_stamp().get_ms();
 
  // use accessor functions (inherited from Connection< >) to obtain delay and
  // target
  Node* target = get_target( t );
  double dendritic_delay = get_delay();
 
  // get spike history in relevant range (t1, t2] from postsynaptic neuron
  std::deque< histentry >::iterator start;
  std::deque< histentry >::iterator finish;
 
  // For a new synapse, t_lastspike_ contains the point in time of the last
  // spike. So we initially read the
  // history(t_last_spike - dendritic_delay, ..., T_spike-dendritic_delay]
  // which increases the access counter for these entries.
  // At registration, all entries' access counters of
  // history[0, ..., t_last_spike - dendritic_delay] have been
  // incremented by ArchivingNode::register_stdp_connection(). See bug #218 for
  // details.
  target->get_history( t_lastspike_ - dendritic_delay, t_spike - dendritic_delay, &start, &finish );
  // If there were no postsynaptic spikes between the current pre-synaptic one
  // t_spike and the previous pre-synaptic one t_lastspike_, there are no pairs
  // to account.
  if ( start != finish )
  {
    // facilitation due to the first postsynaptic spike start->t_
    // since the previous pre-synaptic spike t_lastspike_
 
    double minus_dt;
    minus_dt = t_lastspike_ - ( start->t_ + dendritic_delay );
 
    // get_history() should make sure that
    // start->t_ > t_lastspike_ - dendritic_delay, i.e. minus_dt < 0
    assert( minus_dt < -1.0 * kernel().connection_manager.get_stdp_eps() );
 
    weight_ = facilitate_( weight_, Kplus_ * std::exp( minus_dt / tau_plus_ ) );
 
    // According to the presynaptic-centered nearest-neighbour scheme,
    // a postsynaptic spike
    // (we now know there was at least one between t_lastspike_ and t_spike)
    // erases the state of the synapse,
    // and all the preceding presynaptic spikes are forgotten.
    Kplus_ = 0;
  }
 
  // depression due to the latest postsynaptic spike finish->t_
  // before the current pre-synaptic spike t_spike
  double nearest_neighbor_Kminus;
  double value_to_throw_away;  // discard Kminus and Kminus_triplet here
  target->get_K_values( t_spike - dendritic_delay, value_to_throw_away, nearest_neighbor_Kminus, value_to_throw_away );
  weight_ = depress_( weight_, nearest_neighbor_Kminus );
 
  Kplus_ = Kplus_ * std::exp( ( t_lastspike_ - t_spike ) / tau_plus_ ) + 1.0;
 
  e.set_receiver( *target );
  e.set_weight( weight_ );
  // use accessor functions (inherited from Connection< >) to obtain delay in
  // steps and rport
  e.set_delay_steps( get_delay_steps() );
  e.set_rport( get_rport() );
  e();
 
  t_lastspike_ = t_spike;
 
  return true;
}
 
 
template < typename targetidentifierT >
stdp_nn_pre_centered_synapse< targetidentifierT >::stdp_nn_pre_centered_synapse()
  : ConnectionBase()
  , weight_( 1.0 )
  , tau_plus_( 20.0 )
  , lambda_( 0.01 )
  , alpha_( 1.0 )
  , mu_plus_( 1.0 )
  , mu_minus_( 1.0 )
  , Wmax_( 100.0 )
  , Kplus_( 0.0 )
  , t_lastspike_( 0.0 )
{
}
 
template < typename targetidentifierT >
void
stdp_nn_pre_centered_synapse< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
  d[ names::tau_plus ] = tau_plus_;
  d[ names::lambda ] = lambda_;
  d[ names::alpha ] = alpha_;
  d[ names::mu_plus ] = mu_plus_;
  d[ names::mu_minus ] = mu_minus_;
  d[ names::Wmax ] = Wmax_;
  d[ names::Kplus ] = Kplus_;
  d[ names::size_of ] = static_cast< long >( sizeof( *this ) );
}
 
template < typename targetidentifierT >
void
stdp_nn_pre_centered_synapse< targetidentifierT >::set_status( const Dictionary& d, ConnectorModel& cm )
{
  ConnectionBase::set_status( d, cm );
  d.update_value( names::weight, weight_ );
  d.update_value( names::tau_plus, tau_plus_ );
  d.update_value( names::lambda, lambda_ );
  d.update_value( names::alpha, alpha_ );
  d.update_value( names::mu_plus, mu_plus_ );
  d.update_value( names::mu_minus, mu_minus_ );
  d.update_value( names::Wmax, Wmax_ );
  d.update_value( names::Kplus, Kplus_ );
 
  // check if weight_ and Wmax_ have the same sign
  if ( not( ( ( weight_ >= 0 ) - ( weight_ < 0 ) ) == ( ( Wmax_ >= 0 ) - ( Wmax_ < 0 ) ) ) )
  {
    throw BadProperty( "Weight and Wmax must have same sign." );
  }
 
  if ( Kplus_ < 0 )
  {
    throw BadProperty( "Kplus must be non-negative." );
  }
}
 
}  // of namespace nest
 
#endif  // of #ifndef STDP_NN_PRE_CENTERED_SYNAPSE_H