multimeter.h

Go to the documentation of this file.

/*
 *  multimeter.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 MULTIMETER_H
#define MULTIMETER_H

#include <vector>

#include "recording_device.h"
#include "name.h"
#include "node.h"
#include "connection.h"
#include "dictutils.h"
#include "exceptions.h"
#include "sibling_container.h"

/*BeginDocumentation
Name: multimeter - Device to record analog data from neurons.
Synopsis: multimeter Create

Description:
A multimeter records a user-defined set of state variables from connected nodes to memory,
file or stdout. 

The multimeter must be configured with the list of variables to record
from, otherwise it will not record anything. The /recordables property
of a neuron model shows which quantities can be recorded with a multimeter.
A single multimeter should only record from neurons of the same basic
type (e.g. /iaf_cond_alpha and any user-defined models derived from it
using CopyModel). If the defaults or status dictionary of a model neuron
does not contain a /recordables entry, it is not ready for use with
multimeter.

By default, multimeters record values once per ms. Set the parameter /interval to
change this. The recording interval cannot be smaller than the resolution.

Results are returned in the /events entry of the status dictionary. For
each recorded quantity, a vector of doubles is returned. The vector has the
same name as the /recordable. If /withtime is set, times are given in the
/times vector in /events.

Accumulator mode:
Multimeter can operate in accumulator mode. In this case, values for all recorded
variables are added across all recorded nodes (but kept separate in time). This can
be useful to record average membrane potential in a population.

To activate accumulator mode, either set /to_accumulator to true, or set
/record_to [ /accumulator ].  In accumulator mode, you cannot record to file,
to memory, to screen, with GID or with weight. You must activate accumulator mode
before simulating. Accumulator data is never written to file. You must extract it
from the device using GetStatus.

Note:
 - The set of variables to record and the recording interval must be set
   BEFORE the multimeter is connected to any node, and cannot be changed
   afterwards.
 - A multimeter cannot be frozen.
 - If you record with multimeter in accumulator mode and some of the nodes
   you record from and others are not, data will only be collected from the
   unfrozen nodes. Most likely, this will lead to confusing results, so
   you should not use multimeter with frozen nodes.

Parameters: 
     The following parameters can be set in the status dictionary:
     interval     double - Recording interval in ms
     record_from  array  - Array containing the names of variables to record
                           from, obtained from the /recordables entry of the
                           model from which one wants to record
  
Examples:
SLI ] /iaf_cond_alpha Create /n Set
SLI ] n /recordables get ==
[/V_m /g_ex /g_in /t_ref_remaining]
SLI ] /multimeter Create /mm Set
SLI ] mm << /interval 0.5 /record_from [/V_m /g_ex /g_in] >> SetStatus
SLI ] mm n Connect
SLI ] 10 Simulate
SLI ] mm /events get info
--------------------------------------------------
Name                     Type                Value
--------------------------------------------------
g_ex                     doublevectortype    <doublevectortype>
g_in                     doublevectortype    <doublevectortype>
senders                  intvectortype       <intvectortype>
times                    doublevectortype    <doublevectortype>
t_ref_remaining          doublevectortype    <doublevectortype>
V_m                      doublevectortype    <doublevectortype>
--------------------------------------------------
Total number of entries: 6


Sends: DataLoggingRequest

FirstVersion: 2009-04-01

Author: Hans Ekkehard Plesser

SeeAlso: Device, RecordingDevice
*/

namespace nest {
  
  class Network;

  class Multimeter : public Node {

  public:
    Multimeter();
    Multimeter(const Multimeter&);     
    
    bool has_proxies() const { return false; } 

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

    port send_test_event(Node&, rport, synindex, bool);

    void handle(DataLoggingReply&);

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

  protected:
    void init_state_(Node const&);
    void init_buffers_();
    void calibrate();
    void finalize();

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

    bool is_active(Time const & T) const;
    
    void print_value_(const std::vector<double_t>&);
    
    void add_data_(DictionaryDatum&) const;

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

    RecordingDevice device_;

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

    struct Buffers_;

    struct Parameters_ {
      Time interval_;                 
      std::vector<Name> record_from_; 
      
      Parameters_();
      Parameters_(const Parameters_&);
      void get(DictionaryDatum&) const;
      void set(const DictionaryDatum&, const Buffers_&);
    };

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

    struct State_ {
      std::vector<std::vector<double_t> > data_;      
    };

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

    struct Buffers_ {
      Buffers_();

      bool has_targets_;
    };

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

    struct Variables_ {
        bool new_request_;

        size_t current_request_data_start_;
    };

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

    Parameters_ P_;
    State_      S_;
    Buffers_    B_;
    Variables_  V_;
  };
  

  inline
  void nest::Multimeter::get_status(DictionaryDatum &d) const
  {
    // get the data from the device
    device_.get_status(d);
    
    // we need to add analog data to the events dictionary
    DictionaryDatum dd = getValue<DictionaryDatum>(d, names::events);
    add_data_(dd);

    // if we are the device on thread 0, also get the data from the
    // siblings on other threads
    if (get_thread() == 0)
    {
      const SiblingContainer* siblings = network()->get_thread_siblings(get_gid());
      std::vector<Node*>::const_iterator sibling;
      for (sibling = siblings->begin() + 1; sibling != siblings->end(); ++sibling)
        (*sibling)->get_status(d);
    }

    P_.get(d);
  }

  inline
  void nest::Multimeter::set_status(const DictionaryDatum &d)
  {
    // protect Multimeter from being frozen
    bool freeze = false;
    if ( updateValue<bool>(d, names::frozen, freeze) && freeze )
      throw BadProperty("Multimeter cannot be frozen.");

    Parameters_ ptmp = P_;
    ptmp.set(d, B_);
    
    // Set properties in device. As a side effect, this will clear data_,
    // if /clear_events set in d
    device_.set_status(d, S_.data_);

    P_ = ptmp;
  }
  

} // Namespace

#endif