################################
Run your first NEURON simulation
################################

.. 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.

Pre-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

Create a ``data`` folder in your project folder and save inside:

- A custom stellate cell morphology :download:`here </../../../examples/neuron-simulation/data/StellateCell.swc>` as ``StellateCell.swc``.
- The Stellate model available :download:`here </../../../examples/neuron-simulation/data/Stellate.py>` as ``Stellate.py``.


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 network configuration should be as follows:

.. tab-set-code::

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.json
      :language: json
      :lines: 1-69

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
      :language: yaml
      :lines: 1-62

    .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
      :language: python
      :lines: 1-57

Copy the configuration in you favorite format and put it in the project folder
as ``neuron-simulation.[YOUR EXTENSION]``

At this stage, your project folder should contain these files:

| .
| ├── data
| │    ├── StellateCell.swc
| │    └── Stellate.py
| ├── pyproject.toml
| └── neuron-simulation.yaml  # or .json or .py

Then, the configuration should be compiled:

.. code-block:: bash

    bsb compile --verbosity 3 neuron-simulation.json
    # or
    bsb compile --verbosity 3 neuron-simulation.yaml
    # or
    python neuron-simulation.py

Now we have to configure the simulation block.

Configuration of the simulation
===============================

We want here to see the postsynaptic response of our cells upon receiving an
excitatory input. Each cell will receive one spike on their dendrites and
we will check its effect on the postsynaptic current.

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::

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.json
      :language: json
      :lines: 70-75

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
      :language: yaml
      :lines: 63-68

    .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
      :language: python
      :lines: 59-68

Cell Models
-----------

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, we will leverage the ``data/Stellate.py``
NEURON model provided before. Please 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`.


.. tab-set-code::

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.json
      :language: json
      :lines: 76-81

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
      :language: yaml
      :lines: 69-72

    .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
      :language: python
      :lines: 70-72

Connection Models
-----------------

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, 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:: /../../../examples/neuron-simulation/configs/guide_neuron.json
      :language: json
      :lines: 82-87

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
      :language: yaml
      :lines: 73-78

    .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
      :language: python
      :lines: 74-84

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.
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::

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.json
      :language: json
      :lines: 88-128

    .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
      :language: yaml
      :lines: 79-127

    .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
      :language: python
      :lines: 86-119

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`` (excitatory) 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 all the synaptic types on
the cell's dendrites, within the same spherical region. Here too, not all synapses might be recorded.

Final configuration file
------------------------

.. tab-set-code::

  .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.json
    :language: json

  .. literalinclude:: /../../../examples/neuron-simulation/configs/guide_neuron.yaml
    :language: yaml

  .. literalinclude:: /../../../examples/neuron-simulation/scripts/guide_neuron.py
    :language: python
    :lines: 3-122

Running the Simulation
----------------------

Simulations are separated from the reconstruction pipeline (see the
:doc:`top level guide </getting-started/top-level-guide>`),
which means you do not need to recompile your network to add a simulation to your stored Configuration.
In this example, we only modified the ``Configuration`` in the :guilabel:`simulations` block but this updates were
not been saved in the network file.
So, you need to update your file, using either the ``reconfigure`` command or the ``store_active_config`` method.

.. tab-set-code::

  .. code-block:: bash

    bsb reconfigure my_network.hdf5 neuron-simulation.json
    # or
    bsb reconfigure my_network.hdf5 neuron-simulation.yaml

  .. code-block:: python

    storage = scaffold.storage
    storage.store_active_config(config)

You can now run your simulation:

.. tab-set-code::

  .. code-block:: bash

    bsb simulate my_network.hdf5 neuronsim -o simulation-results

  .. code-block:: python

        import pathlib
        from bsb import from_storage

        scaffold = from_storage("my_network.hdf5")
        # create the simulation results folder
        root = pathlib.Path("simulation-results")
        root.mkdir()
        # run the simulation and save the results
        result = scaffold.run_simulation("neuronsim")
        result.write(root / "neuronsimulation.nio", "ow")

The results of the simulation will be stored in the ``"simulation-results"`` folder.

.. note::
    If you run the simulation with the command line interface, the name of the output nio file is randomized by BSB.

For more detailed information about simulation modules,
please refer to the :doc:`simulation section </simulation/intro>`.

Congratulations, you simulated your first BSB reconstructed network with NEURON!

.. rubric:: Next steps:

.. grid:: 1 1 1 2
    :gutter: 1


    .. grid-item-card:: :octicon:`fold-up;1em;sd-text-warning` Analyze your Results
        :link: analyze_analog_signals
        :link-type: doc

        How to extract your data.

    .. grid-item-card:: :octicon:`tools;1em;sd-text-warning` Make custom components
       :link: guide_components
       :link-type: ref

       Learn how to write your own components to e.g. place or connect cells.

    .. grid-item-card:: :octicon:`gear;1em;sd-text-warning` Learn about Components
       :link: components
       :link-type: ref

       Explore more about the main components.

    .. grid-item-card:: :octicon:`device-camera-video;1em;sd-text-warning` Examples
        :link: examples
        :link-type: ref

        Explore more advanced examples