diff --git a/doc/userdoc/download.rst b/doc/userdoc/download.rst deleted file mode 100644 index c8faea3c2a..0000000000 --- a/doc/userdoc/download.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _download: - -Download NEST -============= - -.. pull-quote:: - - For standard situations where you just want to use but not modify - NEST, you don't have to download the source code. - - Distribution packages ease the installation on Debian/Ubuntu, - Fedora, macOS and Conda. - - See our :ref:`installation instructions ` to - find the right option for you. - -Here you'll find the lastest versions of the source code and virtual machine (VM) images for download. -If you use NEST for your project, don't forget to :ref:`cite NEST `! - - -Download the source code ------------------------- - -* If you are compiling NEST from source, you can download the zip or tarball of the `latest release `_ from our GitHub page. - You can find the download link below the release notes in the section labeled "Assets". - -* Then, follow the installation instructions for :ref:`Linux ` or :ref:`macOS `. - -* You can also test out the `latest developer version `_ from GitHub. - - -.. _download_livemedia: - -Download the NEST image for VMs -------------------------------- - -The VM image of NEST is available in the OVA format, and is suitable, for example, for importing into VirtualBox. -If you run **Windows**, this is the option for you OR if you just want to run NEST without installing it on your computer. - -* Download the `latest live media image `_. - - `Checksum `_ - -* After downloading the virtual machine, check out the :ref:`install instructions for Live Media `. - - -Older versions of VM images ---------------------------- - - -`NEST Live Media 3.1 `_ - -`Checksum 3.1 `_ - -`NEST Live Media 2.20.2 `_ - -`Checksum 2.20.2 `_ - - -We continuously aim to improve NEST, implement features, and fix bugs with every new version; -thus, we encourage our users to use the **most recent version of NEST**. - - ----- - -NEST is available under the :ref:`GNU General Public License 2 or later `. This means that you can - -- use NEST for your research, -- modify and improve NEST according to your needs, -- distribute NEST to others under the same license. diff --git a/doc/userdoc/installation/admin.rst b/doc/userdoc/installation/admin.rst new file mode 100644 index 0000000000..c8ce741cd8 --- /dev/null +++ b/doc/userdoc/installation/admin.rst @@ -0,0 +1,26 @@ +.. _admin_install: + +Administrator installation instructions +--------------------------------------- + +If you need to deploy NEST on a machine + + +* Check out our guides to :ref:`optimizing NEST for HPC systems ` + +Configure HPC systems +~~~~~~~~~~~~~~~~~~~~~ + +Here are some :ref:`configuration options ` that may be useful on supercomputers and large clusters. + +Docker install +~~~~~~~~~~~~~~ + +Check out the :ref:`docker installation instructions `. + + +See the `nest-docker README `_ to find out more. + + + + diff --git a/doc/userdoc/installation/conda_forge.rst b/doc/userdoc/installation/conda_forge.rst new file mode 100644 index 0000000000..2bbffb493f --- /dev/null +++ b/doc/userdoc/installation/conda_forge.rst @@ -0,0 +1,53 @@ +.. _conda_forge_install: + +Conda forge install +=================== + +1. To keep your conda setup tidy, we recommend that you install NEST into + a separate `conda environment `_ + together with Python packages that you will use when working with NEST; + see also our :ref:`conda_tips`. + + To install the latest version of NEST in a new environment called ``ENVNAME``, just run + + .. code-block:: sh + + conda create --name ENVNAME -c conda-forge nest-simulator + + To install additional packages into the environment, just list them together with ``nest-simulator``. + + .. code-block:: sh + + conda create --name ENVNAME -c conda-forge nest-simulator jupyterlab seaborn + +#. To see all NEST versions available via conda, either run + + .. code-block:: sh + + conda search -c conda-forge nest-simulator + + or browse the `conda forge file list + `_ (note + there are multiple pages). To install, e.g., NEST 2.18.0, run + + .. code-block:: sh + + conda create --name nest_2_18_0 -c conda-forge nest-simulator=2.18.0=* + + The syntax for this install follows the pattern: ``nest-simulator==``. + +#. Activate your environment: + + .. code-block:: sh + + conda activate ENVNAME + +#. Note the following: + + - We currently provide NEST with thread-based parallelization on conda. This should suffice for most + uses on personal computers. + - Until dedicated conda builds for Apple's M1 chip (arm64) become available, you should expect relatively + poor performance on computers with the M1 chip. You need to :ref:`build NEST yourself ` on + M1 systems for good performance. + + diff --git a/doc/userdoc/installation/condaenv_install.rst b/doc/userdoc/installation/condaenv_install.rst new file mode 100644 index 0000000000..9b348aa8d5 --- /dev/null +++ b/doc/userdoc/installation/condaenv_install.rst @@ -0,0 +1,57 @@ +.. _condaenv: + +Install from source in a conda environment +========================================== + +* Create a conda environment from the `environment.yml `_ file. + We recommend specifying a dedicated location (``-p ``) for your environment. + See the `conda documentation `_ + on using a custom location rather than the default envs folder. + +.. code-block:: sh + + conda env create -f nest-simulator/environment.yml --p + conda activate + +* Create a build directory: + +.. code-block:: sh + + mkdir build_dir + +* Change to the build directory: + +.. code-block:: sh + + cd build_dir + +* Configure NEST. Add the cmake option ``-CDMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX`` to link nest to your active conda environment. + You may need additional ``cmake`` options (see :ref:`cmake_options`). + +.. code-block:: sh + + cmake -DCMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX + +* Compile and install NEST: + +.. code-block:: sh + + make + make install + make installcheck + +For your convenience, a shell script setting all required environment variables is provided in +``/bin/nest_vars.sh``. Setting the environment variables in your active shell session requires +sourcing the script: + +.. code-block:: sh + + source /bin/nest_vars.sh + + + +.. note:: + + To build the developer or user documentation see :ref:`doc_workflow` + + diff --git a/doc/userdoc/installation/developer.rst b/doc/userdoc/installation/developer.rst new file mode 100644 index 0000000000..2225d5b7fe --- /dev/null +++ b/doc/userdoc/installation/developer.rst @@ -0,0 +1,54 @@ +.. _dev_install: + +Install NEST from source +========================= + + +.. note:: + + Please see our :ref:`development workflows and guidelines `, if you need + a refresher in git or need to review the coding or documentation guidelines. + + + +* Clone nest-simulator from Github ``_: + +.. code-block:: sh + + git clone git@github.com:/nest-simulator.git + + +* or download the tarball `here `_ and unpack it: + +.. code-block:: sh + + tar -xzvf nest-simulator-x.y.tar.gz + + + +We have provided an `environment.yml `_ +file that contains all possible packages needed for NEST development. +See our instructions for installing NEST from source in a :ref:`conda environment ` + +OR + +If you want to install NEST without any environment, see the :ref:`instructions here `. + +What gets installed where +------------------------- + +By default, everything will be installed to the subdirectories ``/{bin,lib,share}``, where +``/install/path`` is the install path given to ``cmake``: + +- Executables ``/bin`` +- Dynamic libraries ``/lib/`` +- SLI libraries ``/share/nest/sli`` +- SLI documentation ``/share/doc/nest`` +- Examples ``/share/doc/nest/examples`` +- PyNEST ``/lib/pythonX.Y/site-packages/nest`` +- PyNEST examples ``/share/doc/nest/examples/pynest`` + +If you want to run the ``nest`` executable or use the ``nest`` Python module without providing explicit paths, you +have to add the installation directory to your search paths. + + diff --git a/doc/userdoc/installation/docker.rst b/doc/userdoc/installation/docker.rst new file mode 100644 index 0000000000..60edf60c90 --- /dev/null +++ b/doc/userdoc/installation/docker.rst @@ -0,0 +1,195 @@ +.. _docker: + +|macos| |linux| |windows| Docker +-------------------------------- + +Docker provides an isolated container to run applications. + +1. If you do not have Docker installed, follow the Docker + installation instructions for your system here: + https://docs.docker.com/install/. + + If you are using **Linux**, we **strongly recommend** you + also create a Docker group to manage Docker as a non-root + user. See instructions on the Docker website: + https://docs.docker.com/install/linux/linux-postinstall/ + + +2. Create a directory or change into a directory that you want + to use for your project. + +.. code-block:: bash + + mkdir my_nest_scripts + cd my_nest_scripts + + +Usage + + +You can use the docker images directly out of docker-registry.ebrains.eu like this: + +.. code-block:: bash + + docker pull docker-registry.ebrains.eu/nest/nest-simulator:TAG + +``TAG`` can be a version of NEST ``2.20.2`` or later. Alternatively, you can use ``dev`` for the +development branch (master). + +NEST 3.2 and later +^^^^^^^^^^^^^^^^^^ + +As of NEST 3.2, you can use the docker-compose feature. + +To use 'docker-compose' you need the definition file from the git repository. Download it: + +.. code-block:: bash + + wget https://raw.githubusercontent.com/steffengraber/nest-docker/master/docker-compose.yml + + +You can then run ``docker-compose up`` with one of the following options: + +- NEST server + +.. code-block:: bash + + docker-compose up nest-server + +or + +.. code-block:: bash + + docker run -it --rm -e NEST_CONTAINER_MODE=nest-server -p 5000:5000 / + docker-registry.ebrains.eu/nest/nest-simulator: + +Starts the NEST API server container and opens the corresponding port 5000. Test it with `curl localhost:5000/api`. +See the :ref:`nest_server` documentation for more details. + +- NEST desktop + +.. code-block:: bash + + docker-compose up nest-desktop + +or + +.. code-block:: bash + + docker run -it --rm -e NEST_CONTAINER_MODE=nest-server -p 5000:5000 / + docker-registry.ebrains.eu/nest/nest-simulator: + docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -p 8000:8000 / + -e NEST_CONTAINER_MODE=nest-desktop docker-registry.ebrains.eu/nest/nest-simulator: + +Starts the NEST server and the NEST desktop web interface. Port 8000 is also made available. +Open NEST Desktop in the web browser using the following http link: `http://localhost:8000` + +Visit the :doc:`NEST Desktop ` documentation to learn more. + +- Jupyter notebook with NEST + +.. code-block:: bash + + docker-compose up nest-notebook + +or + +.. code-block:: bash + + docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=notebook / + -p 8080:8080 docker-registry.ebrains.eu/nest/nest-simulator: + +Starts a notebook server with pre-installed NEST. The corresponding URL is displayed in the console. You can copy an +d paste into your browser. + + +- Jupyter lab with NEST + +.. code-block:: bash + + docker-compose up nest-jupyterlab + +or + +.. code-block:: bash + + docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=jupyterlab / + -p 8080:8080 docker-registry.ebrains.eu/nest/nest-simulator:) + +Starts a Jupyter lab server with pre-installed NEST. The corresponding URL is displayed in the console. +Copy and paste the URL into your browser. + + + +To stop and delete running containers use `docker-compose down`. + + +To run NEST 2.20.2 +^^^^^^^^^^^^^^^^^^ + +Jupyter notebook with NEST 2.20.2: + +.. code-block:: bash + + docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=notebook / + -p 8080:8080 docker-registry.ebrains.eu/nest/nest-simulator:2.20.2 + +Jupyter lab with NEST 2.20.2 + +.. code-block:: bash + + docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=jupyterlab / + -p 8080:8080 docker-registry.ebrains.eu/nest/nest-simulator:2.20.2 + +NEST dev +^^^^^^^^ + +If you want to use the compose configuration for the ``dev`` NEST version, you can use the following file option: + +.. code-block:: bash + + wget https://raw.githubusercontent.com/steffengraber/nest-docker/master/docker-compose.yml + docker-compose -f docker-compose-dev.yml up nest-notebook + +On Windows +^^^^^^^^^^ + +.. note:: + + The following commands should work on Windows. Please note that NEST does not officially + support Windows! + +.. code-block:: bash + + docker run -it --rm -v %cd%:/opt/data -p 8080:8080 -e NEST_CONTAINER_MODE= / + docker-registry.ebrains.eu/nest/nest-simulator: + +In Powershell, '%cd%' might not work for the current directory. Then +you should explicitly specify a folder with existing write permissions. + +In any case, this will download the docker image with the pre-installed +NEST master from docker-registry.ebrains.eu and start it. After booting an URL is presented. +Click on it or copy it to your browser. Voilá Jupyter notebook starts from +the docker image. + +You can update the image with: + +.. code-block:: bash + + docker pull docker-registry.ebrains.eu/nest/nest-simulator: + + + +For more information, you can checkout the `nest-docker repository `_ + +.. |linux| image:: ../static/img/linux.png + :scale: 15% + +.. |macos| image:: ../static/img/macos.png + :scale: 15% + + +.. |windows| image:: ../static/img/windows.png + :scale: 15% + + diff --git a/doc/userdoc/installation/index.rst b/doc/userdoc/installation/index.rst index 7c7e231228..d3a3e95c6b 100644 --- a/doc/userdoc/installation/index.rst +++ b/doc/userdoc/installation/index.rst @@ -3,352 +3,61 @@ Install NEST ============ -Standard installation ---------------------- -These installation instructions should work for most users who do -not need custom configurations for their systems. If you want to -compile NEST from source, check the :ref:`advanced_install` section -and :ref:`cmake_options`. +Install pre-built NEST package +------------------------------ -.. tabs:: +|user| I'm a user who wants to :ref:`install NEST on my computer ` +| - .. tab:: Ubuntu +Install NEST for a class or workshop +------------------------------------ - Ubuntu users can install NEST via the PPA repository. +|lecturer| I'm a lecturer who wants to :ref:`use NEST to teach ` - 1. Add the PPA repository for NEST and update apt: +| - .. code-block:: bash +Install NEST for HPC +-------------------- - sudo add-apt-repository ppa:nest-simulator/nest - sudo apt-get update +|admin| I'm an administrator or user who wants to :ref:`set up NEST on a large cluster or supercomputer ` - 2. Install NEST: +| - .. code-block:: bash +Install NEST from source +------------------------ - sudo apt-get install nest - - - .. tab:: Debian - - Debian users can install NEST via the Ubuntu PPA repository. - - 1. Create a new ``apt`` repository entry in ``/etc/apt/sources.list.d/nest-simulator-ubuntu-nest-XXX.list`` by: - - .. code-block:: bash - - sudo apt install devscripts build-essential software-properties-common dpkg-dev - sudo add-apt-repository --enable-source ppa:nest-simulator/nest - - 2. Disable the binary package in the repository file created under ``/etc/apt/sources.list.d/`` by commenting - out the ``deb`` line, while keeping the ``deb-src`` line. It should look similar to this: - - .. code-block:: bash - - #deb http://ppa.launchpad.net/nest-simulator/nest/ubuntu focal main - deb-src http://ppa.launchpad.net/nest-simulator/nest/ubuntu focal main - - - 3. Import the PPA GPC key and rebuild the package: - - .. code-block:: bash - - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 \ - --recv-keys 0CF7539642ABD23CBCA8D487F0B8B6C5EC02D7DD - sudo apt update - sudo apt source --build nest - - 4. Install any missing dependencies, if ``apt`` tells you so. - In addition, install: - - .. code-block:: bash - - sudo apt install python3-all dh-python - - 5. After installing the dependencies, enter ``sudo apt source --build nest`` again. - When the build finished, look for lines like - - .. code-block:: bash - - dpkg-deb: building package 'nest-dbgsym' in '../nest-dbgsym_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb'. - dpkg-deb: building package 'nest' in '../nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb'. - #dh binary - dpkg-genbuildinfo --build=binary - dpkg-genchanges --build=binary >../nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.changes - - and note down the full package name. In the above example this would be - `nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb`, where the number `202001311135` and potentially the - Ubuntu version number may be different. - - 6. Install the ready Debian package after the rebuild: - - .. code-block:: bash - - sudo dpkg --install nest-simulator-x.y.z~NUMBER~ubuntu20.04.1_amd64.deb - - The package name is taken from the result of the previous step. `NUMBER` and potentially the Ubuntu - version might differ. - - 7. Test the package: - - .. code-block:: bash - - python3 - import nest - - - .. tab:: NeuroFedora - - The NeuroFedora team has generously provided the latest - versions of NEST on their platform. As that is available in the - standard Fedora platform repositories, it can simply be - installed using ``dnf``: - - .. code-block:: bash - - sudo dnf install python3-nest - - Find out more on the NeuroFedora site: https://neuro.fedoraproject.org. - - .. tab:: Homebrew (macOS) - - 1. `Install Homebrew `_. - - 2. Install NEST via: - - .. code-block:: bash - - brew install nest - - .. _conda_forge_install: - - .. tab:: Conda (Linux/macOS) - - .. note:: - - For NEST 3.x, the conda-forge package is available from NEST 3.3. - - For NEST 2.x, the conda-forge package is available from NEST 2.16.0. - - 1. To keep your conda setup tidy, we recommend that you install NEST into - a separate `conda environment `_ - together with Python packages that you will use when working with NEST; - see also our :ref:`conda_tips`. - - To install the latest version of NEST in a new environment called ``ENVNAME``, just run - - .. code-block:: sh - - conda create --name ENVNAME -c conda-forge nest-simulator - - To install additional packages into the environment, just list them together with ``nest-simulator``. - - .. code-block:: sh - - conda create --name ENVNAME -c conda-forge nest-simulator jupyterlab seaborn - - #. To see all NEST versions available via conda, either run - - .. code-block:: sh - - conda search -c conda-forge nest-simulator - - or browse the `conda forge file list - `_ (note - there are multiple pages). To install, e.g., NEST 2.18.0, run - - .. code-block:: sh - - conda create --name nest_2_18_0 -c conda-forge nest-simulator=2.18.0=* - - The syntax for this install follows the pattern: ``nest-simulator==``. - - #. Activate your environment: - - .. code-block:: sh - - conda activate ENVNAME - - #. Note the following: - - - We currently provide NEST with thread-based parallelization on Conda. This should suffice for most - uses on personal computers. - - Until dedicated conda builds for Apple's M1 chip (arm64) become available, you should expect relatively - poor performance on computers with the M1 chip. You need to :ref:`build NEST yourself ` on - M1 systems for good performance. - - -.. _docker_vm_install: - -In addition to native installations from ready-made packages, we -provide containerized versions of NEST in several formats: - -.. tabs:: - - .. tab:: Docker (Linux/macOS) - - Docker provides an isolated container to run applications. The - NEST Docker container includes a complete install of NEST and - is set up so you can create, modify, and run Juptyer Notebooks - and save them on your host machine. (See the Note below for - alternative ways to use the Docker container.) - - 1. If you do not have Docker installed, follow the Docker - installation instructions for your system here: - https://docs.docker.com/install/. - - If you are using **Linux**, we **strongly recommend** you - also create a Docker group to manage Docker as a non-root - user. See instructions on the Docker website: - https://docs.docker.com/install/linux/linux-postinstall/ - - - 2. Create a directory or change into a directory that you want - to use for your Jupyter Notebooks. - - .. code-block:: bash - - mkdir my_nest_scripts - cd my_nest_scripts - - 3. Run the Docker container. Replace the ```` with one - of the latest NEST versions (e.g., ``2.20.0``) or use - ``latest`` for the most recent build from the source code. - - .. code-block:: bash - - docker run --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -p 8080:8080 nestsim/nest: jupyterlab - - - 4. Once completed, a link to a Jupyter Notebook will be - generated, as shown below. You can then copy and paste the - link into your browser. - - .. image:: ../static/img/docker_link.png - :align: center - :width: 1000px - - - 5. You can now use the Jupyter Notebook as you normally - would. Anything saved in the Notebook will be placed in the - directory you started the Notebook from. - - 6. You can shutdown the Notebook in the terminal by typing - :kbd:`Ctrl-c` twice. Once the Notebook is shutdown the - container running NEST is removed. - - - .. note:: - - You can check for updates to the Docker build by typing: - - .. code-block:: bash - - docker pull nestsim/nest: - - .. note:: - - You can also create an instance of a terminal within the container itself and, for example, run Python scripts. - - .. code-block:: - - docker run --rm -it -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -p 8080:8080 nestsim/nest: /bin/bash - - See the `README `_ to find out more, but note some functionality, such as DISPLAY, will not be available. - - .. tab:: Live Media (cross-platform) - - We have live media (.ova) if you want to run NEST in a virtual machine. This option is suitable for Windows users, since we don't support - NEST natively on Windows, - - :ref:`Download the live media here `, and follow the :ref:`instructions to set up the virtual machine ` . - - - - -**Once NEST is installed, you can run it in Python, IPython, or Jupyter Notebook** - -For example, in the terminal type: - - .. code-block:: bash - - python3 - -Once in Python you can type: - - .. code-block:: python - - import nest - -**or as a stand alone application**:: - - nest - - -If installation was successful, you should see the NEST splash screen in the terminal: - -.. figure:: ../static/img/import_nest.png - :scale: 50% - :alt: import nest - - -**Installation is now complete!** -**:ref:`Now we can start creating simulations! `** +|dev| I'm a developer who wants to :ref:`do development in NEST ` ---- If installation didn't work, see the :ref:`troubleshooting section `. -.. seealso:: - - * :ref:`PyNEST tutorials ` - - * :ref:`Example networks ` - - ----- - -.. _advanced_install: - -Advanced installation ---------------------- - -**If you need special configuration options or want to compile NEST yourself, follow -these instructions.** - - -.. tabs:: - - .. tab:: Ubuntu/Debian - - Download the source code for the `current release `_. - - Follow instructions for :ref:`linux_install` and take a look at our :ref:`cmake_options`. - - - .. tab:: GitHub - - Get the latest developer version on `GitHub `_. Fork NEST into your GitHub repository (see details on :ref:`GitHub workflows here `). - - - .. tab:: macOS - - For further options on installing NEST on macOS, see :ref:`mac_install` for Macs. - - - .. tab:: HPC systems - - :ref:`Instructions for high performance computers ` provides some instructions for certain machines. - .. toctree:: :hidden: + :glob: - linux_install mac_install hpc_install livemedia cmake_options + * + +.. |user| image:: ../static/img/020-user_black.png + :target: user.html + :width: 100px + +.. |dev| image:: ../static/img/dev_black.png + :target: developer.html + :width: 100px + +.. |admin| image:: ../static/img/001-shuttle_black.png + :target: admin.html + :width: 100px + +.. |lecturer| image:: ../static/img/class_black.png + :target: lecturer.html + :width: 100px + diff --git a/doc/userdoc/installation/lecturer.rst b/doc/userdoc/installation/lecturer.rst new file mode 100644 index 0000000000..1815293e48 --- /dev/null +++ b/doc/userdoc/installation/lecturer.rst @@ -0,0 +1,52 @@ +.. _lecturer: + +Lecturer installation instructions +---------------------------------- + + +NEST Desktop +~~~~~~~~~~~~ + +* :doc:`NEST Desktop ` is a graphical user interface designed for illustrating neural network concepts + ideal for the classroom setting. + +We recommend you checkout the NEST desktop project and see if it fits your needs! + + +Docker install +~~~~~~~~~~~~~~ + +We provide a docker container for NEST, with options to include NEST-Desktop, Jupyter notebooks or Jupyterlab. + +See :ref:`instructions for docker here `. + + + +Live media +~~~~~~~~~~ + + +We provide an OVA live media format that can work in virtual machines (like Virtualbox). +See the :ref:`live media install instructions here ` + +Alternatively, you can check out the `Comp-Neuro Fedora Project `_. +They provide an image of many computational neuroscience tools including NEST! + +.. note:: + + NEST developers do not officially support the Comp-Neuro Fedora Project. Questions and issues regarding the image from + Comp-Neuro Fedora should be directed to that community. + +.. admonition:: Teaching material + + Here is some material that you find useful for your students: + + * :ref:`PyNEST tutorials ` + + * For creating and modifying models, see :doc:`NESTML tutorials ` + + + + + + diff --git a/doc/userdoc/installation/linux_install.rst b/doc/userdoc/installation/linux_install.rst deleted file mode 100644 index 7de26aaa8a..0000000000 --- a/doc/userdoc/installation/linux_install.rst +++ /dev/null @@ -1,248 +0,0 @@ -.. _linux_install: - -Ubuntu/Debian Installation -========================== - -.. _standard: - -Dependencies ------------- - -To build NEST, you need a recent version of `CMake `_ and -`libtool `_; the latter should be available for most systems and is -probably already installed. - -.. note:: - - NEST requires CMake 3.12 or higher, but we recommend version 3.16. You can type ``cmake --version`` on the - commandline to check your current version. - -The `GNU readline library `_ is recommended if you use NEST interactively -**without Python**. Although most Linux distributions have GNU readline installed, you still need to install its -development package if you want to use GNU readline with NEST. GNU readline itself depends on -`libncurses `_ (or libtermcap on older systems). Again, the development packages -are needed to compile NEST. - -The `GNU Scientific Library `_ is needed by several neuron models, in particular -those with conductance based synapses. If you want these models, please install the GNU Scientific Library along with -its development packages. - -For efficient sorting algorithms the `Boost library `_ is used. Since this is an essential -factor for the communication of spikes, some simulations are significantly faster when NEST is compiled with Boost. - -If you want to use PyNEST, we recommend to install the following along with their development packages: - -- `Python 3.8 or higher `_ -- `Cython 0.28.3 or higher `_ -- `NumPy `_ -- `SciPy `_ -- `Matplotlib 3.0 or higher `_ -- `IPython `_ - - -.. _source-install: - -Installation from source in a virtual Python environment --------------------------------------------------------- - -The following are the basic steps to compile and install NEST from source code. See the -:ref:`CMake Options ` or the :ref:`High Performance Computing ` instructions to -further adjust settings for your system. - -* If not already installed on your system, the following packages are recommended (see also the `Dependencies`_ - section) - -.. code-block:: bash - - sudo apt install -y \ - cython \ - libgsl-dev \ - libltdl-dev \ - libncurses-dev \ - libreadline-dev \ - openmpi-bin \ - libopenmpi-dev - -* When NEST is installed with Python and without ``cmake`` option ``-DCMAKE_INSTALL_PREFIX=``, - only `virtual environments `_ are supported. - Activate the virtual environment you want to use, or if you don't already have one, create a new virtual environment for NEST: - -.. code-block:: bash - - python -m venv nest_env - source nest_env/bin/activate - -* Unpack the tarball - -.. code-block:: sh - - tar -xzvf nest-simulator-x.y.z.tar.gz - -* Create a build directory: - -.. code-block:: sh - - mkdir nest-simulator-x.y.z-build - -* Change to the build directory: - -.. code-block:: sh - - cd nest-simulator-x.y.z-build - -* Configure NEST. You may need additional ``cmake`` options (see :ref:`cmake_options`). - -.. code-block:: sh - - cmake - -* Compile and install NEST: - -.. code-block:: sh - - make - make install - make installcheck - -NEST should now be successfully installed in your active Python environment. - -* See the :ref:`Getting started ` pages to find out how to get going with NEST or check out our - :ref:`example networks `. - - -Installation from source without a virtual Python environment -------------------------------------------------------------- - -The following are the basic steps to compile and install NEST from source code. See the -:ref:`CMake Options ` or the :ref:`High Performance Computing ` instructions to -further adjust settings for your system. - -* If not already installed on your system, the following packages are recommended (see also the `Dependencies`_ - section) - -.. code-block:: bash - - sudo apt install -y \ - cython \ - libgsl-dev \ - libltdl-dev \ - libncurses-dev \ - libreadline-dev \ - python3-all-dev \ - python3-numpy \ - python3-scipy \ - python3-matplotlib \ - python3-nose \ - python3-junitparser \ - python3-mpi4py \ - openmpi-bin \ - libopenmpi-dev - -* Unpack the tarball - -.. code-block:: sh - - tar -xzvf nest-simulator-x.y.z.tar.gz - -* Create a build directory: - -.. code-block:: sh - - mkdir nest-simulator-x.y.z-build - -* Change to the build directory: - -.. code-block:: sh - - cd nest-simulator-x.y.z-build - -* Configure NEST. You may need additional ``cmake`` options (see :ref:`cmake_options`). - Installing NEST with Python outside a virtual Python environment requires the - ``cmake`` option ``-DCMAKE_INSTALL_PREFIX=``. - -.. code-block:: sh - - cmake -DCMAKE_INSTALL_PREFIX:PATH= - -.. note:: - - ``/install/path`` should be an absolute path - -.. note:: - - Python bindings are enabled by default. Add the configuration option ``-Dwith-python=OFF`` to disable them. - -* Compile and install NEST: - -.. code-block:: sh - - make - make install - make installcheck - -NEST should now be successfully installed on your system. - -* Before using NEST, make sure that all required environment variables are set correctly. In short, this can be - established by sourcing the shell script ``nest_vars.sh``, which is installed into the path for binaries selected - during the CMake run. See the section `Environment variables`_ for details. - -* See the :ref:`Getting started ` pages to find out how to get going with NEST or check out our - :ref:`example networks `. - - -What gets installed where -------------------------- - -By default, everything will be installed to the subdirectories ``/{bin,lib,share}``, where -``/install/path`` is the install path given to ``cmake``: - -- Executables ``/bin`` -- Dynamic libraries ``/lib/`` -- SLI libraries ``/share/nest/sli`` -- Documentation ``/share/doc/nest`` -- Examples ``/share/doc/nest/examples`` -- PyNEST ``/lib/pythonX.Y/site-packages/nest`` -- PyNEST examples ``/share/doc/nest/examples/pynest`` - -If you want to run the ``nest`` executable or use the ``nest`` Python module without providing explicit paths, you -have to add the installation directory to your search paths. -Please refer to the :ref:`next section ` section for this. - - -.. _environment_variables: - -Environment variables ---------------------- - -A number of environment variables are used to specify where the components of a NEST installation are found. In -particular when installing to a custom directory, it is typically necessary to explicitly set these variables, so that -your operating system can find the NEST binaries, its libraries and custom extension modules. - -For your convenience, a shell script setting all required environment variables is provided in -``/bin/nest_vars.sh``. Setting the environment variables in your active shell session requires -sourcing the script: - -.. code-block:: sh - - source /bin/nest_vars.sh - -You may want to include this line in your ``.bashrc`` file, so that the environment variables are set automatically -whenever you open a new terminal. - -The following variables are set in ``nest_vars.sh``: - -.. list-table:: - :header-rows: 1 - :widths: 10 30 - - * - Variable - - Description - * - ``PYTHONPATH`` - - Search path for non-standard Python module locations. Will be newly set or prepended to the already existing - variable if it is already set. - * - ``PATH`` - - Search path for binaries. Will be newly set or prepended to the already existing variable if it is already set. - -If your operating system does not find the ``nest`` executable or if Python does not find the ``nest`` module, your -path variables may not be set correctly. This may also be the case if Python cannot load the ``nest`` module due to -missing or incompatible libraries. diff --git a/doc/userdoc/installation/livemedia.rst b/doc/userdoc/installation/livemedia.rst index 7c8726ad85..d22cc36c02 100644 --- a/doc/userdoc/installation/livemedia.rst +++ b/doc/userdoc/installation/livemedia.rst @@ -25,12 +25,19 @@ SuSe:: sudo zypper install virtualbox -Windows users can follow instructions on the website (see above). -NEST image setup ------------------- -* Download the `NEST live medium `_ +.. _download_livemedia: + +Download the NEST image for VMs +------------------------------- + +The VM image of NEST is available in the OVA format, and is suitable, for example, for importing into VirtualBox. +If you run **Windows**, this is the option for you OR if you just want to run NEST without installing it on your computer. + +* Download the `latest live media image `_. + + `Checksum `_ * Start Virtual Box and import the virtual machine image (**File** > **Import Appliance**) @@ -38,6 +45,26 @@ NEST image setup * The user password is **nest**. + + +Older versions of VM images +--------------------------- + + +`NEST Live Media 3.1 `_ + +`Checksum 3.1 `_ + +`NEST Live Media 2.20.2 `_ + +`Checksum 2.20.2 `_ + + +We continuously aim to improve NEST, implement features, and fix bugs with every new version; +thus, we encourage our users to use the **most recent version of NEST**. + + + Notes ~~~~~~~~ diff --git a/doc/userdoc/installation/noenv_install.rst b/doc/userdoc/installation/noenv_install.rst new file mode 100644 index 0000000000..7c1a2ed7f9 --- /dev/null +++ b/doc/userdoc/installation/noenv_install.rst @@ -0,0 +1,99 @@ +.. _noenv: + +Install from source without a virtual environment +================================================= + +The following are the basic steps to compile and install NEST from source code. See the +:ref:`CMake Options ` or the :ref:`High Performance Computing ` instructions to +further adjust settings for your system. + +* If not already installed on your system, the following packages are recommended. + +.. important:: + + The list below does not include the requirements for building documentation or running NEST server. + The complete list of packages for an entire development environment can be found in the `environment.yml + `_ file. + For more information see the :ref:`doc_workflow` and :ref:`nest_server` docs. + +.. code-block:: bash + + sudo apt install -y \ + cmake \ + gsl-bin \ + libgsl-dev \ + libboost-dev \ + cython3 \ + libreadline-dev \ + python3-all-dev \ + python3-numpy \ + python3-scipy \ + python3-matplotlib \ + python3-nose \ + python3-junitparser \ + ipython3 \ + python3-future \ + openmpi-bin \ + libopenmpi-dev \ + python3-mpi4py \ + libmusic-dev \ + music-bin \ + python3-pip \ + python3-pytest \ + python3-pytest-timeout \ + python3-pytest-xdist + +* Create an install directory + +.. code-block:: sh + + mkdir nest-install + +We will refer to the full path of this directory by . + +* Create a build directory: + +.. code-block:: sh + + mkdir nest-build + +* Change to the build directory: + +.. code-block:: sh + + cd nest-build + +* Configure NEST. You may need additional ``cmake`` options (see :ref:`cmake_options`). + Installing NEST with Python outside a virtual Python environment requires the + ``cmake`` option ``-DCMAKE_INSTALL_PREFIX=``. + +.. code-block:: sh + + cmake -DCMAKE_INSTALL_PREFIX:PATH= + +.. note:: + + ```` should be an absolute path + +.. note:: + + Python bindings are enabled by default. Add the configuration option ``-Dwith-python=OFF`` to disable them. + +* Compile and install NEST: + +.. code-block:: sh + + make + make install + make installcheck + +For your convenience, a shell script setting all required environment variables is provided in +``/bin/nest_vars.sh``. Setting the environment variables in your active shell session requires +sourcing the script: + +.. code-block:: sh + + source /bin/nest_vars.sh + + + diff --git a/doc/userdoc/installation/user.rst b/doc/userdoc/installation/user.rst new file mode 100644 index 0000000000..1005339a46 --- /dev/null +++ b/doc/userdoc/installation/user.rst @@ -0,0 +1,145 @@ +.. _user_install: + +User install instructions +========================= + +Cross-platform |macos| |linux| |windows| +---------------------------------------- + +Docker +~~~~~ + +:ref:`See our docker installation instructions `. + +Conda install +~~~~~~~~~~~~~ + +You can install NEST with the :ref:`Conda forge package `. + +Live media +~~~~~~~~~ + +We have live media (.ova) if you want to run NEST in a virtual machine. + +:ref:`Download the live media here `, and follow the :doc:`instructions to set up the virtual machine ` . + + +------------- + +|linux| Linux +--------------- + +Ubuntu +~~~~~~ + +Ubuntu users can install NEST via the PPA repository. + +1. Add the PPA repository for NEST and update apt: + +.. code-block:: bash + + sudo add-apt-repository ppa:nest-simulator/nest + sudo apt-get update + +2. Install NEST: + +.. code-block:: bash + + sudo apt-get install nest + +Debian +~~~~~~ + +Debian users can install NEST via the Ubuntu PPA repository. + +1. Create a new ``apt`` repository entry in ``/etc/apt/sources.list.d/nest-simulator-ubuntu-nest-XXX.list`` by: + +.. code-block:: bash + + sudo apt install devscripts build-essential software-properties-common dpkg-dev + sudo add-apt-repository --enable-source ppa:nest-simulator/nest + +2. Disable the binary package in the repository file created under ``/etc/apt/sources.list.d/`` by commenting + out the ``deb`` line, while keeping the ``deb-src`` line. It should look similar to this: + +.. code-block:: bash + + #deb http://ppa.launchpad.net/nest-simulator/nest/ubuntu focal main + deb-src http://ppa.launchpad.net/nest-simulator/nest/ubuntu focal main + + +3. Import the PPA GPC key and rebuild the package: + +.. code-block:: bash + + sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 \ + --recv-keys 0CF7539642ABD23CBCA8D487F0B8B6C5EC02D7DD + sudo apt update + sudo apt source --build nest + +4. Install any missing dependencies, if ``apt`` tells you so. + In addition, install: + +.. code-block:: bash + + sudo apt install python3-all dh-python + +5. After installing the dependencies, enter ``sudo apt source --build nest`` again. + When the build finished, look for lines like: + +.. code-block:: bash + + dpkg-deb: building package 'nest-dbgsym' in '../nest-dbgsym_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb'. + dpkg-deb: building package 'nest' in '../nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb'. + #dh binary + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.changes + +and note down the full package name. In the above example this would be +`nest_2.20.0-0~202001311135~ubuntu20.04.1_amd64.deb`, where the number `202001311135` and potentially the +Ubuntu version number may be different. + +6. Install the ready Debian package after the rebuild: + +.. code-block:: bash + + sudo dpkg --install nest-simulator-x.y.z~NUMBER~ubuntu20.04.1_amd64.deb + + The package name is taken from the result of the previous step. `NUMBER` and potentially the Ubuntu + version might differ. + +7. Test the package: + +.. code-block:: bash + + python3 + import nest + +|macos| macOS +------------- + +1. `Install Homebrew `_. + +2. Install NEST via: + +.. code-block:: bash + + brew install nest + +----- + + + + +.. |linux| image:: ../static/img/linux.png + :scale: 11% + +.. |macos| image:: ../static/img/macos.png + :scale: 11% + + +.. |windows| image:: ../static/img/windows.png + :scale: 11% + + + diff --git a/doc/userdoc/static/css/custom.css b/doc/userdoc/static/css/custom.css index 67c37a61e7..b5138e6755 100644 --- a/doc/userdoc/static/css/custom.css +++ b/doc/userdoc/static/css/custom.css @@ -1,10 +1,29 @@ -.wy-breadcrumbs-aside { + .wy-breadcrumbs-aside { display: none !important; } .keep-us-sustainable { background-color: #272525; } +div.twocol { + width: 430px; + height: 180px; + border-top-width: 1px; + border-top-style: solid; + border-bottom-width: 1px; + border-bottom-style: solid; +} + + +div.leftside { + width: 150px; + padding: 10px 3px 0px 0px; + float: left; +} + +div.rightside { + margin-left: 160px; +} .rst-content dl:not(.docutils) [class^="sig-prename descclassname"] { display: none; diff --git a/doc/userdoc/static/img/001-shuttle.png b/doc/userdoc/static/img/001-shuttle.png new file mode 100644 index 0000000000..5afc5b2dc2 Binary files /dev/null and b/doc/userdoc/static/img/001-shuttle.png differ diff --git a/doc/userdoc/static/img/001-shuttle_black.png b/doc/userdoc/static/img/001-shuttle_black.png new file mode 100644 index 0000000000..d68656d696 Binary files /dev/null and b/doc/userdoc/static/img/001-shuttle_black.png differ diff --git a/doc/userdoc/static/img/005-artificial-intelligence-1.png b/doc/userdoc/static/img/005-artificial-intelligence-1.png new file mode 100644 index 0000000000..095e31fe64 Binary files /dev/null and b/doc/userdoc/static/img/005-artificial-intelligence-1.png differ diff --git a/doc/userdoc/static/img/010-book-1.png b/doc/userdoc/static/img/010-book-1.png new file mode 100644 index 0000000000..4885e71312 Binary files /dev/null and b/doc/userdoc/static/img/010-book-1.png differ diff --git a/doc/userdoc/static/img/012-brain.png b/doc/userdoc/static/img/012-brain.png new file mode 100644 index 0000000000..a2c535ea36 Binary files /dev/null and b/doc/userdoc/static/img/012-brain.png differ diff --git a/doc/userdoc/static/img/014-teacher.png b/doc/userdoc/static/img/014-teacher.png new file mode 100644 index 0000000000..56808df923 Binary files /dev/null and b/doc/userdoc/static/img/014-teacher.png differ diff --git a/doc/userdoc/static/img/014-teacher_black.png b/doc/userdoc/static/img/014-teacher_black.png new file mode 100644 index 0000000000..fbddeba37c Binary files /dev/null and b/doc/userdoc/static/img/014-teacher_black.png differ diff --git a/doc/userdoc/static/img/019-programmer-1.png b/doc/userdoc/static/img/019-programmer-1.png new file mode 100644 index 0000000000..724671814d Binary files /dev/null and b/doc/userdoc/static/img/019-programmer-1.png differ diff --git a/doc/userdoc/static/img/019-programmer-1_black.png b/doc/userdoc/static/img/019-programmer-1_black.png new file mode 100644 index 0000000000..27d4b7cb06 Binary files /dev/null and b/doc/userdoc/static/img/019-programmer-1_black.png differ diff --git a/doc/userdoc/static/img/020-user.png b/doc/userdoc/static/img/020-user.png new file mode 100644 index 0000000000..a04152e711 Binary files /dev/null and b/doc/userdoc/static/img/020-user.png differ diff --git a/doc/userdoc/static/img/020-user_black.png b/doc/userdoc/static/img/020-user_black.png new file mode 100644 index 0000000000..286a28e2ff Binary files /dev/null and b/doc/userdoc/static/img/020-user_black.png differ diff --git a/doc/userdoc/static/img/037-network.png b/doc/userdoc/static/img/037-network.png new file mode 100644 index 0000000000..f9ced37abb Binary files /dev/null and b/doc/userdoc/static/img/037-network.png differ diff --git a/doc/userdoc/static/img/class_black.png b/doc/userdoc/static/img/class_black.png new file mode 100644 index 0000000000..4b8c31710d Binary files /dev/null and b/doc/userdoc/static/img/class_black.png differ diff --git a/doc/userdoc/static/img/dev_black.png b/doc/userdoc/static/img/dev_black.png new file mode 100644 index 0000000000..287653266f Binary files /dev/null and b/doc/userdoc/static/img/dev_black.png differ diff --git a/doc/userdoc/static/img/linux.png b/doc/userdoc/static/img/linux.png new file mode 100644 index 0000000000..615e0ce9d1 Binary files /dev/null and b/doc/userdoc/static/img/linux.png differ diff --git a/doc/userdoc/static/img/macos.png b/doc/userdoc/static/img/macos.png new file mode 100644 index 0000000000..5e813e6b80 Binary files /dev/null and b/doc/userdoc/static/img/macos.png differ diff --git a/doc/userdoc/static/img/windows.png b/doc/userdoc/static/img/windows.png new file mode 100644 index 0000000000..89aca9626d Binary files /dev/null and b/doc/userdoc/static/img/windows.png differ diff --git a/pynest/examples/store_restore_network.py b/pynest/examples/store_restore_network.py index a3cf5a7aca..9de07b0fc9 100644 --- a/pynest/examples/store_restore_network.py +++ b/pynest/examples/store_restore_network.py @@ -72,6 +72,7 @@ # input. Excitatory connections are plastic (STDP). Spike activity of # the excitatory population is recorded. + class EINetwork: """ A simple balanced random network with plastic excitatory synapses.