diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst index 2371536334..1176894c5c 100644 --- a/doc/htmldoc/devices/index.rst +++ b/doc/htmldoc/devices/index.rst @@ -3,6 +3,21 @@ All about devices in NEST ========================= +.. grid:: 1 1 2 2 + :gutter: 1 + + .. grid-item-card:: Stimulate the network + :class-title: sd-d-flex-row sd-align-minor-center + :link: stimuate_network + :link-type: ref + + .. grid-item-card:: Get data from simulation + :class-title: sd-d-flex-row sd-align-minor-center + :link: record_simulations + :link-type: ref + + + .. toctree:: :maxdepth: 1 :glob: diff --git a/doc/htmldoc/devices/record_from_simulations.rst b/doc/htmldoc/devices/record_from_simulations.rst index 0520f6adec..f6122aeda2 100644 --- a/doc/htmldoc/devices/record_from_simulations.rst +++ b/doc/htmldoc/devices/record_from_simulations.rst @@ -38,15 +38,39 @@ 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: -Recorders for every-day situations ----------------------------------- +What values can I record? +------------------------- + +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: Where does data end up? ----------------------- @@ -55,10 +79,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 +87,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 +137,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 +146,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 +166,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 diff --git a/models/multimeter.h b/models/multimeter.h index 027387f093..a6c106d74e 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..91c2b7e1b7 100644 --- a/models/spike_recorder.h +++ b/models/spike_recorder.h @@ -57,13 +57,14 @@ spike creation rather than that of their arrival. :: - >>> neurons = nest.Create('iaf_psc_alpha', 5) - >>> sr = nest.Create('spike_recorder') + >>> neurons = nest.Create("iaf_psc_alpha", 5) + >>> sr = 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 +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 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) 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 74363f47a2..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,13 +58,13 @@ 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 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. 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 diff --git a/nestkernel/recording_device.h b/nestkernel/recording_device.h index 7164eafe94..03df1f4769 100644 --- a/nestkernel/recording_device.h +++ b/nestkernel/recording_device.h @@ -59,9 +59,31 @@ 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") + +.. 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. + + 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 `. Recorder properties +++++++++++++++++++