sli_neuron.h

Go to the documentation of this file.

/*
 *  sli_neuron.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 SLI_NEURON_H
#define SLI_NEURON_H

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

namespace nest{

  class Network;

  /* BeginDocumentation
Name: sli_neuron - neuron with SLI callback

Description:
The sli_neuron is a model whose state, update and calibration can be
defined in SLI.

The state of the neuron is a SLI dictionary which can be retrieved
with GetStatus. The state should contain two procedures:
 1. /update
 2. /calibrate

/calibrate is called before the simulation starts. It is used to
           pre-compute constants of the dynamics and to scale
           parameters to the temporal resolution.  A minimal
           implementation of calibrate is:

           /calibrate { GetResolution /h Set } def

/update    is called during simulation and must propagate the node's
           state by one integration step h.  If /update decides that
           the node should spike, it must set the variable /spike to
           true.

Both /calibrate and /update are called with the node's status
dictionary on top of the dictionary stack.  This means that node
variables override names in the systemdict or in the userdict.
Moreover, all definitions are done in the node's statusdict and
persist throughout the simulation.

Errors.
If an error occurs during the evaluation of /calibrate or /update, the
errorneous neuron is skipped and update proceeds to the next node
until the time-slice is finished. After the time-slice is finished,
simulation terminates with an additional error message that issues the
global id of the errorneous node.

Errors are handled by the SLI standard errorhandler. In addition, the
contents of the error dictionary is copied into the node's status
dictionary, to allow debugging of the node.

Parameters: 


Sends: SpikeEvent

Receives: SpikeEvent, CurrentEvent, DataLoggingRequest

Author: Diesmann, Plesser, Gewaltig
FirstVersion: January 2009
SeeAlso: iaf_psc_delta, iaf_psc_exp, iaf_cond_exp, testsuite::test_sli_neuron
*/

  class sli_neuron : public Archiving_Node
  {
    
  public:        
      
    sli_neuron();
    sli_neuron(const sli_neuron&);

    using Node::handle;
    using Node::handles_test_event;

    port send_test_event(Node&, rport, synindex, bool);
    
    void handle(SpikeEvent &);
    void handle(CurrentEvent &);
    void handle(DataLoggingRequest &);
    
    
    port handles_test_event(SpikeEvent&, rport);
    port handles_test_event(CurrentEvent&, rport);
    port handles_test_event(DataLoggingRequest&, rport);


    void get_status(DictionaryDatum &) const;
    void set_status(const DictionaryDatum &);

  private:

    DictionaryDatum get_status_dict_();

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

    void update(Time const &, const long_t, const long_t);

    void get(DictionaryDatum&) const;  
    void set(const DictionaryDatum&);  

    // The next two classes need to be friends to access the State_ class/member
    friend class RecordablesMap<sli_neuron>;
    friend class UniversalDataLogger<sli_neuron>;

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

    struct Buffers_ {
      Buffers_(sli_neuron &);
      Buffers_(const Buffers_ &, sli_neuron &);
      
      RingBuffer ex_spikes_;
      RingBuffer in_spikes_;
      RingBuffer currents_;


      UniversalDataLogger<sli_neuron> logger_;
    };

    // Access functions for UniversalDataLogger -------------------------------

    double_t get_V_m_() const
    {
      double vm = 0.0;
      if (state_->known(names::V_m))
        vm = getValue<double>(state_, names::V_m);
      
      return vm;
    }
    
    // ---------------------------------------------------------------- 

    DictionaryDatum state_;
    Token *vm_t; 
    Token *update_t; 
    Token *calibrate_t; 
    Token *in_spikes_t; 
    Token *ex_spikes_t; 
    Token *currents_t;  
    Token *last_spike_t; 
    Token *out_events_t; 
    Token *spike_t;//< Boolean for fast spike initiation
    Buffers_        B_;

    static RecordablesMap<sli_neuron> recordablesMap_;

  };

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

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

inline
port sli_neuron::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 
DictionaryDatum sli_neuron::get_status_dict_()
{
  return state_;
}

inline
void sli_neuron::get_status(DictionaryDatum &d) const
{
  // We needn't do anything else here, since d already points to 
  // sli_neuron::state_, because of Node::get_status_dict_(). 
  // 
  Archiving_Node::get_status(d);
  (*d)[names::recordables] = recordablesMap_.get_list();
}

inline
void sli_neuron::set_status(const DictionaryDatum &d)
{
  Archiving_Node::set_status(d);

  // To initialize the state dictionary, we copy all entries from d into s.
  // Later, the state dictionary will be in the interpreter and values are changed
  // automatically. SetStatus is then only needed to change properties of Archiving_Node.
  for ( TokenMap::const_iterator it = d->begin();it != d->end(); ++it)
  {
    state_->insert(it->first, it->second);
    it->second.set_access_flag();
  }
}

} // namespace

#endif /* #ifndef SLI_NEURON_H */