Merge branch 'main' into feature/optimization

.gitmodules

@@ -2,5 +2,5 @@
 	path = docs/MiV-Shared-Docs
 	url = https://github.com/GazzolaLab/MiV-Shared-Docs
 [submodule "docs/tutorial/MiV-Simulator-Cases"]
-	path = docs/tutorial/MiV-Simulator-Cases
+	path = docs/MiV-Simulator-Cases
 	url = https://github.com/GazzolaLab/MiV-Simulator-Cases

docs/guide/index.rst

@@ -3,11 +3,14 @@ Guide/Examples
 
 .. toctree::
    :maxdepth: 2
-   :caption: Guide
+   :caption: How-To guides
 
-Indices and tables
-==================
+   microcircuit-mea
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Examples
+
+   rc-separation
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/guide/microcircuit-mea.rst

@@ -0,0 +1,46 @@
+Simulating Multielectrode Arrays
+================================================
+
+A common system of interest in neural simulation are Multielectrode Arrays (MEA) which integrate multiple microelectrodes to obtain or deliver neural signals to the culture.
+
+To construct MEAs in simulation, you can position artificial STIM(umlus) cells that emulate delivering electrodes and/or position LFP readouts to emulate obtaining electrodes.
+
+Positioning 'electrode' STIM cells
+----------------------------------
+
+Given the x,y,z coordinates of your MEA electrodes, you can insert them into the culture via a callback.
+
+.. code:: python
+
+   # define callable that returns MEA coordinates
+   def callable(n, extents): # -> (n, 3)
+       ...
+       return xyz_coordinate_array
+
+
+   "cell_distributions": {
+     "STIM": {     # generate STIM(ulus) cells
+       "@callable": 64   # @ to invoke callable during generation
+     },
+     ...
+   }
+
+   "layer_extents": { 
+      "@callable": [      # extents definition
+          [0.0, 0.0, 0.0],
+          [200.0, 200.0, 150.0],
+      ],
+      ...
+   }
+
+
+Positioning 'electrode' LFPs
+----------------------------
+
+To emulate the readout feature of the electrodes, you can leverage the ``miv_simulator.lfp.LFP`` class.
+
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/interface/experiment/rc.py
+   :language: python
+   :linenos:
+   :lines: 5,73-88

docs/guide/rc-separation.rst

@@ -0,0 +1,22 @@
+Separation property of a reservoir culture
+==========================================
+
+.. note::
+    This example uses the :doc:`imperative interface <../tutorial/imperative-interface>`.
+
+
+This example constructs a microcircuit reservoir simulation that
+reproduces a classic seperation property experiment by `Maass et
+al. 2002 <https://direct.mit.edu/neco/article/14/11/2531-2560/6650>`__.
+
+To run this example, make sure to change into the ``3-interface-api``
+directory within the `MiV-Simulator-Cases <https://github.com/GazzolaLab/MiV-Simulator-Cases>`__ repository. Then run the
+entire ``rc-separation.py`` script or execute each individual step
+below.
+
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/rc-separation.py
+   :language: python
+   :linenos:
+   :lines: 10-270
+

docs/tutorial/configuration_description.rst

@@ -0,0 +1,106 @@
+******************
+YAML Configuration 
+******************
+
+The MiV-Simulator leverages a YAML-based configuration format to declaratively describe complex neural systems. The user-specified configuration files are used to generate concrete instantiations of the system used in the simulation. 
+For example, a YAML user configuration may describe the number and distribution of neurons which is used during network construction to determine the exact sampled soma positions.
+
+The different configuration templates that are used for simulation construction are described below.
+
+
+Simulation Configuration
+========================
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Microcircuit_Small.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Connection_Velocity.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Definitions.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Geometry_Small.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+Synapse / Dentrites Configuration
+=================================
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Microcircuit_Connections.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Axon_Extent.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/OLM_synapse_density.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/PVBC_synapse_density.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/PYR_synapse_density.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/PYR_SoldadoMagraner.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Synapse_Parameter_Rules.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+Input / Stimulation Configuration
+=================================
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Input_Configuration.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+
+Post-Process Configuration
+==========================
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Recording.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Analysis_Configuration.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+Miscellaneous Configuration
+===========================
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Random.yaml
+   :linenos:
+   :language: yaml
+   :caption:
+
+.. literalinclude:: ../MiV-Simulator-Cases/1-construction/config/Global.yaml
+   :linenos:
+   :language: yaml
+   :caption:

docs/tutorial/docker.md

@@ -1,4 +1,4 @@
-# Installation: Docker Image
+# Docker Image
 
 :::{note}
 The docker image is not optimized for high-performance computing. The image file only provides necessary installation for users to quickly try-run a simple model.

docs/tutorial/imperative-interface.rst

@@ -0,0 +1,67 @@
+Imperative interface
+====================
+
+MiV-Simulator includes an imperative interface built
+on `machinable <https://machinable.org>`__ that can be useful in more
+custom use cases that are not supported out-of-the-box.
+
+The interface API works different from the declarative mode described in
+prior sections where the entire simulation was specified using YAML.
+Instead, the API gives you full control to construct the simulation
+imperatively using Python.
+
+Generally, the process breaks down into (1) generating the
+``cells.h5``/``connections.h5`` that represent the neural systems, and
+(2) loading the cells and connection into the execution runtime to
+simulate the dynamics.
+
+Constructing the neural H5
+--------------------------
+
+To construct the neuro H5 files that describe the specific network
+instantiation, the ``miv_simulator.interface`` module provides
+configurable `machinable
+components <https://machinable.org/guide/component.html>`__ that can be
+chained as follows:
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/rc-separation.py
+   :language: python
+   :linenos:
+   :lines: 14-112
+
+You are free to modify or entirely replace any step in the pipeline. Notably, machinable will automatically keep track of configuration changes to determine if generation steps need to be re-executed. This means that file geneneration is cached and managed behind the scences.
+You can access the resulting filepaths of the generated H5 files via ``graph.files()``.
+
+Launching the simulation
+------------------------
+
+To simulate the network, the generated H5 files can be loaded into the execution environment, for example:
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/interface/experiment/rc.py
+   :language: python
+   :linenos:
+   :lines: 4,16,54-71
+
+This will load and construct all cells and connections that will be part of the simulation. You are free to add additional elements to the system, such as an LFP to read out signals, for example:
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/interface/experiment/rc.py
+   :language: python
+   :linenos:
+   :lines: 5,16,73-88
+
+The execution environment provides access to all NEURON objects, allowing to set up and modify elements as needed. For example, you can use NEURON usual ``cell.play`` function to generate stimulation patterns:
+
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/interface/experiment/rc.py
+   :language: python
+   :linenos:
+   :lines: 96-101
+
+Finally, you can launch and control the simulation using the standard NEURON API:
+
+.. literalinclude:: ../MiV-Simulator-Cases/3-interface-api/interface/experiment/rc.py
+   :language: python
+   :linenos:
+   :lines: 103-119
+
+The full code example using the above code for reservoir computing can be found `here <https://github.com/GazzolaLab/MiV-Simulator-Cases/blob/main/3-interface-api/rc-separation.py>`__.

docs/tutorial/index.rst

@@ -3,16 +3,26 @@ Tutorial
 
 .. toctree::
    :maxdepth: 2
-   :caption: How-To
+   :caption: Installation
 
    installation
    docker
 
-.. include:: MiV-Simulator-Cases/toctree.rstlib
+.. toctree::
+   :maxdepth: 2
+   :caption: Simulator
+
+   configuration_description
+   ../MiV-Simulator-Cases/1-construction/constructing_a_network_model
+   ../MiV-Simulator-Cases/2-single-compartment/single_compartment
 
 .. toctree::
    :maxdepth: 2
-   :caption: Case Study
+   :caption: API
+
+   imperative-interface
+
+
 
 
 Indices and tables

docs/tutorial/installation.md

@@ -1,4 +1,4 @@
-# Installation: Generic from Source
+# From Source
 
 The installation consist two part: python-dependencies and external libraries.