tsodyks2_synapse.h

Go to the documentation of this file.

/*
 *  tsodyks2_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 TSODYKS2_SYNAPSE_H
#define TSODYKS2_SYNAPSE_H
 
// C++ includes:
#include <cmath>
 
// Includes from nestkernel:
#include "connection.h"
 
namespace nest
{
 
/* BeginUserDocs: synapse, chemical, functional, stp, Tsodyks
 
Short description
+++++++++++++++++
 
Synapse type with short term plasticity
 
Description
+++++++++++
 
This synapse model implements synaptic short-term depression and short-term
facilitation according to :footcite:p:`Tsodyks1997` and :footcite:p:`Fuhrmann2002`. It solves Eq (2) from
:footcite:p:`Tsodyks1997` and modulates U according to eq. (2) of :footcite:p:`Fuhrmann2002`.
 
This connection merely scales the synaptic weight, based on the spike history
and the parameters of the kinetic model. Thus, it is suitable for all types
of synaptic dynamics, that is current or conductance based.
 
The parameter ``A_se`` from the publications is represented by the
synaptic weight. The variable x in the synapse properties is the
factor that scales the synaptic weight.
 
Setting the parameter ``tau_fac`` to zero disables facilitation.
 
Please note that the initial value of ``u`` should be equal to the value of
``U``. Thus, when setting a new value for ``U`` before the start of the
simulation, make sure to set ``u`` to the same value.
 
.. 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.
 
See also :footcite:p:`Maass2002`.
 
Under identical conditions, the tsodyks2_synapse produces slightly
lower peak amplitudes than the tsodyks_synapse. However, the
qualitative behavior is identical. The script
:doc:`../auto_examples/evaluate_tsodyks2_synapse` compares the two
synapse models.
 
Parameters
++++++++++
 
The following parameters can be set in the status dictionary:
 
========  ======  ========================================================
 U        real    Parameter determining the increase in u with each spike
                  (U1) [0,1], default = 0.5
 u        real    The probability of release (U_se) [0,1],
                  default = U
 x        real    Current scaling factor of the weight, default = 1.0
 tau_fac  ms      Time constant for facilitation, default = 0 (off)
 tau_rec  ms      Time constant for depression, default = 800
========  ======  ========================================================
 
References
++++++++++
 
.. footbibliography::
 
Transmits
+++++++++
 
SpikeEvent
 
See also
++++++++
 
tsodyks_synapse, stdp_synapse, static_synapse
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: tsodyks2_synapse
 
EndUserDocs */
 
void register_tsodyks2_synapse( const std::string& name );
 
template < typename targetidentifierT >
class tsodyks2_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;
 
  tsodyks2_synapse();
 
  tsodyks2_synapse( const tsodyks2_synapse& ) = default;
  tsodyks2_synapse& operator=( const tsodyks2_synapse& ) = default;
 
  ~tsodyks2_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;
    }
  };
 
 
  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 );
  }
 
  void
  set_weight( double w )
  {
    weight_ = w;
  }
 
 
private:
  double weight_;
  double U_;            
  double u_;            
  double x_;            
  double tau_rec_;      
  double tau_fac_;      
  double t_lastspike_;  
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties tsodyks2_synapse< targetidentifierT >::properties;
 
template < typename targetidentifierT >
inline bool
tsodyks2_synapse< targetidentifierT >::send( Event& e, size_t t, const CommonSynapseProperties& )
{
  Node* target = get_target( t );
  const double t_spike = e.get_stamp().get_ms();
 
  if ( t_lastspike_ >= 0.0 )
  {
    // only update x and u if this is not the first spike to pass through the synapse
 
    const double h = t_spike - t_lastspike_;
    double x_decay = std::exp( -h / tau_rec_ );
    double u_decay = ( tau_fac_ == 0 ) ? 0.0 : std::exp( -h / tau_fac_ );  // tau_fac == 0 disables facilitation
 
    // now we compute spike number n+1
    x_ = 1. + ( x_ - x_ * u_ - 1. ) * x_decay;  // Eq. 5 from Maass & Markram (2002)
    u_ = U_ + u_ * ( 1. - U_ ) * u_decay;       // Eq. 4 from Maass & Markram (2002)
  }
 
  // We use the current values for the spike number n.
  e.set_receiver( *target );
  e.set_weight( x_ * u_ * weight_ );
  // send the spike to the target
  e.set_delay_steps( get_delay_steps() );
  e.set_rport( get_rport() );
  e();
 
  t_lastspike_ = t_spike;
 
  return true;
}
 
template < typename targetidentifierT >
tsodyks2_synapse< targetidentifierT >::tsodyks2_synapse()
  : ConnectionBase()
  , weight_( 1.0 )
  , U_( 0.5 )
  , u_( U_ )
  , x_( 1.0 )
  , tau_rec_( 800.0 )
  , tau_fac_( 0.0 )
  , t_lastspike_( -1.0 )
{
}
 
template < typename targetidentifierT >
void
tsodyks2_synapse< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
 
  d[ names::dU ] = U_;
  d[ names::u ] = u_;
  d[ names::tau_rec ] = tau_rec_;
  d[ names::tau_fac ] = tau_fac_;
  d[ names::x ] = x_;
  d[ names::size_of ] = static_cast< long >( sizeof( *this ) );
}
 
template < typename targetidentifierT >
void
tsodyks2_synapse< targetidentifierT >::set_status( const Dictionary& d, ConnectorModel& cm )
{
  ConnectionBase::set_status( d, cm );
  d.update_value( names::weight, weight_ );
 
  d.update_value( names::dU, U_ );
  if ( U_ > 1.0 or U_ < 0.0 )
  {
    throw BadProperty( "'U' must be in [0,1]." );
  }
 
  d.update_value( names::u, u_ );
  if ( u_ > 1.0 or u_ < 0.0 )
  {
    throw BadProperty( "'u' must be in [0,1]." );
  }
 
  d.update_value( names::tau_rec, tau_rec_ );
  if ( tau_rec_ <= 0.0 )
  {
    throw BadProperty( "'tau_rec' must be > 0." );
  }
 
  d.update_value( names::tau_fac, tau_fac_ );
  if ( tau_fac_ < 0.0 )
  {
    throw BadProperty( "'tau_fac' must be >= 0." );
  }
 
  d.update_value( names::x, x_ );
}
 
}  // namespace
 
#endif  // TSODYKS2_SYNAPSE_H