Merge branch 'master' into nest-server-reqs

Author: babsey

README.md

@@ -12,7 +12,7 @@
 
 [![Ubuntu version](https://img.shields.io/badge/ubuntu-(PPA)-blue?logo=debian)](https://nest-simulator.readthedocs.io/en/latest/installation/)
 [![Fedora package](https://img.shields.io/fedora/v/nest?logo=fedora)](https://src.fedoraproject.org/rpms/nest)
-[![Conda version](https://img.shields.io/conda/vn/conda-forge/nest-simulator.svg?logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/nest-simulator)
+[![conda-forge version](https://img.shields.io/conda/vn/conda-forge/nest-simulator.svg?logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/nest-simulator)
 [![Homebrew version](https://img.shields.io/homebrew/v/nest.svg?logo=apple)](https://formulae.brew.sh/formula/nest)
 [![Docker Image Version](https://img.shields.io/docker/v/nest/nest-simulator?color=blue&label=docker&logo=docker&logoColor=white&sort=semver)](https://hub.docker.com/r/nest/nest-simulator)
 [![Virtual applicance](https://img.shields.io/badge/VM-v3.7-blue?logo=CodeSandbox)](https://nest-simulator.readthedocs.io/en/latest/installation/livemedia.html#live-media)
@@ -22,110 +22,81 @@
 
 NEST is a simulator for spiking neural network models that focuses on the
 dynamics, size and structure of neural systems rather than on the exact
-morphology of individual neurons. The development of NEST is coordinated by the
-NEST Initiative. General information on the NEST Initiative can be found at
-its homepage at https://www.nest-initiative.org.
+morphology of individual neurons.
+
+A NEST simulation tries to follow the logic of an electrophysiological
+experiment that takes place inside a computer with the difference that the
+neural system to be investigated must be defined by the experimenter.
 
 NEST is ideal for networks of spiking neurons of any size, for example:
 
-- Models of information processing e.g. in the visual or auditory cortex of
+- Models of information processing, e.g., in the visual or auditory cortex of
   mammals,
-- Models of network activity dynamics, e.g. laminar cortical networks or
+- Models of network activity dynamics, e.g., laminar cortical networks or
   balanced random networks,
 - Models of learning and plasticity.
 
-For copyright information please refer to the `LICENSE` file and to the
-information header in the source files.
+## Key features of NEST
 
-## How do I use NEST?
+* NEST provides a Python interface or a stand-alone application
+* NEST provides a large collection of [neurons and synapse models](https://nest-simulator.org/documentation/models/index.html)
+* NEST provides numerous [example network scripts](https://nest-simulator.org/documentation/examples/index.html) along with
+  [tutorials and guides](https://nest-simulator.org/documentation/get-started_index.html) to help you develop your simulation
+* NEST has a large community of experienced developers and users; NEST was first released in 1994 under the name SYNOD, and has been extended and improved ever since
+* NEST is extensible: you can extend NEST by adding your own modules
+* NEST is scalable: Use NEST on your laptop or the largest supercomputers
+* NEST is memory efficient: It makes the best use of your multi-core computer and compute clusters with minimal user intervention
+* NEST is an open source project and is licensed under the GNU General Public License v2 or later
+* NEST employs continuous integration workflows in order to maintain high code quality standards for correct and reproducible simulations
 
-You can use NEST either via Python (PyNEST) or as a stand-alone application
-(nest). PyNEST provides a set of commands to the Python interpreter which give
-you access to NEST's simulation kernel. With these commands, you describe and
-run your network simulation. You can also complement PyNEST with PyNN, a
-simulator-independent set of Python commands to formulate and run neural
-simulations. While you define your simulations in Python, the actual simulation
-is executed within NEST's highly optimized simulation kernel which is written
-in C++.
 
-A NEST simulation tries to follow the logic of an electrophysiological
-experiment that takes place inside a computer with the difference, that the
-neural system to be investigated must be defined by the experimenter.
+## Documentation
 
-The neural system is defined by a possibly large number of neurons and their
-connections. In a NEST network, different neuron and synapse models can
-coexist. Any two neurons can have multiple connections with different
-properties. Thus, the connectivity can in general not be described by a weight
-or connectivity matrix but rather as an adjacency list.
-
-To manipulate or observe the network dynamics, the experimenter can define
-so-called devices which represent the various instruments (for measuring and
-stimulation) found in an experiment. These devices write their data either to
-memory or to file.
-
-NEST is extensible and new models for neurons, synapses, and devices can be
-added.
-
-To get started with NEST, please see the [Documentation Page for
-Tutorials](https://www.nest-simulator.org/documentation/).
-
-## Why should I use NEST?
-
-To learn more about the capabilities of NEST, please read the complete [feature
-summary](https://www.nest-simulator.org/features/).
-
-- NEST provides over 50 neuron models many of which have been published. Choose
-  from simple integrate-and-fire neurons with current or conductance based
-  synapses, over the Izhikevich or AdEx models, to Hodgkin-Huxley models.
-- NEST provides over 10 synapse models, including short-term plasticity
-  (Tsodyks & Markram) and different variants of spike-timing dependent
-  plasticity (STDP).
-- NEST provides many examples that help you getting started with your own
-  simulation project.
-- NEST offers convenient and efficient commands to define and connect large
-  networks, ranging from algorithmically determined connections to data-driven
-  connectivity.
-- NEST lets you inspect and modify the state of each neuron and each connection
-  at any time during a simulation.
-- NEST is fast and memory efficient. It makes best use of your multi-core
-  computer and compute clusters with minimal user intervention.
-- NEST runs on a wide range of UNIX-like systems, from MacBooks to
-  supercomputers.
-- NEST has minimal dependencies. All it really needs is a C++ compiler.
-  Everything else is optional.
-- NEST developers are using agile continuous integration-based workflows in
-  order to maintain high code quality standards for correct and reproducible
-  simulations.
-- NEST has one of the largest and most experienced developer communities of all
-  neural simulators. NEST was first released in 1994 under the name SYNOD and
-  has been extended and improved ever since.
+Please visit our [online documentation](https://nest-simulator.org/documentation) for details on installing and using NEST.
 
-## License
 
-NEST is open source software and is licensed under the [GNU General Public
-License v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) or
-later.
+## Cite NEST
+
+If you use NEST as part of your research, please cite the *version* of NEST you used.
+The full citation for each release can be found on [Zenodo](https://zenodo.org/search?q=title%3ANEST%20AND%20-description%3Agraphical%20AND%20simulator&l=list&p=1&s=10&sort=publication-desc)
+
+For general citations, please use
+
+`Gewaltig M-O & Diesmann M (2007) NEST (Neural Simulation Tool) Scholarpedia 2(4):1430.`
+
+## Contact
 
-## Installing NEST
 
-Please see the online [NEST Installation Instructions](http://www.nest-simulator.org/installation)
-to find out how to install NEST.
+If you need help or would like to discuss an idea or issue,
+join our [maling list](https://nest-simulator.org/documentation/developer_space/guidelines/mailing_list_guidelines.html),
+where we encourage active participation from our developers and users to share their knowledge and experience with NEST.
 
-## Getting help
 
-- You can run the `help` command in the NEST interpreter to find documentation
-  and learn more about available commands.
-- For queries regarding NEST usage, please use the [NEST users mailing
-  list](https://www.nest-initiative.org/mailinglist/).
-- Information on the Python bindings to NEST can be found in
-  `${prefix}/share/doc/nest/README.md`.
-- For those looking to extend NEST, developer documentation on [Contributing to
-  NEST](https://nest-simulator.readthedocs.io/en/latest/contribute/index.html) is available.
+You can find other [ways to get in touch here](https://nest-simulator.org/documentation/community.html).
 
-## Citing NEST
 
-Please cite NEST if you use it in your work.
+## Contribute
 
-- You can find all the information for [citing NEST here](https://nest-simulator.readthedocs.io/en/latest/citing-nest.html)
+NEST is built on an active community and we welcome contributions to our code and documentation.
 
 
+For bug reports, feature requests, documentation improvements, or other issues,
+you can create a [GitHub issue](https://github.com/nest/nest-simulator/issues/new/choose),
+
+For working with NEST code and documentation, you can find guidelines for contributions
+[in our documentation](https://nest-simulator.org/documentation/developer_space/index.html#contribute-to-nest)
+
+
+## Publications
+
+You can find a list of NEST [related publications here](https://www.nest-simulator.org/publications/).
+
+## License
+
+
+NEST is open source software and is licensed under the [GNU General Public
+License v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) or
+later.
+
+General information on the NEST Initiative can be found at
+its homepage at https://www.nest-initiative.org.

bin/nest-server-mpi

@@ -73,4 +73,4 @@ else:
                 continue
 
         log(call_name, f"sending reponse gather, data={response}")
-        comm.gather(nest.serializable(response), root=0)
+        comm.gather(nest.serialize_data(response), root=0)

doc/htmldoc/benchmark_results.rst

@@ -44,7 +44,13 @@ Strong scaling experiment of the Multi-area-model [5]_
        :class: sd-align-major-center
        :columns: 10
 
-       .. image:: /static/img/mam_benchmark.png
+       Dynamical regime: Ground state
+       
+       .. image:: /static/img/mam_ground-state_benchmark.png
+
+       Dynamical regime: Metastable state
+       
+       .. image:: /static/img/mam_metastable-state_benchmark.png
 
 
 .. grid:: 1 1 1 1
@@ -54,6 +60,7 @@ Strong scaling experiment of the Multi-area-model [5]_
        :class: sd-align-minor-center
 
        * The model has ~4.1 million neurons and ~24 billion synapses, minimal delay 0.1 ms
+       * It can be run in two different dynamical regimes: the ground state and the metastable state [5]_.
        * 2 MPI processes per node, 64 threads per MPI process
        * Steady decrease of run time with additional compute resources
        * Data averaged over 3 runs with different seeds, error bars indicate standard deviation

doc/htmldoc/developer_space/guidelines/mailing_list_guidelines.rst

@@ -30,7 +30,7 @@ please follow the guidelines below:
 
       * the steps you took that lead to the problem.
       * the specific error messages you get.
-      * relevant system and version information (e.g.,  Ubuntu 22.04/ NEST 3.5 installed using the Conda package).
+      * relevant system and version information (e.g.,  Ubuntu 22.04/ NEST 3.8 installed using the conda-forge package).
 
 #. Keep topics separate.
 

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

@@ -84,30 +84,38 @@ If you have not done so alrealdy first
 Set up your environment
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Using the Conda package (includes everything to build NEST, including documentation)
-````````````````````````````````````````````````````````````````````````````````````
+Using the conda-forge package (includes everything to build NEST, including documentation)
+```````````````````````````````````````````````````````````````````````````````````````````
 
-For details on Conda, see :ref:`conda_tips`
+For details on installation see :ref:`conda_forge_install`
 
 .. code-block:: bash
 
     cd <nest_source_dir>/
-    conda env create -p conda/
-    conda activate conda/
+    mamba env create -p mamba/
+    mamba activate mamba/
 
 If you later on want to deactivate or delete the build environment:
 
 .. code-block:: bash
 
-   conda deactivate
-   rm -rf conda/
+   mamba deactivate
+   rm -rf mamba/
 
 Using pip (includes packages for documentation only)
 ````````````````````````````````````````````````````
 
 If you want to install only a minimal set of packages for building the
 documentation and avoid using Conda, you can use pip:
 
+Create and activate  a Python virtual environment:
+
+.. code-block:: bash
+
+   python -m venv <myvenv>
+
+   source <myvenv>/bin/activate
+
 .. code-block:: bash
 
     pip3 install -r <nest_source_dir>/doc/requirements.txt

doc/htmldoc/developer_space/workflows/nest_with_ides.rst

@@ -25,7 +25,7 @@ Requirements and limitations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * Focus on single build configuration
-* Assumes all dependencies (OpenMPI, GSL, etc) installed in a Conda environment
+* Assumes all dependencies (OpenMPI, GSL, etc) installed in a Mamba environment
 * Does not support debugging on macOS (because Eclipse does not support lldb)
 * Does not read the NEST `.clang-format` file, so code formatting may
   be incorrect
@@ -62,25 +62,25 @@ Setting up the project
 #. Right click the project and choose ``Properties`` from the context
    menu
 
-   a. Under ``C/C++ Build/Build Variables``, define ``BUILD_DIR`` and ``CONDA_ENV``,
+   a. Under ``C/C++ Build/Build Variables``, define ``BUILD_DIR`` and ``MAMBA_ENV``,
       both of type ``Path``. The first should contain the full path to the build
-      directory you created above, the second the full path to your conda
-      environment, usually something like ``.../miniconda3/envs/nest-dev``.
+      directory you created above, the second the full path to your mamba
+      environment, usually something like ``.../mamba/envs/nest-dev``.
    #. Under ``C/C++ Build – [Tab] Builder Settings``,
 
       #. uncheck ``Use default build command``
       #. set ``Build Command`` to ``make -k -j4 all install`` (adjust
 	 number of processes to your situation)
       #. set ``Build Directory`` to ``${BUILD_DIR}``
    #. Under ``C/C++ Build > Environment``, prepend
-      ``${CONDA_ENV}/bin`` to ``PATH``
+      ``${MAMBA_ENV}/bin`` to ``PATH``
    #. Under ``C/C++ General > Paths and Symbols – [Tab] Includes``, add the
       following two direcories
 
       * ``${BUILD_DIR}/libnestutil`` (contains ``config.h``)
-      * ``${CONDA_ENV}/include`` (all headers from packages provided in conda environment)
+      * ``${mamba_env}/include`` (all headers from packages provided in Mamba environment)
    #. Under ``PyDev - Interpreter/Grammar``, choose the interpreter from
-      your Conda environment (you may need to add it by following the
+      your Mamba environment (you may need to add it by following the
       ``Click here to configure an interpreter not listed`` link and
       then ``Browse for python/pypy exe`` (this temporarily takes you
       to the global Eclipse preferences in a separate window).
@@ -261,7 +261,7 @@ We need several packages installed, before we can become productive with NEST:
 * gsl
 * cmake
 * libtool
-* ipython, python, cython, ... The best way to install all the python requirements is to use `Anaconda <https://store.continuum.io/cshop/anaconda/>`_.
+* ipython, python, cython, ... The best way to install all the python requirements is to use `Mamba <https://mamba.readthedocs.io/en/latest/index.html/>`_.
 
 We present two ways to install the rest: MacPorts and Homebrew. For both versions you need to have Xcode and Xcode command line tools installed:
 

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

@@ -140,7 +140,7 @@ Questions and answers about precise neurons
 13. Q: **What is the rate at which spikes are missed in a typical
     large-scale neuronal network simulation of integrate-and-fire model
     neurons with linear subthreshold dynamics in the balanced state and
-    a spike rate of around 10 Hz**?
+    a spike rate of around 10 spks/s**?
 
     A: At a typical parameter setting for a simulation with around 10,000
     neurons and 15 million synapses, the total rate at which spikes are

doc/htmldoc/get-started_index.rst

@@ -226,7 +226,7 @@ More topics
    Simulation behavior <nest_behavior/running_simulations>
    Randomness in NEST <nest_behavior/random_numbers>
    Built-in timers <nest_behavior/built-in_timers>
-   Connect NEST with other tools <connect_nest/index>
+   Connect NEST with other tools <interface_nest/index>
    From NEST 2.x to 3.x <whats_new/v3.0/refguide_nest2_nest3>
 
 .. toctree::

doc/htmldoc/hpc/slurm_script.rst

@@ -42,6 +42,8 @@ In this example, we are using 1 node, which contains 2 sockets and 64 cores per
    export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK
    export OMP_PROC_BIND=TRUE
 
+   # Optional
+   python -c "import nest, subprocess as s, os; s.check_call(['/usr/bin/pldd', str(os.getpid())])" 2>&1 | tee -a "pldd-nest.out"
 
    # On some systems, MPI is run by SLURM
    srun --exclusive python3 my_nest_simulation.py
@@ -174,6 +176,21 @@ will prevent the threads from moving around.
 
 |
 
+::
+
+   python -c "import nest, subprocess as s, os; s.check_call(['/usr/bin/pldd', str(os.getpid())])" 2>&1 | tee -a "pldd-nest.out"
+
+Prints out the linked libraries into a file with name ``pldd-nest.out``.
+In this way, you can check whether dynamically linked librariries for
+the execution of ``nest`` is indeed used. For example, you can check if ``jemalloc`` is used for the network construction
+in highly parallel simulations.
+
+.. note::
+
+   The above command uses ``pldd`` which is commonly available in Linux distributions. However, you might need to change
+   the path, which you can find with the command ``which pldd``.
+
+|
 
 You can then tell the job script to schedule your simulation.
 Setting the ``exclusive`` option prevents other processes or jobs from doing work on the same node.
@@ -222,11 +239,3 @@ It should match the number of ``cpus-per-task``.
 .. seealso::
 
     :ref:`parallel_computing`
-
-
-
-
-
-
-
-