From ac795cea82261c2a74d895c9a9dd3b134abe80e4 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Wed, 17 Jan 2024 11:31:28 +0100 Subject: [PATCH 1/8] modify layout of install pages --- doc/htmldoc/installation/cmake_options.rst | 4 +- doc/htmldoc/installation/docker.rst | 43 +++++++++++----- doc/htmldoc/installation/hpc_install.rst | 40 ++++++++++++++- doc/htmldoc/installation/index.rst | 57 ++++++++++++++-------- doc/htmldoc/installation/user.rst | 5 ++ doc/htmldoc/static/img/dev_orange.svg | 9 ++-- 6 files changed, 116 insertions(+), 42 deletions(-) diff --git a/doc/htmldoc/installation/cmake_options.rst b/doc/htmldoc/installation/cmake_options.rst index a7e570d878..8e919d627a 100644 --- a/doc/htmldoc/installation/cmake_options.rst +++ b/doc/htmldoc/installation/cmake_options.rst @@ -104,7 +104,7 @@ Build documentation If either documentation build is toggled to `ON`, you can then run ``make docs`` if you only want to build the docs. -See also the :ref:`documentation workflow ` for user and developer docs. +See also the :ref:`documentation workflow ` for user facing and technical docs. External libraries @@ -180,7 +180,7 @@ Generic build configuration | ``-Dwith-intel-compiler-flags=[OFF|]``| User defined flags for the Intel compiler | | | [default='-fp-model strict']. Separate multiple flags by ';'. | +------------------------------------------------------+------------------------------------------------------------------+ -| ``-Dwith-cpp-std=[]`` | C++ standard to use for compilation [default='c++17']. | +| ``-Dwith-cpp-std=[]`` | C++ standard to use for compilation [default='c++11']. | +------------------------------------------------------+------------------------------------------------------------------+ | ``-Dwith-libraries=[OFF|]`` | Link additional libraries [default=OFF]. Give full path. Separate| | | multiple libraries by ';'. | diff --git a/doc/htmldoc/installation/docker.rst b/doc/htmldoc/installation/docker.rst index 1bb65b5e9b..5afcc3fd31 100644 --- a/doc/htmldoc/installation/docker.rst +++ b/doc/htmldoc/installation/docker.rst @@ -1,9 +1,10 @@ .. _docker: Docker |macos| |linux| ----------------------- +====================== Docker provides an isolated container to run applications. +Our docker image for NEST also includes NESTML. 1. If you do not have Docker installed, follow the Docker installation instructions for your system here: @@ -25,7 +26,7 @@ Docker provides an isolated container to run applications. Usage - +----- You can use the docker images directly out of https://hub.docker.com/r/nest/nest-simulator like this: @@ -37,12 +38,15 @@ like this: ```` can be a version of NEST ``2.20.2`` or later. Alternatively, you can use ``dev`` for the development branch (master). +.. _docker_compose: + NEST 3.2 and later -^^^^^^^^^^^^^^^^^^ +------------------ -As of NEST 3.2, you can use the docker-compose feature. +As of NEST 3.2, you can use the docker-compose feature. This feature provides options to run additional applications along with NEST. -To use 'docker-compose' you need the definition file from the git repository. Download it: +To use ``docker-compose`` you need the definition file from the git repository. +Download it: .. code-block:: bash @@ -50,7 +54,8 @@ To use 'docker-compose' you need the definition file from the git repository. Do You can then run ``docker-compose up`` with one of the following options: -- NEST server +NEST server +~~~~~~~~~~~ .. code-block:: bash @@ -66,7 +71,10 @@ or Starts the NEST API server container and opens the corresponding port 52425. Test it with `curl localhost:52425/api`. See the :ref:`nest_server` documentation for more details. -- NEST desktop +.. _docker_desktop: + +NEST Desktop +~~~~~~~~~~~~ .. code-block:: bash @@ -86,7 +94,8 @@ Open NEST Desktop in the web browser using the following http link: `http://loca Visit the :doc:`NEST Desktop ` documentation to learn more. -- Jupyter notebook with NEST +Jupyter notebook with NEST +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -103,7 +112,8 @@ Starts a notebook server with pre-installed NEST. The corresponding URL is displ d paste into your browser. -- Jupyter lab with NEST +Jupyter lab with NEST +~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -119,12 +129,13 @@ or 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. +Remove container +---------------- - -To stop and delete running containers use `docker-compose down`. +To stop and delete running containers use ``docker-compose down``. To run NEST 2.20.2 -^^^^^^^^^^^^^^^^^^ +------------------ Jupyter notebook with NEST 2.20.2: @@ -134,7 +145,7 @@ Jupyter notebook with NEST 2.20.2: -p 8080:8080 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: @@ -143,6 +154,12 @@ If you want to use the compose configuration for the ``dev`` NEST version, you c wget https://raw.githubusercontent.com/nest/nest-docker/master/docker-compose-dev.yml docker-compose -f docker-compose-dev.yml up nest-notebook +You can specify the container mode (nest-noteobook, nest-desktop, nest-server, or nest-jupyterlab) +This will download the docker image with the pre-installed +NEST master from https://hub.docker.com/r/nest/nest-simulator and start it. +After booting, a URL is presented. Click on it or copy it to your browser. + + .. _docker_win: Run NEST on Windows |windows| diff --git a/doc/htmldoc/installation/hpc_install.rst b/doc/htmldoc/installation/hpc_install.rst index 49fbe20ee6..0a926fcd43 100644 --- a/doc/htmldoc/installation/hpc_install.rst +++ b/doc/htmldoc/installation/hpc_install.rst @@ -3,10 +3,24 @@ High Performance Computer Systems Installation ================================================ +How you want to install NEST on a supercomputer or cluster will depend on your needs +and how the system is set up. + + + +Source install +--------------- + +See our full guide to installing :ref:`NEST from source `, which allows you to control +the configuration options. + + Minimal configuration -------------------------- +~~~~~~~~~~~~~~~~~~~~~~ + -NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer. However, this implies several restrictions: +NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer. +However, this implies several restrictions: - Some neuron and synapse models will not be available, as they depend on ODE solvers from the GNU Scientific Library. - The Python extension will not be available @@ -23,3 +37,25 @@ To configure NEST for compilation without external packages, use the following See the :ref:`CMake Options ` to further adjust settings for your system. + + +NEST docker +----------- + +Alternatively, you can set up the pre-built :ref:`NEST docker container ` that contains +everything you need for NEST, as well as options like NEST server, Jupyterlab, or :doc:`NEST Desktop `. +Our docker container also comes with :doc:`NESTML `. + +Connect to remote machine - NEST Server +--------------------------------------- + +NEST Server can be deployed on a remote machine such as a workstation or cluster, and users +can access the NEST simulation engine through the RESTful API on their laptops. + +See the :ref:`guide to NEST server ` to learn more. + + +.. seealso:: + + + Check out our guides to :ref:`optimizing NEST for HPC systems ` diff --git a/doc/htmldoc/installation/index.rst b/doc/htmldoc/installation/index.rst index 69bc61728c..b785ff2adc 100644 --- a/doc/htmldoc/installation/index.rst +++ b/doc/htmldoc/installation/index.rst @@ -3,40 +3,55 @@ Install NEST ============ -.. grid:: 1 1 2 2 - .. grid-item-card:: |user| Install pre-built NEST package - :class-title: sd-d-flex-row sd-align-minor-center +.. grid:: 3 + :gutter: 1 - I'm a user who wants to :ref:`install NEST on my computer ` + .. grid-item-card:: |user| Install a pre-built NEST package using + :class-title: sd-d-flex-row sd-align-minor-center + * :ref:`Docker (cross-platform) ` + (Includes NESTML) + * :ref:`conda-forge (Linux/macOS) ` + * :ref:`Ubuntu PPA (Linux) ` + * :ref:`Homebrew (macOS) ` + * :ref:`Options for Windows users ` - .. grid-item-card:: |teacher| Install NEST for a class or workshop - :class-title: sd-d-flex-row sd-align-minor-center - I'm a lecturer who wants to :ref:`use NEST to teach ` + .. grid-item-card:: |dev| Source install + :class-title: sd-d-flex-row sd-align-minor-center + If you want to do development with NEST -.. grid:: 1 1 2 2 + * :ref:`dev_install` - .. grid-item-card:: |admin| Install NEST for supercomputers and clusters - :class-title: sd-d-flex-row sd-align-minor-center + .. grid-item-card:: |admin| HPC install + :class-title: sd-d-flex-row sd-align-minor-center - I'm an admin or user who wants to :ref:`run NEST on HPC ` + If you are working with HPC systems - .. grid-item-card:: |dev| Install NEST from source - :class-title: sd-d-flex-row sd-align-minor-center + * :ref:`Install NEST for supercomputers and clusters ` - I'm a developer who wants to :ref:`do development in NEST ` + .. grid-item-card:: |desktop| + :class-title: sd-d-flex-row sd-align-minor-center -.. grid:: 1 1 2 2 + A graphical user interface, ideal for learning and teaching concepts + regarding neural networks in classrooms and workshops. - .. grid-item-card:: |nestml| Install NEST with NESTML - :class-title: sd-d-flex-row sd-align-minor-center + :doc:`NEST Desktop documentation ` :octicon:`link-external` - I'm a user who wants to :doc:`create or customize models `. + :ref:`Install docker container with NEST + NEST Desktop ` + + .. grid-item-card:: |nestml| + :class-title: sd-d-flex-row sd-align-minor-center + + Install the NEST modeling language to create and customize models + + + :doc:`NESTML documentation ` :octicon:`link-external` + + :ref:`Install docker container for NEST + NESTML ` -| @@ -60,5 +75,5 @@ If installation didn't work, see the :ref:`troubleshooting section + id="g9887" + transform="translate(-22.316978,-40.133735)"> Date: Wed, 17 Jan 2024 11:40:22 +0100 Subject: [PATCH 2/8] add nestml and nestdesktoplogos --- doc/htmldoc/static/img/nestdesktop022023.svg | 120 +++++++++++++++++++ doc/htmldoc/static/img/nestml022023.svg | 95 +++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 doc/htmldoc/static/img/nestdesktop022023.svg create mode 100644 doc/htmldoc/static/img/nestml022023.svg diff --git a/doc/htmldoc/static/img/nestdesktop022023.svg b/doc/htmldoc/static/img/nestdesktop022023.svg new file mode 100644 index 0000000000..d688ec8c2f --- /dev/null +++ b/doc/htmldoc/static/img/nestdesktop022023.svg @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/htmldoc/static/img/nestml022023.svg b/doc/htmldoc/static/img/nestml022023.svg new file mode 100644 index 0000000000..07b6832c5c --- /dev/null +++ b/doc/htmldoc/static/img/nestml022023.svg @@ -0,0 +1,95 @@ + + + + + + + + + + + + + + + + + + + From b09167db18c5468e1296c140b376a6b976bc7be6 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Wed, 17 Jan 2024 11:54:29 +0100 Subject: [PATCH 3/8] modify heading --- doc/htmldoc/installation/docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/htmldoc/installation/docker.rst b/doc/htmldoc/installation/docker.rst index 5afcc3fd31..c0580b6f1b 100644 --- a/doc/htmldoc/installation/docker.rst +++ b/doc/htmldoc/installation/docker.rst @@ -163,7 +163,7 @@ After booting, a URL is presented. Click on it or copy it to your browser. .. _docker_win: Run NEST on Windows |windows| -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- .. important:: From cd691963eab25083a6eaf37e56a70f6b9545a490 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Tue, 27 Feb 2024 21:21:44 +0100 Subject: [PATCH 4/8] remove hpc install temporarily --- doc/htmldoc/installation/index.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/htmldoc/installation/index.rst b/doc/htmldoc/installation/index.rst index b785ff2adc..2c4bc1a2e7 100644 --- a/doc/htmldoc/installation/index.rst +++ b/doc/htmldoc/installation/index.rst @@ -4,11 +4,12 @@ Install NEST ============ -.. grid:: 3 +.. grid:: 2 :gutter: 1 .. grid-item-card:: |user| Install a pre-built NEST package using :class-title: sd-d-flex-row sd-align-minor-center + :columns: 4 * :ref:`Docker (cross-platform) ` (Includes NESTML) @@ -20,20 +21,18 @@ Install NEST .. grid-item-card:: |dev| Source install :class-title: sd-d-flex-row sd-align-minor-center + :columns: 4 If you want to do development with NEST * :ref:`dev_install` - .. grid-item-card:: |admin| HPC install - :class-title: sd-d-flex-row sd-align-minor-center - - If you are working with HPC systems - - * :ref:`Install NEST for supercomputers and clusters ` +.. grid:: 2 + :gutter: 1 .. grid-item-card:: |desktop| :class-title: sd-d-flex-row sd-align-minor-center + :columns: 4 A graphical user interface, ideal for learning and teaching concepts regarding neural networks in classrooms and workshops. @@ -44,6 +43,7 @@ Install NEST .. grid-item-card:: |nestml| :class-title: sd-d-flex-row sd-align-minor-center + :columns: 4 Install the NEST modeling language to create and customize models From 5b9d1b4156c53f3f0bda44a71137401abe7043df Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Thu, 29 Feb 2024 13:53:25 +0100 Subject: [PATCH 5/8] add requirement carousel --- doc/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index b41e49ad1f..8d7d35a84e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -26,6 +26,7 @@ seaborn>=0.12.2 sphinx>=6.2.1 sphinx_autobuild>=2021.3.14 sphinx-copybutton>=0.5.2 +sphinx-carousel sphinx-notfound-page>=0.8.3 sphinx-design>=0.4.1 sphinx-gallery>=0.13.0 From d7b1d6852490ddaee59d588fd86224f6bc21eaf5 Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Thu, 29 Feb 2024 14:03:18 +0100 Subject: [PATCH 6/8] remove hpc install instructions and admin page not used, move minimal config to cmake options --- doc/htmldoc/installation/admin.rst | 26 --------- doc/htmldoc/installation/cmake_options.rst | 23 ++++++++ doc/htmldoc/installation/hpc_install.rst | 61 ---------------------- doc/htmldoc/installation/index.rst | 1 - doc/htmldoc/installation/noenv_install.rst | 5 +- 5 files changed, 24 insertions(+), 92 deletions(-) delete mode 100644 doc/htmldoc/installation/admin.rst delete mode 100644 doc/htmldoc/installation/hpc_install.rst diff --git a/doc/htmldoc/installation/admin.rst b/doc/htmldoc/installation/admin.rst deleted file mode 100644 index c95367944e..0000000000 --- a/doc/htmldoc/installation/admin.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _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/htmldoc/installation/cmake_options.rst b/doc/htmldoc/installation/cmake_options.rst index 8e919d627a..39c69c0dc8 100644 --- a/doc/htmldoc/installation/cmake_options.rst +++ b/doc/htmldoc/installation/cmake_options.rst @@ -40,6 +40,29 @@ NEST allows for several configuration options for custom builds: .. _modelset_config: +Minimal configuration +~~~~~~~~~~~~~~~~~~~~~~ + + +NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer. +However, this implies several restrictions: + +- Some neuron and synapse models will not be available, as they depend on ODE solvers from the GNU Scientific Library. +- The Python extension will not be available +- Multi-threading and parallel computing facilities will be disabled. + +To configure NEST for compilation without external packages, use the following command:: + + cmake -DCMAKE_INSTALL_PREFIX:PATH= \ + -Dwith-python=OFF \ + -Dwith-gsl=OFF \ + -Dwith-readline=OFF \ + -Dwith-ltdl=OFF \ + -Dwith-openmp=OFF \ + + +See the :ref:`CMake Options ` to further adjust settings for your system. + Select built-in models ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/htmldoc/installation/hpc_install.rst b/doc/htmldoc/installation/hpc_install.rst deleted file mode 100644 index 0a926fcd43..0000000000 --- a/doc/htmldoc/installation/hpc_install.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _hpc_install: - -High Performance Computer Systems Installation -================================================ - -How you want to install NEST on a supercomputer or cluster will depend on your needs -and how the system is set up. - - - -Source install ---------------- - -See our full guide to installing :ref:`NEST from source `, which allows you to control -the configuration options. - - -Minimal configuration -~~~~~~~~~~~~~~~~~~~~~~ - - -NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer. -However, this implies several restrictions: - -- Some neuron and synapse models will not be available, as they depend on ODE solvers from the GNU Scientific Library. -- The Python extension will not be available -- Multi-threading and parallel computing facilities will be disabled. - -To configure NEST for compilation without external packages, use the following command:: - - cmake -DCMAKE_INSTALL_PREFIX:PATH= \ - -Dwith-python=OFF \ - -Dwith-gsl=OFF \ - -Dwith-readline=OFF \ - -Dwith-ltdl=OFF \ - -Dwith-openmp=OFF \ - - -See the :ref:`CMake Options ` to further adjust settings for your system. - - -NEST docker ------------ - -Alternatively, you can set up the pre-built :ref:`NEST docker container ` that contains -everything you need for NEST, as well as options like NEST server, Jupyterlab, or :doc:`NEST Desktop `. -Our docker container also comes with :doc:`NESTML `. - -Connect to remote machine - NEST Server ---------------------------------------- - -NEST Server can be deployed on a remote machine such as a workstation or cluster, and users -can access the NEST simulation engine through the RESTful API on their laptops. - -See the :ref:`guide to NEST server ` to learn more. - - -.. seealso:: - - - Check out our guides to :ref:`optimizing NEST for HPC systems ` diff --git a/doc/htmldoc/installation/index.rst b/doc/htmldoc/installation/index.rst index 2c4bc1a2e7..5303b9fdf7 100644 --- a/doc/htmldoc/installation/index.rst +++ b/doc/htmldoc/installation/index.rst @@ -66,7 +66,6 @@ If installation didn't work, see the :ref:`troubleshooting section ` or the :ref:`High Performance Computing ` instructions to +:ref:`CMake Options ` instructions to further adjust settings for your system. * If not already installed on your system, the following packages are recommended. @@ -95,6 +95,3 @@ sourcing the script: .. code-block:: sh source /bin/nest_vars.sh - - - From 4140029543589534648e116fd90ee51ab151e06b Mon Sep 17 00:00:00 2001 From: Jessica Mitchell Date: Mon, 4 Mar 2024 08:58:53 +0100 Subject: [PATCH 7/8] add hpc --- doc/htmldoc/installation/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/htmldoc/installation/index.rst b/doc/htmldoc/installation/index.rst index 5303b9fdf7..e4479978e2 100644 --- a/doc/htmldoc/installation/index.rst +++ b/doc/htmldoc/installation/index.rst @@ -53,6 +53,14 @@ Install NEST :ref:`Install docker container for NEST + NESTML ` + .. grid-item-card:: |hpc| Configure HPC systems + :class-title: sd-d-flex-row sd-align-minor-center + :columns: 4 + + Find out how to set up and optimize HPC systems for NEST + + * :ref:`optimize_performance` + ---- @@ -76,3 +84,4 @@ If installation didn't work, see the :ref:`troubleshooting section Date: Tue, 5 Mar 2024 13:25:03 +0100 Subject: [PATCH 8/8] add bullets and subheading --- doc/htmldoc/installation/index.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/htmldoc/installation/index.rst b/doc/htmldoc/installation/index.rst index e4479978e2..b8637fab7a 100644 --- a/doc/htmldoc/installation/index.rst +++ b/doc/htmldoc/installation/index.rst @@ -27,6 +27,9 @@ Install NEST * :ref:`dev_install` +Install related tools +~~~~~~~~~~~~~~~~~~~~~ + .. grid:: 2 :gutter: 1 @@ -37,9 +40,9 @@ Install NEST A graphical user interface, ideal for learning and teaching concepts regarding neural networks in classrooms and workshops. - :doc:`NEST Desktop documentation ` :octicon:`link-external` + * :doc:`NEST Desktop documentation ` :octicon:`link-external` - :ref:`Install docker container with NEST + NEST Desktop ` + * :ref:`Install docker container with NEST + NEST Desktop ` .. grid-item-card:: |nestml| :class-title: sd-d-flex-row sd-align-minor-center @@ -48,9 +51,9 @@ Install NEST Install the NEST modeling language to create and customize models - :doc:`NESTML documentation ` :octicon:`link-external` + * :doc:`NESTML documentation ` :octicon:`link-external` - :ref:`Install docker container for NEST + NESTML ` + * :ref:`Install docker container for NEST + NESTML ` .. grid-item-card:: |hpc| Configure HPC systems