Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add information about nest_vars.sh and update Linux installation instructions #1515

Merged
merged 29 commits into from
Jun 16, 2020
Merged
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
d4c52cb
Add module loading path subheading
sarakonradi Apr 15, 2020
8918bb8
Add module path information
sarakonradi Apr 15, 2020
c634598
Update nest_vars.sh section
sarakonradi Apr 15, 2020
e317788
update documentation of nest_vars.sh
clinssen Apr 21, 2020
e139456
manual rebase linux_install.rst on latest master branch
clinssen Apr 22, 2020
6f195e4
Merge pull request #2 from clinssen/update_nest_vars_doc
sarakonradi Apr 22, 2020
0768ee4
Shorten title underline
sarakonradi Apr 22, 2020
c57244b
Remore "to" as suggested by @clinssen
sarakonradi Apr 22, 2020
c22db7f
Remove "to" as suggested by @clinssen
sarakonradi Apr 22, 2020
e2dc529
Merge branch 'fix_issue_1222' of github.com:sarakonradi/nest-simulato…
sarakonradi Apr 22, 2020
70c824b
Remove "to" as suggested by @clinssen
sarakonradi Apr 22, 2020
52d6863
Remove "to" as suggested by @clinssen
sarakonradi Apr 22, 2020
7da3ace
Update CMake note as suggested by @clinssen
sarakonradi Apr 22, 2020
62e5602
Fix merge conflict in linux_install.rst
sarakonradi Apr 23, 2020
92641c0
Add CMake install link, as suggested by @gtrensch
sarakonradi Apr 23, 2020
0fe9d7c
Merge branch 'fix_issue_1222' of origin into fix_issue_1222
sarakonradi Apr 23, 2020
6e3462d
change apt package versions to Python 3
clinssen Apr 24, 2020
0866ea3
Merge pull request sarakonradi/nest-simulator#4 from clinssen/update_…
sarakonradi Apr 24, 2020
df499ae
Update environment variables information in doc/installation/linux_in…
sarakonradi Apr 28, 2020
517debf
Update "environment variables" section in doc/installation/linux_inst…
sarakonradi Apr 28, 2020
592f5c0
Update shell script information in doc/installation/linux_install.rst
sarakonradi Apr 28, 2020
e028e6d
Apply remaining suggestions to doc/installation/linux_install.rst
sarakonradi Apr 28, 2020
30a924a
Fix conflict in doc/installation/linux_install.rst
sarakonradi Apr 28, 2020
636b03a
Merge branch 'fix_issue_1222' of github.com:sarakonradi/nest-simulato…
sarakonradi Apr 28, 2020
fd1cb9c
Update note format in doc/installation/linux_install.rst
sarakonradi Apr 28, 2020
7675fd6
Refer to 'Environment variables' section, as suggested by @clinssen
sarakonradi May 4, 2020
16a9e5f
Update install path, as suggested by @clinssen
sarakonradi May 4, 2020
91d3a01
Merge branch 'master' into fix_issue_1222
sarakonradi May 14, 2020
b8298ed
Add information on Boost
sarakonradi May 20, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 84 additions & 56 deletions doc/installation/linux_install.rst
Original file line number Diff line number Diff line change
@@ -1,29 +1,51 @@
Ubuntu/Debian Installation
===============================
==========================

.. _standard:

Installation from source
--------------------------
Dependencies
------------

To build NEST, you need a recent version of `CMake <https://cmake.org/install>`_ and `libtool <https://www.gnu.org/software/libtool/libtool.html>`_; the latter should be available for most systems and is probably already installed.
terhorstd marked this conversation as resolved.
Show resolved Hide resolved

.. 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 <http://www.gnu.org/software/readline/>`_ 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 want to use GNU readline with NEST. GNU readline itself depends on `libncurses <http://www.gnu.org/software/ncurses/>`_ (or libtermcap on older systems). Again, the development packages are needed to compile NEST.

The `GNU Scientific Library <http://www.gnu.org/software/gsl/>`_ 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.

sarakonradi marked this conversation as resolved.
Show resolved Hide resolved
For efficient sorting algorithms the Boost library <https://www.boost.org/> is used. Since this is an essential factor for the communication of spikes, some simulations are significantly faster when NEST is compile with Boost.
If you want to use PyNEST, we recommend to install the following along with their development packages:

- `Python 3.5 or higher <http://www.python.org>`_
- `NumPy <http://www.scipy.org>`_
- `SciPy <http://www.scipy.org>`_
- `Matplotlib 3.0 or higher <http://matplotlib.org>`_
- `IPython <http://ipython.org>`_

The following are the basic steps to compile and install NEST from source code:

Installation from source
------------------------

The following are the basic steps to compile and install NEST from source code. See the :doc:`Configuration Options <install_options>` or the :doc:`High Performance Computing <hpc_install>` 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-get install -y \
sudo apt install -y \
cython \
libgsl-dev \
libltdl-dev \
libncurses-dev \
libreadline-dev \
python-all-dev \
python-numpy \
python-scipy \
python-matplotlib \
python-nose \
python3-all-dev \
python3-numpy \
python3-scipy \
python3-matplotlib \
python3-nose \
openmpi-bin \
libopenmpi-dev

Expand Down Expand Up @@ -53,7 +75,9 @@ The following are the basic steps to compile and install NEST from source code:

cmake -DCMAKE_INSTALL_PREFIX:PATH=</install/path> </path/to/NEST/src>

.. note:: ``/install/path`` should be an absolute path
.. note::

``/install/path`` should be an absolute path

.. note::

Expand All @@ -67,63 +91,67 @@ The following are the basic steps to compile and install NEST from source code:
make install
make installcheck

NEST should now be successfully installed on your system. You should now be able to ``import nest`` from a python or ipython shell.

.. admonition:: IMPORTANT!

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. In this case, please run:
NEST should now be successfully installed on your system.

.. code-block:: sh
* 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.

source </path/to/nest_install_dir>/bin/nest_vars.sh
* See the :doc:`Getting started <../getting_started>` pages to find out how to get going with NEST or check out our :doc:`example networks <../auto_examples/index>`.

to set the necessary environment variables. You may want to include this line in your ``.bashrc`` file, so that the environment variables are set automatically.

See the :doc:`Getting started <../getting_started>` pages to find out how to get going with NEST or check out our :doc:`example networks <../auto_examples/index>`.

Dependencies
-------------

To build NEST, you need a recent version of `CMake <https://cmake.org>`_ and `libtool <https://www.gnu.org/software/libtool/libtool.html>`_; 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.X. You can type ``cmake --version`` on the commandline to check your current version.

The `GNU readline library <http://www.gnu.org/software/readline/>`_ 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 want to use GNU readline with NEST. GNU readline itself depends on `libncurses <http://www.gnu.org/software/ncurses/>`_ (or libtermcap on older systems). Again, the development packages are needed to compile NEST.

The `GNU Scientific Library <http://www.gnu.org/software/gsl/>`_ 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.

If you want to use PyNEST, we recommend to install the following along with their development packages:

- `Python 3.X <http://www.python.org>`_
- `NumPy <http://www.scipy.org>`_
- `SciPy <http://www.scipy.org>`_
- `Matplotlib 3.X <http://matplotlib.org>`_
- `IPython <http://ipython.org>`_


See the :doc:`Configuration Options <install_options>` or the :doc:`High Performance Computing <hpc_install>` instructions to further adjust settings for your system.

What gets installed where
---------------------------
-------------------------

By default, everything will be installed to the subdirectories ``/install/path/{bin,lib,share}``, where ``/install/path`` is the install path given to ``cmake``:

- Executables ``/install/path/bin``
- Dynamic libraries ``/install/path/lib/nest``
- SLI libraries ``/install/path/share/nest/sli``
- Documentation ``/install/path/share/doc/nest``
- Examples ``/install/path/share/doc/nest/examples``
- PyNEST ``/install/path/lib/pythonX.Y/site-packages/nest``
- PyNEST examples ``/install/path/share/doc/nest/examples/pynest``
- Extras ``/install/path/share/nest/extras/``
- Dynamic libraries ``/install/path/lib/``
- SLI libraries ``/install/path/share/nest/sli``
- Documentation ``/install/path/share/doc/nest``
- Examples ``/install/path/share/doc/nest/examples``
- PyNEST ``/install/path/lib/pythonX.Y/site-packages/nest``
- PyNEST examples ``/install/path/share/doc/nest/examples/pynest``
- Extras ``/install/path/share/nest/extras/``

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. For example, if you are using bash:
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 <environment_variables>` section for this.

.. code-block:: sh

export PATH=$PATH:/install/path/bin
export PYTHONPATH=/install/path/lib/pythonX.Y/site-packages:$PYTHONPATH
.. _environment_variables:

Environment variables
---------------------

The script ``/install/path/bin/nest_vars.sh`` can be sourced in ``.bashrc`` and will set these paths for you. This also allows to switch between NEST installations in a convenient manner.
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 ``/install/path/bin/nest_vars.sh``. Setting the environment variables in your active shell session requires sourcing the script:

.. code-block:: sh

source </install/path/>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
* - ``NEST_INSTALL_DIR``
- NEST installation directory. Contains ``bin``, ``lib``, etc.
* - ``NEST_DATA_DIR``
- NEST finds standard *.sli files in ``$NEST_DATA_DIR/sli``
* - ``NEST_DOC_DIR``
- NEST built-in online help finds help files in ``$NEST_DOC_DIR/help``
* - ``NEST_PYTHON_PREFIX``
- The path where the PyNEST bindings are installed.
* - ``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.
* - ``LD_LIBRARY_PATH``
- Search path for shared objects (*.so files). Note: called ``DYLD_LIBRARY_PATH`` on MacOS. 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.