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>. Detailed installation 
instructions can be found below, including instructions for macOS, BlueGene/Q
and Fujitsu Sparc64 systems.

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"
