From 668e1c4b23290c4a2afe8096055aa437b83a0782 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Thu, 1 Feb 2024 12:38:17 +0100 Subject: [PATCH 01/14] update docs with events usecase --- doc/htmldoc/devices/index.rst | 54 +++++++++++++++++++++++++++++++++++ models/multimeter.h | 3 +- models/spike_recorder.h | 17 +++++++++-- 3 files changed, 70 insertions(+), 4 deletions(-) diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst index 2371536334..e994861277 100644 --- a/doc/htmldoc/devices/index.rst +++ b/doc/htmldoc/devices/index.rst @@ -3,6 +3,60 @@ All about devices in NEST ========================= + + +Stimulating devices + + +Recording devices + +- What kind of devices can be used to record data + + - multimeter: record analog values from neurons. + + - What kinds of values can be recorded? + + This depends on the neuron model specified. You can get a list of properties that you can + record using the ``recordables`` property. + + :: + + >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] + ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] + + - spike recorder: collects and records all spikes it receives from neurons that are connected to it + + - weight recorder: Recording weights from synapses + + +- How do I get data out + + Recorded data is handed over to recording backend + + + You can specify the recording backend using ``record_to`` parameter + Each recording backend has their own parameters + +See examples +https://nest-simulator.readthedocs.io/en/latest/auto_examples/recording_demo.html + https://nest-simulator.readthedocs.io/en/latest/auto_examples/multimeter_file.html +Basic +.. code-block:: + + >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] + ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] + + The record_from property of a multimeter (a list, empty by default) can be set to contain the name(s) of one or more of these recordables to have them sampled during simulation. + + mm = nest.Create('multimeter', 1, {'record_from': ['V_m', 'g_ex']}) + +``sr = nest.Create('spike_recorder', params={'record_to': 'ascii'})`` + +``record_to`` + +/bin/bash: line 1: :w: command not found +- Device properties + .. toctree:: :maxdepth: 1 :glob: diff --git a/models/multimeter.h b/models/multimeter.h index b22190c5a2..58ffeedfaf 100644 --- a/models/multimeter.h +++ b/models/multimeter.h @@ -66,7 +66,8 @@ recordables to have them sampled during simulation. :: - mm = nest.Create('multimeter', 1, {'record_from': ['V_m', 'g_ex']}) + mm = nest.Create('multimeter', 1, {'record_from': ['V_m', 'g_ex'], + 'record_to': memory}) The sampling interval for recordings (given in ms) can be controlled using the ``multimeter`` parameter ``interval``. The default value of diff --git a/models/spike_recorder.h b/models/spike_recorder.h index dd995fc596..21ccd54faa 100644 --- a/models/spike_recorder.h +++ b/models/spike_recorder.h @@ -58,12 +58,23 @@ spike creation rather than that of their arrival. :: >>> neurons = nest.Create('iaf_psc_alpha', 5) - >>> sr = nest.Create('spike_recorder') + >>> sr = new = nest.Create("spike_recorder", params={"record_to":"memory", "time_in_steps": False}) >>> nest.Connect(neurons, sr) - -The call to ``Connect`` will fail if the connection direction is + . + . + . + >>> nest.Simulate(100) + # If recording backend is set to "memory", the spike times can be retrieved in the events + # parameter. See below for more information about data handling. + >>> sr.get("events") + {'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), + 'times': array([ 2.1, 4.4, 6.7, 8.9, 11.1, 13.3, 15.5, 17.7, 19.9, 22.1, 24.3, + 26.5, 28.7])} + +Note the call to ``Connect`` will fail if the connection direction is reversed (i.e., connecting *sr* to *neurons*). + .. include:: ../models/recording_device.rst See also From f67cf3a85b5b2b86f60a4cb8ef78b486c71be1ae Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 4 Mar 2024 12:12:27 +0100 Subject: [PATCH 02/14] add more text --- doc/htmldoc/devices/index.rst | 106 ++++++++++++++++++++++++++++------ 1 file changed, 88 insertions(+), 18 deletions(-) diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst index e994861277..e6ab9c2e6b 100644 --- a/doc/htmldoc/devices/index.rst +++ b/doc/htmldoc/devices/index.rst @@ -4,43 +4,113 @@ All about devices in NEST ========================= +What kind of values can be recorded? +------------------------------------ -Stimulating devices +This depends on neuron or synapse model specified. +You can get a list of properties that you can record using the ``recordables`` property. -Recording devices + :: -- What kind of devices can be used to record data + >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] + ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] - - multimeter: record analog values from neurons. - - What kinds of values can be recorded? +- multimeter: record analog values from neurons. - This depends on the neuron model specified. You can get a list of properties that you can - record using the ``recordables`` property. +- spike recorder: collects and records all spikes it receives from neurons that are connected to it - :: +- weight recorder: Recording weights from synapses - >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] - ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] +How can I get data out? +----------------------- - - spike recorder: collects and records all spikes it receives from neurons that are connected to it +We have several ways you can access the data you recorded, these are referred to as ``recording_backends`` - - weight recorder: Recording weights from synapses +- output to Ascii file +- output to memory +- output to screen +- output to SionLib +- output to MPI -- How do I get data out +You can specify the recording backend using ``record_to`` parameter + +Each recording backend has their own parameters + +By default the data will record to "memory" +Stimulating devices - Recorded data is handed over to recording backend +Get spike data out, membrane potential, synaptic conductances, synaptic weights - You can specify the recording backend using ``record_to`` parameter - Each recording backend has their own parameters + + +Recording devices + +- What kind of devices can be used to record data + +- What kinds of values can be recorded? + +- How do I get data out + + + :: + + nest.Create("spike_recorder", 1, {"record_to": "ascii", "time_in_steps": True} + sr =nest.Create("spike_recorder", 1, {"record_to": "memory", "time_in_steps": True} + + +data recorded by recording backend ascii (time_in_steps=True) +[['sender' 'time_step' 'time_offset'] + ['1' '21' '0.000'] + ['1' '44' '0.000'] + ['1' '67' '0.000'] + ['1' '89' '0.000'] + ['1' '111' '0.000'] + ['1' '133' '0.000'] + ['1' '155' '0.000'] + ['1' '177' '0.000'] + ['1' '199' '0.000'] + ['1' '221' '0.000'] + ['1' '243' '0.000'] + ['1' '265' '0.000'] + ['1' '287' '0.000']] + +simulation resolution in ms: 0.1 +data recorded by recording backend ascii (time_in_steps=False) +[['sender' 'time_ms'] + ['1' '2.100'] + ['1' '4.400'] + ['1' '6.700'] + ['1' '8.900'] + ['1' '11.100'] + ['1' '13.300'] + ['1' '15.500'] + ['1' '17.700'] + ['1' '19.900'] + ['1' '22.100'] + ['1' '24.300'] + ['1' '26.500'] + ['1' '28.700']] +simulation resolution in ms: 0.1 + +data recorded by recording backend memory (time_in_steps=False) +{'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), +'times': array([ 2.1, 4.4, 6.7, 8.9, 11.1, 13.3, 15.5, 17.7, 19.9, 22.1, 24.3, 26.5, 28.7])} +data recorded by recording backend memory (time_in_steps=True) +{'offsets': array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]), +'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), +'times': array([ 21, 44, 67, 89, 111, 133, 155, 177, 199, 221, 243, 265, 287])} See examples -https://nest-simulator.readthedocs.io/en/latest/auto_examples/recording_demo.html - https://nest-simulator.readthedocs.io/en/latest/auto_examples/multimeter_file.html + +https://nest-simulator.readthedocs.io/en/latest/auto_examples/recording_demo.html + https://nest-simulator.readthedocs.io/en/latest/auto_examples/multimeter_file.html + Basic + .. code-block:: >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] From fe68d910f7ea54e5370f4d455fa4d913ec64c837 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Tue, 5 Mar 2024 13:21:05 +0100 Subject: [PATCH 03/14] fix typo, move block --- doc/htmldoc/devices/index.rst | 13 +++++++------ nestkernel/recording_backend_screen.h | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst index e6ab9c2e6b..0f6f6feb59 100644 --- a/doc/htmldoc/devices/index.rst +++ b/doc/htmldoc/devices/index.rst @@ -34,9 +34,15 @@ We have several ways you can access the data you recorded, these are referred to - output to SionLib - output to MPI - You can specify the recording backend using ``record_to`` parameter + :: + + nest.Create("spike_recorder", 1, {"record_to": "ascii", "time_in_steps": True} + + + + Each recording backend has their own parameters By default the data will record to "memory" @@ -56,11 +62,6 @@ Recording devices - How do I get data out - :: - - nest.Create("spike_recorder", 1, {"record_to": "ascii", "time_in_steps": True} - sr =nest.Create("spike_recorder", 1, {"record_to": "memory", "time_in_steps": True} - data recorded by recording backend ascii (time_in_steps=True) [['sender' 'time_step' 'time_offset'] diff --git a/nestkernel/recording_backend_screen.h b/nestkernel/recording_backend_screen.h index 74363f47a2..89a3639112 100644 --- a/nestkernel/recording_backend_screen.h +++ b/nestkernel/recording_backend_screen.h @@ -64,7 +64,7 @@ precision controls the number of decimal places used to write decimal numbers to the terminal. -time_in_step +time_in_steps A boolean (default: false) specifying whether to print time in steps, i.e., in integer multiples of the resolution and an offset, rather than just in ms. From 352084325b44f07df1cc3936f13e38f88dc48a6d Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 18 Mar 2024 15:06:12 +0100 Subject: [PATCH 04/14] replace single with double quote --- models/spike_recorder.h | 14 ++------------ models/weight_recorder.h | 2 +- 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/models/spike_recorder.h b/models/spike_recorder.h index 21ccd54faa..91c2b7e1b7 100644 --- a/models/spike_recorder.h +++ b/models/spike_recorder.h @@ -57,19 +57,9 @@ spike creation rather than that of their arrival. :: - >>> neurons = nest.Create('iaf_psc_alpha', 5) - >>> sr = new = nest.Create("spike_recorder", params={"record_to":"memory", "time_in_steps": False}) + >>> neurons = nest.Create("iaf_psc_alpha", 5) + >>> sr = nest.Create("spike_recorder", params={"record_to":"memory", "time_in_steps": False}) >>> nest.Connect(neurons, sr) - . - . - . - >>> nest.Simulate(100) - # If recording backend is set to "memory", the spike times can be retrieved in the events - # parameter. See below for more information about data handling. - >>> sr.get("events") - {'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), - 'times': array([ 2.1, 4.4, 6.7, 8.9, 11.1, 13.3, 15.5, 17.7, 19.9, 22.1, 24.3, - 26.5, 28.7])} Note the call to ``Connect`` will fail if the connection direction is reversed (i.e., connecting *sr* to *neurons*). diff --git a/models/weight_recorder.h b/models/weight_recorder.h index 41d5910837..ef23ad8f6d 100644 --- a/models/weight_recorder.h +++ b/models/weight_recorder.h @@ -63,7 +63,7 @@ synapses that fulfill the given criteria. :: - >>> wr = nest.Create('weight_recorder') + >>> wr = nest.Create("weight_recorder") >>> nest.CopyModel("stdp_synapse", "stdp_synapse_rec", {"weight_recorder": wr}) >>> pre = nest.Create("iaf_psc_alpha", 10) From 98120b94e7a7b39822ad352a2dcf521721857efc Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 18 Mar 2024 15:06:40 +0100 Subject: [PATCH 05/14] change heading symbols to match rest of docs --- nestkernel/recording_backend_ascii.h | 8 ++++---- nestkernel/recording_backend_memory.h | 6 +++--- nestkernel/recording_backend_mpi.h | 8 ++++---- nestkernel/recording_backend_screen.h | 6 +++--- nestkernel/recording_backend_sionlib.h | 12 ++++++------ 5 files changed, 20 insertions(+), 20 deletions(-) diff --git a/nestkernel/recording_backend_ascii.h b/nestkernel/recording_backend_ascii.h index b9ede68dea..7ec7d74b62 100644 --- a/nestkernel/recording_backend_ascii.h +++ b/nestkernel/recording_backend_ascii.h @@ -31,10 +31,10 @@ /* BeginUserDocs: NOINDEX Recording backend `ascii` - Write data to plain text files -########################################################## +---------------------------------------------------------- Description -+++++++++++ +~~~~~~~~~~~ The `ascii` recording backend writes collected data persistently to a plain text ASCII file. It can be used for small to medium sized @@ -77,7 +77,7 @@ for avoiding name clashes is to set the kernel attributes ``data_path`` or ``data_prefix``, to write to a different file. Data format -+++++++++++ +~~~~~~~~~~~ Any file written by the `ascii` recording backend starts with an informational header. The first header line contains the NEST version, @@ -105,7 +105,7 @@ point offset in ms from the next integer grid point. controlled using the recorder property ``precision``. Parameter summary -+++++++++++++++++ +~~~~~~~~~~~~~~~~~ file_extension A string (default: *"dat"*) that specifies the file name extension, diff --git a/nestkernel/recording_backend_memory.h b/nestkernel/recording_backend_memory.h index 47798d3585..73061f6d8e 100644 --- a/nestkernel/recording_backend_memory.h +++ b/nestkernel/recording_backend_memory.h @@ -29,10 +29,10 @@ /* BeginUserDocs: NOINDEX Recording backend `memory` - Store data in main memory -###################################################### +------------------------------------------------------ Description -+++++++++++ +~~~~~~~~~~~ When a recording device sends data to the ``memory`` backend, it is stored internally in efficient vectors. These vectors are made @@ -66,7 +66,7 @@ recording device. To delete data from memory, `n_events` can be set to 0. Other values cannot be set. Parameter summary -+++++++++++++++++ +~~~~~~~~~~~~~~~~~ events A dictionary containing the recorded data in the form of one numeric diff --git a/nestkernel/recording_backend_mpi.h b/nestkernel/recording_backend_mpi.h index 65ed506dba..6e4acc7560 100644 --- a/nestkernel/recording_backend_mpi.h +++ b/nestkernel/recording_backend_mpi.h @@ -34,10 +34,10 @@ /* BeginUserDocs: NOINDEX Recording backend `mpi` - Send data with MPI -############################################ +-------------------------------------------- Description -+++++++++++ +~~~~~~~~~~~ .. admonition:: Availability @@ -65,7 +65,7 @@ its node ID. This path can only be set outside of a `Run` context (i.e. after ``Prepare()`` has been called, but ``Cleanup()`` has not). Communication Protocol -++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~ The following protocol is used to exchange information between both MPI processes. The protocol is described using the following format @@ -80,7 +80,7 @@ for the MPI messages: (value, number, type, source/destination, tag) 7) ``Cleanup`` : Send at this en of the simulation (true, 1, CXX_BOOL, 0, 2) Data format -+++++++++++ +~~~~~~~~~~~ The format of the data sent is an array consisting of (id device, id node, time is ms). diff --git a/nestkernel/recording_backend_screen.h b/nestkernel/recording_backend_screen.h index 89a3639112..371a116bfb 100644 --- a/nestkernel/recording_backend_screen.h +++ b/nestkernel/recording_backend_screen.h @@ -29,10 +29,10 @@ /* BeginUserDocs: NOINDEX Recording backend `screen` - Write data to the terminal -####################################################### +------------------------------------------------------- Description -+++++++++++ +~~~~~~~~~~~ When initially conceiving and debugging simulations, it can be useful to check recordings in a more ad hoc fashion. The recording backend @@ -58,7 +58,7 @@ floating point offset in ms from the next grid point. down the simulation. Parameter summary -+++++++++++++++++ +~~~~~~~~~~~~~~~~~ precision controls the number of decimal places used to write decimal numbers diff --git a/nestkernel/recording_backend_sionlib.h b/nestkernel/recording_backend_sionlib.h index aa3baaa047..40e6ddf183 100644 --- a/nestkernel/recording_backend_sionlib.h +++ b/nestkernel/recording_backend_sionlib.h @@ -32,10 +32,10 @@ /* BeginUserDocs: NOINDEX Recording backend `sionlib` - Store data to an efficient binary format -###################################################################### +---------------------------------------------------------------------- Description -+++++++++++ +~~~~~~~~~~~ .. admonition:: Availability @@ -80,7 +80,7 @@ attribute. An alternative way for avoiding name clashes is to set the kernel attributes ``data_path`` or ``data_prefix``, to write to a different file. Data format -+++++++++++ +~~~~~~~~~~~ In contrast to other recording backends, the ``sionlib`` backend writes the data from all recorders using it to a single container @@ -108,7 +108,7 @@ following figure. NEST SIONlib binary file format. Reading the data -++++++++++++++++ +~~~~~~~~~~~~~~~~ As the binary format of the files produced by the ``sionlib`` does not conform to any standard, parsing them manually might be a bit @@ -118,7 +118,7 @@ and further documentation for this module can be found in its own `repository `_. Recorder-specific parameters -++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ label A recorder-specific string (default: *""*) that serves as alias @@ -126,7 +126,7 @@ label section of the container files. Global parameters -+++++++++++++++++ +~~~~~~~~~~~~~~~~~ These parameters can be set by assigning a nested dictionary to the kernel attribute ``recording_backends``. The dictionary has to have From f079b21a7b087575dcaca2bacdcbef3845420f3d Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 18 Mar 2024 15:07:24 +0100 Subject: [PATCH 06/14] improved index page for devices - not used atm --- doc/htmldoc/devices/index.rst | 130 +++------------------------------- 1 file changed, 10 insertions(+), 120 deletions(-) diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst index 0f6f6feb59..1176894c5c 100644 --- a/doc/htmldoc/devices/index.rst +++ b/doc/htmldoc/devices/index.rst @@ -3,130 +3,20 @@ All about devices in NEST ========================= +.. grid:: 1 1 2 2 + :gutter: 1 -What kind of values can be recorded? ------------------------------------- + .. grid-item-card:: Stimulate the network + :class-title: sd-d-flex-row sd-align-minor-center + :link: stimuate_network + :link-type: ref -This depends on neuron or synapse model specified. + .. grid-item-card:: Get data from simulation + :class-title: sd-d-flex-row sd-align-minor-center + :link: record_simulations + :link-type: ref -You can get a list of properties that you can record using the ``recordables`` property. - :: - - >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] - ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] - - -- multimeter: record analog values from neurons. - -- spike recorder: collects and records all spikes it receives from neurons that are connected to it - -- weight recorder: Recording weights from synapses - -How can I get data out? ------------------------ - -We have several ways you can access the data you recorded, these are referred to as ``recording_backends`` - -- output to Ascii file -- output to memory -- output to screen -- output to SionLib -- output to MPI - -You can specify the recording backend using ``record_to`` parameter - - :: - - nest.Create("spike_recorder", 1, {"record_to": "ascii", "time_in_steps": True} - - - - -Each recording backend has their own parameters - -By default the data will record to "memory" -Stimulating devices - - -Get spike data out, membrane potential, synaptic conductances, synaptic weights - - - -Recording devices - -- What kind of devices can be used to record data - -- What kinds of values can be recorded? - -- How do I get data out - - - -data recorded by recording backend ascii (time_in_steps=True) -[['sender' 'time_step' 'time_offset'] - ['1' '21' '0.000'] - ['1' '44' '0.000'] - ['1' '67' '0.000'] - ['1' '89' '0.000'] - ['1' '111' '0.000'] - ['1' '133' '0.000'] - ['1' '155' '0.000'] - ['1' '177' '0.000'] - ['1' '199' '0.000'] - ['1' '221' '0.000'] - ['1' '243' '0.000'] - ['1' '265' '0.000'] - ['1' '287' '0.000']] - -simulation resolution in ms: 0.1 -data recorded by recording backend ascii (time_in_steps=False) -[['sender' 'time_ms'] - ['1' '2.100'] - ['1' '4.400'] - ['1' '6.700'] - ['1' '8.900'] - ['1' '11.100'] - ['1' '13.300'] - ['1' '15.500'] - ['1' '17.700'] - ['1' '19.900'] - ['1' '22.100'] - ['1' '24.300'] - ['1' '26.500'] - ['1' '28.700']] -simulation resolution in ms: 0.1 - -data recorded by recording backend memory (time_in_steps=False) -{'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), -'times': array([ 2.1, 4.4, 6.7, 8.9, 11.1, 13.3, 15.5, 17.7, 19.9, 22.1, 24.3, 26.5, 28.7])} -data recorded by recording backend memory (time_in_steps=True) -{'offsets': array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]), -'senders': array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), -'times': array([ 21, 44, 67, 89, 111, 133, 155, 177, 199, 221, 243, 265, 287])} - -See examples - -https://nest-simulator.readthedocs.io/en/latest/auto_examples/recording_demo.html - https://nest-simulator.readthedocs.io/en/latest/auto_examples/multimeter_file.html - -Basic - -.. code-block:: - - >>> nest.GetDefaults('iaf_cond_alpha')['recordables'] - ['g_ex', 'g_in', 't_ref_remaining', 'V_m'] - - The record_from property of a multimeter (a list, empty by default) can be set to contain the name(s) of one or more of these recordables to have them sampled during simulation. - - mm = nest.Create('multimeter', 1, {'record_from': ['V_m', 'g_ex']}) - -``sr = nest.Create('spike_recorder', params={'record_to': 'ascii'})`` - -``record_to`` - -/bin/bash: line 1: :w: command not found -- Device properties .. toctree:: :maxdepth: 1 From 5f3bbeb85ce0c31fd99e67bef57603bbcf9ef2ab Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 18 Mar 2024 15:08:30 +0100 Subject: [PATCH 07/14] add explicit example of how recording backends and events are used --- nestkernel/recording_device.h | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index 7164eafe94..f29e3ae1ce 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -59,9 +59,22 @@ Data handling +++++++++++++ All recorded data is handed over to the recording backend, selected -via the ``record_to`` property. More details on available backends and -their properties can be found in the :ref:`guide to recording from -simulations `. +via the ``record_to`` property:: + + >>> sr = nest.Create("spike_recorder", params={"record_to":"ascii", "time_in_steps": False}) + >>> mm = nest.Create("multimeter", 1, {"record_from": ["V_m", "g_ex"], "record_to": memory}) + + +By default, data recorded from recorders is stored in the `memory` backend. +You can access the data recorded by the recorders with the ``events`` property. + +:: + + mm_events = mm.get("events") + + +The complete list of parameters and other recording backend options +can be found in the :ref:`guide to recording from simulations `. Recorder properties +++++++++++++++++++ From dc38aa087daab13c16711c9b6bed24f79e227437 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 18 Mar 2024 15:09:03 +0100 Subject: [PATCH 08/14] include the backend docs directly into page, and make more explicit examples of getting data out --- .../devices/record_from_simulations.rst | 83 ++++++++++++++----- 1 file changed, 61 insertions(+), 22 deletions(-) diff --git a/doc/htmldoc/devices/record_from_simulations.rst b/doc/htmldoc/devices/record_from_simulations.rst index 0520f6adec..c591cb9ac3 100644 --- a/doc/htmldoc/devices/record_from_simulations.rst +++ b/doc/htmldoc/devices/record_from_simulations.rst @@ -38,13 +38,36 @@ Recording devices can fundamentally be subdivided into two groups: neuron (not the neuron to the sampler), and that the neuron must support the particular type of sampling. +What values can I record? +------------------------- -Recorders for every-day situations ----------------------------------- +This depends on neuron or synapse model specified. + +You can get a list of properties that you can record using the ``recordables`` property. + + :: + + >>> nest.GetDefaults("iaf_cond_alpha")["recordables"] + ["g_ex", "g_in", "t_ref_remaining", "V_m"] + + +Recorders available in NEST +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- :doc:`/models/multimeter` + + +- :doc:`/models/spike_recorder` + + +- :doc:`/models/weight_recorder` + +Check out the following examples to see how the recorders are used: + +- :doc:`/auto_examples/recording_demo` +- :doc:`/auto_examples/multimeter_file` +- :doc:`/auto_examples/urbanczik_synapse_example` uses all 3 recorders. -- :doc:`../models/multimeter` -- :doc:`../models/spike_recorder` -- :doc:`../models/weight_recorder` .. _recording_backends: @@ -55,10 +78,6 @@ After a recording device has collected or sampled data, the data is handed to a dedicated *recording backend*, set for each recorder. These are responsible for how the data are processed. -Theoretically, recording backends are completely free in what they do -with the data. The ones included in NEST can collect data in memory, -display it on the terminal, or write it to files. - To specify the recording backend for a given recording device, the property ``record_to`` of the latter has to be set to the name of the recording backend to be used. This can either happen already in the @@ -67,13 +86,33 @@ call to :py:func:`.Create` or by using :py:func:`.SetStatus` on the model instan :: - sr = nest.Create('spike_recorder', params={'record_to': 'ascii'}) + sr = nest.Create("spike_recorder", params={"record_to": "memory"}) Storing data in memory using the `memory` backend is the default for all recording devices as this does not require any additional setup of data paths or filesystem permissions and allows a convenient readout of data by the user after simulation. +For example, you can use the ``events`` property to get the data output from the `memory` backend +from any of the recorders: + +:: + + >>> spike_recorder.get("events") + {"senders": array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]), + "times": array([ 2.1, 4.4, 6.7, 8.9, 11.1, 13.3, 15.5, 17.7, 19.9, 22.1, 24.3, 26.5, 28.7])} + +Additional properties can be set, depending on the recorder and recording backend used. + +For example: + +:: + + mm = nest.Create( "multimeter", + params={"interval": 0.1, "record_from": ["V_m", "g_ex", "g_in"], "record_to": "ascii", "label": "my_multimeter"}, + ) + + Each recording backend may provide a specific set of parameters (explained in the backend documentation below) that will be included in the model status dictionary once the backend is set. This means @@ -97,7 +136,7 @@ kernel attribute ``recording_backends``. :: >>> print(nest.recording_backends) - ('ascii', 'memory', 'mpi', 'screen', 'sionlib') + ("ascii", "memory", "mpi", "screen", "sionlib") If a recording backend has global properties (i.e., parameters shared by all enrolled recording devices), those can be inspected with @@ -106,17 +145,17 @@ by all enrolled recording devices), those can be inspected with :: >>> nest.GetDefaults("sionlib") - {'buffer_size': 1024, - 'filename': '', - 'sion_chunksize': 262144, - 'sion_collective': False, - 'sion_n_files': 1} + {"buffer_size": 1024, + "filename": "", + "sion_chunksize": 262144, + "sion_collective": False, + "sion_n_files": 1} Such global parameters can be set using :py:func:`.SetDefaults` :: - >>> nest.SetDefaults('sionlib', {'buffer_size': 512}) + >>> nest.SetDefaults("sionlib", {"buffer_size": 512}) Built-in backends ----------------- @@ -126,8 +165,8 @@ NEST. Please note that the availability of some of them depends on the compile-time configuration for NEST. See the backend documentation for details. -- :doc:`../models/recording_backend_memory` -- :doc:`../models/recording_backend_ascii` -- :doc:`../models/recording_backend_screen` -- :doc:`../models/recording_backend_sionlib` -- :doc:`../models/recording_backend_mpi` +.. include:: ../models/recording_backend_memory.rst +.. include:: ../models/recording_backend_ascii.rst +.. include:: ../models/recording_backend_screen.rst +.. include:: ../models/recording_backend_sionlib.rst +.. include:: ../models/recording_backend_mpi.rst From 96edf3a38de4a1ce40940a464542d51f06f6d51a Mon Sep 17 00:00:00 2001 From: jessica-mitchell Date: Wed, 27 Mar 2024 08:56:48 +0100 Subject: [PATCH 09/14] Update nestkernel/recording_device.h --- nestkernel/recording_device.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index f29e3ae1ce..c44690642d 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -62,7 +62,7 @@ All recorded data is handed over to the recording backend, selected via the ``record_to`` property:: >>> sr = nest.Create("spike_recorder", params={"record_to":"ascii", "time_in_steps": False}) - >>> mm = nest.Create("multimeter", 1, {"record_from": ["V_m", "g_ex"], "record_to": memory}) + >>> mm = nest.Create("multimeter", 1, {"record_from": ["V_m", "g_ex"], "record_to": "memory"}) By default, data recorded from recorders is stored in the `memory` backend. From aeeadad208892d5bbfd831479c69d71a7c737287 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Wed, 27 Mar 2024 11:51:34 +0100 Subject: [PATCH 10/14] add note --- nestkernel/recording_device.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index c44690642d..7b2f5fab16 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -72,9 +72,14 @@ You can access the data recorded by the recorders with the ``events`` property. mm_events = mm.get("events") +.. note:: -The complete list of parameters and other recording backend options -can be found in the :ref:`guide to recording from simulations `. + The type of recording backend you choose may affect the efficiency of your simulation. + Increasingly larger simulations may benefit from the `ascii` or `sionlib` backend, as the `memory` + backend might be slower when retrieving large data sets. + + The complete list of parameters and other recording backend options + can be found in the :ref:`guide to recording from simulations `. Recorder properties +++++++++++++++++++ From 9358ef2260927d8848d43cad8f6d02327d3c6c00 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Tue, 2 Apr 2024 10:11:10 +0200 Subject: [PATCH 11/14] move label --- doc/htmldoc/devices/record_from_simulations.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/htmldoc/devices/record_from_simulations.rst b/doc/htmldoc/devices/record_from_simulations.rst index c591cb9ac3..f6122aeda2 100644 --- a/doc/htmldoc/devices/record_from_simulations.rst +++ b/doc/htmldoc/devices/record_from_simulations.rst @@ -38,6 +38,8 @@ Recording devices can fundamentally be subdivided into two groups: neuron (not the neuron to the sampler), and that the neuron must support the particular type of sampling. +.. _recording_backends: + What values can I record? ------------------------- @@ -69,7 +71,6 @@ Check out the following examples to see how the recorders are used: - :doc:`/auto_examples/urbanczik_synapse_example` uses all 3 recorders. -.. _recording_backends: Where does data end up? ----------------------- From 4e1a736ef71f10e62f2ac67c68f7b4b05415272b Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Tue, 9 Apr 2024 14:20:09 +0200 Subject: [PATCH 12/14] modify text --- nestkernel/recording_device.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index 7b2f5fab16..a7ac679c47 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -76,7 +76,7 @@ You can access the data recorded by the recorders with the ``events`` property. The type of recording backend you choose may affect the efficiency of your simulation. Increasingly larger simulations may benefit from the `ascii` or `sionlib` backend, as the `memory` - backend might be slower when retrieving large data sets. + backend can become slow at larger scales. The complete list of parameters and other recording backend options can be found in the :ref:`guide to recording from simulations `. From 88ad022fa0914a95b6f15bc863700f5b79d7f7e8 Mon Sep 17 00:00:00 2001 From: jessica-mitchell Date: Mon, 15 Apr 2024 10:13:29 +0200 Subject: [PATCH 13/14] Update nestkernel/recording_device.h Co-authored-by: Dennis Terhorst --- nestkernel/recording_device.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index a7ac679c47..f941f019d4 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -75,8 +75,9 @@ You can access the data recorded by the recorders with the ``events`` property. .. note:: The type of recording backend you choose may affect the efficiency of your simulation. - Increasingly larger simulations may benefit from the `ascii` or `sionlib` backend, as the `memory` - backend can become slow at larger scales. + The `memory` backend is ideal for interactive work, but can only be used for limited amount of data. Additionally, transferring data to disk later on may be slower than directly writing from the NEST kernel via `ascii` or `sionlib` backends. + + Large simulations with many threads may benefit from the `sionlib` backend, as the `ascii` backend opens many files which can be very time consuming on parallel file systems. The complete list of parameters and other recording backend options can be found in the :ref:`guide to recording from simulations `. From 11f909dde118fdd230bb6a55a94e709a7473fb62 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 15 Apr 2024 11:43:49 +0200 Subject: [PATCH 14/14] fix line length --- nestkernel/recording_device.h | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index f941f019d4..03df1f4769 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -75,9 +75,12 @@ You can access the data recorded by the recorders with the ``events`` property. .. note:: The type of recording backend you choose may affect the efficiency of your simulation. - The `memory` backend is ideal for interactive work, but can only be used for limited amount of data. Additionally, transferring data to disk later on may be slower than directly writing from the NEST kernel via `ascii` or `sionlib` backends. + The `memory` backend is ideal for interactive work, but can only be used for limited + amount of data. Additionally, transferring data to disk later on may be slower than + directly writing from the NEST kernel via `ascii` or `sionlib` backends. - Large simulations with many threads may benefit from the `sionlib` backend, as the `ascii` backend opens many files which can be very time consuming on parallel file systems. + Large simulations with many threads may benefit from the `sionlib` backend, as the `ascii` + backend opens many files which can be very time consuming on parallel file systems. The complete list of parameters and other recording backend options can be found in the :ref:`guide to recording from simulations `.