recording_device.h

Go to the documentation of this file.

/*
 *  recording_device.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 RECORDING_DEVICE_H
#define RECORDING_DEVICE_H
 
// C++ includes:
#include <fstream>
#include <vector>
 
// Includes from nestkernel:
#include "device.h"
#include "device_node.h"
#include "kernel_manager.h"
#include "nest_types.h"
#include "node.h"
#include "recording_backend.h"
 
 
namespace nest
{
 
/* BeginUserDocs: NOINDEX
 
Short description
+++++++++++++++++
 
Recording device
 
Description
+++++++++++
 
Recording time window
+++++++++++++++++++++
 
The time span during which the recorder actively records can be
specified using the properties ``start`` and ``stop``. These define
the recording period of the device in ms. An additional property
``origin`` allows to shift the recording window by a certain time,
which can be useful in experimental protocols with :ref:`repeated
simulations <stepped_simulations>`. Please note that events with
timestamp `t = start` are not recorded.
 
Data handling
+++++++++++++
 
All recorded data is handed over to the recording backend, selected
via the ``record_to`` property::
 
   >>> sr  = nest.Create("spike_recorder", params={"record_to":"ascii", "time_in_steps": False})
   >>> mm = nest.Create("multimeter", 1, {"record_from": ["V_m", "g_ex"], "record_to": "memory"})
 
 
By default, data recorded from recorders is stored in the `memory` backend.
You can access the data recorded by the recorders with the ``events`` property.
 
::
 
   mm_events = mm.get("events")
 
.. note::
 
   The type of recording backend you choose may affect the efficiency of your simulation.
   The  `memory` backend is ideal for interactive work, but can only be used for limited
   amount of data. Additionally, transferring data to disk later on may be slower than
   directly writing from the NEST kernel via `ascii` or `sionlib` backends.
 
   Large simulations with many threads may benefit from the `sionlib` backend, as the `ascii`
   backend opens many files which can be very time consuming on parallel file systems.
 
   The complete list of parameters and other recording backend options
   can be found in the :ref:`guide to recording from simulations <recording_backends>`.
 
Recorder properties
+++++++++++++++++++
 
label
    A string (default: `""`) specifying an arbitrary textual label for
    the device.  Recording backends might use the label to generate
    device specific identifiers like filenames and such.
 
n_events
    The number of events that were collected by the recorder can be
    read out of the `n_events` entry. The number of events can be reset
    to 0. Other values cannot be set.
 
origin
    A positive floating point number (default : `0.0`) used as the
    reference time in ms for `start` and `stop`.
 
record_to
    A string (default: `"memory"`) containing the name of the recording
    backend where to write data to. An empty string turns all recording
    of individual events off.
 
start
    A positive floating point number (default: `0.0`) specifying the
    activation time in ms, relative to `origin`.
 
stop
    A floating point number (default: `infinity`) specifying the
    deactivation time in ms, relative to `origin`. The value of `stop`
    must be greater than or equal to `start`.
 
EndUserDocs */
 
class RecordingDevice : public DeviceNode, public Device
{
public:
  RecordingDevice();
  RecordingDevice( const RecordingDevice& );
 
  using Device::pre_run_hook;
  using Node::pre_run_hook;
  void pre_run_hook( const std::vector< std::string >&, const std::vector< std::string >& );
 
  bool is_active( Time const& T ) const override;
 
  enum Type
  {
    MULTIMETER,
    SPIKE_RECORDER,
    SPIN_DETECTOR,
    WEIGHT_RECORDER
  };
 
  virtual Type get_type() const = 0;
 
  const std::string& get_label() const;
 
  void set_status( const Dictionary& ) override;
  void get_status( Dictionary& ) const override;
 
protected:
  void write( const Event&, const std::vector< double >&, const std::vector< long >& );
  void set_initialized_() override;
 
private:
  struct Parameters_
  {
    std::string label_;      
    std::string record_to_;  
 
    Parameters_();
    Parameters_( const Parameters_& ) = default;
    Parameters_& operator=( const Parameters_& ) = default;
    void get( Dictionary& ) const;
    void set( const Dictionary& );
  } P_;
 
  struct State_
  {
    size_t n_events_;  
 
    State_();
    void get( Dictionary& ) const;
    void set( const Dictionary& );
  } S_;
 
  Dictionary backend_params_;
};
 
}  // namespace
 
#endif /* #ifndef RECORDING_DEVICE_H */