Abstract base class for all NESTio recording backends. More...

#include <recording_backend.h>

Inheritance diagram for nest::RecordingBackend:

Public Member Functions
	RecordingBackend ()

virtual	~RecordingBackend () throw ()

virtual void	initialize ()=0

virtual void	finalize ()=0

virtual void	enroll (const RecordingDevice &device, const Dictionary &params)=0
	Enroll a `RecordingDevice` with the `RecordingBackend`.

virtual void	disenroll (const RecordingDevice &device)=0
	Disenroll a `RecordingDevice` from the `RecordingBackend`.

virtual void	set_value_names (const RecordingDevice &device, const std::vector< std::string > &double_value_names, const std::vector< std::string > &long_value_names)=0
	To make the names of recorded quantities known to the `RecordingBackend`, the vectors `double_value_names` and `long_value_names` can be set appropriately.

virtual void	prepare ()=0
	Prepare the backend at begin of the NEST Simulate function.

virtual void	cleanup ()=0
	Clean up the backend at the end of a user level call to the NEST Simulate function.

virtual void	pre_run_hook ()=0
	Initialize global backend-specific data structures.

virtual void	post_run_hook ()=0
	Clean up the backend at the end of a Run.

virtual void	post_step_hook ()=0
	Do work required at the end of each simulation step.

virtual void	write (const RecordingDevice &device, const Event &event, const std::vector< double > &double_values, const std::vector< long > &long_values)=0
	Write the data from the event to the backend specific channel together with the values given.

virtual void	set_status (const Dictionary &params)=0
	Set the status of the recording backend using the key-value pairs contained in the params dictionary.

virtual void	get_status (Dictionary &params) const =0
	Return the status of the recording backend by writing it to the given params dictionary.

virtual void	check_device_status (const Dictionary &params) const =0
	Check if the given per-device properties are valid and usable by the backend.

virtual void	get_device_defaults (Dictionary &params) const =0
	Return the per-device defaults by writing it to the given params dictionary.

virtual void	get_device_status (const RecordingDevice &device, Dictionary &params) const =0
	Return the per-device status of the given recording device by writing it to the given params dictionary.

Static Public Attributes
static const std::vector< std::string >	NO_DOUBLE_VALUE_NAMES

static const std::vector< std::string >	NO_LONG_VALUE_NAMES

static const std::vector< double >	NO_DOUBLE_VALUES

static const std::vector< long >	NO_LONG_VALUES

Detailed Description

Abstract base class for all NESTio recording backends.

This class provides the interface for the NESTio recording backends with which RecordingDevices can be enrolled for recording and which they can use to write their data.

Built-in recording backends are registered in the constructor of IOManager by inserting an instance of each of them into a std::map under the name of the backend.

A user level call to Simulate internally executes the sequence Prepare → Run → Cleanup. During Prepare, the prepare() function of each backend is called by the IOManager. This gives the backend an opportunity to prepare data structures for the upcoming simulation cycle.

The user level function Run drives the simulation main loop by uptating all nodes. At its beginning it calls pre_run_hook() on each recording backend via the IOManager. At the end of each run, it calls post_run_hook() respectively.

During the simulation, recording devices call IOManager::write() in order to record data. These calls are forwarded to the backend, the device is enrolled with. Cleanup on the user level finally calls the cleanup() function of all backends.

Constructor & Destructor Documentation

◆ RecordingBackend()

nest::RecordingBackend::RecordingBackend ( )

inline

◆ ~RecordingBackend()

virtual nest::RecordingBackend::~RecordingBackend	(	)
throw	(
	)

inlinevirtual

Member Function Documentation

◆ check_device_status()

virtual void nest::RecordingBackend::check_device_status ( const Dictionary & params ) const

pure virtual

Check if the given per-device properties are valid and usable by the backend.

This function is used to validate properties when SetDefaults is called on a recording device. If the properties are found to be valid, they will be cached in the recording device and set for individual instances by means of the call to enroll from the device's set_initialized_() function. In case the properties are invalid, this function is expected to throw BadProperty.

Parameters

params the parameter dictionary to validate

See also: get_device_defaults(), get_device_status()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ cleanup()

virtual void nest::RecordingBackend::cleanup ( )

pure virtual

Clean up the backend at the end of a user level call to the NEST Simulate function.

This function is called by SimulationManager::cleanup() and allows the backend to close open files or network connections or take similar action.

See also: prepare()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ disenroll()

virtual void nest::RecordingBackend::disenroll ( const RecordingDevice & device )

pure virtual

Disenroll a RecordingDevice from the RecordingBackend.

This function is considered to be the opposite of enroll() in the sense that it cancels the enrollment of a RecordingDevice from a RecordingBackend by deleting all device specific data. When setting a new recording backend for a recording device, this function is called for each backend the device is not enrolled with.

Parameters

device the RecordingDevice to be disenrolled

See also: enroll()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ enroll()

virtual void nest::RecordingBackend::enroll	(	const RecordingDevice &	device,
		const Dictionary &	params
	)

pure virtual

Enroll a RecordingDevice with the RecordingBackend.

When this function is called by a RecordingDevice device, the RecordingBackend can set up per-device data structures and properties. Individual device instances can be identified using the thread and node_id of the device.

This function is called from the set_initialized_() function of the device and their set_status() function. The companion function set_value_names() is called from Node::pre_run_hook() and makes the names of values to be recorded known.

A backend needs to be able to cope with multiple calls to this function, as multiple calls to set_status() may occur on the device. For already enrolled devices this usually means that only the parameters in params have to be set, but no further actions are needed.

Each recording backend must ensure that enrollment (including all settings made by the user) is persistent over multiple calls to Prepare, while the enrollment of all devices should end with a call to finalize().

A common implementation of this function will create an entry in a thread-local map, associating the device's node ID with the device-specific backend properties and an output facility of some kind.

Parameters

device	the RecordingDevice to be enrolled
params	device-specific backend parameters

See also: set_value_names(), disenroll(), write(),

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ finalize()

virtual void nest::RecordingBackend::finalize ( )

pure virtual

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ get_device_defaults()

virtual void nest::RecordingBackend::get_device_defaults ( Dictionary & params ) const

pure virtual

Return the per-device defaults by writing it to the given params dictionary.

Parameters

params the dictionary to add device-specific backend parameters to

See also: check_device_status(), get_device_status()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ get_device_status()

virtual void nest::RecordingBackend::get_device_status	(	const RecordingDevice &	device,
		Dictionary &	params
	)		const

pure virtual

Return the per-device status of the given recording device by writing it to the given params dictionary.

Please note that a corresponding setter function does not exist. Device-specific backend parameters are given in the call to enroll.

Parameters

device	the recording device for which the status is returned
params	the dictionary to add device-specific backend parameters to

See also: enroll(), check_device_status(), get_device_defaults()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendScreen, nest::RecordingBackendMPI, and nest::RecordingBackendSIONlib.

◆ get_status()

virtual void nest::RecordingBackend::get_status ( Dictionary & params ) const

pure virtual

Return the status of the recording backend by writing it to the given params dictionary.

Parameters

params the status of the recording backend

See also: set_status()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ initialize()

virtual void nest::RecordingBackend::initialize ( )

pure virtual

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ post_run_hook()

virtual void nest::RecordingBackend::post_run_hook ( )

pure virtual

Clean up the backend at the end of a Run.

This is called right before SimulationManager::run() terminates. It allows the backend to flush open files, write remaining data to the screen, or perform similar operations that make sure that the user has access to all data from the previous simulation run.

See also: pre_run_hook()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ post_step_hook()

virtual void nest::RecordingBackend::post_step_hook ( )

pure virtual

Do work required at the end of each simulation step.

This is called at the very end of each simulation step. It can for example be used to carry out writing to files in a synchronized way, all threads on all MPI processes performing it at the same time.

See also: pre_run_hook()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ pre_run_hook()

virtual void nest::RecordingBackend::pre_run_hook ( )

pure virtual

Initialize global backend-specific data structures.

This function is called on each backend right at the very beginning of SimulationManager::run(). It can be used for initializations which have to be repeated at the beginning of every single call to run in a prepare-run-run-...-run-run-cleanup sequence.

See also: post_run_hook()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ prepare()

virtual void nest::RecordingBackend::prepare ( )

pure virtual

Prepare the backend at begin of the NEST Simulate function.

This function is called by KernelManager::prepare() and allows the backend to open files or establish network connections or take similar action.

See also: cleanup()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ set_status()

virtual void nest::RecordingBackend::set_status ( const Dictionary & params )

pure virtual

Set the status of the recording backend using the key-value pairs contained in the params dictionary.

Parameters

params the status of the recording backend

See also: get_status()

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ set_value_names()

virtual void nest::RecordingBackend::set_value_names	(	const RecordingDevice &	device,
		const std::vector< std::string > &	double_value_names,
		const std::vector< std::string > &	long_value_names
	)

pure virtual

To make the names of recorded quantities known to the RecordingBackend, the vectors double_value_names and long_value_names can be set appropriately.

If no values of a certain type (or none at all) will be recorded by device, the constants NO_DOUBLE_VALUE_NAMES and NO_LONG_VALUE_NAMES can be used. Please note that the lengths of the value names vectors must correspond to the length of the data vectors written during calls to write(), although this is not enforced by the API.

Parameters

device	the device to set the value names for
double_value_names	the names for double values to be recorded
long_value_names	the names for long values to be recorded

See also: enroll(), disenroll(), write(),

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

◆ write()

virtual void nest::RecordingBackend::write	(	const RecordingDevice &	device,
		const Event &	event,
		const std::vector< double > &	double_values,
		const std::vector< long > &	long_values
	)

pure virtual

Write the data from the event to the backend specific channel together with the values given.

This function needs to respect the time_in_steps property of the device and should return as quickly as possible if the RecordingDevice device is not enrolled with the backend.

Parameters

device	the RecordingDevice, backend-specific channel to write to
event	the event
double_values	vector of double valued to be written
long_values	vector of long values to be written

Implemented in nest::RecordingBackendASCII, nest::RecordingBackendMemory, nest::RecordingBackendMPI, nest::RecordingBackendScreen, and nest::RecordingBackendSIONlib.

Member Data Documentation

◆ NO_DOUBLE_VALUE_NAMES

const std::vector< std::string > nest::RecordingBackend::NO_DOUBLE_VALUE_NAMES

static

Referenced by nest::spike_recorder::pre_run_hook(), and nest::spin_detector::pre_run_hook().

◆ NO_DOUBLE_VALUES

const std::vector< double > nest::RecordingBackend::NO_DOUBLE_VALUES

static

Referenced by nest::spike_recorder::handle(), nest::spin_detector::handle(), and nest::spin_detector::update().

◆ NO_LONG_VALUE_NAMES

const std::vector< std::string > nest::RecordingBackend::NO_LONG_VALUE_NAMES

static

Referenced by nest::multimeter::pre_run_hook(), and nest::spike_recorder::pre_run_hook().

◆ NO_LONG_VALUES

const std::vector< long > nest::RecordingBackend::NO_LONG_VALUES

static

Referenced by nest::multimeter::handle(), and nest::spike_recorder::handle().

The documentation for this class was generated from the following files:

	NEST main@caf0ae8

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RecordingBackend()

◆ ~RecordingBackend()

Member Function Documentation

◆ check_device_status()

◆ cleanup()

◆ disenroll()

◆ enroll()

◆ finalize()

◆ get_device_defaults()

◆ get_device_status()

◆ get_status()

◆ initialize()

◆ post_run_hook()

◆ post_step_hook()

◆ pre_run_hook()

◆ prepare()

◆ set_status()

◆ set_value_names()

◆ write()

Member Data Documentation

◆ NO_DOUBLE_VALUE_NAMES

◆ NO_DOUBLE_VALUES

◆ NO_LONG_VALUE_NAMES

◆ NO_LONG_VALUES