tsodyks_synapse.h

Go to the documentation of this file.

/*
 *  tsodyks_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 TSODYKS_SYNAPSE_H
#define TSODYKS_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:`Tsodyks2000`. In particular it solves Eqs (3) and (4) from
this paper in an exact manner.
 
Synaptic depression is motivated by depletion of vesicles in the readily
releasable pool of synaptic vesicles (variable x in equation (3)). Synaptic
facilitation comes about by a presynaptic increase of release probability,
which is modeled by variable U in Eq (4).
 
The original interpretation of variable y is the amount of glutamate
concentration in the synaptic cleft. In :footcite:p:`Tsodyks2000` this variable is taken to be
directly proportional to the synaptic current caused in the postsynaptic
neuron (with the synaptic weight w as a proportionality constant). In order
to reproduce the results of :footcite:p:`Tsodyks2000` and to use this model of synaptic plasticity
in its original sense, the user therefore has to ensure the following
conditions:
 
1.) The postsynaptic neuron must be of type ``iaf_psc_exp`` or ``iaf_psc_exp_htum``,
because these neuron models have a postsynaptic current which decays
exponentially.
 
2.) The time constant of each ``tsodyks_synapse`` targeting a particular neuron
must be chosen equal to that neuron's synaptic time constant. In particular
that means that all synapses targeting a particular neuron have the same
parameter ``tau_psc``.
 
However, there are no technical restrictions using this model of synaptic
plasticity also in conjunction with neuron models that have a different
dynamics for their synaptic current or conductance. The effective synaptic
weight, which will be transmitted to the postsynaptic neuron upon occurrence
of a spike at time t is :math:`u(t) \cdot x(t) \cdot w`, where ``u(t)`` and ``x(t)``
are defined in Eq (3) and (4), w is the synaptic weight specified upon connection.
The interpretation is as follows: The quantity :math:`u(t) \cdot x(t)` is the release
probability times the amount of releasable synaptic vesicles at time t of the
presynaptic neuron's spike, so this equals the amount of transmitter expelled
into the synaptic cleft.
 
The amount of transmitter then relaxes back to 0 with time constant tau_psc
of the synapse's variable y. Since the dynamics of ``y(t)`` is linear, the
postsynaptic neuron can reconstruct from the amplitude of the synaptic
impulse :math:`u(t) \cdot x(t) \cdot w` the full shape of ``y(t)``. The postsynaptic
neuron, however, might choose to have a synaptic current that is not necessarily
identical to the concentration of transmitter ``y(t)`` in the synaptic cleft. It may
realize an arbitrary postsynaptic effect depending on ``y(t)``.
 
.. 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
++++++++++
 
The following parameters can be set in the status dictionary:
 
========  ======  ========================================================
 U        real    Parameter determining the increase in u with each spike
                  [0,1]
 tau_psc  ms      Time constant of synaptic current
 tau_fac  ms      Time constant for facilitation
 tau_rec  ms      Time constant for depression
 x        real    Initial fraction of synaptic vesicles in the readily
                  releasable pool [0,1]
 y        real    Initial fraction of synaptic vesicles in the synaptic
                  cleft [0,1]
 u        real    Initial release probability of synaptic vesicles [0,1]
========  ======  ========================================================
 
References
++++++++++
 
.. footbibliography::
 
Transmits
+++++++++
 
SpikeEvent
 
See also
++++++++
 
iaf_tum_2000, stdp_synapse, static_synapse, iaf_psc_exp
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: tsodyks_synapse
 
EndUserDocs */
 
void register_tsodyks_synapse( const std::string& name );
 
template < typename targetidentifierT >
class tsodyks_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;
 
  tsodyks_synapse();
 
  tsodyks_synapse( const tsodyks_synapse& ) = default;
  tsodyks_synapse& operator=( const tsodyks_synapse& ) = default;
 
  ~tsodyks_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 tau_psc_;      
  double tau_fac_;      
  double tau_rec_;      
  double U_;            
  double x_;            
  double y_;            
  double u_;            
  double t_lastspike_;  
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties tsodyks_synapse< targetidentifierT >::properties;
 
template < typename targetidentifierT >
inline bool
tsodyks_synapse< targetidentifierT >::send( Event& e, size_t t, const CommonSynapseProperties& )
{
  const double t_spike = e.get_stamp().get_ms();
  const double h = t_spike - t_lastspike_;
 
  Node* target = get_target( t );
 
 
  // t_lastspike_ = 0 initially
  // this has no influence on the dynamics, IF y = z = 0 initially
  // !!! x != 1.0 -> z != 0.0 -> t_lastspike_=0 has influence on dynamics
 
  // propagator
  double Puu = ( tau_fac_ == 0.0 ) ? 0.0 : std::exp( -h / tau_fac_ );
  double Pyy = std::exp( -h / tau_psc_ );
  double Pzz = std::expm1( -h / tau_rec_ );
  double Pxy = ( Pzz * tau_rec_ - ( Pyy - 1.0 ) * tau_psc_ ) / ( tau_psc_ - tau_rec_ );
 
  double z = 1.0 - x_ - y_;
 
  // propagation t_lastspike_ -> t_spike
  // don't change the order !
 
  u_ *= Puu;
  x_ += Pxy * y_ - Pzz * z;
  y_ *= Pyy;
 
  // delta function u
  u_ += U_ * ( 1.0 - u_ );
 
  // postsynaptic current step caused by incoming spike
  double delta_y_tsp = u_ * x_;
 
  // delta function x, y
  x_ -= delta_y_tsp;
  y_ += delta_y_tsp;
 
 
  e.set_receiver( *target );
  e.set_weight( delta_y_tsp * weight_ );
  e.set_delay_steps( get_delay_steps() );
  e.set_rport( get_rport() );
  e();
 
  t_lastspike_ = t_spike;
 
  return true;
}
 
template < typename targetidentifierT >
tsodyks_synapse< targetidentifierT >::tsodyks_synapse()
  : ConnectionBase()
  , weight_( 1.0 )
  , tau_psc_( 3.0 )
  , tau_fac_( 0.0 )
  , tau_rec_( 800.0 )
  , U_( 0.5 )
  , x_( 1.0 )
  , y_( 0.0 )
  , u_( 0.0 )
  , t_lastspike_( 0.0 )
{
}
 
template < typename targetidentifierT >
void
tsodyks_synapse< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
  d[ names::U ] = U_;
  d[ names::tau_psc ] = tau_psc_;
  d[ names::tau_rec ] = tau_rec_;
  d[ names::tau_fac ] = tau_fac_;
  d[ names::x ] = x_;
  d[ names::y ] = y_;
  d[ names::u ] = u_;
  d[ names::size_of ] = static_cast< long >( sizeof( *this ) );
}
 
template < typename targetidentifierT >
void
tsodyks_synapse< targetidentifierT >::set_status( const Dictionary& d, ConnectorModel& cm )
{
  // Handle parameters that may throw an exception first, so we can leave the
  // synapse untouched
  // in case of invalid parameter values
  double x = x_;
  double y = y_;
  d.update_value( names::x, x );
  d.update_value( names::y, y );
 
  if ( x + y > 1.0 )
  {
    throw BadProperty( "x + y must be <= 1.0." );
  }
 
  x_ = x;
  y_ = y;
 
  ConnectionBase::set_status( d, cm );
  d.update_value( names::weight, weight_ );
 
  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_psc, tau_psc_ );
  if ( tau_psc_ <= 0.0 )
  {
    throw BadProperty( "'tau_psc' must be > 0." );
  }
 
  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::u, u_ );
  if ( u_ > 1.0 or u_ < 0.0 )
  {
    throw BadProperty( "'u' must be in [0,1]." );
  }
}
 
}  // namespace
 
#endif  // TSODYKS_SYNAPSE_H