stdp_triplet_synapse.h

Go to the documentation of this file.

/*
 *  stdp_triplet_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_TRIPLET_SYNAPSE_H
#define STDP_TRIPLET_SYNAPSE_H
 
// C-header for math.h since copysign() is in C99 but not C++98
#include "connection.h"
#include <math.h>
 
namespace nest
{
 
/* BeginUserDocs: synapse, chemical, functional, stdp
 
Short description
+++++++++++++++++
 
Synapse type with spike-timing dependent plasticity (triplets)
 
Description
+++++++++++
 
``stdp_triplet_synapse`` is a connection with spike time dependent
plasticity accounting for spike triplet effects (as defined in :footcite:p:`Pfister2006`).
 
Notes:
 
- Presynaptic traces ``r_1`` and ``r_2`` of :footcite:p:`Pfister2006` are stored in the connection as
  ``Kplus`` and ``Kplus_triplet`` and decay with time-constants ``tau_plus`` and
  ``tau_plus_triplet``, respectively.
- Postsynaptic traces ``o_1`` and ``o_2`` of :footcite:p:`Pfister2006` are acquired from the postsynaptic
  neuron states ``Kminus_`` and ``triplet_Kminus_`` which decay on time-constants
  ``tau_minus`` and ``tau_minus_triplet``, respectively. These two time-constants
  can be set as properties of the postsynaptic neuron.
- This version implements the 'all-to-all' spike interaction of :footcite:p:`Pfister2006`. The
  'nearest-spike' interaction of :footcite:p:`Pfister2006` can currently not be implemented
  without changing the postsynaptic archiving-node (clip the traces to a
  maximum of 1).
 
.. 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          real    Time constant of short presynaptic trace
                           (tau_plus of :footcite:p:`Pfister2006`)
 tau_plus_triplet  real    Time constant of long presynaptic trace
                           (tau_x of :footcite:p:`Pfister2006`)
 Aplus             real    Weight of pair potentiation rule
                           (A_plus_2 of :footcite:p:`Pfister2006`)
 Aplus_triplet     real    Weight of triplet potentiation rule
                           (A_plus_3 of :footcite:p:`Pfister2006`)
 Aminus            real    Weight of pair depression rule
                           (A_minus_2 of :footcite:p:`Pfister2006`)
 Aminus_triplet    real    Weight of triplet depression rule
                           (A_minus_3 of :footcite:p:`Pfister2006`)
 Wmax              real    Maximum allowed weight
=================  ======  ===========================================
 
=============== ======  ===========================================
**States**
-------------------------------------------------------------------
 Kplus          real    Pre-synaptic trace (r_1 of :footcite:p:`Pfister2006`)
 Kplus_triplet  real    Triplet pre-synaptic trace (r_2 of :footcite:p:`Pfister2006`)
=============== ======  ===========================================
 
Transmits
+++++++++
 
SpikeEvent
 
References
++++++++++
 
.. footbibliography::
 
See also
++++++++
 
stdp_triplet_synapse_hpc, stdp_synapse, static_synapse
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: stdp_triplet_synapse
 
 
EndUserDocs */
 
// connections are templates of target identifier type
// (used for pointer / target index addressing)
// derived from generic connection template
 
void register_stdp_triplet_synapse( const std::string& name );
 
template < typename targetidentifierT >
class stdp_triplet_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_triplet_synapse();
 
  stdp_triplet_synapse( const stdp_triplet_synapse& ) = default;
  stdp_triplet_synapse& operator=( const stdp_triplet_synapse& ) = default;
 
  ~stdp_triplet_synapse()
  {
  }
 
  // 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;
    }
  };
 
  /*
   * This function calls check_connection on the sender and checks if the
   * receiver accepts the event type and receptor type requested by the sender.
   * Node::check_connection() will either confirm the receiver port by returning
   * true or false if the connection should be ignored.
   * We have to override the base class' implementation, since for STDP
   * connections we have to call register_stdp_connection on the target neuron
   * to inform the Archiver to collect spikes for this connection.
   *
   * \param s The source node
   * \param r The target node
   * \param receptor_type The ID of the requested receptor type
   */
  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:
  inline double
  facilitate_( double w, double kplus, double ky )
  {
    double new_w = std::abs( w ) + kplus * ( Aplus_ + Aplus_triplet_ * ky );
    return copysign( new_w < std::abs( Wmax_ ) ? new_w : Wmax_, Wmax_ );
  }
 
  inline double
  depress_( double w, double kminus, double Kplus_triplet_ )
  {
    double new_w = std::abs( w ) - kminus * ( Aminus_ + Aminus_triplet_ * Kplus_triplet_ );
    return copysign( new_w > 0.0 ? new_w : 0.0, Wmax_ );
  }
 
  // data members of each connection
  double weight_;
  double tau_plus_;
  double tau_plus_triplet_;
  double Aplus_;
  double Aminus_;
  double Aplus_triplet_;
  double Aminus_triplet_;
  double Kplus_;
  double Kplus_triplet_;
  double Wmax_;
  double t_lastspike_;
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties stdp_triplet_synapse< targetidentifierT >::properties;
 
template < typename targetidentifierT >
inline bool
stdp_triplet_synapse< targetidentifierT >::send( Event& e, size_t t, const CommonSynapseProperties& )
{
  double t_spike = e.get_stamp().get_ms();
  double dendritic_delay = get_delay();
  Node* target = get_target( t );
 
  // get spike history in relevant range (t1, t2] from postsynaptic neuron
  std::deque< histentry >::iterator start;
  std::deque< histentry >::iterator finish;
  target->get_history( t_lastspike_ - dendritic_delay, t_spike - dendritic_delay, &start, &finish );
 
  // facilitation due to postsynaptic spikes since last pre-synaptic spike
  while ( start != finish )
  {
    // postsynaptic spike is delayed by dendritic_delay so that
    // it is effectively late by that much at the synapse.
    double minus_dt = t_lastspike_ - ( start->t_ + dendritic_delay );
 
    // subtract 1.0 yields the Kminus_triplet value just prior to
    // the postsynaptic spike, implementing the t-epsilon in
    // Pfister et al, 2006
    double ky = start->Kminus_triplet_ - 1.0;
    ++start;
    // 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_ ), ky );
  }
 
  // depression due to new pre-synaptic spike
  Kplus_triplet_ *= std::exp( ( t_lastspike_ - t_spike ) / tau_plus_triplet_ );
 
  // dendritic delay means we must look back in time by that amount
  // for determining the K value, because the K value must propagate
  // out to the synapse
  weight_ = depress_( weight_, target->get_K_value( t_spike - dendritic_delay ), Kplus_triplet_ );
 
  Kplus_triplet_ += 1.0;
  Kplus_ = Kplus_ * std::exp( ( t_lastspike_ - t_spike ) / tau_plus_ ) + 1.0;
 
  e.set_receiver( *target );
  e.set_weight( weight_ );
  e.set_delay_steps( get_delay_steps() );
  e.set_rport( get_rport() );
  e();
 
  t_lastspike_ = t_spike;
 
  return true;
}
 
// Defaults come from Pfister & Gerstner (2006) data fitting and table 3.
template < typename targetidentifierT >
stdp_triplet_synapse< targetidentifierT >::stdp_triplet_synapse()
  : ConnectionBase()
  , weight_( 1.0 )
  , tau_plus_( 16.8 )
  , tau_plus_triplet_( 101.0 )
  , Aplus_( 5e-10 )
  , Aminus_( 7e-3 )
  , Aplus_triplet_( 6.2e-3 )
  , Aminus_triplet_( 2.3e-4 )
  , Kplus_( 0.0 )
  , Kplus_triplet_( 0.0 )
  , Wmax_( 100.0 )
  , t_lastspike_( 0.0 )
{
}
 
template < typename targetidentifierT >
void
stdp_triplet_synapse< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
  d[ names::tau_plus ] = tau_plus_;
  d[ names::tau_plus_triplet ] = tau_plus_triplet_;
  d[ names::Aplus ] = Aplus_;
  d[ names::Aminus ] = Aminus_;
  d[ names::Aplus_triplet ] = Aplus_triplet_;
  d[ names::Aminus_triplet ] = Aminus_triplet_;
  d[ names::Kplus ] = Kplus_;
  d[ names::Kplus_triplet ] = Kplus_triplet_;
  d[ names::Wmax ] = Wmax_;
}
 
template < typename targetidentifierT >
void
stdp_triplet_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::tau_plus_triplet, tau_plus_triplet_ );
  d.update_value( names::Aplus, Aplus_ );
  d.update_value( names::Aminus, Aminus_ );
  d.update_value( names::Aplus_triplet, Aplus_triplet_ );
  d.update_value( names::Aminus_triplet, Aminus_triplet_ );
  d.update_value( names::Kplus, Kplus_ );
  d.update_value( names::Kplus_triplet, Kplus_triplet_ );
  d.update_value( names::Wmax, Wmax_ );
 
  // check if weight_ and Wmax_ has the same sign
  if ( not( ( ( weight_ >= 0 ) - ( weight_ < 0 ) ) == ( ( Wmax_ >= 0 ) - ( Wmax_ < 0 ) ) ) )
  {
    throw BadProperty( "Weight and Wmax must have same sign." );
  }
 
  if ( not( Kplus_ >= 0 ) )
  {
    throw BadProperty( "State Kplus must be positive." );
  }
 
  if ( Kplus_triplet_ < 0 )
  {
    throw BadProperty( "State Kplus_triplet must be positive." );
  }
}
 
}  // of namespace nest
 
#endif  // of #ifndef STDP_TRIPLET_SYNAPSE_H