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
 
// C++ includes:
#include <vector>
 
// Includes from nestkernel:
#include "connection.h"
#include "device_node.h"
#include "exceptions.h"
#include "kernel_manager.h"
#include "nest_timeconverter.h"
#include "recording_device.h"
 
/* BeginUserDocs: device, recorder
 
Short description
+++++++++++++++++
 
Sampling continuous quantities from neurons
 
Description
+++++++++++
 
Most sampling use cases are covered by the ``multimeter``, which
allows to record analog values from neurons. Models which have such
values expose a ``recordables`` property that lists all recordable
quantities. This property can be inspected using ``GetDefaults`` on
the model class or ``GetStatus`` on a model instance. It cannot be
changed by the user.
 
::
 
   >>> nest.GetDefaults('iaf_cond_alpha')['recordables']
   ['g_ex', 'g_in', 't_ref_remaining', 'V_m']
 
The ``record_from`` property of a ``multimeter`` (a list, empty by
default) can be set to contain the name(s) of one or more of these
recordables to have them sampled during simulation.
 
::
 
   mm = nest.Create('multimeter', 1, {'record_from': ['V_m', 'g_ex'],
   'record_to': 'memory'})
 
The sampling interval for recordings (given in ms) can be controlled
using the ``multimeter`` parameter ``interval``. The default value of
1.0 ms can be changed by supplying a new value either in the call to
``Create`` or by using ``SetStatus`` on the model instance. To sample
values at every simulation time step, use
 
::
 
   nest.SetStatus(mm, {'interval': nest.resolution})
 
The recording interval must be greater than or equal to the
:ref:`simulation resolution <simulation_resolution>`, which defaults
to 0.1 ms.
 
.. warning::
 
   The set of variables to record from and the recording interval must
   be set **before** the ``multimeter`` is connected to any neuron.
   These properties cannot be changed afterwards.
 
After configuration, a ``multimeter`` can be connected to the neurons
it should record from by using the standard ``Connect`` routine.
 
::
 
    neurons = nest.Create('iaf_psc_alpha', 100)
    nest.Connect(mm, neurons)
 
To learn more about possible connection patterns and additional
options when using ``Connect``, see the guide on :ref:`connectivity
concepts <connectivity_concepts>`.
 
The above call to ``Connect`` would fail if the neurons would not
support the sampling of the values ``V_m`` and ``g_ex``. It would also
fail if carried out in the wrong direction, that is , trying to connect the
neurons to `mm`.
 
.. note::
 
   A pre-configured  ``multimeter`` is available under the name ``voltmeter``.  Its
   ``record_from`` property is already set to record the variable ``V_m``
   from the neurons it is connected to.
 
.. include:: ../models/recording_device.rst
 
record_from
    A list (default: `[]`) of parameters and state variables to sample
    from the nodes, the multimeter is connected to. Potential
    recordables are given in the corresponding model documentation.
 
interval
    A float (default: 1.0) specifying the interval in ms, at which
    data is collected from the nodes, the multimeter is connected to.
    Must be a multiple of the resolution.
 
See also
++++++++
 
Examples using this model
+++++++++++++++++++++++++
 
.. listexamples:: multimeter
 
EndUserDocs */
 
namespace nest
{
 
void register_multimeter( const std::string& name );
void register_voltmeter( const std::string& name );
 
class multimeter : public RecordingDevice
{
 
public:
  multimeter();
  multimeter( const multimeter& );
 
  bool
  has_proxies() const override
  {
    return false;
  }
 
  bool
  local_receiver() const override
  {
    return true;
  }
 
  std::string
  get_element_type() const override
  {
    return names::recorder;
  }
 
  using Node::handle;
  using Node::handles_test_event;
  using Node::sends_signal;
 
  size_t send_test_event( Node&, size_t, synindex, bool ) override;
 
  void handle( DataLoggingReply& ) override;
 
  SignalType sends_signal() const override;
 
  Type get_type() const override;
  void get_status( Dictionary& ) const override;
  void set_status( const Dictionary& ) override;
 
  void calibrate_time( const TimeConverter& tc ) override;
 
protected:
  void pre_run_hook() override;
 
  void update( Time const&, const long, const long ) override;
 
private:
  struct Buffers_;
 
  struct Parameters_
  {
    Time interval_;                           
    Time offset_;                             
    std::vector< std::string > record_from_;  
 
    Parameters_();
    Parameters_( const Parameters_& );
    Parameters_& operator=( const Parameters_& );
    void get( Dictionary& ) const;
    void set( const Dictionary&, const Buffers_&, Node* node );
  };
 
  // ------------------------------------------------------------
 
 
  struct Buffers_
  {
    Buffers_();
 
    bool has_targets_;
  };
 
  // ------------------------------------------------------------
 
 
  Parameters_ P_;
  Buffers_ B_;
};
 
 
inline void
multimeter::get_status( Dictionary& d ) const
{
  RecordingDevice::get_status( d );
  P_.get( d );
 
  if ( is_model_prototype() )
  {
    return;  // no data to collect
  }
 
  // if we are the device on thread 0, also get the data from the
  // siblings on other threads
  if ( get_thread() == 0 )
  {
    const std::vector< Node* > siblings = kernel().node_manager.get_thread_siblings( get_node_id() );
    std::vector< Node* >::const_iterator s;
    for ( s = siblings.begin() + 1; s != siblings.end(); ++s )
    {
      ( *s )->get_status( d );
    }
  }
}
 
inline void
multimeter::set_status( const Dictionary& d )
{
  // protect multimeter from being frozen
  bool freeze = false;
  if ( d.update_value( names::frozen, freeze ) and freeze )
  {
    throw BadProperty( "multimeter cannot be frozen." );
  }
 
  Parameters_ ptmp = P_;
  ptmp.set( d, B_, this );
 
  RecordingDevice::set_status( d );
  P_ = ptmp;
}
 
inline SignalType
multimeter::sends_signal() const
{
  return ALL;
}
 
inline void
multimeter::calibrate_time( const TimeConverter& tc )
{
  P_.interval_ = tc.from_old_tics( P_.interval_.get_tics() );
  P_.offset_ = tc.from_old_tics( P_.offset_.get_tics() );
}
 
 
//
// Declaration of voltmeter subclass
//
 
class voltmeter : public multimeter
{
public:
  voltmeter();
  voltmeter( const voltmeter& );
};
 
}  // namespace nest
 
#endif