Base class for all recording devices. More...

#include <recording_device.h>

Inheritance diagram for nest::RecordingDevice:

Classes
struct	Buffers_

struct	Parameters_

struct	State_

Public Types
enum	Mode { SPIKE_DETECTOR, MULTIMETER, SPIN_DETECTOR }
	Device mode. More...

Public Member Functions
	RecordingDevice (const Node &, Mode, const std::string &, bool, bool, bool=false)
	Create recording device information. More...

	RecordingDevice (const Node &, const RecordingDevice &)
	Copy from prototype member. More...

virtual	~RecordingDevice ()

void	init_parameters (const RecordingDevice &)

void	init_state (const RecordingDevice &)

void	init_buffers ()
	Close file stream. More...

void	calibrate ()
	Ensure streams are open for writing. More...

void	finalize ()
	Flush output stream if requested. More...

void	record_event (const Event &, bool endrecord=true)
	Record common information for one event. More...

template<typename ValueT >
void	print_value (const ValueT &, bool endrecord=true)
	Print single item of type ValueT. More...

bool	is_active (Time const &T) const
	Indicate if recording device is active. More...

void	get_status (DictionaryDatum &) const

void	set_status (const DictionaryDatum &)
	Set properties of recording device. More...

template<typename DataT >
void	set_status (const DictionaryDatum &, DataT &t)
	Special version for recorders that need to have their data cleared. More...

bool	to_screen () const

bool	to_file () const

bool	to_memory () const

bool	to_accumulator () const

void	set_precise (bool use_precise, long precision)

Public Member Functions inherited from nest::Device
	Device ()

	Device (const Device &n)

virtual	~Device ()

virtual void	init_parameters (const Device &)
	Reset parameters to those of model; also resets state. More...

virtual void	init_state (const Device &)
	Reset dynamic state to that of model. More...

long_t	get_t_min_ () const
	Return lower limit in steps. More...

long_t	get_t_max_ () const
	Return upper limit in steps. More...

Time const &	get_origin () const

Time const &	get_start () const

Time const &	get_stop () const

Private Member Functions
void	print_time_ (std::ostream &, const Time &, double offset)
	Print the time-stamp according to the recorder's flags. More...

void	print_id_ (std::ostream &, index)
	Print a node's global ID and/or address, according to the recorder's flags. More...

void	print_weight_ (std::ostream &, double)
	Print the weight of an event. More...

void	store_data_ (index, const Time &, double, double)
	Store data in internal structure. More...

void	clear_data_ ()
	Clear data in internal structure, and call clear_data_hook(). More...

void	flush_stream_ ()
	Flush output stream (not std::cout). More...

const std::string	build_filename_ () const
	Build filename from parts. More...

Private Attributes
const Node &	node_
	node to which device instance belongs More...

const Mode	mode_
	operating mode, depends on owning node More...

Parameters_	P_

State_	S_

Buffers_	B_

Buffers_	V_

Detailed Description

Base class for all recording devices.

Recording devices collect data and output it to the screen, store it internally or write it to files. This class provides for time windowing of data registration, temporary storage of data and output of data to files.

If the device is configured to record from start to stop, this is interpreted as (start, stop], i.e., the earliest recorded event will have time stamp start+1, as it was generated during the update step (start, start+1].

Class RecordingDevice by itself manages the identity and time of the recorded events, including precise event times, but not any additional data about the events. Use class AnalogRecordingDevice if you need to store additional data; that class also provides sampling at a given interval.

Note: The RecordingDevice class breaks the general persistence rules with respect to Parameters, State, Buffers and Variables. The central problem is that changes to /data_prefix in the root node require us to close output file streams and re-open them under new names. The only way to detect such changes is by comparing the current file name with a filename constructed anew upon each call to calibrate(). We cannot use init_buffers() here, since it is called only once after ResetNetwork. Thus, even though the file stream is a Buffer, we need to place all file opening in calibrate(). init_buffers() merely closes the stream if close_on_reset_ is true.

Todo:: Some aspects of RecordingDevice behavior depend on the type of device: Multimeter needs to have its data cleared on n_events==0 and provides an accumulator mode which is administered by RecordingDevice. To tell recording device about this deviating behavior, we mark the type of "owning device" with an enum flag on construction. This is not very clean and should probably be solved by subclassing instead.

Author: HEP 2002-07-22, 2008-03-21, 2011-02-11

Member Enumeration Documentation

enum nest::RecordingDevice::Mode

Device mode.

Enumerator
SPIKE_DETECTOR
MULTIMETER
SPIN_DETECTOR

Constructor & Destructor Documentation

nest::RecordingDevice::RecordingDevice	(	const Node &	n,
		Mode	mode,
		const std::string &	file_ext,
		bool	withtime,
		bool	withgid,
		bool	withweight = `false`
	)

Create recording device information.

Parameters

Node	of which the device is member.
Mode	of recording device.
Default	file name extension, excluding ".".
Default	value for withtime property
Default	value for withgid property
Default	value for withweight property

nest::RecordingDevice::RecordingDevice	(	const Node &	n,
		const RecordingDevice &	d
	)

Copy from prototype member.

Parameters

Node	of which the device is member.
Prototype	member to copy

virtual nest::RecordingDevice::~RecordingDevice ( )

inlinevirtual

Member Function Documentation

const std::string nest::RecordingDevice::build_filename_ ( ) const

private

Build filename from parts.

Note: This function returns the filename, it does not manipulate any data member.

References nest::Network::get_data_path(), nest::Network::get_data_prefix(), nest::Communicator::get_num_virtual_processes(), and nest::Node::network().

void nest::RecordingDevice::calibrate ( )

virtual

Ensure streams are open for writing.

See also: Introductory comment for class.

Reimplemented from nest::Device.

References assert(), nest::names::binary, nest::Device::calibrate(), SLIInterpreter::M_ERROR, SLIInterpreter::M_INFO, nest::Network::message(), nest::Node::network(), nest::Network::overwrite_files(), and nest::names::scientific.

Referenced by nest::Multimeter::calibrate().

void nest::RecordingDevice::clear_data_ ( )

private

Clear data in internal structure, and call clear_data_hook().

See also: clear_data_hook().

void nest::RecordingDevice::finalize ( )

virtual

Flush output stream if requested.

Reimplemented from nest::Device.

References SLIInterpreter::M_ERROR, nest::Network::message(), and nest::Node::network().

Referenced by nest::spin_detector::finalize(), nest::spike_detector::finalize(), and nest::Multimeter::finalize().

void nest::RecordingDevice::flush_stream_ ( )

private

Flush output stream (not std::cout).

void nest::RecordingDevice::get_status ( DictionaryDatum & d ) const

inlinevirtual

Reimplemented from nest::Device.

References nest::names::element_type, nest::RecordingDevice::Parameters_::get(), nest::RecordingDevice::State_::get(), nest::Device::get_status(), P_, nest::names::recorder, and S_.

void nest::RecordingDevice::init_buffers ( )

virtual

Close file stream.

See also: Introductory comment for class, calibrate()

Reimplemented from nest::Device.

References nest::Device::init_buffers().

Referenced by nest::Multimeter::init_buffers_().

void nest::RecordingDevice::init_parameters ( const RecordingDevice & pr )

References nest::Device::init_parameters(), P_, and S_.

void nest::RecordingDevice::init_state ( const RecordingDevice & pr )

References nest::Device::init_state(), and S_.

Referenced by nest::Multimeter::init_state_().

bool nest::RecordingDevice::is_active ( Time const & T ) const

inlinevirtual

Indicate if recording device is active.

The argument is the time stamp of the event, and the device is active if start_ < T <= stop_.

Implements nest::Device.

References nest::Time::get_steps(), nest::Device::get_t_max_(), and nest::Device::get_t_min_().

void nest::RecordingDevice::print_id_	(	std::ostream &	os,
		index	gid
	)

private

Print a node's global ID and/or address, according to the recorder's flags.

void nest::RecordingDevice::print_time_	(	std::ostream &	os,
		const Time &	t,
		double	offset
	)

private

Print the time-stamp according to the recorder's flags.

The following combinations are possible: time_in_steps & precise_times: give steps and offsets separately time_in_steps : give steps, ignore offsets precise_times: give time in ms, take into account offsets none set : give time in ms, ignore offsets

References nest::Time::get_ms(), and nest::Time::get_steps().

template<typename ValueT >

void nest::RecordingDevice::print_value	(	const ValueT &	value,
		bool	endrecord = `true`
	)

Print single item of type ValueT.

Parameters

endrecord pass false if more data is to come on same line.

References B_, nest::RecordingDevice::Buffers_::fs_, P_, nest::RecordingDevice::Parameters_::to_file_, and nest::RecordingDevice::Parameters_::to_screen_.

Referenced by nest::Multimeter::print_value_().

void nest::RecordingDevice::print_weight_	(	std::ostream &	os,
		double	weight
	)

private

Print the weight of an event.

void nest::RecordingDevice::record_event	(	const Event &	event,
		bool	endrecord = `true`
	)

Record common information for one event.

This function extracts sender and time information from the given event and handles it as specified by the Recorder settings. The following information is extracted:

time stamp
offset
sender ID
Parameters

endrecord pass false if more data is to come on same line

References nest::names::offset.

Referenced by nest::Multimeter::handle().

void nest::RecordingDevice::set_precise	(	bool	use_precise,
		long	precision
	)

inline

References P_, nest::RecordingDevice::Parameters_::precise_times_, nest::names::precision, and nest::RecordingDevice::Parameters_::precision_.

void nest::RecordingDevice::set_status ( const DictionaryDatum & d )

virtual

Set properties of recording device.

Setting properties of recording devices is special:

Changing /label will close the current stream and open a new stream on next call to Simulate (if recording to file)
The state cannot be set, except that passing "/n_events 0" will clear all stored data from memory (no effect on file streams)
Passing "/close_stream true" will close the output stream if writing to a file. NB: The next call to Simulate will re-open the file, over- writing it.
Modifying /data_prefix in the root node will close the current stream and open a new stream on next call to Simulate (if recording to file).

Reimplemented from nest::Device.

References nest::RecordingDevice::State_::clear_events(), nest::RecordingDevice::Parameters_::set(), nest::RecordingDevice::State_::set(), and nest::Device::set_status().

Referenced by set_status().

template<typename DataT >