Merge pull request #3 from nest/master

Remove _t from datatypes

Author: hesam-setareh

CMakeLists.txt

@@ -28,7 +28,7 @@ set( NEST_USER_EMAIL "nest_user@nest-initiative.org" )
 
 # VERSION exported to libnestutil/config.h, extras/create_release.sh
 set( NEST_VERSION_MAJOR 2 )
-set( NEST_VERSION_MINOR 10 )
+set( NEST_VERSION_MINOR 11 )
 set( NEST_VERSION_PATCHLEVEL 0 )
 
 set( NEST_VERSION_VERSION "${NEST_VERSION_MAJOR}.${NEST_VERSION_MINOR}.${NEST_VERSION_PATCHLEVEL}" )

INSTALL

@@ -5,7 +5,7 @@ http://www.nest-simulator.org/installation
 Introduction
 ============
 
-NEST is installed with cmake (at least v2.8.12). In the simplest case, the commands
+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
@@ -14,6 +14,12 @@ NEST is installed with cmake (at least v2.8.12). In the simplest case, the comma
 should build and install NEST to <install-path>. Detailed installation 
 instructions can be found below.
 
+Choice of CMake Version
+=======================
+
+We recommend to use `cmake` v3.4, 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
 ==================
@@ -72,11 +78,12 @@ Set default libraries:
     -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]
+    -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.
@@ -85,13 +92,13 @@ Set default libraries:
 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
+    -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;off;flags>]  Enable user defined warnings. Separate
+    -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;off;flags>]    Enable user defined debug flags. Separate
+    -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.
@@ -115,34 +122,77 @@ Configuring NEST for Distributed Simulation with MPI
      -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
+    -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`.
 
-as 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 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
+    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:
+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
 
@@ -151,20 +201,66 @@ 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
+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:
-
-    # 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
+```
+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.
 
 Compiling for Fujitsu Sparc64
 =============================
@@ -189,25 +285,25 @@ On the K Computer:
       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
+      ../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
+      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

README.md

@@ -140,6 +140,10 @@ Here is a suitable BibTeX entry:
 }
 ```
 
+If you use  NEST v2.8.0, please cite it as `Eppler, Jochen Martin et al. (2015).
+NEST 2.8.0. Zenodo. 10.5281/zenodo.32969`. The full citation is available in
+different formats on [Zenodo](http://dx.doi.org/10.5281/zenodo.32969).
+
 For all other versions below NEST v2.8.0 please use: [Gewaltig M-O & Diesmann M
 (2007) NEST (Neural Simulation Tool) Scholarpedia
 2(4):1430](http://www.scholarpedia.org/article/NEST_(Neural_Simulation_Tool)).

cmake/Platform/BlueGeneQ_XLC.cmake

@@ -35,7 +35,7 @@ set( CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O2 -g -qarch=qp -qtune=qp -DNDEBUG" CACHE
 set( OpenMP_C_FLAGS "-qsmp=omp" CACHE STRING "Compiler flag for OpenMP parallelization" FORCE )
 set( OpenMP_CXX_FLAGS "-qsmp=omp" CACHE STRING "Compiler flag for OpenMP parallelization" FORCE )
 
-set( with-warning "-qinfo=all" CACHE STRING "Enable user defined warnings. [default ON, when ON, defaults to '-Wall']" FORCE )
+set( with-warning "-qinfo=all" CACHE STRING "Enable user defined warnings. [default ON, when ON, defaults to '-Wall']" )
 
 if ( static-libraries )
   __bluegeneq_setup_static( XL CXX )

cmake/ProcessOptions.cmake

@@ -338,21 +338,26 @@ endfunction()
 function( NEST_PROCESS_WITH_PYTHON )
   # Find Python
   set( HAVE_PYTHON OFF PARENT_SCOPE )
-  if ( with-python )
-    if ( NOT ${with-python} STREQUAL "ON" )
-      # a path is set
-      set( PYTHON_EXECUTABLE ${with-python} )
+  if ( ${with-python} STREQUAL "ON" OR  ${with-python} STREQUAL "2" OR  ${with-python} STREQUAL "3" )
+
+    # Localize the Python interpreter
+    if ( ${with-python} STREQUAL "ON" )
+      find_package( PythonInterp )
+    elseif ( ${with-python} STREQUAL "2" )  
+      find_package( PythonInterp 2 REQUIRED )
+    elseif ( ${with-python} STREQUAL "3" )
+      find_package( PythonInterp 3 REQUIRED )
     endif ()
 
-    find_package( PythonInterp )
     if ( PYTHONINTERP_FOUND )
       set( PYTHONINTERP_FOUND "${PYTHONINTERP_FOUND}" PARENT_SCOPE )
       set( PYTHON_EXECUTABLE ${PYTHON_EXECUTABLE} PARENT_SCOPE )
       set( PYTHON ${PYTHON_EXECUTABLE} PARENT_SCOPE )
       set( PYTHON_VERSION ${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR} PARENT_SCOPE )
 
-      # need python lib and header...
-      find_package( PythonLibs )
+      # Localize Python lib/header files and make sure that their version matches 
+      # the Python interpreter version !
+      find_package( PythonLibs ${PYTHON_VERSION_STRING} EXACT )
       if ( PYTHONLIBS_FOUND )
         set( HAVE_PYTHON ON PARENT_SCOPE )
         # export found variables to parent scope
@@ -377,10 +382,12 @@ function( NEST_PROCESS_WITH_PYTHON )
             set( CYTHON_VERSION "${CYTHON_VERSION}" PARENT_SCOPE )
           endif ()
         endif ()
-
         set( PYEXECDIR "${CMAKE_INSTALL_LIBDIR}/python${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR}/site-packages" PARENT_SCOPE )
       endif ()
     endif ()
+  elseif ( ${with-python} STREQUAL "OFF" )
+  else ()
+    message( FATAL_ERROR "Invalid option: -Dwith-python=" ${with-python} )
   endif ()
 endfunction()