Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

exascale-brainsim/tips-on-nest.md

Go to file
 
 
Cannot retrieve contributors at this time
Tips on NEST Preparations Build from Source Errors During Build Debugging the NEST Project How to Add New Code to NEST
142 lines (110 sloc) 8.79 KB
Raw Blame
Open in GitHub Desktop

Tips on NEST

This document contains tips on how to build, install, and modify the source of the NEST project. NEST is written in C++ and wonderfully documented.

Preparations

I am assuming that the reader wants to research/understand how NEST works.

You must have a Linux/Mac system having GCC-toolchain. On Windows machines, I recommend installing Ubuntu 12.10 with Wubi.

When your Linux system is up and running, do the following:

  • Have GCC version >= 4.7.2.
  • Install Python, and make sure it is compiled with the same version of GCC that you have. When you run Python from shell, it tells which GCC was used to compile it.
  • Along with Python, it is recommended that you have Cython, NumPy, SciPy, and Matplotlib installed.
  • Have GSL (GNU Scientific Library) installed.
  • Have your favorite MPI library (e.g., OpenMPI) installed.
  • Have GNU Autotools, Autoconf, and Automake installed.
  • Have doxygen installed.

Create a virtual environment for experimenting with NEST. For example, on my machine I created the directory /home/saad/venv and inside that I created the virtual environment nest-dbg. You can use pyvenv for this purpose. A virtual environment is nothing but a directory containing a copy of a Python distribution. When you create a virtual environment, your currently active python gets copied to that location. That way, when you activate this virtual environment, this directory will be placed at the beginning of your PATH environment variable and anyone looking for the program python will find this Python even if there are other Python versions present in your system.

Create a new directory called nest. Then, download the latest version of NEST source code. and extract the source inside this directory. This should add the subdirectory nest-2.6.0 inside the nest directory assuming you downloaded nest-2.6.0.

I recommend you add this folder in a version control system, such as git.

Build from Source

  • Inside the nest directory, create a directory build. Now, the nest directory contains two subdirectories: nest-2.6.0 and build.
  • First, we need to figure out where the NEST will be installed. This is called the prefix directory. This should be the virtual environment we created for NEST in the preparation step. In my case, the prefix is /home/saad/venv/nest-dbg.
  • Now we need to know which options shall we use to build NEST. For our purpose, we must use MPI and OpenMP, use debugging enabled without any optimization. Together with prefix, our configuration options are as follows: --prefix=/home/saad/venv/nest-dbg --with-mpi --with-openmp --with-debug --with-optimize=-O0.
  • If you want to build without Python support, you should add the option --without-python to the above.
  • Open a command window (shell). Then activate our virtual environment by the command /home/saad/venv/nest-dbg/bin/activate. This makes our Python available to for the NEST installation. From now on, whenever we are going to work with NEST, this environment must be activated.
  • In the shell, type cd /home/saad/nest/build. Now we are inside the build directory.
  • Now we should configure NEST, by typing ../nest-2.6.0/configure --prefix=/home/saad/venv/nest-dbg --with-mpi --with-openmp --with-debug --with-optimize=-O0 | tee nest-configure.out. configure is a shell script in the NEST distribution which examines your system and create necessary Makefiles inside the build directory. The program tee is used to show us the output of the configure script while also saving the output to the file nest-configure.out.
  • Examine the last bits of the above output. If everything is fine, it should tell something like the following:
--------------------------------------------------------------------------------
NEST Configuration Summary
--------------------------------------------------------------------------------

C compiler          : gcc
C compiler flags    : -W -Wall -pedantic -Wno-long-long -g -O0 -g -O2 -fopenmp
C++ compiler        : mpicxx
C++ compiler flags  : -W -Wall -pedantic -Wno-long-long -g -O0 -fopenmp

Python bindings     : Yes (Python 3.4: /home/saad/venv/nest-dbg/bin/python)
User modules        : None
Extra modules       : models precise topology
Dynamic modules     : None

Use threading       : Yes (OpenMP)

Use GSL             : Yes
Use MPI             : Yes
Use MUSIC           : No
Use libneurosim     : No

--------------------------------------------------------------------------------

The NEST executable will be installed to:
  /home/saad/venv/nest-dbg/bin/

Documentation and examples will be installed to:
  /home/saad/venv/nest-dbg/share/doc/nest/

PyNEST will be installed to:
  /home/saad/venv/nest-dbg/lib/python3.4/site-packages

To set necessary environment variables, add the following line
to your ~/.bashrc :
  source /home/saad/venv/nest-dbg/bin/nest_vars.sh

--------------------------------------------------------------------------------

You can now build and install NEST with
  make
  make install
  make installcheck
  • It is important to check that the NEST is going to be installed in the location we want (in our virtual environment), and that it has detected MPI, OpenMP, Python and GSL. If something is wrong/missing, NEST will tell you and you should fix these before you proceed.
  • Now we are ready to build (make) NEST from source. In the shell, just write make, and hope that everything will be fine. If there are no error messages, you have successfully built NEST from source. The binaries (executables and libraries) are still inside the build directory.
  • In the shell, type make install. The executables/libraries will now be copied to the prefix directory we specified during running the configure script.
  • You can now type nest and if everything was alright, you should see the following prompt:
saad@ubuntu:~/nest/build-2.6.0-gpu/nest$ ./nest

              -- N E S T --
  Copyright (C) 2004 The NEST Initiative
  Version 2.6.0 Jan 22 2015 00:42:35

This program is provided AS IS and comes with
NO WARRANTY. See the file LICENSE for details.

Problems or suggestions?
  Website     : http://www.nest-initiative.org
  Mailing list: nest_user@nest-initiative.org

Type 'help' to get more information.
Type 'quit' or CTRL-D to quit NEST.
SLI ]

SLI means Simulation Language Interface, which is NEST's interactive command prompt. You can type quit and the program will exit. You can also try examples from the NEST documentation.

Errors During Build

Here is a possible linking error during building NEST.

A linking error:

Error Details:

  • Linker Error Message: "Undefined reference to Time::LimitPosInf::tics in Time::Time(...)". The same happened also with Time::LimitNegInf on all constructors Time::Time(...) for members tics and delays.
  • While Linking: libnest.la
  • Error at Source File: nestkernel/nest_time.h (Time constructors)
  • Consequences: Build failed

Reason of the linker error: The error happened because the class Time::LimitPosInf (likewise, Time::LimitNegInf) has static const members. However, although similar static const members of Time::Range had been defined in nest_time.cpp, the static const members of Time::LimitPosInf (likewise, Time::LimitNegInf) were not defined in the cpp file.

See http://stackoverflow.com/questions/272900/vectorpush-back-odr-uses-the-value-causing-undefined-reference-to-static-clas

Resolution: After adding the following code in nestkernel/nest_time.cpp (at line 58), the linker errors were resolved and the build succeeded.

const tic_t  Time::LimitPosInf::tics;
const delay  Time::LimitPosInf::steps;
const tic_t  Time::LimitNegInf::tics;
const delay  Time::LimitNegInf::steps;

Debugging the NEST Project

You can set up a project with your favourite IDE (e.g., NetBeans or Eclipse) and create a C++ project with existing source from the nest/nest-2.6.0 directory. Because we have built NEST with debug information, you will be use your IDE's debugging facilities.

How to Add New Code to NEST

See Adding New Code to NEST.