Merge branch 'master' into split-api-docs

doc/htmldoc/conf.py

@@ -374,11 +374,6 @@ def copy_example_file(src):
 copy_example_file("examples/Potjans_2014/raster_plot.png")
 copy_example_file("examples/Potjans_2014/microcircuit.png")
 copy_example_file("examples/hpc_benchmark_connectivity.svg")
-copyfile(
-    os.path.join(pynest_dir, "examples/Potjans_2014/README.rst"),
-    "examples/README.rst",
-)
-
 
 def patch_documentation(patch_url):
     """Apply a hot-fix patch to the documentation before building it.
@@ -405,10 +400,9 @@ def patch_documentation(patch_url):
       3. retrieve the patch
 
     """
-
     print("Preparing patch...")
     try:
-        git_dir = repo_root_dir / ".git"
+        git_dir = f"{repo_root_dir}/.git"
         git_hash = subprocess.check_output(
             f"GIT_DIR='{git_dir}' git rev-parse HEAD", shell=True, encoding="utf8"
         ).strip()
@@ -418,7 +412,7 @@ def patch_documentation(patch_url):
         print(f"  retrieving {patch_url}")
         urlretrieve(patch_url, patch_file)
         print(f"  applying {patch_file}")
-        result = subprocess.check_output("patch -p3", stdin=open(patch_file, "r"), stderr=subprocess.STDOUT, shell=True)
+        result = subprocess.check_output(f"git apply '{patch_file}'", stderr=subprocess.STDOUT, shell=True)
         print(f"Patch result: {result}")
     except Exception as exc:
         print(f"Error while applying patch: {exc}")

doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst

@@ -104,7 +104,7 @@ commands.
 
 3. Build the docs:
 
-.. code-black:: bash
+.. code-block:: bash
 
    sphinx-build . ../_build/html -b html
 

doc/htmldoc/devices/record_from_simulations.rst

@@ -101,7 +101,7 @@ kernel attribute ``recording_backends``.
 
 If a recording backend has global properties (i.e., parameters shared
 by all enrolled recording devices), those can be inspected with
-:py:func`.GetDefaults`
+:py:func:`.GetDefaults`
 
 ::
 

doc/htmldoc/examples/index.rst

@@ -237,6 +237,7 @@ PyNEST examples
 .. toctree::
    :hidden:
 
+   running_notebooks
    ../auto_examples/sudoku/index
    ../auto_examples/pong/index
    ../auto_examples/spatial/index
@@ -284,6 +285,8 @@ PyNEST examples
    ../auto_examples/brunel_siegert_nest
    ../auto_examples/brunel_exp_multisynapse_nest
    ../auto_examples/brunel_alpha_evolution_strategies
+   ../auto_examples/sonata_example/index
+   ../auto_examples/sonata_example/sonata_network
    ../auto_examples/spatial/conncomp
    ../auto_examples/spatial/conncon_sources
    ../auto_examples/spatial/conncon_targets

doc/htmldoc/faqs/faqs.rst

@@ -86,4 +86,6 @@ Connections
        nest.Connect(n, n[:1], sync_spec={'model'='exc_dist_syn'})
        nest.Simulate(10)
 
+.. _faqs_precise_neurons:
+
 .. include:: qa-precise-spike-times.rst

doc/htmldoc/faqs/qa-precise-spike-times.rst

@@ -1,5 +1,3 @@
-.. _faqs_precise_neurons:
-
 Questions and answers about precise neurons
 -------------------------------------------
 

doc/htmldoc/hpc/slurm_script.rst

@@ -116,7 +116,7 @@ trying to increase the speed of the simulation.
    How many nodes do you need for your simulations?
    This depends on how much memory is available for each node.
 
-   For example: The :ref:`microcircuit model <toc_microcircuit>` requires around 16 GB of memory and the `multi-area-model <https://github.com/INM-6/multi-area-model>`_ requires 1.4 TB.
+   For example: The :doc:`microcircuit model <../auto_examples/Potjans_2014/index>` requires around 16 GB of memory and the `multi-area-model <https://github.com/INM-6/multi-area-model>`_ requires 1.4 TB.
    If a node has 128 GB of memory then one node is more than sufficient for the microcircuit model but the multi-area model
    will need 12 nodes to run.
 

doc/htmldoc/hpc/threading.rst

@@ -22,7 +22,7 @@ For a detailed investigation, we recommend reading Kurth et al. 2022 [1]_.
 .. _pinning_threads:
 
 Pinning threads
---------------
+---------------
 
 Pinning threads allows you to control the distribution of threads across available cores on your system, and is particularly
 useful in high performance computing (HPC) systems.

doc/htmldoc/installation/admin.rst

@@ -6,7 +6,7 @@ Administrator installation instructions
 If you need to deploy NEST on a machine
 
 
-*  Check out our guides to :ref:`optimizing NEST for HPC systems <hpc_index>`
+*  Check out our guides to :ref:`optimizing NEST for HPC systems <optimize_performance>`
 
 Configure HPC systems
 ~~~~~~~~~~~~~~~~~~~~~

doc/htmldoc/model_details/HillTononiModels.ipynb

@@ -74,7 +74,7 @@
     "The repolarizing current is active during, and only during the refractory period:\n",
     "\\begin{equation}\n",
     "g_{\\text{spike}} = \\begin{cases}  1  & \\text{neuron is refractory}\\\\\n",
-    " 0 & \\text{else} \\end{cases}\n",
+    "0 & \\text{else} \\end{cases}\n",
     "\\end{equation}\n",
     "\n",
     "During the refractory period, the neuron cannot fire new spikes, but all state variables evolve freely, nothing is clamped. \n",
@@ -147,7 +147,7 @@
     "N_T &= 2 \\\\\n",
     "m_T^{\\infty}(V) &=  \\frac{1}{1+\\exp\\left(-\\frac{V+59\\text{mV}}{6.2\\text{mV}}\\right)}\\\\\n",
     "\\tau_{m,T}(V) &= 0.13\\text{ms} \n",
-    "  + \\frac{0.22\\text{ms}}{\\exp\\left(-\\frac{V  + 132\\text{mV}}{16.7\\text{mV}}\\right) + \\exp\\left(\\frac{V +  16.8\\text{mV}}{18.2\\text{mV}}\\right)} \\\\ \n",
+    "+ \\frac{0.22\\text{ms}}{\\exp\\left(-\\frac{V  + 132\\text{mV}}{16.7\\text{mV}}\\right) + \\exp\\left(\\frac{V +  16.8\\text{mV}}{18.2\\text{mV}}\\right)} \\\\ \n",
     "h_T^{\\infty}(V) &=  \\frac{1}{1+\\exp\\left(\\frac{V+83\\text{mV}}{4\\text{mV}}\\right)}\\\\\n",
     "\\tau_{h,T}(V) &= 8.2\\text{ms} +  \\frac{56.6\\text{ms} +  0.27\\text{ms} \\exp\\left(\\frac{V   + 115.2\\text{mV}}{5\\text{mV}}\\right)}{1 +   \\exp\\left(\\frac{V  + 86\\text{mV}}{3.2\\text{mV}}\\right)}\n",
     "\\end{align}\n",
@@ -201,30 +201,30 @@
     "##### Equations in paper\n",
     "\n",
     "\\begin{align}\n",
-    " dD/dt &= D_{\\text{influx}} - D(1-D_{\\text{eq}})/\\tau_D \\\\\n",
-    " D_{\\text{influx}} &= 1/\\{1+ \\exp[-(V-D_{\\theta})/\\sigma_D]\\} \\\\\n",
-    " m_{DK}^{\\infty} &= 1/1 + (d_{1/2}D)^{3.5}\n",
+    "dD/dt &= D_{\\text{influx}} - D(1-D_{\\text{eq}})/\\tau_D \\\\\n",
+    "D_{\\text{influx}} &= 1/\\{1+ \\exp[-(V-D_{\\theta})/\\sigma_D]\\} \\\\\n",
+    "m_{DK}^{\\infty} &= 1/1 + (d_{1/2}D)^{3.5}\n",
     "\\end{align}\n",
     "\n",
     "There are several problems with these equations.\n",
     "\n",
     "In the steady state the first equation becomes\n",
     "\\begin{equation}\n",
-    " 0 = - D(1-D_{\\text{eq}})/\\tau_D \n",
-    " \\end{equation}\n",
-    " with solution\n",
-    " \\begin{equation}\n",
-    " D = 0\n",
+    "0 = - D(1-D_{\\text{eq}})/\\tau_D \n",
+    "\\end{equation}\n",
+    "with solution\n",
+    "\\begin{equation}\n",
+    "D = 0\n",
     "\\end{equation}\n",
     "This contradicts both the statement [HT05, p. 1679] that $D\\to D_{\\text{eq}}$ in this case, and the requirement that $D>0$ to avoid a singluarity in the equation for $m_{DK}^{\\infty}$. The most plausible correction is\n",
     "\\begin{equation}\n",
-    " dD/dt = D_{\\text{influx}} - (D-D_{\\text{eq}})/\\tau_D \n",
+    "dD/dt = D_{\\text{influx}} - (D-D_{\\text{eq}})/\\tau_D \n",
     "\\end{equation}\n",
     "\n",
     "The third equation appears incorrect and logic as well as Wang et al, *J Neurophysiol* 89:3279–3293, 2003, Eq 9, cited in [HT05, p 1679], indicate that the correct equation is\n",
     "\n",
     "\\begin{equation}\n",
-    " m_{DK}^{\\infty} = 1/(1 + (d_{1/2} / D)^{3.5})\n",
+    "m_{DK}^{\\infty} = 1/(1 + (d_{1/2} / D)^{3.5})\n",
     "\\end{equation}\n",
     "\n",
     "\n",
@@ -235,10 +235,10 @@
     "\n",
     "\\begin{align}\n",
     "I_{DK} &= - g_{\\text{peak},DK} m_{DK}(V,t) (V - E_{DK})\\\\\n",
-    " m_{DK} &= \\frac{1}{1 + \\left(\\frac{d_{1/2}}{D}\\right)^{3.5}}\\\\\n",
-    " \\frac{dD}{dt} &= D_{\\text{influx}}(V) - \\frac{D-D_{\\text{eq}}}{\\tau_D} = \\frac{D_{\\infty}(V)-D}{\\tau_D} \\\\\n",
-    " D_{\\infty}(V) &= \\tau_D D_{\\text{influx}}(V) + {D_{\\text{eq}}}\\\\\n",
-    " D_{\\text{influx}} &= \\frac{D_{\\text{influx,peak}}}{1+ \\exp\\left(-\\frac{V-D_{\\theta}}{\\sigma_D}\\right)} \n",
+    "m_{DK} &= \\frac{1}{1 + \\left(\\frac{d_{1/2}}{D}\\right)^{3.5}}\\\\\n",
+    "\\frac{dD}{dt} &= D_{\\text{influx}}(V) - \\frac{D-D_{\\text{eq}}}{\\tau_D} = \\frac{D_{\\infty}(V)-D}{\\tau_D} \\\\\n",
+    "D_{\\infty}(V) &= \\tau_D D_{\\text{influx}}(V) + {D_{\\text{eq}}}\\\\\n",
+    "D_{\\text{influx}} &= \\frac{D_{\\text{influx,peak}}}{1+ \\exp\\left(-\\frac{V-D_{\\theta}}{\\sigma_D}\\right)} \n",
     "\\end{align}\n",
     "\n",
     "with \n",
@@ -281,10 +281,10 @@
     "The conductance change due to a single input spike at time $t=0$ through a channel of type $X$ is given by (see below for exceptions)\n",
     "\n",
     "\\begin{align}\n",
-    "    \\bar{g}_X(t) &= g_X(t)\\\\\n",
-    "    g_X(t) &= g_{\\text{peak}, X}\\frac{\\exp(-t/\\tau_1) - \\exp(-t/\\tau_2)}{\n",
-    "                 \\exp(-t_{\\text{peak}}/\\tau_1) - \\exp(-t_{\\text{peak}}/\\tau_2)} \\Theta(t)\\\\\n",
-    "     t_{\\text{peak}} &= \\frac{\\tau_2 \\tau_1}{\\tau_2 - \\tau_1} \\ln\\frac{ \\tau_2}{\\tau_1}\n",
+    "\\bar{g}_X(t) &= g_X(t)\\\\\n",
+    "g_X(t) &= g_{\\text{peak}, X}\\frac{\\exp(-t/\\tau_1) - \\exp(-t/\\tau_2)}{\n",
+    "\\exp(-t_{\\text{peak}}/\\tau_1) - \\exp(-t_{\\text{peak}}/\\tau_2)} \\Theta(t)\\\\\n",
+    "t_{\\text{peak}} &= \\frac{\\tau_2 \\tau_1}{\\tau_2 - \\tau_1} \\ln\\frac{ \\tau_2}{\\tau_1}\n",
     "\\end{align} \n",
     "\n",
     "where $t_{\\text{peak}}$ is the time of the conductance maximum and $\\tau_1$ and $\\tau_2$ are synaptic rise- and decay-time, respectively; $\\Theta(t)$ is the Heaviside step function. The equation is integrated using exact integration in Synthesis; in NEST, it is included in the ODE-system integrated using the Runge-Kutta-Fehlberg 4(5) solver from GSL.\n",
@@ -306,11 +306,11 @@
     "The voltage-dependent gating $m(V, t)$ is defined as follows (based on textual description, Vargas-Caballero and Robinson *J Neurophysiol* 89:2778–2783, 2003, [doi:10.1152/jn.01038.2002](http://dx.doi.org/10.1152/jn.01038.2002), and code inspection):\n",
     "\n",
     "\\begin{align}\n",
-    "     m(V, t) &= a(V) m_{\\text{fast}}^*(V, t) + ( 1 - a(V) ) m_{\\text{slow}}^*(V, t)\\\\\n",
-    "     a(V)    &= 0.51 - 0.0028 V \\\\\n",
-    "     m^{\\infty}(V) &= \\frac{1}{ 1 + \\exp\\left( -S_{\\text{act}} ( V - V_{\\text{act}} ) \\right) } \\\\\n",
-    "     m_X^*(V, t) &= \\min(m^{\\infty}(V), m_X(V, t))\\\\\n",
-    "      \\frac{\\text{d}m_X}{\\text{d}t} &= \\frac{m^{\\infty}(V) - m_X }{ \\tau_{\\text{Mg}, X}}\n",
+    "m(V, t) &= a(V) m_{\\text{fast}}^*(V, t) + ( 1 - a(V) ) m_{\\text{slow}}^*(V, t)\\\\\n",
+    "a(V)    &= 0.51 - 0.0028 V \\\\\n",
+    "m^{\\infty}(V) &= \\frac{1}{ 1 + \\exp\\left( -S_{\\text{act}} ( V - V_{\\text{act}} ) \\right) } \\\\\n",
+    "m_X^*(V, t) &= \\min(m^{\\infty}(V), m_X(V, t))\\\\\n",
+    "\\frac{\\text{d}m_X}{\\text{d}t} &= \\frac{m^{\\infty}(V) - m_X }{ \\tau_{\\text{Mg}, X}}\n",
     "\\end{align} \n",
     "\n",
     "where $X$ is \"slow\" or \"fast\". $a(V)$ expresses voltage-dependent weighting between slow and fast unblocking, $m^{\\infty}(V)$ the steady-state value of the proportion of unblocked NMDA-channels, the minimum condition in $m_X^*(V,t)$ the instantaneous blocking and the differential equation for $m_X(V,t)$ the unblocking dynamics.\n",
@@ -1004,7 +1004,7 @@
     "I_T &= g_{\\text{peak}, T} m_T^2(V, t) h_T(V,t) (V-E_T) \\\\\n",
     "m_T^{\\infty}(V) &=  \\frac{1}{1+\\exp\\left(-\\frac{V+59\\text{mV}}{6.2\\text{mV}}\\right)}\\\\\n",
     "\\tau_{m,T}(V) &= 0.13\\text{ms} \n",
-    "  + \\frac{0.22\\text{ms}}{\\exp\\left(-\\frac{V  + 132\\text{mV}}{16.7\\text{mV}}\\right) + \\exp\\left(\\frac{V +  16.8\\text{mV}}{18.2\\text{mV}}\\right)} \\\\ \n",
+    "+ \\frac{0.22\\text{ms}}{\\exp\\left(-\\frac{V  + 132\\text{mV}}{16.7\\text{mV}}\\right) + \\exp\\left(\\frac{V +  16.8\\text{mV}}{18.2\\text{mV}}\\right)} \\\\ \n",
     "h_T^{\\infty}(V) &=  \\frac{1}{1+\\exp\\left(\\frac{V+83\\text{mV}}{4\\text{mV}}\\right)}\\\\\n",
     "\\tau_{h,T}(V) &= 8.2\\text{ms} +  \\frac{56.6\\text{ms} +  0.27\\text{ms} \\exp\\left(\\frac{V   + 115.2\\text{mV}}{5\\text{mV}}\\right)}{1 +   \\exp\\left(\\frac{V  + 86\\text{mV}}{3.2\\text{mV}}\\right)}\n",
     "\\end{align}"
@@ -1248,10 +1248,10 @@
     "\n",
     "\\begin{align}\n",
     "I_{DK} &= - g_{\\text{peak},DK} m_{DK}(V,t) (V - E_{DK})\\\\\n",
-    " m_{DK} &= \\frac{1}{1 + \\left(\\frac{d_{1/2}}{D}\\right)^{3.5}}\\\\\n",
-    " \\frac{dD}{dt} &= D_{\\text{influx}}(V) - \\frac{D-D_{\\text{eq}}}{\\tau_D} = \\frac{D_{\\infty}(V)-D}{\\tau_D} \\\\\n",
-    " D_{\\infty}(V) &= \\tau_D D_{\\text{influx}}(V) + {D_{\\text{eq}}}\\\\\n",
-    " D_{\\text{influx}} &= \\frac{D_{\\text{influx,peak}}}{1+ \\exp\\left(-\\frac{V-D_{\\theta}}{\\sigma_D}\\right)} \n",
+    "m_{DK} &= \\frac{1}{1 + \\left(\\frac{d_{1/2}}{D}\\right)^{3.5}}\\\\\n",
+    "\\frac{dD}{dt} &= D_{\\text{influx}}(V) - \\frac{D-D_{\\text{eq}}}{\\tau_D} = \\frac{D_{\\infty}(V)-D}{\\tau_D} \\\\\n",
+    "D_{\\infty}(V) &= \\tau_D D_{\\text{influx}}(V) + {D_{\\text{eq}}}\\\\\n",
+    "D_{\\text{influx}} &= \\frac{D_{\\text{influx,peak}}}{1+ \\exp\\left(-\\frac{V-D_{\\theta}}{\\sigma_D}\\right)} \n",
     "\\end{align}\n",
     "\n",
     "with \n",
@@ -1363,8 +1363,8 @@
    "metadata": {},
    "source": [
     "- Note that current in steady state is \n",
-    "    - $\\approx 0$ for $V < -40$mV\n",
-    "    - $\\sim -(V-E_{DK})$ for $V> -30$mV"
+    "- $\\approx 0$ for $V < -40$mV\n",
+    "- $\\sim -(V-E_{DK})$ for $V> -30$mV"
    ]
   },
   {
@@ -1717,11 +1717,11 @@
     "The equations for this channel are\n",
     "\n",
     "\\begin{align}\n",
-    "    \\bar{g}_{\\text{NMDA}}(t) &= m(V, t) g_{\\text{NMDA}}(t)     m(V, t)\\\\ &= a(V) m_{\\text{fast}}^*(V, t) + ( 1 - a(V) ) m_{\\text{slow}}^*(V, t)\\\\\n",
-    "     a(V)    &= 0.51 - 0.0028 V \\\\\n",
-    "     m^{\\infty}(V) &= \\frac{1}{ 1 + \\exp\\left( -S_{\\text{act}} ( V - V_{\\text{act}} ) \\right) } \\\\\n",
-    "     m_X^*(V, t) &= \\min(m^{\\infty}(V), m_X(V, t))\\\\\n",
-    "      \\frac{\\text{d}m_X}{\\text{d}t} &= \\frac{m^{\\infty}(V) - m_X }{ \\tau_{\\text{Mg}, X}}\n",
+    "\\bar{g}_{\\text{NMDA}}(t) &= m(V, t) g_{\\text{NMDA}}(t)     m(V, t)\\\\ &= a(V) m_{\\text{fast}}^*(V, t) + ( 1 - a(V) ) m_{\\text{slow}}^*(V, t)\\\\\n",
+    "a(V)    &= 0.51 - 0.0028 V \\\\\n",
+    "m^{\\infty}(V) &= \\frac{1}{ 1 + \\exp\\left( -S_{\\text{act}} ( V - V_{\\text{act}} ) \\right) } \\\\\n",
+    "m_X^*(V, t) &= \\min(m^{\\infty}(V), m_X(V, t))\\\\\n",
+    "\\frac{\\text{d}m_X}{\\text{d}t} &= \\frac{m^{\\infty}(V) - m_X }{ \\tau_{\\text{Mg}, X}}\n",
     "\\end{align} \n",
     "\n",
     "where $g_{\\text{NMDA}}(t)$ is the beta functions as for the other channels. In case of instantaneous unblocking, $m=m^{\\infty}$."

doc/htmldoc/nest_behavior/running_simulations.rst

@@ -82,7 +82,7 @@ In linear simulation scripts that build a network, simulate it, carry
 out some post-processing and exit, the user does not have to worry about
 the delay extrema *dmin* and *dmax* as they are set automatically to the
 correct values. However, NEST also allows subsequent calls
-to\ :py:func:`.Simulate`, which only work correctly if the content of the spike
+to :py:func:`.Simulate`, which only work correctly if the content of the spike
 buffers is preserved over the simulations.
 
 As mentioned above, the size of that buffer depends on *dmin+dmax* and
@@ -125,7 +125,7 @@ also means that the membrane potential recording will never show values
 above the threshold. The time of the spike is always the time at *the
 end of the interval* during which the threshold was crossed.
 
-NEST also has a some models that determine the precise time of the
+NEST also has some models that determine the precise time of the
 threshold crossing during the interval. Please see the documentation on
 :ref:`precise spike time neurons <sim_precise_spike_times>`
 for details about neuron update in continuous time and the

doc/htmldoc/neurons/parametrization.rst

@@ -167,7 +167,7 @@ others can be used when connecting.
    spatial_nodes = nest.Create('iaf_psc_alpha', positions=positions)
 
    parameter = -60 + nest.spatial.pos.x + (0.4 * nest.spatial.pos.x * nest.random.normal())
-   spatial_nodes.set('V_m'=parameter)
+   spatial_nodes.set(V_m=parameter)
 
    node_pos = np.array(nest.GetPosition(spatial_nodes))
    node_pos[:,1]
@@ -252,7 +252,7 @@ parameter:
     fig, ax = pyplot.subplots(figsize=(12, 6))
     bars = ax.hist(targets, bins=N, edgecolor='black', linewidth=1.2)
 
-    pyplot.xticks(bars[1] + 0.5,np.arange(1, N+1))
+    pyplot.xticks(bars[1] + 0.5,np.arange(1, N+2))
     ax.set_title('Connections from node with NodeID {}'.format(spatial_nodes[middle_node].get('global_id')))
     ax.set_xlabel('Target NodeID')
     ax.set_ylabel('Num. connections');
@@ -468,9 +468,9 @@ Using parameters makes it easy to set node properties
 |                                               |                                                    |
 | ::                                            | ::                                                 |
 |                                               |                                                    |
-|     for gid in nrns:                          |     nrns.V_m=nest.random.uniform(-20., 20)         |
-|       v_m = numpy.random.uniform(-20., 20.)   |                                                    |
-|       nest.SetStatus([node_id], {'V_m': V_m}) |                                                    |
+|     for gid in nrns:                          |     nrns.V_m = nest.random.uniform(-20.0, 20.0)    |
+|       v_m = numpy.random.uniform(-20.0, 20.0) |                                                    |
+|       nest.SetStatus(gid, {"V_m": v_m})       |                                                    |
 |                                               |                                                    |
 |                                               |                                                    |
 +-----------------------------------------------+----------------------------------------------------+