docs: WIP on guide for neuron simulation

move images in the images folder.
The morphology and python stellate model should be removed from the repo when they will be available on the dbbs models public repo.

docs/core/storage.rst

@@ -6,10 +6,13 @@ Storage
 
 Storage engines
 ===============
-
+**to do**
 
 FS
 --
 
+**to do**
+
 HDF5
 ----
+**to do**

docs/getting-started/configs/guide-neuron.json

@@ -12,7 +12,7 @@
   },
   "partitions": {
     "stellate_layer": {
-    "thickness": 300.0,
+    "thickness": 300.0
   }
 },
 "regions": {
@@ -28,7 +28,7 @@
         "tags": {
             16: ["dendrites", "proximal_dendrites"],
             17: ["dendrites", "distal_dendrites"],
-            18: ["axon", "axon_initial_segment"],
+            18: ["axon", "axon_initial_segment"]
             }      
         }
     }
@@ -84,9 +84,7 @@
       "connection_models": {
         "stellate_to_stellate": 
         {
-          "synapses": [{"synapse" : "AMPA", "weight": 0.001, "delay":1},
-                       {"synapse" : "GABA", "weight": 0.001, "delay":1},
-                       {"synapse" : "NMDA", "weight": 0.001, "delay":1}]
+          "synapses": [{"synapse": "GABA", "weight": 0.001, "delay": 1}]
         }
       },
       "devices": {
@@ -112,8 +110,8 @@
           "device": "voltage_recorder",
           "targetting": {
             "strategy": "sphere",
-            "radius" : 600,
-            "origin" : [50,150,50],
+            "radius" : 100,
+            "origin" : [50, 100, 150],
             "cell_models" : ["stellate_cell"]
           }
         },
@@ -122,8 +120,8 @@
           "synapse_types": ["AMPA", "NMDA"],
           "targetting": {
             "strategy": "sphere",
-            "radius" : 600,
-            "origin" : [50,150,50],
+            "radius" : 100,
+            "origin" : [50, 100, 150],
             "cell_models" : ["stellate_cell"]
           },
          "locations":{

docs/getting-started/simulations/analyze_analog_signals.rst

@@ -39,20 +39,20 @@ Additional information is available through the annotations attribute.
     :language: python
     :lines: 10-49
 
-This code generates one plot for each analog signal recorded, meaning one plot per device for each
-cell or synapse recorded. The resulting figures are saved in the ``simulation-results`` folder.
+This code generates 2 plots: one for an analog signal recorded at the synapse and one for the membrane
+potential. The resulting figures are saved in the ``simulation-results`` folder.
 
 Here are some example of the figures that are produced:
 
-.. figure:: /getting-started/data/vrecorder_example.png
+.. figure:: /images/vrecorder_example.png
   :figwidth: 90%
 
-  Example of the membrane potential recorded for the cell with 0 ID.
+  Example of the membrane potential recorded.
 
-.. figure:: /getting-started/data/synapse_recorder_example.png
+.. figure:: /images/synapse_recorder_example.png
   :figwidth: 90%
 
-  Example of the AMPA synapse current recoded for the cell with 2 ID.
+  Example of the AMPA synapse current recoded.
 
 .. rubric:: Next steps:
 

docs/getting-started/simulations/guide_nest.rst

@@ -9,18 +9,41 @@ Run your first NEST simulation
     This guide is a continuation of the
     :doc:`Getting Started guide </getting-started/getting-started_reconstruction>`.
 
-In this tutorial, we assume that you have successfully reconstructed a network with BSB.
-We will now guide you through the process of configuring a simulation with BSB for your network.
+Install requirements
+====================
 
-Let's start by configuring the global simulation parameters.
-These include the :guilabel:`simulator` to be used. BSB supports the following simulators:
+`NEST <https://nest-simulator.readthedocs.io/en/stable/>`_ is one of the supported
+simulators of the BSB.
+As for the other simulator, its adapter code is stored in a separate repository:
+`bsb-neuron <https://github.com/dbbs-lab/bsb-nest>`_
+
+So, you would need to install it with pip:
+
+.. code-block:: bash
+
+    pip install bsb-nest
+
+Unfortunately, the NEST simulator at the moment can not be installed directly by pip, but
+fortunately NEST provides
+`tutorials <https://nest-simulator.readthedocs.io/en/stable/installation/index.html>`_
+to install it in your python environment.
 
-- `NEST simulator <https://nest-simulator.readthedocs.io/en/stable/>`_
-- `NEURON simulator <https://www.neuron.yale.edu/neuron/>`_
-- `ARBOR simulator <https://arbor-sim.org/>`_
+Make sure that you can both load BSB and NEST before continuing any further:
 
-In this example, we are going to present how to configure a point neuron simulation with NEST in BSB.
+.. code-block:: python
 
+    import nest
+    import bsb
+
+Configuration of the simulation
+===============================
+
+In this tutorial, we assume that you have successfully reconstructed a network with BSB.
+We will now guide you through the process of configuring a simulation with BSB for your network.
+
+Let's start by configuring the global simulation parameters.
+These include the :guilabel:`simulator` to be used; in our example, we are setting it to
+use NEST.
 Additionally, you need to define the :guilabel:`resolution` (the time step of the simulation in milliseconds)
 and the :guilabel:`duration` (the total length of the simulation in milliseconds).
 Therefore, your simulation block should be structured as follows:
@@ -125,7 +148,7 @@ Connection Models
 -----------------
 
 For each connection type of your network, you also need to define a model describing its synapses' dynamics.
-Similar to the :guilabel:`cell_models` block, each :guilabel:`connection_model` you define should use a key
+Similar to the :guilabel:`cell_models` block, for each :guilabel:`connection_model` you should use a key
 that corresponds to a ``ConnectivitySet`` created during reconstruction (as explained in the previous
 :doc:`section </getting-started/getting-started_reconstruction>`).
 In this example, we assign the ``static_synapse`` model to the connections :guilabel:`A_to_B`.
@@ -165,6 +188,11 @@ Devices
 In the :guilabel:`devices` block, include all interfaces you wish to use for interacting with the network.
 These devices correspond typically to stimulators and measurement instruments.
 
+Use the :guilabel:`device` key to select the type of device.
+We also introduce here the :guilabel:`targetting` concept for the devices: This configuration node allows you to
+filter elements of your neuron circuit to which you want to link your devices (see the targetting section on
+:doc:`this page </simulation/intro>` for more details).
+
 .. tab-set-code::
 
     .. code-block:: json
@@ -229,8 +257,6 @@ These devices correspond typically to stimulators and measurement instruments.
               )
             )
 
-Using the :guilabel:`device` key, you select the type of device to use, and with :guilabel:`targetting`,
-you specify the target objects of the device.
 In our example, we add a ``poisson_generator`` that simulates cells spiking at ``20`` Hz.
 These latter "cells" are each connected one ``top_type`` cell and transmit their spike events with a delay
 of `1` ms and the weight of the connection is ``40``.
@@ -253,7 +279,7 @@ Final configuration file
 
 
 Running the Simulation
-----------------------
+======================
 
 Simulations are separated from the reconstruction pipeline (see the
 :doc:`top level guide </getting-started/top-level-guide>`),

docs/getting-started/simulations/guide_neuron.rst

@@ -2,17 +2,42 @@
 Run your first NEURON simulation
 ################################
 
-In this example we are going to present how to configure a simulation of a multi-compartment neurons network.
-To proceed, please install the following additional packages:
+.. note::
+
+    This guide uses notions on the BSB reconstructions that are explained in
+    :doc:`Getting Started guide </getting-started/getting-started_reconstruction>`.
+
+In this tutorial, we present how to configure a NEURON simulation for a multi-compartment
+neuron network.
+
+Install requirements
+====================
+
+`NEURON <https://www.neuron.yale.edu/neuron/>`_ is one of the supported simulators of the
+BSB. As for the other simulator, its adapter code is stored in a separate repository:
+`bsb-neuron <https://github.com/dbbs-lab/bsb-neuron>`_
+
+So, you would need to install it with pip:
 
 .. code-block:: bash
 
     pip install bsb-neuron[parallel]
+
+We will also need some model files for NEURON which you can obtain and link to bsb like so:
+
+.. code-block:: bash
+
     pip install dbbs-catalogue
 
-For this example, we will build a network consisting of a layer of mouse
-stellate cells connected through axon-dendrite overlap, using the strategy :doc:`VoxelIntersection </connectivity/connection-strategies>`.
-The morphology of a custom stellate cell is provided :download:`here </getting-started/data/StellateCell.swc>`.
+BSB reconstruction for this tutorial
+====================================
+
+For this example, we will build a network consisting of a single ``layer`` of
+``stellate_cells`` connected through axon-dendrite overlap, using the strategy
+:doc:`VoxelIntersection </connectivity/connection-strategies>`.
+The morphology of a custom stellate cell is provided
+:download:`here </getting-started/data/StellateCell.swc>`.
+Please save this file in your project folder as ``StellateCell.swc``.
 
 The network configuration should be as follows:
 
@@ -26,31 +51,25 @@ The network configuration should be as follows:
       :language: python
       :lines: 1-54
 
-The configuration should be compiled:
-
-.. tab-set-code::
-
-  .. code-block:: bash
-
-    bsb compile --verbosity 3 network_configuration.json
+Copy the configuration in you favorite format and put it in the project folder
+as ``neuron-simulation.json`` or  as ``neuron-simulation.py``
 
+Then, the configuration should be compiled:
 
-  .. code-block:: python
-
-    import bsb.options
-    from bsb import Scaffold
-
-    bsb.options.verbosity = 3
+.. code-block:: bash
 
-    scaffold = Scaffold(config)
-    scaffold.compile()
+    bsb compile --verbosity 3 neuron-simulation.json
+    # or
+    python neuron-simulation.py
 
 Now we have to configure the simulation block.
-Let's start by configuring the global simulation parameters: first of all
-define a :guilabel:`simulator`, then you need to define the :guilabel:`resolution`
-(the time step of the simulation in milliseconds),
-the :guilabel:`duration` (the total length of the simulation in milliseconds) and
-the :guilabel:`temperature` (celsius unit).
+
+Let's start by configuring the global simulation parameters: first of all,
+define a :guilabel:`simulator`; in our example, we are setting it to
+use NEURON.
+Then you need to define the :guilabel:`resolution` (the time step of the simulation in
+milliseconds), the :guilabel:`duration` (the total length of the simulation in
+milliseconds) and the :guilabel:`temperature` (celsius unit).
 
 .. tab-set-code::
 
@@ -65,17 +84,20 @@ the :guilabel:`temperature` (celsius unit).
 Cell Models
 -----------
 
-For each **cell type** population in your network, you must assign a **NEURON model** to define the cell's behavior. This model
-encapsulates all the specifications for ion channels and synapses covering all components of the cell..
-Within a model the synapse parameters are defined in the :guilabel:`synapse_types` attribute, while the
-parameters for ion channel mechanisms are defined in :guilabel:`cable_types`. A detailed discussion of model
-characteristics is beyond the scope of this guide; therefore, a ready-to-use Stellate model is provided
-:download:`here </getting-started/data/Stellate.py>`.
+For each **cell type** population in your network, you must assign a **NEURON model**
+to define the cell's behavior.
+
+In short, these models encapsulate all the specifications for ion channels and synapses
+covering all compartments of the neuron. Discussing NEURON model characteristics is
+beyond the scope of this guide; therefore, a ready-to-use Stellate model is provided
+:download:`here </../examples/tutorials/Stellate.py>`. Save it as a ``Stellate.py``
+file in your project folder and review its contents.
+
+Within the model file, you will find a model definition called
+:guilabel:`definitionStellate`, which includes all the customized parameters. This is
+the object you will refer to in your configuration. Note also that the parameters for
+the ion channel mechanisms are in the attribute :guilabel:`cable_types`.
 
-Save the Stellate.py file in your project folder and review its contents.
-Inside, you will find a model definition called
-:guilabel:`definitionStellate`, which includes all the customized parameters.
-This is the object you will reference in your configuration.
 
 .. tab-set-code::
 
@@ -90,37 +112,38 @@ This is the object you will reference in your configuration.
 Connection Models
 -----------------
 
-For each connection type of your network, you also need to define a model describing its synapses' dynamics.
-Similar to the :guilabel:`cell_models` block, each :guilabel:`connection_model` you define should use a key
-that corresponds to a ``ConnectivitySet`` created during reconstruction (as explained in the previous
+For each connection type of your network, you also need to provide a NEURON model
+describing its synapses' dynamics. Similar to the :guilabel:`cell_models` block, for
+each :guilabel:`connection_model` you should use a key that corresponds to a
+``ConnectivitySet`` created during reconstruction (as explained in the previous
 :doc:`section </getting-started/getting-started_reconstruction>`).
-In this example we have only the :guilabel:`stellate_to_stellate` connection, where we assign the synapses
-defined in the model file, namely :guilabel:`AMPA`, :guilabel:`GABA`, and :guilabel:`NMDA`.
+In this example, to the :guilabel:`stellate_to_stellate` connection is assigned a
+reference to one of the :guilabel:`synapse_types`, defined in the ``Stellate.py``
+model file: :guilabel:`GABA`.
 
 .. tab-set-code::
 
     .. literalinclude:: /getting-started/configs/guide-neuron.json
       :language: json
-      :lines: 84-91
+      :lines: 84-89
 
     .. literalinclude:: /../examples/tutorials/neuron-simulation.py
       :language: python
-      :lines: 65-73
+      :lines: 65-69
 
-At all the synapses is assigned a :guilabel:`weight` of 0.001 and a :guilabel:`delay` (ms) of 1.
+To each synapse is assigned a :guilabel:`weight` of 0.001 and a :guilabel:`delay` (ms) of 1.
 
 Devices
 -------
 
-In the :guilabel:`devices` block, include all interfaces you wish to use for interacting with the network.
+In the :guilabel:`devices` block, include all interfaces you wish to use for interacting with
+the network.
 These devices correspond typically to stimulators and measurement instruments.
 
-In this example, a :guilabel:`spike_generator` is used to stimulate the cell with ID 0,
-starting at 9 ms, with 1 spike. The stimulus targets the dendrites through AMPA and NMDA synapses.
-The membrane potential is recorded using a :guilabel:`voltage_recorder`, which collects the
-signal from within a 600 µm radius sphere. Synapse activity is monitored with a :guilabel:`synapse_recorder`
-for the :guilabel:`AMPA` and :guilabel:`NMDA` synapses on the cell's dendrites,
-within the same spherical region.
+Use the :guilabel:`device` key to select the type of device.
+We also introduce here the :guilabel:`targetting` concept for the devices: This configuration
+node allows you to filter elements of your neuron circuit to which you want to link your
+devices (see the targetting section on :doc:`this page </simulation/intro>` for more details).
 
 .. tab-set-code::
 
@@ -132,6 +155,19 @@ within the same spherical region.
       :language: python
       :lines: 74-107
 
+In this example, a :guilabel:`spike_generator` is used to produce ``1`` spike (attribute
+:guilabel:`number`) at ``9`` ms and send it to the cell with ID ``0`` (using the
+:guilabel:`targetting`) after ``1`` ms of delay and a :guilabel:`weight` of ``0.01``.
+The stimulus targets the ``AMPA`` and ``NMDA`` synapses located on the ``dendrites`` of the cell.
+
+The membrane potential is recorded using a :guilabel:`voltage_recorder`, which collects the
+signal from within a ``100`` µm radius sphere at the center of the circuit. Hence, not all cells
+might be recorded.
+
+Synapse activity is monitored with a :guilabel:`synapse_recorder`
+for the :guilabel:`AMPA` and :guilabel:`NMDA` synapses on the cell's dendrites, within the same
+spherical region. Here too, not all synapses might be recorded.
+
 Final configuration file
 ------------------------