iaf_psc_exp_ps.h

Go to the documentation of this file.

/*
 *  iaf_psc_exp_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_EXP_PS_H
#define IAF_PSC_EXP_PS_H

#include "config.h"

#include "nest.h"
#include "event.h"
#include "node.h"
#include "ring_buffer.h"
#include "slice_ring_buffer.h"
#include "connection.h"
#include "universal_data_logger.h"
#include "recordables_map.h"

#include <vector>

/*BeginDocumentation
Name: iaf_psc_exp_ps - Leaky integrate-and-fire neuron
with exponential postsynaptic currents; canoncial implementation;
bisectioning method for approximation of threshold crossing.

Description:
iaf_psc_exp_ps is the "canonical" implementation of the leaky
integrate-and-fire model neuron with exponential postsynaptic currents
that uses the bisectioning method to approximate the timing of a threshold
crossing [1,2]. This is the most exact implementation available.

The canonical implementation handles neuronal dynamics in a locally
event-based manner with in coarse time grid defined by the minimum
delay in the network, see [1,2]. Incoming spikes are applied at the
precise moment of their arrival, while the precise time of outgoing
spikes is determined by bisectioning once a threshold crossing has
been detected. Return from refractoriness occurs precisely at spike
time plus refractory period.

This implementation is more complex than the plain iaf_psc_exp
neuron, but achieves much higher precision. In particular, it does not
suffer any binning of spike times to grid points. Depending on your
application, the canonical application with bisectioning may provide
superior overall performance given an accuracy goal; see [1,2] for
details. Subthreshold dynamics are integrated using exact integration
between events [3].

Parameters: 
  The following parameters can be set in the status dictionary.
  E_L           double - Resting membrane potential in mV.
  C_m           double - Specific capacitance of the membrane in pF/mum^2.
  tau_m         double - Membrane time constant in ms.
  tau_syn_ex    double - Excitatory synaptic time constant in ms.
  tau_syn_in    double - Inhibitory synaptic time constant in ms.
  t_ref         double - Duration of refractory period in ms.
  V_th          double - Spike threshold in mV.
  I_e           double - Constant input current in pA.
  V_min         double - Absolute lower value for the membrane potential.
  V_reset       double - Reset value for the membrane potential.

Remarks:
  Please note that this node is capable of sending precise spike times
  to target nodes (on-grid spike time plus offset). If this node is
  connected to a spike_detector, the property "precise_times" of the
  spike_detector has to be set to true in order to record the offsets
  in addition to the on-grid spike times.
  
Note:
  tau_m != tau_syn_{ex,in} is required by the current implementation to avoid a
  degenerate case of the ODE describing the model [1]. For very similar values,
  numerics will be unstable.

References:
  [1] Morrison A, Straube S, Plesser HE & Diesmann M (2007) Exact subthreshold
      integration with continuous spike times in discrete time neural network
      simulations. Neural Comput 19, 47-79
  [2] Hanuschkin A, Kunkel S, Helias M, Morrison A and Diesmann M (2010) A
      general and efficient method for incorporating precise spike times in
      globally timedriven simulations. Front Neuroinform 4:113
  [3] Rotter S & Diesmann M (1999) Exact simulation of time-invariant linear
      systems with applications to neuronal modeling. Biol Cybern 81:381-402
        
Author: Kunkel

Sends: SpikeEvent

Receives: SpikeEvent, CurrentEvent, DataLoggingRequest

SeeAlso: iaf_psc_exp, iaf_psc_alpha_canon
*/ 

namespace nest
{

  class iaf_psc_exp_ps : public Node
  {
    
    class Network;
    
  public:
    
    iaf_psc_exp_ps();
    
    iaf_psc_exp_ps(const iaf_psc_exp_ps &);
    
    using Node::handle;
    using Node::handles_test_event;

    port send_test_event(Node &, rport, synindex, bool);
   
    port handles_test_event(SpikeEvent&, rport);
    port handles_test_event(CurrentEvent&, rport);
    port handles_test_event(DataLoggingRequest &, rport);
    
    void handle(SpikeEvent &);
    void handle(CurrentEvent &);
    void handle(DataLoggingRequest &);
   
    bool is_off_grid() const  // uses off_grid events
    {
      return true;
    }
    
    void get_status(DictionaryDatum &) const;
    void set_status(const DictionaryDatum &);
    
  private:

    void init_state_(const Node & proto);
    void init_buffers_();
    void calibrate();

    void update(Time const & origin, const long_t from, const long_t to);
    
    // The next two classes need to be friends to access the State_ class/member
    friend class RecordablesMap<iaf_psc_exp_ps>;
    friend class UniversalDataLogger<iaf_psc_exp_ps>;
    
    void set_spiketime(Time const &);
    
    void propagate_(const double_t dt);
    
    void emit_spike_(const Time & origin, const long_t lag, 
             const double_t t0, const double_t dt);
    
    void emit_instant_spike_(const Time & origin, const long_t lag, 
                 const double_t spike_offset);
    
    double_t bisectioning_(const double_t dt) const;
    
    // ---------------------------------------------------------------- 

    struct Parameters_
    {
      double_t tau_m_; 
      
      double_t tau_ex_;
      
      double_t tau_in_;
      
      double_t c_m_;
      
      double_t t_ref_;
      
      double_t E_L_;
      
      double_t I_e_;
      
      double_t U_th_;
      
      double_t U_min_;
      
      double_t U_reset_;
      
      Parameters_();  
      
      void get(DictionaryDatum &) const;  

      double set(const DictionaryDatum &);
    };
    
    // ---------------------------------------------------------------- 

    struct State_
    {
      double_t y0_;  
      double_t y1_ex_;  
      double_t y1_in_;  
      double_t y2_;  
      
      bool is_refractory_;  
      long_t   last_spike_step_;  
      double_t last_spike_offset_;  
      
      State_();  
      
      void get(DictionaryDatum &, const Parameters_ &) const;

      void set(const DictionaryDatum &, const Parameters_ &, double);
    };
    
    // ---------------------------------------------------------------- 

    struct Buffers_
    {
      Buffers_(iaf_psc_exp_ps &);
      Buffers_(const Buffers_ &, iaf_psc_exp_ps &);

      SliceRingBuffer events_;
      RingBuffer currents_; 
      
      UniversalDataLogger<iaf_psc_exp_ps> logger_;
    };

    // ---------------------------------------------------------------- 

    struct Variables_
    { 
      double_t h_ms_;              
      long_t   refractory_steps_;  
      double_t expm1_tau_m_;       
      double_t expm1_tau_ex_;      
      double_t expm1_tau_in_;      
      double_t P20_;               
      double_t P21_in_;            
      double_t P21_ex_;            
      double_t y0_before_;         
      double_t y1_ex_before_;      
      double_t y1_in_before_;      
      double_t y2_before_;         
    };
    
    // Access functions for UniversalDataLogger -------------------------------
    
    double_t get_V_m_() const { return S_.y2_ + P_.E_L_; }
    
    // ---------------------------------------------------------------- 
    
    Parameters_ P_;
    State_      S_;
    Variables_  V_;
    Buffers_    B_;
    static RecordablesMap<iaf_psc_exp_ps> recordablesMap_;
  };
 
  inline
  port nest::iaf_psc_exp_ps::send_test_event(Node& target, rport receptor_type, synindex, bool)
  {
    SpikeEvent e;
    e.set_sender(*this);
    return target.handles_test_event(e, receptor_type);
  }
  
  inline
  port iaf_psc_exp_ps::handles_test_event(SpikeEvent&, rport receptor_type)
  {
    if (receptor_type != 0)
        throw UnknownReceptorType(receptor_type, get_name());
    return 0;
  }
 
  inline
  port iaf_psc_exp_ps::handles_test_event(CurrentEvent&, rport receptor_type)
  {
     if (receptor_type != 0)
        throw UnknownReceptorType(receptor_type, get_name());
     return 0;
  }
 
  inline
  port iaf_psc_exp_ps::handles_test_event(DataLoggingRequest& dlr, 
                                          rport 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::get_status(DictionaryDatum & d) const
  {
    P_.get(d);
    S_.get(d, P_);
  }

  inline
  void iaf_psc_exp_ps::set_status(const DictionaryDatum & d)
  {
     Parameters_ ptmp = P_;  // temporary copy in case of errors
    const double delta_EL = ptmp.set(d);            // throws if BadProperty
    State_ stmp = S_;       // temporary copy in case of errors
    stmp.set(d, ptmp, delta_EL);      // throws if BadProperty

    // if we get here, temporaries contain consistent set of properties
    P_ = ptmp;
    S_ = stmp;
  }
  
} // namespace

#endif // IAF_PSC_EXP_PS_H