eprop_synapse_bsshslm_2020.h

Go to the documentation of this file.

/*
 *  eprop_synapse_bsshslm_2020.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 EPROP_SYNAPSE_BSSHSLM_2020_H
#define EPROP_SYNAPSE_BSSHSLM_2020_H
 
// nestkernel
#include "connection.h"
#include "connector_base.h"
#include "eprop_archiving_node.h"
#include "target_identifier.h"
#include "weight_optimizer.h"
 
namespace nest
{
 
/* BeginUserDocs: synapse, abstract, learning, Bellec, e-prop plasticity, 3-factor
 
Short description
+++++++++++++++++
 
Synapse type for e-prop plasticity
 
Description
+++++++++++
 
``eprop_synapse_bsshslm_2020`` is an implementation of a connector model to create synapses between postsynaptic
neurons :math:`j` and presynaptic neurons :math:`i` for eligibility propagation (e-prop) plasticity.
 
E-prop plasticity was originally introduced and implemented in TensorFlow in :footcite:p:`Bellec2020`.
 
The suffix ``_bsshslm_2020`` follows the NEST convention to indicate in the
model name the paper that introduced it by the first letter of the authors' last
names and the publication year.
 
The e-prop synapse collects the presynaptic spikes needed for calculating the
weight update. When it is time to update, it triggers the calculation of the
gradient which is specific to the post-synaptic neuron and is thus defined there.
 
Eventually, it optimizes the weight with the specified optimizer.
 
E-prop synapses require archiving of continuous quantities. Therefore e-prop
synapses can only be connected to neuron models that are capable of
archiving. So far, compatible models are ``eprop_iaf_bsshslm_2020``,
``eprop_iaf_adapt_bsshslm_2020``, and ``eprop_readout_bsshslm_2020``.
 
For more information, see the following topics:
 
* other e-prop plasticity models:
 
      * :doc:`eprop_iaf_bsshslm_2020<../models/eprop_iaf_bsshslm_2020/>`
      * :doc:`eprop_iaf_adapt_bsshslm_2020<../models/eprop_iaf_adapt_bsshslm_2020/>`
      * :doc:`eprop_readout_bsshslm_2020<../models/eprop_readout_bsshslm_2020/>`
      * :doc:`eprop_learning_signal_connection_bsshslm_2020<../models/eprop_learning_signal_connection_bsshslm_2020/>`
 
* :doc:`weight optimizer<../models/weight_optimizer/>`
* triggering synaptic plasticity computations to reduce memory usage via the
  :ref:`flush event mechanism<flush_event_mechanism>`
 
Details on the event-based NEST implementation of e-prop can be found in :footcite:p:`KorcsakGorzo2025`.
 
.. 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.
 
==================== ======= =============== ========= ======================================================
**Common e-prop synapse parameters**
-------------------------------------------------------------------------------------------------------------
Parameter            Unit    Math equivalent Default   Description
==================== ======= =============== ========= ======================================================
``average_gradient`` Boolean                 ``False`` If ``True``, average the gradient over the learning
                                                       window
``optimizer``                                     {}   Dictionary of optimizer parameters
==================== ======= =============== ========= ======================================================
 
============= ==== ========================= ======= ================================
**Individual synapse parameters**
-------------------------------------------------------------------------------------
Parameter     Unit Math equivalent           Default Description
============= ==== ========================= ======= ================================
``delay``     ms   :math:`d_{ji}`                1.0 Dendritic delay
``weight``    pA   :math:`W_{ji}`                1.0 Initial value of synaptic weight
============= ==== ========================= ======= ================================
 
================= ==== ========================= ======= ==============================
**Individual e-prop synapse parameters**
---------------------------------------------------------------------------------------
Parameter         Unit Math equivalent           Default Description
================= ==== ========================= ======= ==============================
``tau_m_readout`` ms   :math:`\tau_\text{m,out}`    10.0 Time constant for low-pass
                                                         filtering of eligibility trace
================= ==== ========================= ======= ==============================
 
Recordables
+++++++++++
 
The following variables can be recorded.
 
================== ==== =============== ============= ===============
**Synapse recordables**
---------------------------------------------------------------------
State variable     Unit Math equivalent Initial value Description
================== ==== =============== ============= ===============
``weight``         pA   :math:`B_{jk}`            1.0 Synaptic weight
================== ==== =============== ============= ===============
 
Usage
+++++
 
This model can only be used in combination with the other e-prop models
and the network architecture requires specific wiring, input, and output.
The usage is demonstrated in several
:doc:`supervised regression and classification tasks <../auto_examples/eprop_plasticity/index>`
reproducing among others the original proof-of-concept tasks in :footcite:p:`Bellec2020`.
 
Transmits
+++++++++
 
SpikeEvent, DSSpikeEvent
 
References
++++++++++
 
.. footbibliography::
 
See also
++++++++
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: eprop_synapse_bsshslm_2020
 
EndUserDocs */
 
class EpropSynapseBSSHSLM2020CommonProperties : public CommonSynapseProperties
{
public:
  // Default constructor.
  EpropSynapseBSSHSLM2020CommonProperties();
 
  EpropSynapseBSSHSLM2020CommonProperties( const EpropSynapseBSSHSLM2020CommonProperties& );
 
  EpropSynapseBSSHSLM2020CommonProperties& operator=( const EpropSynapseBSSHSLM2020CommonProperties& ) = delete;
 
  ~EpropSynapseBSSHSLM2020CommonProperties();
 
  void get_status( Dictionary& d ) const;
 
  void set_status( const Dictionary& d, ConnectorModel& cm );
 
  bool average_gradient_;
 
  WeightOptimizerCommonProperties* optimizer_cp_;
};
 
void register_eprop_synapse_bsshslm_2020( const std::string& name );
 
template < typename targetidentifierT >
class eprop_synapse_bsshslm_2020 : public Connection< targetidentifierT >
{
 
public:
  typedef EpropSynapseBSSHSLM2020CommonProperties CommonPropertiesType;
 
  typedef Connection< targetidentifierT > ConnectionBase;
 
  static constexpr bool supports_flush_event = true;
 
  static constexpr ConnectionModelProperties properties = ConnectionModelProperties::HAS_DELAY
    | ConnectionModelProperties::IS_PRIMARY | ConnectionModelProperties::REQUIRES_EPROP_ARCHIVING
    | ConnectionModelProperties::SUPPORTS_HPC;
 
  eprop_synapse_bsshslm_2020();
 
  ~eprop_synapse_bsshslm_2020();
 
  eprop_synapse_bsshslm_2020( const eprop_synapse_bsshslm_2020& );
 
  eprop_synapse_bsshslm_2020& operator=( const eprop_synapse_bsshslm_2020& );
 
  eprop_synapse_bsshslm_2020( eprop_synapse_bsshslm_2020&& );
 
  eprop_synapse_bsshslm_2020& operator=( eprop_synapse_bsshslm_2020&& );
 
  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 thread, const EpropSynapseBSSHSLM2020CommonProperties& cp );
 
  class ConnTestDummyNode : public ConnTestDummyNodeBase
  {
  public:
    using ConnTestDummyNodeBase::handles_test_event;
 
    size_t
    handles_test_event( SpikeEvent&, size_t )
    {
      return invalid_port;
    }
 
    size_t
    handles_test_event( DSSpikeEvent&, size_t )
    {
      return invalid_port;
    }
  };
 
  void check_connection( Node& s, Node& t, size_t receptor_type, const CommonPropertiesType& cp );
 
  void
  set_weight( const double w )
  {
    weight_ = w;
  }
 
  void delete_optimizer();
 
private:
  double weight_;
 
  double gradient_;
 
  long t_spike_previous_;
 
  bool previous_was_flush_event_;
 
  long t_previous_update_;
 
  long t_next_update_;
 
  long t_previous_trigger_spike_;
 
  double tau_m_readout_;
 
  double kappa_;
 
  bool is_recurrent_to_recurrent_conn_;
 
  std::vector< long > presyn_isis_;
 
  WeightOptimizer* optimizer_;
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties eprop_synapse_bsshslm_2020< targetidentifierT >::properties;
 
// Explicitly declare specializations of Connector methods that need to do special things for eprop_synapse_bsshslm_2020
template <>
void Connector< eprop_synapse_bsshslm_2020< TargetIdentifierPtrRport > >::disable_connection( const size_t lcid );
 
template <>
void Connector< eprop_synapse_bsshslm_2020< TargetIdentifierIndex > >::disable_connection( const size_t lcid );
 
template <>
Connector< eprop_synapse_bsshslm_2020< TargetIdentifierPtrRport > >::~Connector();
 
template <>
Connector< eprop_synapse_bsshslm_2020< TargetIdentifierIndex > >::~Connector();
 
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >::eprop_synapse_bsshslm_2020()
  : ConnectionBase()
  , weight_( 1.0 )
  , gradient_( 0.0 )
  , t_spike_previous_( 0 )
  , previous_was_flush_event_( false )
  , t_previous_update_( 0 )
  , t_next_update_( 0 )
  , t_previous_trigger_spike_( 0 )
  , tau_m_readout_( 10.0 )
  , kappa_( std::exp( -Time::get_resolution().get_ms() / tau_m_readout_ ) )
  , is_recurrent_to_recurrent_conn_( false )
  , optimizer_( nullptr )
{
}
 
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >::~eprop_synapse_bsshslm_2020()
{
}
 
// This copy constructor is used to create instances from prototypes.
// Therefore, only parameter values are copied.
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >::eprop_synapse_bsshslm_2020( const eprop_synapse_bsshslm_2020& es )
  : ConnectionBase( es )
  , weight_( es.weight_ )
  , gradient_( es.gradient_ )
  , t_spike_previous_( 0 )
  , previous_was_flush_event_( false )
  , t_previous_update_( 0 )
  , t_next_update_( kernel().simulation_manager.get_eprop_update_interval().get_steps() )
  , t_previous_trigger_spike_( 0 )
  , tau_m_readout_( es.tau_m_readout_ )
  , kappa_( std::exp( -Time::get_resolution().get_ms() / tau_m_readout_ ) )
  , is_recurrent_to_recurrent_conn_( es.is_recurrent_to_recurrent_conn_ )
  , optimizer_( es.optimizer_ )
{
}
 
// This copy assignment operator is used to write a connection into the connection array.
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >&
eprop_synapse_bsshslm_2020< targetidentifierT >::operator=( const eprop_synapse_bsshslm_2020& es )
{
  if ( this == &es )
  {
    return *this;
  }
 
  ConnectionBase::operator=( es );
 
  weight_ = es.weight_;
  gradient_ = es.gradient_;
  t_spike_previous_ = es.t_spike_previous_;
  previous_was_flush_event_ = es.previous_was_flush_event_;
  t_previous_update_ = es.t_previous_update_;
  t_next_update_ = es.t_next_update_;
  t_previous_trigger_spike_ = es.t_previous_trigger_spike_;
  tau_m_readout_ = es.tau_m_readout_;
  kappa_ = es.kappa_;
  is_recurrent_to_recurrent_conn_ = es.is_recurrent_to_recurrent_conn_;
  optimizer_ = es.optimizer_;
 
  return *this;
}
 
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >::eprop_synapse_bsshslm_2020( eprop_synapse_bsshslm_2020&& es )
  : ConnectionBase( es )
  , weight_( es.weight_ )
  , gradient_( es.gradient_ )
  , t_spike_previous_( 0 )
  , previous_was_flush_event_( false )
  , t_previous_update_( 0 )
  , t_next_update_( es.t_next_update_ )
  , t_previous_trigger_spike_( 0 )
  , tau_m_readout_( es.tau_m_readout_ )
  , kappa_( es.kappa_ )
  , is_recurrent_to_recurrent_conn_( es.is_recurrent_to_recurrent_conn_ )
  , optimizer_( es.optimizer_ )
{
  es.optimizer_ = nullptr;
}
 
// This move assignment operator is used to write a connection into the connection array.
template < typename targetidentifierT >
eprop_synapse_bsshslm_2020< targetidentifierT >&
eprop_synapse_bsshslm_2020< targetidentifierT >::operator=( eprop_synapse_bsshslm_2020&& es )
{
  if ( this == &es )
  {
    return *this;
  }
 
  ConnectionBase::operator=( es );
 
  weight_ = es.weight_;
  gradient_ = es.gradient_;
  t_spike_previous_ = es.t_spike_previous_;
  previous_was_flush_event_ = es.previous_was_flush_event_;
  t_previous_update_ = es.t_previous_update_;
  t_next_update_ = es.t_next_update_;
  t_previous_trigger_spike_ = es.t_previous_trigger_spike_;
  tau_m_readout_ = es.tau_m_readout_;
  kappa_ = es.kappa_;
  is_recurrent_to_recurrent_conn_ = es.is_recurrent_to_recurrent_conn_;
 
  optimizer_ = es.optimizer_;
  es.optimizer_ = nullptr;
 
  return *this;
}
 
template < typename targetidentifierT >
inline void
eprop_synapse_bsshslm_2020< targetidentifierT >::check_connection( Node& s,
  Node& t,
  size_t receptor_type,
  const CommonPropertiesType& cp )
{
  // When we get here, delay has been set so we can check it.
  if ( get_delay_steps() != 1 )
  {
    throw IllegalConnection( "eprop synapses currently require a delay of one simulation step" );
  }
 
  ConnTestDummyNode dummy_target;
  ConnectionBase::check_connection_( dummy_target, s, t, receptor_type );
 
  t.register_eprop_connection();
  t.initialize_update_history();
 
  optimizer_ = cp.optimizer_cp_->get_optimizer();
}
 
template < typename targetidentifierT >
inline void
eprop_synapse_bsshslm_2020< targetidentifierT >::delete_optimizer()
{
  delete optimizer_;
  // do not set to nullptr to allow detection of double deletion
}
 
template < typename targetidentifierT >
bool
eprop_synapse_bsshslm_2020< targetidentifierT >::send( Event& e,
  size_t thread,
  const EpropSynapseBSSHSLM2020CommonProperties& cp )
{
  Node* target = get_target( thread );
  assert( target );
 
  const long t_spike = e.get_stamp().get_steps();
  const bool is_flush_event = e.is_flush_event();
 
  if ( previous_was_flush_event_ )
  {
    if ( is_flush_event )
    {
      return false;
    }
 
    t_spike_previous_ = t_spike;
    t_previous_trigger_spike_ = t_spike;
  }
 
  const long update_interval = kernel().simulation_manager.get_eprop_update_interval().get_steps();
  const long shift = target->get_shift();
 
  const long interval_step = ( t_spike - shift ) % update_interval;
 
  if ( target->is_eprop_recurrent_node() and interval_step == 0 )
  {
    return false;
  }
 
  if ( t_previous_trigger_spike_ == 0 )
  {
    t_previous_trigger_spike_ = t_spike;
  }
 
  if ( t_spike_previous_ > 0 )
  {
    const long presyn_isi =
      std::min( t_spike, t_next_update_ + shift ) - std::min( t_spike_previous_, t_next_update_ + shift );
 
    if ( presyn_isi > 0 )
    {
      presyn_isis_.push_back( presyn_isi );
    }
  }
 
  if ( t_spike > t_next_update_ + shift )
  {
    const long idx_current_update = ( t_spike - shift ) / update_interval;
    const long t_current_update = idx_current_update * update_interval;
 
    target->write_update_to_history( t_previous_update_, t_current_update, is_flush_event, previous_was_flush_event_ );
 
    if ( not presyn_isis_.empty() and t_spike_previous_ > 0 )
    {
      gradient_ += target->compute_gradient(
        presyn_isis_, t_previous_update_, t_previous_trigger_spike_, kappa_, cp.average_gradient_ );
    }
 
    if ( not is_flush_event )
    {
      weight_ = optimizer_->optimized_weight( *cp.optimizer_cp_, idx_current_update, gradient_, weight_ );
      gradient_ = 0.0;
    }
 
    t_previous_update_ = t_current_update;
    t_next_update_ = t_current_update + update_interval;
 
    t_previous_trigger_spike_ = t_spike;
  }
  else
  {
    if ( not is_flush_event and previous_was_flush_event_ )
    {
      const long idx_current_update = ( t_spike - shift ) / update_interval;
      const long t_current_update = idx_current_update * update_interval;
 
      target->write_update_to_history(
        t_previous_update_, t_current_update, is_flush_event, previous_was_flush_event_ );
 
      weight_ = optimizer_->optimized_weight( *cp.optimizer_cp_, idx_current_update, gradient_, weight_ );
      gradient_ = 0.0;
    }
  }
 
  if ( not is_flush_event )
  {
    t_spike_previous_ = t_spike;
 
    e.set_receiver( *target );
    e.set_weight( weight_ );
    e.set_delay_steps( get_delay_steps() );
    e.set_rport( get_rport() );
    e();
  }
 
  previous_was_flush_event_ = is_flush_event;
 
  return true;
}
 
template < typename targetidentifierT >
void
eprop_synapse_bsshslm_2020< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
  d[ names::tau_m_readout ] = tau_m_readout_;
  d[ names::size_of ] = static_cast< long >( sizeof( *this ) );
 
  Dictionary optimizer_dict;
 
  // The default_connection_ has no optimizer, therefore we need to protect it
  if ( optimizer_ )
  {
    optimizer_->get_status( optimizer_dict );
    d[ names::optimizer ] = optimizer_dict;
  }
}
 
template < typename targetidentifierT >
void
eprop_synapse_bsshslm_2020< targetidentifierT >::set_status( const Dictionary& d, ConnectorModel& cm )
{
  ConnectionBase::set_status( d, cm );
  if ( d.known( names::optimizer ) and optimizer_ )
  {
    // We must pass here if called by SetDefaults. In that case, the user will get an error
    // message because the parameters for the synapse-specific optimizer have not been accessed.
    optimizer_->set_status( d.get< Dictionary >( names::optimizer ) );
  }
 
  d.update_value( names::weight, weight_ );
 
  if ( d.update_value( names::tau_m_readout, tau_m_readout_ ) )
  {
    if ( tau_m_readout_ <= 0 )
    {
      throw BadProperty( "Membrane time constant of readout neuron tau_m_readout > 0 required." );
    }
    kappa_ = std::exp( -Time::get_resolution().get_ms() / tau_m_readout_ );
  }
 
  const auto& gcm =
    dynamic_cast< const GenericConnectorModel< eprop_synapse_bsshslm_2020< targetidentifierT > >& >( cm );
  const CommonPropertiesType& epcp = gcm.get_common_properties();
  if ( weight_ < epcp.optimizer_cp_->get_Wmin() )
  {
    throw BadProperty( "Minimal weight Wmin ≤ weight required." );
  }
 
  if ( weight_ > epcp.optimizer_cp_->get_Wmax() )
  {
    throw BadProperty( "weight ≤ maximal weight Wmax required." );
  }
}
 
}  // namespace nest
 
#endif  // EPROP_SYNAPSE_BSSHSLM_2020_H