Add EI_clustered_network by Rostami et al to PyNEST examples

doc/htmldoc/examples/index.rst

@@ -80,31 +80,31 @@ PyNEST examples
 
            * :doc:`../auto_examples/Potjans_2014/index`
 
+
+
+    .. grid-item-card:: EI clustered network (Rostami)
+           :img-top: ../static/img/pynest/EI_clustered_network_schematic.png
+
+           :doc:`../auto_examples/EI_clustered_network/index`
+
+
+
+.. grid:: 1 1 2 3
+
     .. grid-item-card:: GLIF (from Allen institute)
            :img-top: ../static/img/pynest/glif_cond.png
 
            * :doc:`../auto_examples/glif_cond_neuron`
            * :doc:`../auto_examples/glif_psc_neuron`
            * :doc:`../auto_examples/glif_psc_double_alpha_neuron`
 
-
-
-.. grid:: 1 1 2 3
-
     .. grid-item-card:: Compartmental neurons
            :img-top: ../static/img/pynest/dendritic_synapse_conductances.png
 
            * :doc:`../auto_examples/compartmental_model/receptors_and_current`
            * :doc:`../auto_examples/compartmental_model/two_comps`
 
 
-    .. grid-item-card:: Rate neurons
-           :img-top: ../static/img/pynest/rate_neuron.png
-
-           * :doc:`../auto_examples/lin_rate_ipn_network`
-           * :doc:`../auto_examples/rate_neuron_dm`
-
-
 
     .. grid-item-card:: GIF (from Gerstner lab)
            :img-top: ../static/img/pynest/gif_pop.png
@@ -116,6 +116,13 @@ PyNEST examples
 
 .. grid:: 1 1 2 3
 
+    .. grid-item-card:: Rate neurons
+           :img-top: ../static/img/pynest/rate_neuron.png
+
+           * :doc:`../auto_examples/lin_rate_ipn_network`
+           * :doc:`../auto_examples/rate_neuron_dm`
+
+
     .. grid-item-card:: Hodgkin-Huxley
            :img-top: ../static/img/pynest/hh_phase.png
 
@@ -127,14 +134,14 @@ PyNEST examples
 
            * :doc:`../auto_examples/BrodyHopfield`
 
+.. grid:: 1 1 2 3
+
     .. grid-item-card:: Brette and Gerstner
            :img-top: ../static/img/pynest/brette_gerstner2c.png
 
            * :doc:`../auto_examples/brette_gerstner_fig_2c`
            * :doc:`../auto_examples/brette_gerstner_fig_3d`
 
-.. grid:: 1 1 2 3
-
 
     .. grid-item-card:: Precise spiking
            :img-top: ../static/img/pynest/precisespiking.png
@@ -146,11 +153,6 @@ PyNEST examples
 
            * :doc:`../auto_examples/CampbellSiegert`
 
-    .. grid-item-card:: SONATA network
-           :img-top: ../static/img/300_pointneurons.png
-
-           * :doc:`../auto_examples/sonata_example/sonata_network`
-
 
 .. grid:: 1 1 2 3
 
@@ -232,6 +234,11 @@ PyNEST examples
 
 .. grid:: 1 1 2 3
 
+    .. grid-item-card:: SONATA network
+           :img-top: ../static/img/300_pointneurons.png
+
+           * :doc:`../auto_examples/sonata_example/sonata_network`
+
     .. grid-item-card:: HPC benchmark
            :img-top: ../static/img/nest_logo-faded.png
 
@@ -331,6 +338,7 @@ PyNEST examples
    ../auto_examples/astrocytes/astrocyte_interaction
    ../auto_examples/astrocytes/astrocyte_small_network
    ../auto_examples/astrocytes/astrocyte_brunel
+   ../auto_examples/EI_clustered_network/index
 
 .. toctree::
    :hidden:

pynest/examples/EI_clustered_network/README.rst

@@ -0,0 +1,67 @@
+EI-clustered circuit model
+===========================
+
+This is PyNEST implementation of the EI-clustered circuit model described by Rostami et al. [1]_.
+
+.. figure:: /static/img/pynest/EI_clustered_network_schematic.png
+   :alt: EI-clustered circuit model.
+
+   Schematic of the EI-clustered circuit model. The network consists of Q clusters with one excitatory and one inhibitory population each.
+
+Citing this code
+----------------
+
+If you use this code, we ask you to cite the paper by Rostami et al. [1]_ and the NEST release on Zenodo.
+
+File structure
+--------------
+
+* :doc:`run_simulation.py <run_simulation>`: an example script to try out the EI-clustered circuit model
+* :doc:`network.py <network>`: the main Network class with functions to build and simulate the network
+* :doc:`helper.py <helper>`: helper functions for calculation of synaptic weights and currents
+* :doc:`general_helper.py <general_helper>`: helper functions to merge dictionaries and plot function for raster plots
+* :doc:`default_parameters.py <default_parameters>`: default parameters for the network and simulation
+
+Running the simulation
+----------------------
+
+.. code-block:: bash
+
+   python3 run_simulation.py
+
+A raster plot of the network activity is saved as ``Rasterplot.png``.
+
+The code can be parallelized by using multiple threads during the NEST simulation.
+This can be done by setting the parameter ``n_jobs`` in the ``run_simulation.py`` script.
+
+Contributions to this PyNEST model implementation
+--------------------------------------------------------------
+2023: inital bersion of code and documentation by Felix J. Schmitt, Vahid Rostami and Martin Nawrot.
+
+Acknowledgments
+---------------
+
+Funding for the study by Rostami et al. [1]_: This work was supported by the German Research Foundation (DFG),
+in parts through the Collaborative Research Center ’Motor Control in Health and Disease’
+(DFG-SFB 1451, Project-ID 431549029) and under the Institutional Strategy of the University of Cologne within the
+German Excellence Initiative (DFG-ZUK 81/1) and in parts through the DFG graduate school
+’Neural Circuit Analysis’ (DFG-RTG 1960, ID 365082554) and through the European Union’s Horizon 2020 Framework
+Programme for Research and Innovation under grant agreement number 945539 (Human Brain Project SGA3).
+The figure is created with BioRender.com.
+
+Other implementations of the EI-clustered model
+-----------------------------------------------
+
+A `GeNN version <https://github.com/nawrotlab/SNN_GeNN_Nest>`__  by Felix J. Schmitt, Vahid Rostami and Martin Nawrot [2]_.
+
+References
+----------
+
+.. [1]  Rostami V, Rost T, Riehle A, van Albada SJ and Nawrot MP. 2020.
+        Excitatory and inhibitory motor cortical clusters account for balance, variability, and task performance.
+        bioRxiv 2020.02.27.968339. DOI: `10.1101/2020.02.27.968339 <https://doi.org/10.1101/2020.02.27.968339>`__.
+
+
+.. [2]  Schmitt FJ, Rostami V and Nawrot MP. 2023.
+        Efficient parameter calibration and real-time simulation of large-scale spiking neural networks with GeNN
+        and NEST. Front. Neuroinform. 17:941696. DOI: `10.3389/fninf.2023.941696 <https://doi.org/10.3389/fninf.2023.941696>`__.

pynest/examples/EI_clustered_network/default_parameters.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+#
+# default_parameters.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+
+"""PyNEST EI-clustered network: default parameters for EI-clustered network
+---------------------------------------------------------------------------
+
+default parameters for EI-clustered network simulation
+"""
+import numpy as np
+
+############################################
+# general parameters
+############################################
+eps = np.finfo(float).eps
+n_jobs = 1
+
+dt = 0.1
+simtime = 1000.0
+warmup = 0.0
+record_voltage = False
+record_from = "all"
+recording_interval = dt
+return_weights = False
+
+############################################
+# neuron parameters
+############################################
+neuron_type = "iaf_psc_exp"  # 'gif_psc_exp'
+E_L = 0.0
+C_m = 1.0
+tau_E = 20.0
+tau_I = 10.0
+t_ref = 5.0
+V_th_E = 20.0
+V_th_I = 20.0
+V_r = 0.0
+I_xE = 1.0
+I_xI = 2.0
+delta_I_xE = 0.0
+delta_I_xI = 0.0
+I_th_E = 1.25
+I_th_I = 0.78
+V_m = "rand"
+
+# synapse parameters
+tau_syn_ex = 3.0
+tau_syn_in = 2.0
+delay = 0.1  # synaptic delay
+
+# Distribution of synaptic weights
+# available distributions= https://nest-simulator.readthedocs.io/en/stable/guides/connection_management.html#dist-params
+
+DistParams = {"distribution": "normal", "sigma": 0.0, "fraction": False}
+
+syn_params = {"U": 0.2, "u": 0.0, "tau_rec": 120.0, "tau_fac": 0.0}
+
+############################################
+# network parameters
+############################################
+
+# number of units
+N_E = 1200
+N_I = 300
+
+# cluster number
+Q = 6
+# cluster weight ratios
+jplus = np.ones((2, 2))
+
+# connection probabilities
+ps = np.array([[0.2, 0.5], [0.5, 0.5]])
+
+# connections strengths
+# weights are js/sqrt(N)
+# nan means they are calculated
+js = np.ones((2, 2)) * np.nan
+# factors for inhibitory weights
+ge = 1.2
+gi = 1.0
+gie = 1.0
+
+# factor multiplied with weights
+s = 1.0
+fixed_indegree = False
+
+############################################
+# stimulation parameters
+############################################
+stim_clusters = None  # clusters to be stimulated
+stim_amp = 0.0  # amplitude of the stimulation current in pA
+stim_starts = []  # list of stimulation start times
+stim_ends = []  # list of stimulation end times