nest::RecordingBackendASCII Class Reference

ASCII specialization of the RecordingBackend interface. More...

#include <recording_backend_ascii.h>

Inheritance diagram for nest::RecordingBackendASCII:

Collaboration diagram for nest::RecordingBackendASCII:

Classes
struct	DeviceData

Public Member Functions
	RecordingBackendASCII ()
	~RecordingBackendASCII () override throw ()
void	initialize () override
void	finalize () override
void	enroll (const RecordingDevice &device, const Dictionary &params) override
	Enroll a RecordingDevice with the RecordingBackend.
void	disenroll (const RecordingDevice &device) override
	Disenroll a RecordingDevice from the RecordingBackend.
void	set_value_names (const RecordingDevice &device, const std::vector< std::string > &double_value_names, const std::vector< std::string > &long_value_names) override
	To make the names of recorded quantities known to the RecordingBackend, the vectors double_value_names and long_value_names can be set appropriately.
void	prepare () override
	Prepare the backend at begin of the NEST Simulate function.
void	cleanup () override
	Clean up the backend at the end of a user level call to the NEST Simulate function.
void	pre_run_hook () override
	Initialize global backend-specific data structures.
void	post_run_hook () override
	Flush files after a single call to Run.
void	post_step_hook () override
	Do work required at the end of each simulation step.
void	write (const RecordingDevice &, const Event &, const std::vector< double > &, const std::vector< long > &) override
	Write the data from the event to the backend specific channel together with the values given.
void	set_status (const Dictionary &) override
	Set the status of the recording backend using the key-value pairs contained in the params dictionary.
void	get_status (Dictionary &) const override
	Return the status of the recording backend by writing it to the given params dictionary.
void	check_device_status (const Dictionary &) const override
	Check if the given per-device properties are valid and usable by the backend.
void	get_device_defaults (Dictionary &) const override
	Return the per-device defaults by writing it to the given params dictionary.
void	get_device_status (const RecordingDevice &device, Dictionary &) const override
	Return the per-device status of the given recording device by writing it to the given params dictionary.
Public Member Functions inherited from nest::RecordingBackend
	RecordingBackend ()
virtual	~RecordingBackend () throw ()

Static Public Attributes
static const unsigned int	ASCII_REC_BACKEND_VERSION = 2
Static Public Attributes inherited from nest::RecordingBackend
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

Private Types
typedef std::vector< std::map< size_t, DeviceData > >	data_map

Private Member Functions
const std::string	compute_vp_node_id_string_ (const RecordingDevice &device) const

Private Attributes
data_map	device_data_

Detailed Description

ASCII specialization of the RecordingBackend interface.

RecordingBackendASCII maintains a data structure mapping one file stream to every recording device instance on every thread. Files are opened and inserted into the map during the enroll() call (issued by the recorder's pre_run_hook() function) and closed in cleanup(), which is called on all registered recording backends by IOManager::cleanup().

Member Typedef Documentation

data_map

typedef std::vector< std::map< size_t, DeviceData > > nest::RecordingBackendASCII::data_map

private

Constructor & Destructor Documentation

RecordingBackendASCII()

nest::RecordingBackendASCII::RecordingBackendASCII

(

)

~RecordingBackendASCII()

nest::RecordingBackendASCII::~RecordingBackendASCII ( ) throw ( )

override

Member Function Documentation

check_device_status()

void nest::RecordingBackendASCII::check_device_status ( const Dictionary &  params ) const

overridevirtual

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()

Implements nest::RecordingBackend.

References nest::RecordingBackendASCII::DeviceData::set_status().

Here is the call graph for this function:

cleanup()

void nest::RecordingBackendASCII::cleanup ( )

overridevirtual

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()

Implements nest::RecordingBackend.

References device_data_.

compute_vp_node_id_string_()

const std::string nest::RecordingBackendASCII::compute_vp_node_id_string_ ( const RecordingDevice &  device ) const

private

References nest::Node::get_node_id(), nest::VPManager::get_num_virtual_processes(), nest::Node::get_vp(), nest::kernel(), nest::KernelManager::node_manager, nest::NodeManager::size(), and nest::KernelManager::vp_manager.

Referenced by enroll().

Here is the call graph for this function:

Here is the caller graph for this function:

disenroll()

void nest::RecordingBackendASCII::disenroll ( const RecordingDevice &  device )

overridevirtual

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()

Implements nest::RecordingBackend.

References device_data_, nest::Node::get_node_id(), and nest::Node::get_thread().

Here is the call graph for this function:

enroll()

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

overridevirtual

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(),

Implements nest::RecordingBackend.

References compute_vp_node_id_string_(), device_data_, nest::Node::get_name(), nest::Node::get_node_id(), and nest::Node::get_thread().

Here is the call graph for this function:

finalize()

void nest::RecordingBackendASCII::finalize ( )

overridevirtual

Implements nest::RecordingBackend.

get_device_defaults()

void nest::RecordingBackendASCII::get_device_defaults ( Dictionary &  params ) const

overridevirtual

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()

Implements nest::RecordingBackend.

References nest::RecordingBackendASCII::DeviceData::get_status().

Here is the call graph for this function:

get_device_status()

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

overridevirtual

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()

Implements nest::RecordingBackend.

References device_data_, nest::Node::get_node_id(), and nest::Node::get_thread().

Here is the call graph for this function:

get_status()

void nest::RecordingBackendASCII::get_status ( Dictionary &  params ) const

overridevirtual

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()

Implements nest::RecordingBackend.

initialize()

void nest::RecordingBackendASCII::initialize ( )

overridevirtual

Implements nest::RecordingBackend.

References device_data_, and nest::kernel().

Here is the call graph for this function:

post_run_hook()

void nest::RecordingBackendASCII::post_run_hook ( )

overridevirtual

Flush files after a single call to Run.

Implements nest::RecordingBackend.

References device_data_.

post_step_hook()

void nest::RecordingBackendASCII::post_step_hook ( )

overridevirtual

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()

Implements nest::RecordingBackend.

pre_run_hook()

void nest::RecordingBackendASCII::pre_run_hook ( )

overridevirtual

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()

Implements nest::RecordingBackend.

prepare()

void nest::RecordingBackendASCII::prepare ( )

overridevirtual

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()

Implements nest::RecordingBackend.

References device_data_.

set_status()

void nest::RecordingBackendASCII::set_status ( const Dictionary &  params )

overridevirtual

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()

Implements nest::RecordingBackend.

set_value_names()

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

overridevirtual

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(),

Implements nest::RecordingBackend.

References device_data_, nest::Node::get_node_id(), and nest::Node::get_thread().

Here is the call graph for this function:

write()

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

overridevirtual

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

Implements nest::RecordingBackend.

References device_data_, nest::Node::get_node_id(), and nest::Node::get_thread().

Here is the call graph for this function:

Member Data Documentation

ASCII_REC_BACKEND_VERSION

const unsigned int nest::RecordingBackendASCII::ASCII_REC_BACKEND_VERSION = 2

static

Referenced by nest::RecordingBackendASCII::DeviceData::open_file().

device_data_

data_map nest::RecordingBackendASCII::device_data_

private

Referenced by cleanup(), disenroll(), enroll(), get_device_status(), initialize(), post_run_hook(), prepare(), set_value_names(), and write().

---

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

• recording_backend_ascii.h
• recording_backend_ascii.cpp