1 /* 2 * recording_device.h 3 * 4 * This file is part of NEST. 5 * 6 * Copyright (C) 2004 The NEST Initiative 7 * 8 * NEST is free software: you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation, either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * NEST is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with NEST. If not, see <http://www.gnu.org/licenses/>. 20 * 21 */ 22 23 #ifndef RECORDING_DEVICE_H 24 #define RECORDING_DEVICE_H 25 26 // C++ includes: 27 #include <fstream> 28 #include <vector> 29 30 // Includes from nestkernel: 31 #include "node.h" 32 #include "device.h" 33 #include "device_node.h" 34 #include "recording_backend.h" 35 #include "nest_types.h" 36 #include "kernel_manager.h" 37 38 // Includes from sli: 39 #include "dictdatum.h" 40 #include "dictutils.h" 41 42 namespace nest 43 { 44 45 /* BeginUserDocs: NOINDEX 46 47 Recording time window 48 +++++++++++++++++++++ 49 50 The time span during which the recorder actively records can be 51 specified using the properties ``start`` and ``stop``. These define 52 the recording period of the device in ms. An additional property 53 ``origin`` allows to shift the recording window by a certain time, 54 which can be useful in experimental protocols with :ref:`repeated 55 simulations <stepped_simulations>`. Please note that events with 56 timestamp `t = start` are not recorded. 57 58 Data handling 59 +++++++++++++ 60 61 All recorded data is handed over to the recording backend, selected 62 via the ``record_to`` property. More details on available backends and 63 their properties can be found in the :ref:`guide to recording from 64 simulations <recording_backends>`. 65 66 Recorder properties 67 +++++++++++++++++++ 68 69 label 70 A string (default: `""`) specifying an arbitrary textual label for 71 the device. Recording backends might use the label to generate 72 device specific identifiers like filenames and such. 73 74 n_events 75 The number of events that were collected by the recorder can be 76 read out of the `n_events` entry. The number of events can be reset 77 to 0. Other values cannot be set. 78 79 origin 80 A positive floating point number (default : `0.0`) used as the 81 reference time in ms for `start` and `stop`. 82 83 record_to 84 A string (default: `"memory"`) containing the name of the recording 85 backend where to write data to. An empty string turns all recording 86 of individual events off. 87 88 start 89 A positive floating point number (default: `0.0`) specifying the 90 activation time in ms, relative to `origin`. 91 92 stop 93 A floating point number (default: `infinity`) specifying the 94 deactivation time in ms, relative to `origin`. The value of `stop` 95 must be greater than or equal to `start`. 96 97 EndUserDocs */ 98 99 /** 100 * Base class for all recording devices. 101 * 102 * Recording devices collect or sample data and output it to one or 103 * more recording backends selected by setting the device property 104 * `record_to` to the name of the backend. 105 * 106 * Class RecordingDevice is merely a shallow interface class from 107 * which concrete recording devices can inherit in order to use the 108 * recording backend infrastructure more easily and provide a 109 * consistent handling of activity windows by means of start/stop and 110 * origin. 111 * 112 * If the device is configured to record from start to stop, this 113 * is interpreted as (start, stop], i.e., the earliest recorded 114 * event will have time stamp start+1, as it was generated during 115 * the update step (start, start+1]. 116 * 117 * If the device node is not an actual instance used by the user, but 118 * rather a prototype node in a Model class, it will cache 119 * device-specific properties of the recording backend and use them 120 * for enrollment of the device with the backend as the last step 121 * during the creation of instances. This mechanism is implemented in 122 * set_status() and set_initialized_(). 123 * 124 * @ingroup Devices 125 * 126 * @author HEP 2002-07-22, 2008-03-21, 2011-02-11 127 */ 128 129 class RecordingDevice : public DeviceNode, public Device 130 { 131 public: 132 RecordingDevice(); 133 RecordingDevice( const RecordingDevice& ); 134 135 using Device::calibrate; 136 using Node::calibrate; 137 void calibrate( const std::vector< Name >&, const std::vector< Name >& ); 138 139 bool is_active( Time const& T ) const override; 140 141 enum Type 142 { 143 MULTIMETER, 144 SPIKE_RECORDER, 145 SPIN_DETECTOR, 146 WEIGHT_RECORDER 147 }; 148 149 virtual Type get_type() const = 0; 150 151 const std::string& get_label() const; 152 153 void set_status( const DictionaryDatum& ) override; 154 void get_status( DictionaryDatum& ) const override; 155 156 protected: 157 void write( const Event&, const std::vector< double >&, const std::vector< long >& ); 158 void set_initialized_() override; 159 160 private: 161 struct Parameters_ 162 { 163 std::string label_; //!< A user-defined label for symbolic device names. 164 Name record_to_; //!< The name of the recording backend to use 165 166 Parameters_(); 167 Parameters_( const Parameters_& ) = default; 168 void get( DictionaryDatum& ) const; 169 void set( const DictionaryDatum& ); 170 } P_; 171 172 struct State_ 173 { 174 size_t n_events_; //!< The number of events recorded by the device. 175 176 State_(); 177 void get( DictionaryDatum& ) const; 178 void set( const DictionaryDatum& ); 179 } S_; 180 181 DictionaryDatum backend_params_; 182 }; 183 184 } // namespace 185 186 #endif // RECORDING_DEVICE_H 187