Modernize random number generator setup

CMakeLists.txt

@@ -175,6 +175,7 @@ nest_check_have_stl_vector_capacity_doubling()
 nest_check_have_xlc_ice_on_using()
 nest_check_have_std_nan()
 nest_check_have_std_isnan()
+nest_check_random123()
 
 ################################################################################
 ##################           Create version string            ##################
@@ -224,11 +225,11 @@ add_subdirectory( examples )
 add_subdirectory( extras )
 add_subdirectory( lib )
 add_subdirectory( libnestutil )
-add_subdirectory( librandom )
 add_subdirectory( models )
 add_subdirectory( sli )
 add_subdirectory( nest )
 add_subdirectory( nestkernel )
+add_subdirectory( thirdparty )
 add_subdirectory( testsuite )
 if ( HAVE_PYTHON )
   add_subdirectory( pynest )
@@ -275,7 +276,6 @@ endforeach ()
 set( ALL_LIBS
   "-lnestutil"
   "-lnest"
-  "-lrandom"
   "-lsli"
   "-lnestkernel"
   "${OpenMP_CXX_FLAGS}"

cmake/CheckExtraCompilerFeatures.cmake

@@ -244,3 +244,24 @@ function( NEST_CHECK_HAVE_STD_ISNAN )
   set( HAVE_STD_ISNAN ${HAVE_STD_ISNAN} PARENT_SCOPE )
   message( STATUS "Check if ::isnan is available from cmath. ${HAVE_STD_ISNAN}" )
 endfunction()
+
+####### Test if Random123 generators work #######
+function( NEST_CHECK_RANDOM123 )
+  message( STATUS "Check if Random123 generators work." )
+  try_run( RUN_RESULT COMPILE_RESULT
+      ${CMAKE_BINARY_DIR}
+      ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/Random123/tests/kat_cpp.cpp
+      CMAKE_FLAGS -DINCLUDE_DIRECTORIES=${CMAKE_CURRENT_SOURCE_DIR}/thirdparty
+      COMPILE_OUTPUT_VARIABLE COMPILE_OUTPUT
+      RUN_OUTPUT_VARIABLE RUN_OUTPUT
+      ARGS ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/Random123/tests/kat_vectors
+      )
+  if ( ${COMPILE_RESULT} AND ${RUN_RESULT} EQUAL 0 )
+    set( HAVE_RANDOM123 ON )
+  else ()
+    message( ${RUN_OUTPUT} )
+    set( HAVE_RANDOM123 OFF )
+  endif ()
+  set( HAVE_RANDOM123 ${HAVE_RANDOM123} PARENT_SCOPE )
+  message( STATUS "Check if Random123 generators work. ${HAVE_RANDOM123}" )
+endfunction()

doc/fulldoc.conf.in

@@ -749,7 +749,6 @@ INPUT		=	@PROJECT_SOURCE_DIR@/README.md \
 			@PROJECT_SOURCE_DIR@/extras \
 			@PROJECT_SOURCE_DIR@/lib \
 			@PROJECT_SOURCE_DIR@/libnestutil \
-			@PROJECT_SOURCE_DIR@/librandom \
 			@PROJECT_SOURCE_DIR@/models \
 			@PROJECT_SOURCE_DIR@/nest \
 			@PROJECT_SOURCE_DIR@/nestkernel \

doc/guides/nest2_to_nest3/nest2_to_nest3_detailed_transition_guide.rst

@@ -304,6 +304,30 @@ Functions related to models
 No Change
 
 
+Functions related to random number generators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In NEST 2.x, you would have to set a global seed and individual seeds for each virtual process manually.
+In NEST 3.0, you set only a single `rng_seed`, which is used as a base for all other seeds.
+
++-------------------------------------------------+----------------------------------------------------------------+
+| NEST 2.x                                        | NEST 3.0                                                       |
++=================================================+================================================================+
+| nest.SetKernelStatus({’grng_seed’ : msd+N_vp})  | nest.SetKernelStatus({'rng_seed': msd})                        |
++-------------------------------------------------+                                                                |
+| nest.SetKernelStatus({’rng_seeds’ : range(      |                                                                |
+| msd+N_vp+1, msd+2*N_vp+1)})                     |                                                                |
+|                                                 |                                                                |
++-------------------------------------------------+----------------------------------------------------------------+
+| nest.ll_api.sli_func('rngdict keys')            | nest.GetKernelStatus('rng_types')                              |
+|                                                 |                                                                |
++-------------------------------------------------+----------------------------------------------------------------+
+| nest.ll_api.sli_run('0 << /grng                 | nest.SetKernelStatus({'rng_type': 'mt19937', 'rng_seed': 101}) |
+| rngdict/MT19937 :: 101 CreateRNG >> SetStatus') |                                                                |
+|                                                 |                                                                |
++-------------------------------------------------+----------------------------------------------------------------+
+
+
 Functions related to parallel computing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/guides/nest2_to_nest3/nest2_to_nest3_overview.rst

@@ -360,7 +360,7 @@ Dictionary with lists when setting parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is now possible to use a dictionary with lists when setting node parameters
-with ``Create()``, ``set()`` or ``SetStatus()``. The values of the lists will 
+with ``Create()``, ``set()`` or ``SetStatus()``. The values of the lists will
 be distributed across the nodes. The way to do this previously was to apply a
 list of dictionaries. This is still possible.
 
@@ -1505,6 +1505,67 @@ All details about the new infrastructure can be found in the guide on
 :doc:`recording from simulations <recording_from_simulations>`.
 
 
+Simpler handling of random number generators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All random number generators managed by the NEST kernel are now seeded by
+providing a single seed :math:`s`  with :math:`1\leq s \leq 2^{31}-1`. The
+kernel automatically seeds the random number streams on the various parallel
+processes:
+
+  +---------------------------------------------+---------------------------------------+
+  | NEST 2.x                                    | NEST 3.0                              |
+  +=============================================+=======================================+
+  |                                             |                                       |
+  | ::                                          | ::                                    |
+  |                                             |                                       |
+  |     msd = n_threads * seed + 1              |     nest.SetKernelStatus({            |
+  |     nest.SetKernelStatus({                  |                    'rng_seed': seed}) |
+  |        'grng_seed': msd,                    |                                       |
+  |        'rng_seeds': range(msd+1,            |                                       |
+  |                           msd+1+n_threads)  |                                       |
+  |        })                                   |                                       |
+  |                                             |                                       |
+  +---------------------------------------------+---------------------------------------+
+
+Changing the type of random number generator to use is easy now:
+
+  +---------------------------------------------+---------------------------------------+
+  | NEST 2.x                                    | NEST 3.0                              |
+  +=============================================+=======================================+
+  |                                             |                                       |
+  | ::                                          | ::                                    |
+  |                                             |                                       |
+  |     # too difficult to show here            |     nest.SetKernelStatus({            |
+  |                                             |               'rng_type': 'mt19937'}) |
+  |                                             |                                       |
+  +---------------------------------------------+---------------------------------------+
+
+Which random number generator types are available can be checked by:
+
+::
+
+    nest.GetKernelStatus('rng_types')
+
+Details about the new random number generators can be found in the guide on :doc:`random number generators<../random_numbers>`.
+
+Counter-based random number generators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In addition to the conventional random number generator types, there is added support for
+"counter-based" random number generators (CBRNGs) with the Random123 library. Where
+conventional RNGs use N iterations of a stateful transformation to find the Nth random
+number, the Nth random number of a CBRNG can be obtained by applying a stateless mixing
+function to N.
+
+The Random123 library is included in NEST, and random number generator types like Philox and
+Threefry are automatically made available.
+
+.. note::
+
+   On some systems or with some compilers, the CBRNGs may not give reliable results. In these
+   cases, they are automatically disabled during compilation and will not be available.
+
+
 What's removed?
 ---------------