INSTALL

This file contains a brief summary or the steps needed to install NEST. More
detailed information is available on the homepage of the NEST simulator at
http://www.nest-simulator.org/installation

Introduction
============

NEST is installed with `cmake` (at least v2.8.12). In the simplest case, the commands

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

should build and install NEST to `/install/path`, which should be an absolute
path. Detailed installation  instructions can be found below, including 
instructions for macOS, BlueGene/Q and Fujitsu Sparc64 systems.

On systems where help extraction is slow, the call to `make install` can be replaced
by `make install-nodoc` to skip the generation of help pages and indices. Using this
option can help developers to speed up development cycles, but is not recommended for
production use as it renders the built-in help system useless.

Choice of CMake Version
=======================

We recommend to use `cmake` v3.4 or later, even though installing NEST with
`cmake` v2.8.12 will in most cases work properly.
For more detailed information please see below: `Python3 Binding (PyNEST)`

Choice of compiler
==================

The default compiler for NEST is GNU gcc/g++, but NEST has also successfully 
been compiled with other compilers, including Intel icc/icpc, Pathscale, 
Portland and IBM compilers.

To select a specific compiler, please add the following flags to your `cmake`
line:

    -DCMAKE_C_COMPILER=<C-compiler> -DCMAKE_CXX_COMPILER=<C++-compiler>

Options for configuring NEST
============================

NEST allows for several configuration options for custom builds:

Change NEST behavior:

    -Dtics_per_ms=[number]     Specify elementary unit of time. [default 1000.0]
    -Dtics_per_step=[number]   Specify resolution. [default 100]
    -Dwith-ps-arrays=[OFF|ON]  Use PS array construction semantics. [default=ON]

Add user modules:

    -Dexternal-modules=[OFF|<list;of;modules>]  External NEST modules to be linked
                                                in, separated by ';'. [default=OFF]

Connect NEST with external projects:

    -Dwith-libneurosim=[OFF|ON|</path/to/libneurosim>]  Request the use of libneurosim.
                                                        Optionally give the directory,
                                                        where libneurosim is installed.
                                                        [default=OFF]
    -Dwith-music=[OFF|ON|</path/to/music>] Request the use of MUSIC. Optionally
                                           give the directory, where MUSIC is installed.
                                           [default=OFF]

Change parallelization scheme:

    -Dwith-mpi=[OFF|ON|</path/to/mpi>]  Request compilation with MPI. Optionally
                                        give directory with MPI installation.
                                        [default=OFF]
    -Dwith-openmp=[OFF|ON|<OpenMP-Flag>]  Enable OpenMP multi-threading. 
                                          Optional: set OMP flag. [default=ON]

Set default libraries:

    -Dwith-gsl=[OFF|ON|</path/to/gsl>]           Find a gsl library. To set a specific
                                                 library, set install path.[default=ON]
    -Dwith-readline=[OFF|ON|</path/to/readline>] Find a GNU Readline library. To set
                                                 a specific library, set install path.
                                                 [default=ON]
    -Dwith-ltdl=[OFF|ON|</path/to/ltdl>]         Find an ltdl library. To set a specific
                                                 ltdl, set install path. NEST uses the
                                                 ltdl for dynamic loading of external
                                                 user modules. [default=ON]
    -Dwith-python=[OFF|ON|2|3]                   Build PyNEST. To set a specific Python
                                                 version, set 2 or 3. [default=ON]
    -Dcythonize-pynest=[OFF|ON]                  Use Cython to cythonize pynestkernel.pyx.
                                                 If OFF, PyNEST has to be build from
                                                 a pre-cythonized pynestkernel.pyx.
                                                 [default=ON]

Change compilation behavior:

    -Dstatic-libraries=[OFF|ON]     Build static executable and libraries. [default=OFF]
    -Dwith-optimize=[OFF|ON|<list;of;flags>]  Enable user defined optimizations. Separate
                                              multiple flags by ';'.
                                              [default OFF, when ON, defaults to '-O3']
    -Dwith-warning=[OFF|ON|<list;of;flags>]   Enable user defined warnings. Separate
                                              multiple flags by ';'.
                                              [default ON, when ON, defaults to '-Wall']
    -Dwith-debug=[OFF|ON|<list;of;flags>]     Enable user defined debug flags. Separate
                                              multiple flags by ';'.
                                              [default OFF, when ON, defaults to '-g']
    -Dwith-libraries=<list;of;libraries>      Link additional libraries. Give full path.
                                              Separate multiple libraries by ';'.
                                              [default OFF]
    -Dwith-includes=<list;of;includes>        Add additional include paths. Give full
                                              path without '-I'. Separate multiple include
                                              paths by ';'. [default OFF]
    -Dwith-defines=<list;of;defines>          Additional defines, e.g. '-DXYZ=1'.
                                              Separate multiple defines by ';'. [default OFF]

Configuring NEST for Distributed Simulation with MPI
====================================================

  1. Try -Dwith-mpi=ON as argument for `cmake`. If it works, fine.
  2. If 1 does not work, or you want to use a non-standard MPI, 
     try -Dwith-mpi=/path/to/my/mpi. 
     Directory mpi should contain include, lib, bin subdirectories for MPI.
  3. If that does not work, but you know the correct compiler wrapper for 
     your machine, try configure -DMPI_CXX_COMPILER=myC++_CompilerWrapper
     -DMPI_C_COMPILER=myC_CompilerWrapper -Dwith-mpi=ON
  4. Sorry, you need to fix your MPI installation. 

Disabling the Python Bindings (PyNEST)
======================================

Please see also the file pynest/README.md in the documentation directory. If you
are impatient, use 

    -Dwith-python=OFF

as an argument to `cmake`.

Python3 Binding (PyNEST)
=========================

To force a Python3-binding in a mixed Python2/3 environment pass

    -Dwith-python=3

as an argument to `cmake`.

`cmake` usually autodetects your Python installation.
In some cases `cmake` might not be able to localize the Python interpreter
and its corresponding libraries correctly. To circumvent such a problem following
`cmake` built-in variables can be set manually and passed to `cmake`:

  PYTHON_EXECUTABLE ..... path to the Python interpreter
  PYTHON_LIBRARY ........ path to libpython
  PYTHON_INCLUDE_DIR .... two include ...
  PYTHON_INCLUDE_DIR2 ... directories

  e.g.: Please note `-Dwith-python=ON` is the default.
  cmake -DCMAKE_INSTALL_PREFIX=</install/path> \
        -DPYTHON_EXECUTABLE=/usr/bin/python3 \
        -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.4m.so \
        -DPYTHON_INCLUDE_DIR=/usr/include/python3.4 \
        -DPYTHON_INCLUDE_DIR2=/usr/include/x86_64-linux-gnu/python3.4m \
        </path/to/NEST/src>
        
Compiling for Apple OSX/macOS
=============================

NEST can currently not be compiled with the clang/clang++ compilers shipping
with macOS. Therefore, you first need to install GCC 6.3 or later. The easiest
way to install all required software is using Homebrew (from http://brew.sh).

  brew install gcc cmake gsl open-mpi libtool
  
will install all required prequisites. You can then configure NEST with 

  cmake -DCMAKE_INSTALL_PREFIX:PATH=</install/path> \
        -DCMAKE_C_COMPILER=gcc-6\
        -DCMAKE_CXX_COMPILER=g++-6 \
        </path/to/NEST/src>

For detailed information on installing NEST under OSX/macOS, please see the
"macOS" section of http://www.nest-simulator.org/installation.

Compiling for BlueGene/Q
========================

NEST provides a cmake tool-chain file for cross compilation for BlueGene/Q. When
configuring NEST use the following `cmake` line:

    cmake -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ_XLC \
          -DCMAKE_INSTALL_PREFIX:PATH=</install/path> \
          -Dwith-python=OFF \
          -Dstatic-libraries=ON \
          </path/to/NEST/src>

If you compile dynamically, be aware that the BlueGene/Q system might not provide an `ltdl`
library. If you want to dynamically load an external user module, you have to
compile and install an `ltdl` yourself and add `-Dwith-ltdl=<ltdl-install-dir>`
to the `cmake` line. Otherwise add `-Dwith-ltdl=OFF`.

Additionally, the design of `cmake`'s MPI handling has a broken design, which is
brittle in the case of BGQ and certain libraries (flags to use SIONlib, for example).

If you run into that, you must force `cmake` to use the wrappers rather than
it's attempts to extract the proper flags for the underlying compiler
as in:
```
-DCMAKE_C_COMPILER=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlc_r
-DCMAKE_CXX_COMPILER=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlcxx_r
```

BlueGene/Q and PyNEST
---------------------

Building PyNEST on BlueGene/Q requires you to compile dynamically, i.e. 
`-Dstatic-libraries=OFF`. Further, you have to cythonize the
`pynest/pynestkernel.pyx/.pyx` on a machine with Cython installed:

    cythonize pynestkernel.pyx

Copy the generated file `pynestkernel.cpp` into `</path/to/NEST/src>/pynest` on
BlueGene/Q and point `-Dwith-python=<...>` to a valid python version for cross
compilation:

    -Dwith-python=/bgsys/tools/Python-2.7/bin/hostpython
or (much better)
    -Dwith-python=/bgsys/local/python3/3.4.2/bin/python3

CMake <3.4 is buggy about finding the matching libraries (for many years).
Thus, you also have to specify `PYTHON_LIBRARY` and `PYTHON_INCLUDE_DIR`
if they are not found OR the incorrect libraries are found, e.g.:

```
-DPYTHON_LIBRARY=/bgsys/tools/Python-2.7/lib64/libpython2.7.so.1.0
-DPYTHON_INCLUDE_DIR=/bgsys/tools/Python-2.7/include/python2.7
```
or (much better)
```
-DPYTHON_LIBRARY=/bgsys/local/python3/3.4.2/lib/libpython3.4m.a
-DPYTHON_INCLUDE_DIR=/bgsys/local/python3/3.4.2/include/python3.4m
```

A complete `cmake` line for PyNEST could look like this:
```
module load gsl

cmake -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ_XLC \
  -DCMAKE_INSTALL_PREFIX=</install/path> \
  -Dstatic-libraries=OFF \
  -Dcythonize-pynest=OFF \
	  -DCMAKE_C_COMPILER=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlc_r \
	  -DCMAKE_CXX_COMPILER=/bgsys/drivers/ppcfloor/comm/xl/bin/mpixlcxx_r \
	  -Dwith-python=/bgsys/local/python3/3.4.2/bin/python3 \
	  -DPYTHON_LIBRARY=/bgsys/local/python3/3.4.2/lib/libpython3.4m.a \
	  -DPYTHON_INCLUDE_DIR=/bgsys/local/python3/3.4.2/include/python3.4m \
  -Dwith-ltdl=OFF \
  <nest-src>
```

Further, for running PyNEST, make sure all python dependencies are installed and
environment variables are set properly:
```
module load python3/3.4.2

# adds PyNEST to the PYTHONPATH
source <nest-install-dir>/bin/nest_vars.sh

# makes HOME and PYTHONPATH available for python
runjob \
  --exp-env HOME \
  --exp-env PATH \
  --exp-env LD_LIBRARY_PATH \
  --exp-env PYTHONUNBUFFERED \
  --exp-env PYTHONPATH \
  ... \
  : /bgsys/local/python3/3.4.2/bin/python3.4 script.py
```

BlueGene/Q and GCC
------------------

Compiling NEST with GCC (`-DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ_GCC`)
might require you to use a GSL library compiled using GCC, otherwise undefined
symbols break your build. After the GSL is built with GCC and installed in
<gsl-install-dir>, add `-Dwith-gsl=<gsl-install-dir>` to the `cmake` line.

BlueGene/Q and Non-Standard Allocators
--------------------------------------

To use NEST with non-standard allocators on BlueGene/Q (e.g., tcmalloc), you
should compile NEST and the allocator with the same compiler, usually GCC.
Since static linking is recommended on BlueGene/Q, the allocator also needs
to be linked statically. This requires specifying linker flags and the
allocator library as shown in the following example:
```
cmake -DCMAKE_TOOLCHAIN_FILE=Platform/BlueGeneQ_GCC \
      -DCMAKE_INSTALL_PREFIX:PATH=$PWD/install \
      -Dstatic-libraries=ON -Dwith-warning=OFF \
      -DCMAKE_EXE_LINKER_FLAGS="-Wl,--allow-multiple-definition" \
      -Dwith-libraries=$HOME/tcmalloc/install/lib/libtcmalloc.a 
``


Compiling for Fujitsu Sparc64
=============================

On the K Computer:
  The preinstalled `cmake` version is 2.6, which is to old for NEST. Please install
  a newer version, e.g. like this:

      wget https://cmake.org/files/v3.4/cmake-3.4.2.tar.gz
      tar -xzf cmake-3.4.2.tar.gz
      mv cmake-3.4.2 cmake.src
      mkdir cmake.build
      cd cmake.build
      ../cmake.src/bootstrap --prefix=$PWD/install --parallel=4
      gmake -j4
      gmake install

  Also you might need a cross compiled GNU Scientific Library (GSL). For GSL 2.1
  this is a possible installation scenario:

      wget ftp://ftp.gnu.org/gnu/gsl/gsl-2.1.tar.gz
      tar -xzf gsl-2.1.tar.gz
      mkdir gsl-2.1.build gsl-2.1.install
      cd gsl-2.1.build
      ../gsl-2.1/configure --prefix=$PWD/../gsl-2.1.install/ \
                           CC=mpifccpx \
                           CXX=mpiFCCpx \
                           CFLAGS="-Nnoline" \
                           CXXFLAGS="--alternative_tokens -O3 -Kfast,openmp, -Nnoline, -Nquickdbg -NRtrap" \
                           --host=sparc64-unknown-linux-gnu \
                           --build=x86_64-unknown-linux-gnu
      gmake -j4
      gmake install

  To install NEST, use the following `cmake` line:

      cmake -DCMAKE_TOOLCHAIN_FILE=Platform/Fujitsu-Sparc64 \
            -DCMAKE_INSTALL_PREFIX:PATH=</install/path> \
            -Dwith-gsl=/path/to/gsl-2.1.install/ \
            -Dwith-optimize="-Kfast" \
            -Dwith-defines="-DUSE_PMA" \
            -Dwith-python=OFF \
            -Dwith-warning=OFF \
            </path/to/NEST/src>
      make -j4
      make install

  The compilation can take quite some time compiling the file `models/modelsmodule.cpp`
  due to generation of many template classes. To speed up the process, you can
  comment out all synapse models you do not need.
  The option `-Kfast` on the K computer enables many different options:

        -O3 -Kdalign,eval,fast_matmul,fp_contract,fp_relaxed,ilfunc,lib,mfunc,ns,omitfp,prefetch_conditional,rdconv -x-

  Be aware that, with the option `-Kfast` an internal compiler error - probably
  an out of memory situation - can occur. One solution is to disable synapse
  models that you don't use in `models/modelsmodule.cpp`. From current observations
  this might be related to the `-x-` option; you can give it a fixed value, e.g
  `-x1`, and the compilation succeeds (the impact on performance was not analyzed):

        -Dwith-optimize="-Kfast -x1"