eprop_synapse.h

Go to the documentation of this file.

/*
 *  eprop_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 EPROP_SYNAPSE_H
#define EPROP_SYNAPSE_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`` is an implementation of a connector model to create synapses between postsynaptic
neurons :math:`j` and presynaptic neurons and :math:`i` for eligibility propagation (e-prop) plasticity.
 
E-prop plasticity was originally introduced and implemented in TensorFlow in :footcite:p:`Bellec2020`.
 
The e-prop synapse triggers the calculation of the gradient at each spike
over an interval that begins at the previous spike and ends at a cutoff specified by the user or the
current spike, depending on which of the two time points is earlier.
The gradient calculation is specific to the post-synaptic neuron and 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``, ``eprop_iaf_psc_delta``, ``eprop_iaf_psc_delta_adapt``,
``eprop_iaf_adapt``, and ``eprop_readout``.
 
For more information, see the following topics:
 
* other e-prop plasticity models:
 
      * :doc:`eprop_iaf<../models/eprop_iaf/>`
      * :doc:`eprop_iaf_adapt<../models/eprop_iaf_adapt/>`
      * :doc:`eprop_readout<../models/eprop_readout/>`
      * :doc:`eprop_learning_signal_connection<../models/eprop_learning_signal_connection/>`
 
* :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
================ ==== =============== ======= ======================================================
``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
============= ==== ========================= ======= =========================================================
 
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
 
EndUserDocs */
 
class EpropSynapseCommonProperties : public CommonSynapseProperties
{
public:
  // Default constructor.
  EpropSynapseCommonProperties();
 
  EpropSynapseCommonProperties( const EpropSynapseCommonProperties& );
 
  EpropSynapseCommonProperties& operator=( const EpropSynapseCommonProperties& ) = delete;
 
  ~EpropSynapseCommonProperties();
 
  void get_status( Dictionary& d ) const;
 
  void set_status( const Dictionary& d, ConnectorModel& cm );
 
  WeightOptimizerCommonProperties* optimizer_cp_;
};
 
void register_eprop_synapse( const std::string& name );
 
template < typename targetidentifierT >
class eprop_synapse : public Connection< targetidentifierT >
{
 
public:
  typedef EpropSynapseCommonProperties CommonPropertiesType;
 
  typedef Connection< targetidentifierT > ConnectionBase;
 
  static constexpr ConnectionModelProperties properties = ConnectionModelProperties::HAS_DELAY
    | ConnectionModelProperties::IS_PRIMARY | ConnectionModelProperties::REQUIRES_EPROP_ARCHIVING
    | ConnectionModelProperties::SUPPORTS_HPC;
 
  static constexpr bool supports_flush_event = true;
 
  eprop_synapse();
 
  ~eprop_synapse();
 
  eprop_synapse( const eprop_synapse& );
 
  eprop_synapse& operator=( const eprop_synapse& );
 
  eprop_synapse( eprop_synapse&& );
 
  eprop_synapse& operator=( eprop_synapse&& );
 
  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 EpropSynapseCommonProperties& 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_;
 
  long t_spike_previous_ = 0;
 
  bool previous_was_flush_event_ = false;
 
  long t_previous_trigger_spike_ = 0;
 
  double z_bar_ = 0.0;
 
  double e_bar_ = 0.0;
 
  double e_bar_reg_ = 0.0;
 
  double epsilon_ = 0.0;
 
  double z_previous_buffer_ = 0.0;
 
  double gradient_ = 0.0;
 
  long remaining_steps_until_cutoff_ = 0;
 
  long decay_steps_ = 0;
 
  WeightOptimizer* optimizer_;
};
 
template < typename targetidentifierT >
constexpr ConnectionModelProperties eprop_synapse< targetidentifierT >::properties;
 
// Explicitly declare specializations of Connector methods that need to do special things for eprop_synapse
template <>
void Connector< eprop_synapse< TargetIdentifierPtrRport > >::disable_connection( const size_t lcid );
 
template <>
void Connector< eprop_synapse< TargetIdentifierIndex > >::disable_connection( const size_t lcid );
 
template <>
Connector< eprop_synapse< TargetIdentifierPtrRport > >::~Connector();
 
template <>
Connector< eprop_synapse< TargetIdentifierIndex > >::~Connector();
 
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >::eprop_synapse()
  : ConnectionBase()
  , weight_( 1.0 )
  , t_spike_previous_( 0 )
  , previous_was_flush_event_( false )
  , t_previous_trigger_spike_( 0 )
  , optimizer_( nullptr )
{
}
 
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >::~eprop_synapse()
{
}
 
// This copy constructor is used to create instances from prototypes.
// Therefore, only parameter values are copied.
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >::eprop_synapse( const eprop_synapse& es )
  : ConnectionBase( es )
  , weight_( es.weight_ )
  , optimizer_( es.optimizer_ )
{
}
 
// This assignment operator is used to write a connection into the connection array.
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >&
eprop_synapse< targetidentifierT >::operator=( const eprop_synapse& es )
{
  if ( this == &es )
  {
    return *this;
  }
 
  ConnectionBase::operator=( es );
 
  weight_ = es.weight_;
  t_spike_previous_ = es.t_spike_previous_;
  previous_was_flush_event_ = es.previous_was_flush_event_;
  t_previous_trigger_spike_ = es.t_previous_trigger_spike_;
  z_bar_ = es.z_bar_;
  e_bar_ = es.e_bar_;
  e_bar_reg_ = es.e_bar_reg_;
  epsilon_ = es.epsilon_;
  z_previous_buffer_ = es.z_previous_buffer_;
  gradient_ = es.gradient_;
  remaining_steps_until_cutoff_ = es.remaining_steps_until_cutoff_;
  decay_steps_ = es.decay_steps_;
  optimizer_ = es.optimizer_;
 
  return *this;
}
 
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >::eprop_synapse( eprop_synapse&& es )
  : ConnectionBase( es )
  , weight_( es.weight_ )
  , t_spike_previous_( es.t_spike_previous_ )
  , previous_was_flush_event_( es.previous_was_flush_event_ )
  , t_previous_trigger_spike_( es.t_previous_trigger_spike_ )
  , z_bar_( es.z_bar_ )
  , e_bar_( es.e_bar_ )
  , e_bar_reg_( es.e_bar_reg_ )
  , epsilon_( es.epsilon_ )
  , z_previous_buffer_( es.z_previous_buffer_ )
  , gradient_( es.gradient_ )
  , remaining_steps_until_cutoff_( es.remaining_steps_until_cutoff_ )
  , decay_steps_( es.decay_steps_ )
  , optimizer_( es.optimizer_ )
{
  // Move operator, therefore we must null the optimizer pointer in the source of the move.
  es.optimizer_ = nullptr;
}
 
// This is the move assignment operator.
template < typename targetidentifierT >
eprop_synapse< targetidentifierT >&
eprop_synapse< targetidentifierT >::operator=( eprop_synapse&& es )
{
  if ( this == &es )
  {
    return *this;
  }
 
  ConnectionBase::operator=( es );
 
  weight_ = es.weight_;
  t_spike_previous_ = es.t_spike_previous_;
  previous_was_flush_event_ = es.previous_was_flush_event_;
  t_previous_trigger_spike_ = es.t_previous_trigger_spike_;
  z_bar_ = es.z_bar_;
  e_bar_ = es.e_bar_;
  e_bar_reg_ = es.e_bar_reg_;
  epsilon_ = es.epsilon_;
  z_previous_buffer_ = es.z_previous_buffer_;
  gradient_ = es.gradient_;
  remaining_steps_until_cutoff_ = es.remaining_steps_until_cutoff_;
  decay_steps_ = es.decay_steps_;
  optimizer_ = es.optimizer_;
 
  // Move assignment, therefore we must null the optimizer pointer in the source of the move.
  es.optimizer_ = nullptr;
 
  return *this;
}
 
template < typename targetidentifierT >
inline void
eprop_synapse< 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();
 
  optimizer_ = cp.optimizer_cp_->get_optimizer();
}
 
template < typename targetidentifierT >
inline void
eprop_synapse< targetidentifierT >::delete_optimizer()
{
  delete optimizer_;
  // do not set to nullptr to allow detection of double deletion
}
 
template < typename targetidentifierT >
bool
eprop_synapse< targetidentifierT >::send( Event& e, size_t thread, const EpropSynapseCommonProperties& 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 ( t_spike_previous_ != 0 )
  {
    target->compute_gradient( t_spike,
      t_spike_previous_,
      z_previous_buffer_,
      z_bar_,
      e_bar_,
      e_bar_reg_,
      epsilon_,
      weight_,
      cp,
      optimizer_,
      is_flush_event,
      previous_was_flush_event_,
      gradient_,
      remaining_steps_until_cutoff_,
      decay_steps_ );
  }
 
  target->erase_used_eprop_history( t_spike, t_spike_previous_ );
 
  t_spike_previous_ = t_spike;
  previous_was_flush_event_ = is_flush_event;
 
  if ( not is_flush_event )
  {
    e.set_receiver( *target );
    e.set_weight( weight_ );
    e.set_delay_steps( get_delay_steps() );
    e.set_rport( get_rport() );
    e();
  }
  return true;
}
 
template < typename targetidentifierT >
void
eprop_synapse< targetidentifierT >::get_status( Dictionary& d ) const
{
  ConnectionBase::get_status( d );
  d[ names::weight ] = weight_;
  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< targetidentifierT >::set_status( const Dictionary& d, ConnectorModel& cm )
{
  ConnectionBase::set_status( d, cm );
  if ( d.known( names::optimizer ) )
  {
    // We must pass here if called by SetDefaults. In that case, the user will get and error
    // message because the parameters for the synapse-specific optimizer have not been accessed.
    if ( optimizer_ )
    {
      optimizer_->set_status( d.get< Dictionary >( names::optimizer ) );
    }
  }
 
  d.update_value( names::weight, weight_ );
 
  const auto& gcm = dynamic_cast< const GenericConnectorModel< eprop_synapse< 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_H