amat2_psc_exp.h

Go to the documentation of this file.

/*
 *  amat2_psc_exp.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 AMAT2_PSC_EXP_H
#define AMAT2_PSC_EXP_H

#include "nest.h"
#include "event.h"
#include "archiving_node.h"
#include "ring_buffer.h"
#include "connection.h"
#include "universal_data_logger.h"
#include "recordables_map.h"

namespace nest
{

  class Network;

  /* BeginDocumentation
     Name: amat2_psc_exp - Non-resetting leaky integrate-and-fire neuron model with
     exponential PSCs and adaptive threshold.

     Description:
     amat2_psc_exp is an implementation of a leaky integrate-and-fire model
     with exponential shaped postsynaptic currents (PSCs). Thus, postsynaptic currents
     have an infinitely short rise time.

     The threshold is lifted when the neuron is fired and then decreases in a fixed
     time scale toward a fixed level [3].

     The threshold crossing is followed by a total refractory period
     during which the neuron is not allowed to fire, even if the membrane
     potential exceeds the threshold. The membrane potential is NOT reset,
     but continuously integrated.

     The linear subthresold dynamics is integrated by the Exact
     Integration scheme [1]. The neuron dynamics is solved on the time
     grid given by the computation step size. Incoming as well as emitted
     spikes are forced to that grid.

     An additional state variable and the corresponding differential
     equation represents a piecewise constant external current.

     The general framework for the consistent formulation of systems with
     neuron like dynamics interacting by point events is described in
     [1]. A flow chart can be found in [2].

     Remarks:
     - The default parameter values for this model are different from the
       corresponding parameter values for mat2_psc_exp.
     - If identical parameters are used, and beta==0, then this model shall
       behave exactly as mat2_psc_exp.
     - The time constants in the model must fullfill the following conditions:
       - tau_m != {tau_syn_ex, tau_syn_in}
       - tau_v != {tau_syn_ex, tau_syn_in}
       - tau_m != tau_v
       This is required to avoid singularities in the numerics. This is a problem
       of implementation only, not a principal problem of the model.
     - Expect unstable numerics if time constants that are required to be different
       are very close.

     Parameters: 
     The following parameters can be set in the status dictionary:

     C_m          double - Capacity of the membrane in pF
     E_L          double - Resting potential in mV
     tau_m        double - Membrane time constant in ms
     tau_syn_ex   double - Time constant of postsynaptic excitatory currents in ms
     tau_syn_in   double - Time constant of postsynaptic inhibitory currents in ms
     t_ref        double - Duration of absolute refractory period (no spiking) in ms
     V_m          double - Membrane potential in mV
     I_e          double - Constant input current in pA
     t_spike      double - Point in time of last spike in ms
     tau_1        double - Short time constant of adaptive threshold in ms [3, eqs 2-3]
     tau_2        double - Long time constant of adaptive threshold in ms [3, eqs 2-3]
     alpha_1      double - Amplitude of short time threshold adaption in mV [3, eqs 2-3]
     alpha_2      double - Amplitude of long time threshold adaption in mV [3, eqs 2-3]
     tau_v        double - Time constant of kernel for voltage-dependent threshold component in ms [3, eqs 16-17]
     beta         double - Scaling coefficient for voltage-dependent threshold component in 1/ms [3, eqs 16-17]
     omega        double - Resting spike threshold in mV (absolute value, not relative to E_L as in [3])

     The following state variables can be read out with the multimeter device:

     V_m          Non-resetting membrane potential
     V_th         Two-timescale adaptive threshold

     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] Rotter S & Diesmann M (1999) Exact simulation of
         time-invariant linear systems with applications to neuronal
         modeling. Biologial Cybernetics 81:381-402.
     [2] Diesmann M, Gewaltig M-O, Rotter S, & Aertsen A (2001) State
         space analysis of synchronous spiking in cortical neural
         networks. Neurocomputing 38-40:565-571.
     [3] Kobayashi R, Tsubo Y and Shinomoto S (2009) Made-to-order
         spiking neuron model equipped with a multi-timescale adaptive
         threshold. Front. Comput. Neurosci. 3:9. doi:10.3389/neuro.10.009.2009
     [4] Yamauchi S, Kim H and Shinomoto S (2011) Elemental spiking neuron model
             for reproducing diverse firing patterns and predicting precise firing
             times. Front. Comput. Neurosci. 5:42. doi: 10.3389/fncom.2011.00042

     Sends: SpikeEvent

     Receives: SpikeEvent, CurrentEvent, DataLoggingRequest

     FirstVersion: April 2013
     Author: Thomas Heiberg & Hans E. Plesser (modified mat2_psc_exp model of Thomas Pfeil)
  */

  class amat2_psc_exp: public Archiving_Node
  {

  public:

    amat2_psc_exp();
    amat2_psc_exp(const amat2_psc_exp&);

    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 &);

    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 &, const long_t, const long_t);

    // The next two classes need to be friends to access private members
    friend class RecordablesMap<amat2_psc_exp>;
    friend class UniversalDataLogger<amat2_psc_exp>;

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

    struct Parameters_ {

      double_t Tau_; 

      double_t C_;

      double_t tau_ref_;

      double_t U0_;

      double_t I_e_;

      double_t tau_ex_;

      double_t tau_in_;

      double_t tau_1_;
      double_t tau_2_;

      double_t alpha_1_;
      double_t alpha_2_;

      double_t beta_;

      double_t tau_v_;

      double_t omega_;

      Parameters_();  

      void get(DictionaryDatum&) const;  

     double set(const DictionaryDatum&);  
    };

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

    struct State_ {
      // state variables
      double_t     i_0_;      // synaptic dc input current, variable 0
      double_t     i_syn_ex_; // postsynaptic current for exc. inputs, variable 1
      double_t     i_syn_in_; // postsynaptic current for inh. inputs, variable 2
      double_t     V_m_;      // membrane potential, variable 3
      double_t     V_th_1_;   // short time adaptive threshold (related to tau_1_), variable 4
      double_t     V_th_2_;   // long time adaptive threshold (related to tau_2_), variable 5
      double_t     V_th_dv_;  // derivative of voltage dependent threshold variable 6
      double_t     V_th_v_;   // voltage dependent threshold, variable 7

      int_t        r_;    // total refractory counter (no spikes can be generated)

      State_();  

      void get(DictionaryDatum&, const Parameters_&) const;

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

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

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

      RingBuffer spikes_ex_;
      RingBuffer spikes_in_;
      RingBuffer currents_;

      UniversalDataLogger<amat2_psc_exp> logger_;
    };

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

    struct Variables_ {

      //    double_t PSCInitialValue_;

      double_t P00_; // constant currents
      double_t P11_;
      double_t P22_;
      double_t P30_;
      double_t P31_;
      double_t P32_;
      double_t P33_;
      double_t P44_;
      double_t P55_;
      double_t P60_;
      double_t P61_;
      double_t P62_;
      double_t P63_;
      double_t P66_;
      double_t P70_;
      double_t P71_;
      double_t P72_;
      double_t P73_;
      double_t P76_;
      double_t P77_;
      
      int_t       RefractoryCountsTot_;
    };
    // ---------------------------------------------------------------- 

    double_t get_V_m_() const { return S_.V_m_ + P_.U0_; }
    double_t get_V_th_() const { return P_.U0_ + P_.omega_ + S_.V_th_1_ + S_.V_th_2_ + S_.V_th_v_; }
    double_t get_V_th_v_() const { return S_.V_th_v_; }

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

    Parameters_ P_;
    State_      S_;
    Variables_  V_;
    Buffers_    B_;
    static RecordablesMap<amat2_psc_exp> recordablesMap_;
  };

  
  inline
  port amat2_psc_exp::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 amat2_psc_exp::handles_test_event(SpikeEvent&, rport receptor_type)
  {
    if (receptor_type != 0)
      throw UnknownReceptorType(receptor_type, get_name());
    return 0;
  }

  inline
  port amat2_psc_exp::handles_test_event(CurrentEvent&, rport receptor_type)
  {
    if (receptor_type != 0)
      throw UnknownReceptorType(receptor_type, get_name());
    return 0;
  }

  inline
    port amat2_psc_exp::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 amat2_psc_exp::get_status(DictionaryDatum &d) const
  {
    P_.get(d);
    S_.get(d, P_);
    Archiving_Node::get_status(d);

    (*d)[names::recordables] = recordablesMap_.get_list();
  }

  inline
  void amat2_psc_exp::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

    // 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.
    Archiving_Node::set_status(d);

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

} // namespace

#endif //AMAT2_PSC_EXP_H