CMake Options for NEST ====================== NEST is installed with ``cmake`` (at least v3.12). In the simplest case, the commands:: cmake -DCMAKE_INSTALL_PREFIX:PATH= make make install should build and install NEST to ``/install/path``, which should be an absolute path. Choice of compiler ------------------ We :doc:`systematically test <../contribute/ci>` NEST using the GNU gcc and the Clang compiler suites. Compilation with other up-to-date compilers should also work, but we do not regularly test against those compilers and can thus only provide limited support. To select a specific compiler, please add the following flags to your ``cmake`` line:: -DCMAKE_C_COMPILER= -DCMAKE_CXX_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] Add user modules:: -Dexternal-modules=[OFF|] External NEST modules to be linked in, separated by ';'. [default=OFF] Connect NEST with external projects:: -Dwith-music=[OFF|ON|] Request the use of MUSIC. Optionally give the directory, where MUSIC is installed. [default=OFF] Change parallelization scheme:: -Dwith-mpi=[OFF|ON|] Request compilation with MPI. Optionally give directory with MPI installation. [default=OFF] -Dwith-openmp=[OFF|ON|] Enable OpenMP multi-threading. Optional: set OMP flag. [default=ON] Set default libraries:: -Dwith-gsl=[OFF|ON|] Find a gsl library. To set a specific library, set install path.[default=ON] -Dwith-readline=[OFF|ON|] Find a GNU Readline library. To set a specific library, set install path. [default=ON] -Dwith-ltdl=[OFF|ON|] 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] Build PyNEST. [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|] Enable user defined optimizations. Separate multiple flags by ';'. [default OFF, when ON, defaults to '-O3'] -Dwith-warning=[OFF|ON|] Enable user defined warnings. Separate multiple flags by ';'. [default ON, when ON, defaults to '-Wall'] -Dwith-debug=[OFF|ON|] Enable user defined debug flags. Separate multiple flags by ';'. [default OFF, when ON, defaults to '-g'] -Dwith-intel-compiler-flags=[] User defined flags for the Intel compiler. Separate multiple flags by ';'. [defaults to '-fp-model strict'] -Dwith-libraries= Link additional libraries. Give full path. Separate multiple libraries by ';'. [default OFF] -Dwith-includes= Add additional include paths. Give full path without '-I'. Separate multiple include paths by ';'. [default OFF] -Dwith-defines= Additional defines, e.g. '-DXYZ=1'. Separate multiple defines by ';'. [default OFF] .. _compile-with-mpi: Configuring NEST for Distributed Simulation with MPI ---------------------------------------------------- NEST supports distributed simulations using the Message Passing Interface (MPI). Depending on your setup, you have to use one of the following steps in order to add support for MPI: 1. Try ``-Dwith-mpi=ON`` as argument for ``cmake``. 2. If 1. does not work, or you want to use a non-standard MPI, try ``-Dwith-mpi=/path/to/my/mpi``. The `mpi` directory should contain the `include`, `lib` and `bin` subdirectories of the MPI installation. 3. If 2. does not work, but you know the correct compiler wrapper for your installation, try adding the following to the invocation of ``cmake``:: -DMPI_CXX_COMPILER=myC++_CompilerWrapper -DMPI_C_COMPILER=myC_CompilerWrapper -Dwith-mpi=ON When running large-scale parallel simualations and recording from many neurons, writing to ASCII files might become prohibitively slow due to the large number of resulting files. By installing the `SIONlib library `_ and supplying its installation path to the ``-Dwith-sionlib=`` option when calling `cmake`, you can enable the :ref:`recording backend for binary files `, which solves this problem. If you compiled NEST with support for MPI and also want to run the corresponding tests, you have to tell it about how your ``mpirun``/``mpiexec`` command works by defining the ``mpirun`` function in your ``~/.nestrc`` file. The file already contains an example implementation that should work with the `OpenMPI `__ implementation. For more details, see the documentation on the :doc:`configuration`. See the :ref:`parallel_computing` to learn how to execute threaded and distributed simulations with NEST. .. _compile_with_libneurosim: Support for libneurosim ----------------------- In order to allow NEST to create connections using external libraries, it provides support for the Connection Generator Interface from *libneurosim*. To request the use of libneurosim, you have to use the follwing switch for the invocation of ``cmake``. It expects either *ON* or *OFF*, or the directory where libneurosim is installed:: -Dwith-libneurosim=[OFF|ON|] For details on how to use the Connection Generator Interface, see the :ref:`guide on connection management `. Disabling the Python Bindings (PyNEST) -------------------------------------- To disable Python bindings use:: -Dwith-python=OFF as an argument to ``cmake``. Python Binding (PyNEST) ----------------------- Note that since NEST 3.0, support for Python 2 has been dropped. Please use Python 3 instead. ``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= \ -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 \ Compiler-specific options ------------------------- NEST has reasonable default compiler options for the most common compilers. Intel compiler ~~~~~~~~~~~~~~ To ensure that computations obey the IEEE754 standard for floating point numerics, the ``-fp-model strict`` flag is used by default, but can be overridden with :: -Dwith-intel-compiler-flags="" Portland compiler ~~~~~~~~~~~~~~~~ Use the ``-Kieee`` flag to ensure that computations obey the IEEE754 standard for floating point numerics.