iaf_psc_alpha_ps.h

Go to the documentation of this file.

/*
 *  iaf_psc_alpha_ps.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_ALPHA_PS_H
#define IAF_PSC_ALPHA_PS_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 "ring_buffer.h"
#include "slice_ring_buffer.h"
#include "universal_data_logger.h"
 
namespace nest
{
 
// Disable clang-formatting for documentation due to over-wide tables.
// clang-format off
/* BeginUserDocs: neuron, integrate-and-fire, current-based, precise, hard threshold
 
Short description
+++++++++++++++++
 
Current-based leaky integrate-and-fire neuron with alpha-shaped
postsynaptic currents using regula falsi method for approximation of
threshold crossing
 
Description
+++++++++++
 
.. versionadded:: 2.18
 
``iaf_psc_alpha_ps`` is the "canonical" implementation of the leaky
integrate-and-fire model neuron with alpha-shaped postsynaptic
currents in the sense of :footcite:p:`Morrison2007a`, that is, the most exact implementation
available. It is a leaky integrate-and-fire neuron model with
 
* a hard threshold,
* a fixed refractory period,
* :math:`\alpha`-shaped synaptic input currents,
* precise spike times based on the regula falsi method :footcite:p:`Morrison2007a`, :footcite:p:`Hanuschkin2010`.
 
Membrane potential evolution, spike emission, and refractoriness
................................................................
 
The membrane potential evolves according to
 
.. math::
 
   \frac{dV_\text{m}}{dt} = -\frac{V_{\text{m}} - E_\text{L}}{\tau_{\text{m}}} + \frac{I_{\text{syn}} + I_\text{e}}{C_{\text{m}}}
 
where the synaptic input current :math:`I_{\text{syn}}(t)` is discussed below and :math:`I_\text{e}` is
a constant input current set as a model parameter.
 
A spike is emitted when the membrane potential crosses the threshold :math:`V_\text{th}` from below;
the precise time of the crossing is determined by a regula falsi method (see below). Subsequently,
 
.. math::
 
   V_\text{m}(t) = V_{\text{reset}} \quad\text{for}\quad t^* \leq t \leq t^* + t_{\text{ref}} \;,
 
that is, the membrane potential is clamped to :math:`V_{\text{reset}}` during the refractory period.
 
Synaptic input
..............
 
The synaptic input current has an excitatory and an inhibitory component,
 
.. math::
 
  I_{\text{syn}}(t) = I_{\text{syn, ex}}(t) + I_{\text{syn, in}}(t)
 
where
 
.. math::
 
   I_{\text{syn, X}}(t) = \sum_{j} w_j \sum_k i_{\text{syn, X}}(t-t_j^k-d_j) \;,
 
where :math:`j` indexes either excitatory (:math:`\text{X} = \text{ex}`)
or inhibitory (:math:`\text{X} = \text{in}`) presynaptic neurons,
:math:`k` indexes the spike times of neuron :math:`j`, and :math:`d_j`
is the delay from neuron :math:`j`.
 
The individual post-synaptic currents (PSCs) are given by
 
.. math::
 
   i_{\text{syn, X}}(t) = \frac{e}{\tau_{\text{syn, X}}} t e^{-\frac{t}{\tau_{\text{syn, X}}}} \Theta(t) \;,
 
where :math:`\Theta(x)` is the Heaviside step function. The PSCs are normalized to unit maximum, that is,
 
.. math::
 
   i_{\text{syn, X}}(t= \tau_{\text{syn, X}}) = 1 \;.
 
As a consequence, the total charge :math:`q` transferred by a single PSC depends
on the synaptic time constant according to
 
.. math::
 
   q = \int_0^{\infty}  i_{\text{syn, X}}(t) dt = e \tau_{\text{syn, X}} \;.
 
By default, :math:`V_\text{m}` is not bounded from below. To limit
hyperpolarization to biophysically plausible values, set parameter
:math:`V_{\text{min}}` as lower bound of :math:`V_\text{m}`.
 
Precise implementation
......................
 
The precise implementation handles neuronal dynamics in a locally
event-based manner with in coarse time grid defined by the minimum
delay in the network, see :footcite:p:`Morrison2007a`. Incoming spikes are applied at the
precise moment of their arrival, while the precise time of outgoing
spikes is determined by a Regula Falsi method to approximate the timing
of a threshold crossing :footcite:p:`Morrison2007a` :footcite:p:`Hanuschkin2010`. Return from refractoriness occurs
precisely at spike time plus refractory period.
 
This implementation is more complex than the plain iaf_psc_alpha
neuron, but achieves much higher precision. In particular, spike times
are not binned to the points of the simulation time grid. Depending on your
application, the canonical implementation may provide superior overall
performance given an accuracy goal; see :footcite:p:`Morrison2007a` for details. Subthreshold
dynamics are integrated using exact integration between events :footcite:p:`Rotter1999`.
 
This model transmits precise spike times to target nodes (on-grid spike
time and offset). If this node is connected to a spike_recorder, the
property "precise_times" of the spike_recorder has to be set to true in
order to record the offsets in addition to the on-grid spike times.
 
The iaf_psc_alpha_ps neuron accepts connections transmitting
CurrentEvents. These events transmit stepwise-constant currents which
can only change at on-grid times.
 
.. note::
 
  If :math:`\tau_{\text{m}}` is very close to :math:`\tau_{\text{syn, ex}}` or
  :math:`\tau_{\text{syn, in}}`, the model will numerically behave as if :math:`\tau_{\text{m}}`
  is equal to :math:`\tau_{\text{syn, ex}}` or :math:`\tau_{\text{syn, in}}`, respectively,
  to avoid numerical instabilities.
 
  For implementation details see the
  `IAF Integration Singularity notebook <../model_details/IAF_Integration_Singularity.ipynb>`_.
 
For details about exact subthreshold integration, please see
:doc:`../neurons/exact-integration`.
 
Parameters
++++++++++
 
The following parameters can be set in the status dictionary.
 
=============== ================== =============================== ========================================================================
**Parameter**   **Default**        **Math equivalent**             **Description**
=============== ================== =============================== ========================================================================
``E_L``         -70 mV             :math:`E_\text{L}`              Resting membrane potential
``C_m``         250 pF             :math:`C_{\text{m}}`            Capacity of the membrane
``tau_m``       10 ms              :math:`\tau_{\text{m}}`         Membrane time constant
``t_ref``       2 ms               :math:`t_{\text{ref}}`          Duration of refractory period
``V_th``        -55 mV             :math:`V_{\text{th}}`           Spike threshold
``V_reset``     -70 mV             :math:`V_{\text{reset}}`        Reset potential of the membrane
``tau_syn_ex``  2 ms               :math:`\tau_{\text{syn, ex}}`   Rise time of the excitatory synaptic current
``tau_syn_in``  2 ms               :math:`\tau_{\text{syn, in}}`   Rise time of the inhibitory synaptic current
``I_e``         0 pA               :math:`I_\text{e}`              Constant input current
``V_min``       :math:`-\infty` mV :math:`V_{\text{min}}`          Absolute lower value for the membrane potential
=============== ================== =============================== ========================================================================
 
The following state variables evolve during simulation and are available either as neuron properties or as recordables.
 
================== ================= ========================== =================================
**State variable** **Initial value** **Math equivalent**        **Description**
================== ================= ========================== =================================
``V_m``            -70 mV            :math:`V_{\text{m}}`       Membrane potential
``I_syn_ex``       0 pA              :math:`I_{\text{syn, ex}}` Excitatory synaptic input current
``I_syn_in``       0 pA              :math:`I_{\text{syn, in}}` Inhibitory synaptic input current
================== ================= ========================== =================================
 
References
++++++++++
 
.. footbibliography::
 
Sends
+++++
 
SpikeEvent
 
Receives
++++++++
 
SpikeEvent, CurrentEvent, DataLoggingRequest
 
See also
++++++++
 
iaf_psc_alpha, iaf_psc_exp_ps
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: iaf_psc_alpha_ps
 
EndUserDocs */
// clang-format on
 
void register_iaf_psc_alpha_ps( const std::string& name );
 
class iaf_psc_alpha_ps : public ArchivingNode
{
public:
  iaf_psc_alpha_ps();
 
  iaf_psc_alpha_ps( const iaf_psc_alpha_ps& );
 
  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
  {
    return true;
  }  // uses off_grid events
 
  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;
 
  bool get_next_event_( const long T, double& ev_offset, double& ev_weight, bool& end_of_refract );
 
  void update( Time const& origin, const long from, const long to ) override;
 
 
  void propagate_( const double dt );
 
  void emit_spike_( Time const& origin, const long lag, const double t0, const double dt );
 
  void emit_instant_spike_( Time const& origin, const long lag, const double spike_offset );
 
  IAFPropagatorAlpha propagator_ex_;
  IAFPropagatorAlpha propagator_in_;
 
  // The next two classes need to be friends to access the State_ class/member
  friend class RecordablesMap< iaf_psc_alpha_ps >;
  friend class UniversalDataLogger< iaf_psc_alpha_ps >;
 
  // ----------------------------------------------------------------
 
  struct Parameters_
  {
 
    double tau_m_;
 
    double tau_syn_ex_;
    double tau_syn_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* );
  };
 
  // ----------------------------------------------------------------
 
  struct State_
  {
    double y_input_;            
    double I_ex_;               
    double dI_ex_;              
    double I_in_;               
    double dI_in_;              
    double V_m_;                
    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, Node* );
  };
 
  // ----------------------------------------------------------------
 
  struct Buffers_
  {
    Buffers_( iaf_psc_alpha_ps& );
    Buffers_( const Buffers_&, iaf_psc_alpha_ps& );
 
    SliceRingBuffer events_;
    RingBuffer currents_;
 
    UniversalDataLogger< iaf_psc_alpha_ps > logger_;
  };
 
  // ----------------------------------------------------------------
 
  struct Variables_
  {
    double h_ms_;            
    double psc_norm_ex_;     
    double psc_norm_in_;     
    long refractory_steps_;  
    double expm1_tau_m_;     
    double exp_tau_syn_ex_;  
    double exp_tau_syn_in_;  
    double P30_;             
    double P31_ex_;          
    double P32_ex_;          
    double P31_in_;          
    double P32_in_;          
    double y_input_before_;  
    double I_ex_before_;     
    double I_in_before_;     
    double dI_ex_before_;    
    double dI_in_before_;    
    double V_m_before_;      
    double inv_tau_m_;       
    double inv_tau_syn_ex_;  
    double inv_tau_syn_in_;  
    double inv_c_m_;         
  };
 
  // Access functions for UniversalDataLogger -------------------------------
 
  double
  get_V_m_() const
  {
    return S_.V_m_ + P_.E_L_;
  }
 
  double
  get_I_ex_() const
  {
    return S_.I_ex_;
  }
 
  double
  get_dI_ex_() const
  {
    return S_.dI_ex_;
  }
 
  double
  get_I_in_() const
  {
    return S_.I_in_;
  }
 
  double
  get_dI_in_() const
  {
    return S_.dI_in_;
  }
 
  // ----------------------------------------------------------------
 
  Parameters_ P_;
  State_ S_;
  Variables_ V_;
  Buffers_ B_;
  static RecordablesMap< iaf_psc_alpha_ps > recordablesMap_;
};
 
inline size_t
iaf_psc_alpha_ps::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_alpha_ps::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_alpha_ps::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_alpha_ps::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_alpha_ps::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_alpha_ps::set_status( const Dictionary& d )
{
  Parameters_ ptmp = P_;                        // temporary copy in case of errors
  const 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_ALPHA_PS_H