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>. Detailed installation 
instructions can be found below.


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

NEST has successfully been compiled with a range of compilers, including
GNU gcc/g++, Intel icc/icpc, Pathscale, Portland and IBM compilers.

One caveat: you should compile NEST with the same compiler and version as
your Python. Strange crashes have been observed on importing NEST when
compiling NEST with g++ 4.3 or later on OSX and importing it into Python
compiled with the standard gcc 4.0 compiler.

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 a ltdl library. To set a specific
                                                 ltdl, set install path.
                                                 [default=ON]
    -Dwith-python=[OFF|ON|</path/to/python>]     Build PyNEST. To set a specific Python,
                                                 set install path. [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;off;flags>] Enable user defined optimizations. Separate
                                              multiple flags by ';'.
                                              [default OFF, when ON, defaults to '-O3']
    -Dwith-warning=[OFF|ON|<list;off;flags>]  Enable user defined warnings. Separate
                                              multiple flags by ';'.
                                              [default ON, when ON, defaults to '-Wall']
    -Dwith-debug=[OFF|ON|<list;off;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 argument to `cmake`.


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>

It is recommended to build statically on larger BlueGene/Q systems. If you need
PyNEST on BlueGene/Q, you have to compile dynamically, i.e. `-Dstatic-libraries=OFF`
and you have to cythonize the `pynest/pynestkernel.pyx/.pxd`
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

Eventually, you also have to specify `PYTHON_LIBRARY` and `PYTHON_INCLUDE_DIR`,
if the they are not 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

Further, for running PyNEST, make sure all python dependencies are installed and
environment variables are set properly:

    # 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 PYTHONPATH ... : python script.py

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"