Merge pull request #2823 from jessica-mitchell/update-microcircuit-docs

Update microcircuit docs regarding virtual process constraint and fix images

doc/htmldoc/conf.py

@@ -354,9 +354,6 @@ def copy_example_file(src):
 
 
 # -- Copy documentation for Microcircuit Model ----------------------------
-copy_example_file("examples/Potjans_2014/box_plot.png")
-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")
 
 

pynest/examples/Potjans_2014/README.rst

@@ -4,19 +4,23 @@ Cortical microcircuit model
 This is a PyNEST implementation of the cortical microcircuit model by Potjans and Diesmann [1]_.
 The network model represents four layers of cortex, L2/3, L4, L5, and L6, each consisting of a population of excitatory neurons and a population of inhibitory neurons.
 
-.. |img1| image:: ../../static/img/microcircuit.png
 
-.. |img2| image:: ../../static/img/raster_plot.png
+.. grid:: 1 2 3 3
+
+   .. grid-item::
+
+     .. image:: ../../static/img/microcircuit.png
+
+   .. grid-item::
+
+     .. image:: ../../static/img/raster_plot.png
+
+   .. grid-item::
+
+     .. image:: ../../static/img/box_plot.png
 
-.. |img3| image:: ../../static/img/box_plot.png
 
-.. table:: 
-   :align: center
 
-   +--------+--------+--------+
-   | |img1| | |img2| | |img3| |
-   +--------+--------+--------+
-
 Left: network sketch [2]_. Middle: raster plot showing spiking activity. Right: firing rates as box plots.
 
 Citing this code
@@ -54,11 +58,21 @@ The output will be saved in the ``data`` directory.
 
 The code can be `parallelized <https://nest-simulator.readthedocs.io/en/latest/guides/parallel_computing.html>`_ using OpenMP and MPI, if NEST has been built with these features.
 The number of threads (per MPI process) can be chosen by adjusting ``local_num_threads`` in ``sim_params.py``.
-The command for running the script with two MPI processes is:
+
+
+.. important::
+
+   When scaling up the microcircuit model, you may encounter errors during simulation when there is less than 4 virtual processes.
+   The number of threads should, therefore, be 4 or more. You can increase
+   the number of MPI processes or set either ``local_num_threads`` to a value >= 4 or replace ``local_num_threads`` by ``total_num_virtual_procs`` and set it to a value >= 4.
+
+   For more information about MPI processes and threading see :ref:`our guide on HPC systems <optimize_performance>`.
+
+The command for running the script with four MPI processes is:
 
 .. code-block:: bash
 
-   mpirun -n 2 python3 run_microcircuit.py
+   mpirun -n 4 python3 run_microcircuit.py
 
 External drive and initial conditions
 -------------------------------------

pynest/examples/Potjans_2014/sim_params.py

@@ -45,8 +45,13 @@
     "data_path": os.path.join(os.getcwd(), "data/"),
     # Seed for NEST
     "rng_seed": 55,
-    # number of threads per MPI process
-    "local_num_threads": 1,
+    # Number of threads per MPI process
+    #
+    # Note that when you scale up the network, the microcircut model
+    # may not run correctly if there is < 4 virtual processes
+    # (i.e., a thread in an MPI process)
+    # If you have 4 or more MPI processes, then you can set this value to 1.
+    "local_num_threads": 4,
     # recording interval of the membrane potential (in ms)
     "rec_V_int": 1.0,
     # if True, data will be overwritten,