stdp_nn_restr_synapse.h

Go to the documentation of this file.

/*
 *  stdp_nn_restr_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_RESTR_SYNAPSE_H
#define STDP_NN_RESTR_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 restricted
symmetric nearest-neighbour spike pairing scheme
 
Description
+++++++++++
 
``stdp_nn_restr_synapse`` is a connector to create synapses with spike time
dependent plasticity with the restricted symmetric nearest-neighbour spike
pairing scheme (fig. 7C in :footcite:p:`Morrison2008`).
 
When a presynaptic spike occurs, it is taken into account in the depression
part of the STDP weight change rule with the nearest preceding postsynaptic
one, but only if the latter occurred not earlier than the previous presynaptic
one. When a postsynaptic spike occurs, it is accounted in the facilitation
rule with the nearest preceding presynaptic one, but only if the latter
occurred not earlier than the previous postsynaptic one. So, a spike can
participate neither in two depression pairs nor in two potentiation pairs.
 
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 relies on an additional variable - the postsynaptic
eligibility trace :footcite:p:`Morrison2008` (implemented on the postsynaptic neuron side). It
decays exponentially with the time constant ``tau_minus`` and increases to 1 on
a post-spike occurrence (instead of increasing by 1 as in ``stdp_synapse``).
 
.. 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_restr_synapse
 
EndUserDocs */
 
// connections are templates of target identifier type (used for pointer /
// target index addressing) derived from generic connection template
 
void register_stdp_nn_restr_synapse( const std::string& name );
 
template < typename targetidentifierT >
class stdp_nn_restr_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_restr_synapse();
 
 
  stdp_nn_restr_synapse( const stdp_nn_restr_synapse& ) = default;
  stdp_nn_restr_synapse& operator=( const stdp_nn_restr_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 t_lastspike_;
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties stdp_nn_restr_synapse< targetidentifierT >::properties;
 
template < typename targetidentifierT >
inline bool
stdp_nn_restr_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 )
  {
    double minus_dt;
 
    // facilitation due to the first postsynaptic spike start->t_
    // since the previous pre-synaptic spike t_lastspike_
    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_, std::exp( minus_dt / tau_plus_ ) );
  }
 
  // depression due to the latest postsynaptic spike finish->t_
  // before the current pre-synaptic spike t_spike
  if ( start != finish )
  {
    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,  // discard Kminus
      nearest_neighbor_Kminus,
      value_to_throw_away  // discard Kminus_triplet
    );
    weight_ = depress_( weight_, nearest_neighbor_Kminus );
  }
 
  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_restr_synapse< targetidentifierT >::stdp_nn_restr_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 )
  , t_lastspike_( 0.0 )
{
}
 
template < typename targetidentifierT >
void
stdp_nn_restr_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::size_of ] = static_cast< long >( sizeof( *this ) );
}
 
template < typename targetidentifierT >
void
stdp_nn_restr_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_ );
 
  // check if weight_ and Wmax_ have the same sign
  if ( ( ( weight_ >= 0 ) - ( weight_ < 0 ) ) != ( ( Wmax_ >= 0 ) - ( Wmax_ < 0 ) ) )
  {
    throw BadProperty( "Weight and Wmax must have same sign." );
  }
}
 
}  // of namespace nest
 
#endif  // of #ifndef STDP_NN_RESTR_SYNAPSE_H