CMake Options for NEST¶

Before compiling and installing NEST, the source code has to be configured with cmake. In the simplest case, the commands:

cmake <nest_source_dir>
make
make install

will build NEST and install it to the site-packages of your Python environment.

Note

If you want to specify an alternative install location, use -DCMAKE_INSTALL_PREFIX:PATH=<nest_install_dir>. It needs to be writable by the user running the install command.

Choice of compiler¶

We systematically test 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 command line:

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

Options for configuring NEST¶

NEST allows for several configuration options for custom builds:

Minimal configuration¶

NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer. However, this implies several restrictions:

Some neuron and synapse models will not be available, as they depend on ODE solvers from the GNU Scientific Library.
The Python extension will not be available
Multi-threading and parallel computing facilities will be disabled.

To configure NEST for compilation without external packages, use the following command:

cmake -DCMAKE_INSTALL_PREFIX:PATH=<nest_install_dir> \
      -Dwith-gsl=OFF \
      -Dwith-ltdl=OFF \
      -Dwith-openmp=OFF \
      </path/to/nest/source>

See the CMake Options to further adjust settings for your system.

Select built-in models¶

By default, NEST will compile and register all neuron and synapse models that are shipped in the source distribution. This is very convenient for an explorative development of simulation scripts, but leads to quite long compilation times and is often not necessary.

There are two ways to restrict the set of built-in models to tailor NEST to your needs:

-Dwith-modelset=<modelset>

Specify the modelset to include. Sample configurations are in the modelsets directory in the top-level of the source tree. A modelset is just a file listing one model header files (without the .h filename extension) to scan for models. Available pre-defined modelsets include: full (all models, default), binary (binary neuron models), rate (rate-based models), precise (high-precision IAF models), iaf_minimal (minimal IAF set), eprop (e-prop learning models), and empty (no built-in models). Using a smaller modelset significantly reduces compilation time. This option is mutually exclusive with -Dwith-models. [default=full].

-Dwith-models=[<modellist>|OFF]

Specify the models to include as a semicolon-separated list of model header files (without the .h filename extension) that are to be scanned for models. This option is mutually exclusive with -Dwith-modelset. [default=OFF].

Maximize performance, reduce energy consumption¶

The following options help to optimize NEST for maximal performance and thus reduced energy consumption.

`-Dwith-optimize="-O3 -march=native"`	Activate most compiler options that do not affect compliance with IEEE754 numerics and optimize for CPU type used
`-Dwith-defines=-DNDEBUG`	Disable all `assert()` statements in NEST

Note

In our experience, gains from these optimizations are not very large. It can still be sensible to test them, especially if you are going to perform a large number of simulations.
Your particular use case may contain edge cases during NEST execution that our extensive test suite has not covered. Internal consistency tests in NEST in the form of assert() statements can help to detect such edge cases. Using the optimization options above removes these internal checks and thus increases the risk that NEST will produce incorrect results. Therefore, use these options only after you have performed multiple simulations of your specific model with default optimization settings (i.e., -O2), which leaves the assertions in place.
Using -march=native requires that you build NEST on the same CPU architecture as you will use to run it.
For the technically minded: Even just using -O3 removes some assert() statements from NEST since we have wrapped some of them in functions, which get eliminated due to interprocedural optimization.

Select parallelization scheme¶

`-Dwith-mpi=[OFF\|ON]`	Build with MPI parallelization [default=OFF]. Enables distributed-memory parallel simulation across multiple processes. Required for `-Dwith-music` and `-Dwith-sionlib`. To pin a specific MPI installation, set `-DMPI_ROOT=/path/to/mpi`.
`-Dwith-openmp=[OFF\|ON]`	Build with OpenMP multi-threading [default=ON]. Enables shared-memory multi-threading for parallel neuron updates within a single process. To pin a specific OpenMP library, set `-DOpenMP_ROOT=/path/to/libomp`.

See also the section on building with MPI below.

Build documentation¶

`-Dwith-devdoc=[OFF\|ON]`	Build the developer (doxygen) documentation [default=OFF]
`-Dwith-userdoc=[OFF\|ON]`	Build the user (Sphinx) documentation [default=OFF]

If either documentation build is toggled to ON, you can then run make docs if you only want to build the docs.

See also the documentation workflow for user-facing and technical docs.

External libraries¶

`-Dwith-music=[OFF\|ON]`	Build with MUSIC [default=OFF]. MUSIC enables multi-simulator coupling, allowing NEST to exchange spikes, continuous data, and messages with other simulators at runtime. Requires `-Dwith-mpi=ON`. To pin a specific installation, set `-DMusic_ROOT=/path/to/music`.
`-Dwith-sionlib=[OFF\|ON]`	Build with SIONlib [default=OFF]. SIONlib provides a high-performance binary recording backend for large-scale distributed simulations. Requires `-Dwith-mpi=ON`. To pin a specific installation, set `-DSIONlib_ROOT=/path/to/sionlib`.
`-Dwith-boost=[OFF\|ON]`	Build with Boost [default=ON]. Boost is used for high-performance sorting of connections (`boost::sort::spreadsort`), for type name introspection in error messages, and for special math functions in the `iaf_bw_2001` neuron model. Without Boost, sorting performance may be reduced and the `iaf_bw_2001` model will not be available. To pin a specific installation, set `-DBoost_ROOT=/path/to/boost`.
`-Dwith-ltdl=[OFF\|ON]`	Build with ltdl library [default=ON]. NEST uses ltdl for dynamic loading of external user modules. Does not work with `-Dwith-static-linking=ON`. To pin a specific installation, set `-DLTDL_ROOT=/path/to/ltdl`.
`-Dwith-gsl=[OFF\|ON]`	Build with the GSL library [default=ON]. GSL is required for neuron models that use the GSL ODE solver for adaptive-step numerical integration, including the conductance-based `iaf_cond_`, `aeif_cond_`, `gif_cond_`, `glif_cond`, and Hodgkin-Huxley (`hh_`) variants, as well as `ht_neuron`, `siegert_neuron`, and several `aeif_psc_` and `hh_psc_` models. Without GSL, these 31 models will not be available. To pin a specific installation, set `-DGSL_ROOT=/path/to/gsl`.
`-Dwith-hdf5=[OFF\|ON]`	Build with HDF5 library [default=OFF]. HDF5 is required for SONATA support, see NEST SONATA guide. Note that the Python packages `h5py` and `pandas` are also required at runtime for SONATA functionality. To pin a specific installation, set `-DHDF5_ROOT=/path/to/hdf5`.

NEST properties¶

`-Dwith-threaded-timers=[OFF\|ON]`	Build with one internal timer per thread [default=ON]. Multi-threaded timers can affect the performance.
`-Dwith-detailed-timers=[OFF\|ON]`	Build with detailed internal time measurements [default=OFF]. Detailed timers can affect the performance. Required to enable `-Dwith-cycle-timers`.
`-Dwith-cycle-timers=[OFF\|ON]`	Build with internal per-cycle time measurements and logging of per-cycle spike counts [default=OFF]. Requires `-Dwith-detailed-timers=ON`. Can affect the performance.
`-Dwith-mpi-sync-timer=[OFF\|ON]`	Build with mpi synchronization barrier and timer [default=OFF]. Can affect the performance.
`-Dwith-target-bits-split=['default'\|'hpc']`	Split of the 64-bit target neuron identifier type [default=’default’]. ‘default’ is recommended for most users. If running on more than 262144 MPI processes or more than 512 threads, change to ‘hpc’.
`-Dwith-full-logging=[OFF\|ON]`	Write debug output to file `dump_<num_ranks>_<rank>.log` [default=OFF]. Developers should wrap debugging output in macro `FULL_LOGGING_ONLY()` and call `kernel().write_dump()` from inside it. The macro can contain almost any valid code.

Generic build configuration¶

`-Dwith-static-linking=[OFF\|ON]`	Build with static linking [default=OFF].
`-Dwith-optimize=[OFF\|ON\|<list;of;flags>]`	Enable user defined optimizations [default=ON (uses ‘-O2’)]. When OFF, no ‘-O’ flag is passed to the compiler. Explicit compiler flags can be given; separate multiple flags by ‘;’.”
`-Dwith-warning=[OFF\|ON\|<list;of;flags>]`	Enable user defined warnings [default=ON (uses ‘-Wall’)]. Separate multiple flags by ‘;’.
`-Dwith-debug=[OFF\|ON\|<list;of;flags>]`	Enable user defined debug flags [default=OFF]. When ON, ‘-g’ is used. Separate multiple flags by ‘;’.
`-Dwith-intel-compiler-strict-math=[OFF\|ON]`	Pass `-fp-model strict` when building with the Intel C++ compiler [default=ON]. This ensures IEEE754-compliant floating-point arithmetic. Disable only if you have verified that the looser default model does not affect your results.
`-Dwith-libraries=[OFF\|<list;of;libraries>]`	Link additional libraries [default=OFF]. Give full path. Separate multiple libraries by ‘;’.
`-Dwith-includes=[OFF\|<list;of;includes>]`	Add additional include paths [default=OFF]. Give full path without ‘-I’. Separate multiple include paths by ‘;’.
`-Dwith-defines=[OFF\|<list;of;defines>]`	Additional defines, e.g. ‘-DXYZ=1’ [default=OFF]. Separate multiple defines by ‘;’.
`-Dwith-version-suffix=[string]`	Set a user defined version suffix [default=’’].
`-DNESTKERNEL_API_CXX=<path>`	Use the given pre-generated `nestkernel_api.cxx` instead of running Cython [default: not set, Cython is run]. See Python Binding (PyNEST) for details.

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:

Try -Dwith-mpi=ON as argument for cmake.

If 1. does not work, or you want to use a non-standard MPI, try adding -DMPI_ROOT=/path/to/my/mpi in addition to -Dwith-mpi=ON. The path should point to the directory containing the include, lib, and bin subdirectories of the MPI installation.
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 simulations 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 enabling it with -Dwith-sionlib=ON when calling cmake, you can enable the recording backend for binary files, which solves this problem. To use a non-standard SIONlib installation, also set -DSIONlib_ROOT=/path/to/sionlib.

In order to run the distributed tests upon make installcheck, NEST needs to know how to execute the launcher of your MPI implementation. CMake is usually able to detect the command line for this, but you can customize it using the following configuration variables (common defaults are shown below):

-DMPIEXEC=/usr/bin/mpirun
-DMPIEXEC_NUMPROCS_FLAG=-np
-DMPIEXEC_PREFLAGS=
-DMPIEXEC_POSTFLAGS=

The final command line is composed in the following way:

$MPIEXEC $MPIEXEC_NUMPROC_FLAG <np> $MPIEXEC_PREFLAGS <prog> $MPIEXEC_POSTFLAGS <args>

For details on setting specific flags for your MPI launcher command, see the CMake documentation.

See the Guide to parallel computing to learn how to execute threaded and distributed simulations with NEST.

Python Binding (PyNEST)¶

Python 3.10 or later is required; NEST always builds PyNEST. cmake autodetects your Python installation. If it picks the wrong interpreter — for example in an environment with multiple Python versions — you can steer it with the standard CMake variable:

-DPython_EXECUTABLE=/path/to/python3

Cython 3.0 or later is also required and must be installed in the same environment as the Python interpreter.

In special cases you may want to run cython outside the NEST build process to generate nestkernel_api.cxx and pass the result in directly. To do so, supply the full path to the file:

-DNESTKERNEL_API_CXX=/path/to/nestkernel_api.cxx

When this variable is set, Cython does not need to be installed. If the file is not yet present at CMake configure time (e.g. because it will be generated by a preceding build step), CMake will warn but not abort; the build will fail at compile time if the file is still missing then. By default (NESTKERNEL_API_CXX not set), Cython runs during the build process to create nestkernel_api.cxx.

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, NEST passes -fp-model strict to the Intel C++ compiler by default. This behaviour is controlled by:

-Dwith-intel-compiler-strict-math=[OFF|ON]   (default: ON)

Portland compiler¶

Use the -Kieee flag to ensure that computations obey the IEEE754 standard for floating point numerics.

`-Dwith-music=[OFF\|ON]`	Build with MUSIC [default=OFF]. MUSIC enables multi-simulator coupling, allowing NEST to exchange spikes, continuous data, and messages with other simulators at runtime. Requires `-Dwith-mpi=ON`. To pin a specific installation, set `-DMusic_ROOT=/path/to/music`.
`-Dwith-sionlib=[OFF\|ON]`	Build with SIONlib [default=OFF]. SIONlib provides a high-performance binary recording backend for large-scale distributed simulations. Requires `-Dwith-mpi=ON`. To pin a specific installation, set `-DSIONlib_ROOT=/path/to/sionlib`.
`-Dwith-boost=[OFF\|ON]`	Build with Boost [default=ON]. Boost is used for high-performance sorting of connections (`boost::sort::spreadsort`), for type name introspection in error messages, and for special math functions in the `iaf_bw_2001` neuron model. Without Boost, sorting performance may be reduced and the `iaf_bw_2001` model will not be available. To pin a specific installation, set `-DBoost_ROOT=/path/to/boost`.
`-Dwith-ltdl=[OFF\|ON]`	Build with ltdl library [default=ON]. NEST uses ltdl for dynamic loading of external user modules. Does not work with `-Dwith-static-linking=ON`. To pin a specific installation, set `-DLTDL_ROOT=/path/to/ltdl`.
`-Dwith-gsl=[OFF\|ON]`	Build with the GSL library [default=ON]. GSL is required for neuron models that use the GSL ODE solver for adaptive-step numerical integration, including the conductance-based `iaf_cond_`, `aeif_cond_`, `gif_cond_`, `glif_cond`, and Hodgkin-Huxley (`hh_`) variants, as well as `ht_neuron`, `siegert_neuron`, and several `aeif_psc_` and `hh_psc_` models. Without GSL, these 31 models will not be available. To pin a specific installation, set `-DGSL_ROOT=/path/to/gsl`.
`-Dwith-hdf5=[OFF\|ON]`	Build with HDF5 library [default=OFF]. HDF5 is required for SONATA support, see NEST SONATA guide. Note that the Python packages `h5py` and `pandas` are also required at runtime for SONATA functionality. To pin a specific installation, set `-DHDF5_ROOT=/path/to/hdf5`.