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

#include "nest.h"
#include "dictdatum.h"
#include "dictutils.h"
#include "lockptr.h"
#include "device.h"

#include <vector>
#include <fstream>

namespace nest {

  /*BeginDocumentation
    Name: RecordingDevice - Common properties of all recording devices.
    Description:

    Recording devices are used to measure properties of or signals emitted
    by network nodes, e.g., using a voltmeter or a spike detector. 

    Recording devices can collect data in memory, display it on the terminal 
    output or write it to file in any combination. The output format can be
    controlled by device parameters as discussed below.
    
    Recording devices can be subdivided into two groups: collectors and samplers.
    - Collectors collect events sent to them; the spike detector is the archetypical
      example. Nodes are connected to collectors and the collector then collects all
      spikes emitted by the nodes connected to it and records them.
    - Samplers actively interrogate their targets at given time intervals (default: 1ms),
      and record the data they obtain. This means that the sampler must be connected
      to the node (not the node to the sampler), and that the node must support the
      particular type of sampling; see device specific documentation for details.

    Recording devices share the start, stop, and origin parameters global to
    devices. Start and stop have the following meaning for stimulating devices
    (origin is just a global offset):
    - Collectors collect all events with timestamps T that fulfill
        start < T <= stop.
      Note that events with timestamp T == start are NOT recorded.
    - Sampling devices sample at times t = nh with
        start < t <= stop
        (t-start) mod interval == 0

    Remarks:
    - Recording devices can only reliably record data generated during the previous
      min_delay interval. This means that in order to ensure consistent results,
      you should always set a stop time for a recording device that is at least
      one min_delay before the end of the simulation time.
    - By default, devices record to memory. If you want to record to file, it may
      be a good idea to turn off recording to memory, to avoid that you computer's
      memory fills up with gigabytes of data: << /to_file true /to_memory false >>.
    - Events are not necessarily recorded in chronological order.
    - The device will not open an existing file, since that would erase the existing
      data in the file. If you want existing files to be overwritten automatically,
      you must set /overwrite_files in the root node.

    Parameters:
    The following parameters are shared with all devices:
    /start  - Actication time, relative to origin.
    /stop   - Inactivation time, relative to origin. 
    /origin - Reference time for start and stop.

    The following parameter is only relevant for sampling devices:
    /interval - Sampling interval in ms (default: 1ms).

    The following parameters control where output is sent/data collected:
    /record_to - An array containing any combination of /file, /memory, /screen,
                 indicating whether to write to file, record in memory or write
                 to the console window. An empty array turns all recording of
                 individual events off, only an event count is kept. You can also pass 
                 strings (file), (memory), (screen), mainly for compatibility with
                 Python.
                
                 The name of the output file is 
                   data_path/data_prefix(label|model_name)-gid-vp.file_extension

                 See /label and /file_extension for how to change the name. /data_prefix
                 is changed in the root node. If you change any part of the name,
                 an open file will be closed and a new file opened.
                 
                 To close the file, pass a /record_to array without /file, or pass
                 /to_file false. If you later turn recording to file on again, the
                 file will be overwritten, unless you have changed data_prefix, label,
                 or file_extension.
                 
    /to_file   - If true, turn on recording to file. Similar to /record_to [/file], but
                 does not affect settings for recording to memory and screen. 
    /to_screen - If true, turn on recording to screen. Similar to /record_to [/screen], but
                 does not affect settings for recording to memory and file. 
    /to_memory - If true, turn on recording to memory Similar to /record_to [/memory], but
                 does not affect settings for recording to file and screen.

    /filenames - Array containing the filenames where data is recorded to. This array has one
                 entry per local thread and is only available if /to_file is set to true, or
                 if /record_to contains /to_file.

    /label     - String specifying an arbitrary label for the device. It is used instead of
                 model_name in the output file name.
    /file_extension - String specifying the file name extension, without leading dot. The
                      default depends on the specific device.
    /close_after_simulate - Close output stream before Simulate returns. If set to false, any output
                            streams will remain open when Simulate returns. (Default: false).
    /flush_after_simulate - Flush output stream before Simulate returns. If set to false, any output
                 streams will be in an undefined state when Simulate returns. (Default: true).
    /flush_records - Flush output stream whenever new data has been written to the stream. This
                    may impede performance (Default: false).
    /close_on_reset - Close output file stream upon ResetNetwork. Upon the next call to Simulate,
                      the file is reopened, overwriting its contents. If set to false, the file
                      will remain open after ResetNetwork, so you can record continuously. NB:
                      the file is always closed upon ResetKernel. (Default: true).
    
    The following parameters control how output is formatted:
    /withtime      - boolean value which specifies whether the network time should be 
                     recorded (default: true).
    /withgid       - boolean value which specifies whether the global id of the observed node(s)
                     should be recorded (default: false).
    /withweight    - boolean value which specifies whether the weight of the event should be
                     recorded (default: false).
    /time_in_steps - boolean value which specifies whether to print time in steps, i.e., multiples 
                     of the resolution, rather than in ms. If combined with /precise_times, each
                     time is printed as a pair of an integer step number and a double offset < 0.
    /precise_times - boolean value which specifies whether offsets describing the precise timing 
                     of a spike within a time step should be taken into account when computing
                     the spike time. This is only useful when recording from neurons that can
                     emit spikes off-grid (see module precise). Times are given in milliseconds.
                     If /time_in_steps is true, times are given as steps and negative offset.
    /scientific    - if set to true, doubles are written in scientific format, otherwise in
                     fixed format; affects file output only, not screen output (default: false)
    /precision     - number of digits to use in output of doubles to file (default: 3)
    /binary        - if set to true, data is written in binary mode to files instead of ASCII.
                     This setting affects file output only, not screen output (default: false)
    /fbuffer_size  - the size of the buffer to use for writing to files. The default size is
                     determined by the implementation of the C++ standard library. To obtain an
                     unbuffered file stream, use a buffer size of 0.

    Data recorded in memory is available through the following parameter:
    /n_events      - Number of events collected or sampled. n_events can be set to 0, but
                     no other value. Setting n_events to 0 will delete all spikes recorded
                     in memory. n_events will count events even when not recording to memory.
    /events        - Dictionary with elements /senders (sender GID, only if /withgid or /withpath
                     are true), /times (spike times in ms or steps, depending on /time_in_steps; 
                     only if /withtime is true) and /offsets (only if /time_in_steps,
                     /precise_times and /withtime are true). All data stored in memory
                     is erased when /n_events is set to 0. 
                                          
    SeeAlso: Device, StimulatingDevice
  */


  class RecordingDevice : public Device 
  {

  public:
    enum Mode { SPIKE_DETECTOR, MULTIMETER, SPIN_DETECTOR };

    RecordingDevice(const Node&, Mode, const std::string&, bool, bool, bool=false);

    RecordingDevice(const Node&, const RecordingDevice&);
    virtual ~RecordingDevice() {}

    using Device::init_parameters;
    void init_parameters(const RecordingDevice&);

    using Device::init_state;
    void init_state(const RecordingDevice&);

    void init_buffers();

    void calibrate();
    
    void finalize();

    void record_event(const Event&, bool endrecord = true);
    
    template <typename ValueT>
    void print_value(const ValueT&, bool endrecord = true);

    bool is_active(Time const & T) const;

    void get_status(DictionaryDatum &) const;
    
    void set_status(const DictionaryDatum &);
    
    template <typename DataT>
    void set_status(const DictionaryDatum &, DataT& t);
    
    bool to_screen() const { return P_.to_screen_; }
    bool to_file()   const { return P_.to_file_;   }
    bool to_memory() const { return P_.to_memory_; }
    bool to_accumulator() const { return P_.to_accumulator_; }

    inline
      void set_precise(bool use_precise, long precision);

  private:

    void print_time_(std::ostream&, const Time&, double offset);

    void print_id_(std::ostream&, index);

    void print_weight_(std::ostream&, double);

    void store_data_(index, const Time&, double, double);
    
    void clear_data_();
    
    void flush_stream_();
    
    const std::string build_filename_() const;
 
    // ------------------------------------------------------------------
    
    struct Buffers_ {
      std::ofstream fs_; 
    };

    // ------------------------------------------------------------------
    
    struct Parameters_ {  
      bool to_file_;       
      bool to_screen_;     
      bool to_memory_;     
      bool to_accumulator_;
      bool time_in_steps_; 
      bool precise_times_; 
      bool withgid_;       
      bool withtime_;      
      bool withweight_;    

      long precision_;     
      bool scientific_;    

      bool binary_;            
      long fbuffer_size_;      
      long fbuffer_size_old_;  

      std::string label_;    
      std::string file_ext_; 
      std::string filename_; 
      bool close_after_simulate_;    
      bool flush_after_simulate_;    
      bool flush_records_;   
      bool close_on_reset_;  

      Parameters_(const std::string&, bool, bool, bool);

      void get(const RecordingDevice&, DictionaryDatum&) const;  
      void set(const RecordingDevice&, const Buffers_&, const DictionaryDatum&);  
    };

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

    struct State_ {
      size_t                events_;              
      std::vector<long>     event_senders_;       
      std::vector<double_t> event_times_ms_;      
      std::vector<long>     event_times_steps_;   
      std::vector<double_t> event_times_offsets_; 
      std::vector<double_t> event_weights_;       

      State_();  
      
      void clear_events();   
      void get(DictionaryDatum&, const Parameters_&) const;  
      void set(const DictionaryDatum&);                      
    };

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

    const Node& node_;  
    const Mode  mode_;  
    Parameters_ P_;
    State_      S_;
    Buffers_    B_;
    Buffers_    V_;
};


inline
bool RecordingDevice::is_active(Time const & T) const
{
  const long_t stamp = T.get_steps();
  
  return get_t_min_() < stamp && stamp <= get_t_max_();
}

inline
void RecordingDevice::get_status(DictionaryDatum &d) const
{
  P_.get(*this, d);
  S_.get(d, P_);
  Device::get_status(d);
    
  (*d)[names::element_type] = LiteralDatum(names::recorder);
}

inline
void RecordingDevice::set_precise(bool use_precise, long precision)
{
  P_.precise_times_ = use_precise;
  P_.precision_ = precision;
}



template <typename ValueT>
void RecordingDevice::print_value(const ValueT& value, bool endrecord)
{
  if ( P_.to_screen_ )
  {
    std::cout << value << '\t';
    if ( endrecord )
      std::cout << '\n';
  }

  if ( P_.to_file_ )
  {
    B_.fs_ << value << '\t';
    if ( endrecord )
      B_.fs_ << '\n';
  }
}

template <typename DataT>
void RecordingDevice::set_status(const DictionaryDatum &d, DataT& data)
{
  // plain set_status does most of the work
  set_status(d);
  
  // if n_events is 0, also clear event data
  if ( S_.events_ == 0 )
    data.clear();
}

} // namespace

#endif  // RECORDING_DEVICE_H