iaf_psc_exp_ps_lossless.h

Go to the documentation of this file.

/*
 *  iaf_psc_exp_ps_lossless.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 IAF_PSC_EXP_PS_LOSSLESS_H
#define IAF_PSC_EXP_PS_LOSSLESS_H
 
// C++ includes:
#include <vector>
 
// Generated includes:
#include "config.h"
 
// Includes from libnestutil:
#include "archiving_node.h"
#include "connection.h"
#include "event.h"
#include "iaf_propagator.h"
#include "nest_types.h"
#include "recordables_map.h"
#include "ring_buffer.h"
#include "slice_ring_buffer.h"
#include "universal_data_logger.h"
 
 
namespace nest
{
 
/* BeginUserDocs: neuron, integrate-and-fire, current-based, precise, hard threshold
 
Short description
+++++++++++++++++
 
Current-based leaky integrate-and-fire neuron with exponential-shaped
postsynaptic currents predicting the exact number of spikes using a
state space analysis
 
Description
+++++++++++
 
``iaf_psc_exp_ps_lossless`` is the precise state space implementation of the leaky
integrate-and-fire model neuron with exponential postsynaptic currents
that uses time reversal to detect spikes :footcite:p:`Krishnan2018`. This is the most exact
implementation available.
 
Time-reversed state space analysis provides a general method to solve the
threshold-detection problem for an integrable, affine or linear time
evolution. This method is based on the idea of propagating the threshold
backwards in time, and see whether it meets the initial state, rather
than propagating the initial state forward in time and see whether it
meets the threshold.
 
.. note::
 
  If `tau_m` is very close to `tau_syn_ex` or `tau_syn_in`, the model
  will numerically behave as if `tau_m` is equal to `tau_syn_ex` or
  `tau_syn_in`, respectively, to avoid numerical instabilities.
 
  For implementation details see the
  `IAF Integration Singularity notebook <../model_details/IAF_Integration_Singularity.ipynb>`_.
 
Parameters
++++++++++
 
The following parameters can be set in the status dictionary.
 
===========  ========  ==========================================================
 E_L         mV        Resting membrane potential
 C_m         pF/mum^2  Specific capacitance of the membrane
 tau_m       ms        Membrane time constant
 tau_syn_ex  ms        Excitatory synaptic time constant
 tau_syn_in  ms        Inhibitory synaptic time constant
 t_ref       ms        Duration of refractory period
 V_th        mV        Spike threshold
 I_e         pA        Constant input current
 V_min       mV        Absolute lower value for the membrane potential.
 V_reset     mV        Reset value for the membrane potential.
===========  ========  ==========================================================
 
References
++++++++++
 
.. footbibliography::
 
Sends
+++++
 
SpikeEvent
 
Receives
++++++++
 
SpikeEvent, CurrentEvent, DataLoggingRequest
 
See also
++++++++
 
iaf_psc_exp_ps
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: iaf_psc_exp_ps_lossless
 
EndUserDocs */
 
void register_iaf_psc_exp_ps_lossless( const std::string& name );
 
class iaf_psc_exp_ps_lossless : public ArchivingNode
{
public:
  iaf_psc_exp_ps_lossless();
 
  iaf_psc_exp_ps_lossless( const iaf_psc_exp_ps_lossless& );
 
  using Node::handle;
  using Node::handles_test_event;
 
  size_t send_test_event( Node&, size_t, synindex, bool ) override;
 
  size_t handles_test_event( SpikeEvent&, size_t ) override;
  size_t handles_test_event( CurrentEvent&, size_t ) override;
  size_t handles_test_event( DataLoggingRequest&, size_t ) override;
 
  void handle( SpikeEvent& ) override;
  void handle( CurrentEvent& ) override;
  void handle( DataLoggingRequest& ) override;
 
  bool
  is_off_grid() const override  // uses off_grid events
  {
    return true;
  }
 
  void get_status( Dictionary& ) const override;
  void set_status( const Dictionary& ) override;
 
  double threshold_distance( double t_step ) const;
 
private:
  void init_buffers_() override;
  void pre_run_hook() override;
 
  void update( Time const& origin, const long from, const long to ) override;
 
  // The next two classes need to be friends to access the State_ class/member
  friend class RecordablesMap< iaf_psc_exp_ps_lossless >;
  friend class UniversalDataLogger< iaf_psc_exp_ps_lossless >;
 
  void propagate_( const double dt );
 
  void emit_spike_( const Time& origin, const long lag, const double t0, const double dt );
 
  void emit_instant_spike_( const Time& origin, const long lag, const double spike_offset );
 
  double is_spike_( const double );
 
  IAFPropagatorExp propagator_ex_;
  IAFPropagatorExp propagator_in_;
 
  // ----------------------------------------------------------------
 
  struct Parameters_
  {
    double tau_m_;
 
    double tau_ex_;
 
    double tau_in_;
 
    double c_m_;
 
    double t_ref_;
 
    double E_L_;
 
    double I_e_;
 
    double U_th_;
 
    double U_min_;
 
    double U_reset_;
 
    Parameters_();  
 
    void get( Dictionary& ) const;                
    double set( const Dictionary&, Node* node );  
  };
 
  // ----------------------------------------------------------------
 
  struct State_
  {
    double y0_;        
    double I_syn_ex_;  
    double I_syn_in_;  
    double y2_;        
 
    bool is_refractory_;        
    long last_spike_step_;      
    double last_spike_offset_;  
 
    State_();  
 
    void get( Dictionary&, const Parameters_& ) const;
    void set( const Dictionary&, const Parameters_&, double delta_EL, Node* );
  };
 
  // ----------------------------------------------------------------
 
  struct Buffers_
  {
    Buffers_( iaf_psc_exp_ps_lossless& );
    Buffers_( const Buffers_&, iaf_psc_exp_ps_lossless& );
 
    SliceRingBuffer events_;
    RingBuffer currents_;
 
    UniversalDataLogger< iaf_psc_exp_ps_lossless > logger_;
  };
 
  // ----------------------------------------------------------------
 
  struct Variables_
  {
    double h_ms_;             
    long refractory_steps_;   
    double expm1_tau_m_;      
    double exp_tau_ex_;       
    double exp_tau_in_;       
    double P20_;              
    double P21_in_;           
    double P21_ex_;           
    double y0_before_;        
    double I_syn_ex_before_;  
    double I_syn_in_before_;  
    double y2_before_;        
 
    double a1_;
    double a2_;
    double a3_;
    double a4_;
 
    double b1_;
    double b2_;
    double b3_;
    double b4_;
 
    double c1_;
    double c2_;
    double c3_;
    double c4_;
    double c5_;
    double c6_;
  };
 
  // Access functions for UniversalDataLogger -------------------------------
 
  double
  get_V_m_() const
  {
    return S_.y2_ + P_.E_L_;
  }
  double
  get_I_syn_() const
  {
    return S_.I_syn_ex_ + S_.I_syn_in_;
  }
  double
  get_I_syn_ex_() const
  {
    return S_.I_syn_ex_;
  }
  double
  get_I_syn_in_() const
  {
    return S_.I_syn_in_;
  }
  // ----------------------------------------------------------------
 
  Parameters_ P_;
  State_ S_;
  Variables_ V_;
  Buffers_ B_;
  static RecordablesMap< iaf_psc_exp_ps_lossless > recordablesMap_;
};
 
inline size_t
iaf_psc_exp_ps_lossless::send_test_event( Node& target, size_t receptor_type, synindex, bool )
{
  SpikeEvent e;
  e.set_sender( *this );
  return target.handles_test_event( e, receptor_type );
}
 
inline size_t
iaf_psc_exp_ps_lossless::handles_test_event( SpikeEvent&, size_t receptor_type )
{
  if ( receptor_type != 0 )
  {
    throw UnknownReceptorType( receptor_type, get_name() );
  }
  return 0;
}
 
inline size_t
iaf_psc_exp_ps_lossless::handles_test_event( CurrentEvent&, size_t receptor_type )
{
  if ( receptor_type != 0 )
  {
    throw UnknownReceptorType( receptor_type, get_name() );
  }
  return 0;
}
 
inline size_t
iaf_psc_exp_ps_lossless::handles_test_event( DataLoggingRequest& dlr, size_t receptor_type )
{
  if ( receptor_type != 0 )
  {
    throw UnknownReceptorType( receptor_type, get_name() );
  }
  return B_.logger_.connect_logging_device( dlr, recordablesMap_ );
}
 
inline void
iaf_psc_exp_ps_lossless::get_status( Dictionary& d ) const
{
  P_.get( d );
  S_.get( d, P_ );
  ArchivingNode::get_status( d );
 
  d[ names::recordables ] = recordablesMap_.get_list();
}
 
inline void
iaf_psc_exp_ps_lossless::set_status( const Dictionary& d )
{
  Parameters_ ptmp = P_;                  // temporary copy in case of errors
  double delta_EL = ptmp.set( d, this );  // throws if BadProperty
  State_ stmp = S_;                       // temporary copy in case of errors
  stmp.set( d, ptmp, delta_EL, this );    // throws if BadProperty
 
  // We now know that (ptmp, stmp) are consistent. We do not
  // write them back to (P_, S_) before we are also sure that
  // the properties to be set in the parent class are internally
  // consistent.
  ArchivingNode::set_status( d );
 
  // if we get here, temporaries contain consistent set of properties
  P_ = ptmp;
  S_ = stmp;
}
}  // namespace
#endif  // IAF_PSC_EXP_PS_LOSSLESS_H