Provisional: extensible random generators and splitting for Gecode 7 (breaking changes)

CMakeLists.txt

@@ -98,6 +98,13 @@ option(GECODE_BUILD_SHARED "Build shared libraries" ${GECODE_BUILD_SHARED_DEFAUL
 option(GECODE_BUILD_STATIC "Build static libraries" ${GECODE_BUILD_STATIC_DEFAULT})
 
 option(GECODE_ENABLE_THREAD "Enable thread support" ON)
+set(GECODE_RANDOM_ENGINE "splitmix" CACHE STRING "Default random engine (splitmix or xorshift64star)")
+set_property(CACHE GECODE_RANDOM_ENGINE PROPERTY STRINGS splitmix xorshift64star)
+if(GECODE_RANDOM_ENGINE STREQUAL "xorshift64star")
+  set(GECODE_RANDOM_XORSHIFT64STAR 1)
+elseif(NOT GECODE_RANDOM_ENGINE STREQUAL "splitmix")
+  message(FATAL_ERROR "GECODE_RANDOM_ENGINE must be splitmix or xorshift64star")
+endif()
 set(GECODE_ENABLE_QT "AUTO" CACHE STRING "Enable Qt support (AUTO, ON, or OFF)")
 set_property(CACHE GECODE_ENABLE_QT PROPERTY STRINGS AUTO ON OFF)
 set(GECODE_ENABLE_GIST_DEFAULT AUTO)
@@ -1399,6 +1406,29 @@ if(BUILD_TESTING)
       list(APPEND GECODE_TEST_LINK_LIBS gecodeflatzinc)
     endif()
     target_link_libraries(gecode-test PRIVATE ${GECODE_TEST_LINK_LIBS})
+    add_executable(gecode-random-replay EXCLUDE_FROM_ALL
+      test/test.cpp test/random-replay.cpp)
+    target_link_libraries(gecode-random-replay PRIVATE ${GECODE_TEST_LINK_LIBS})
+    add_dependencies(gecode-test gecode-random-replay)
+    add_test(NAME random-state-replay
+      COMMAND ${CMAKE_COMMAND} -DREPLAY=$<TARGET_FILE:gecode-random-replay>
+        -P ${CMAKE_CURRENT_SOURCE_DIR}/test/random-replay.cmake)
+    set_tests_properties(random-state-replay PROPERTIES
+      FIXTURES_REQUIRED gecode-test-built)
+    if(GECODE_ENABLE_DRIVER)
+      add_executable(gecode-random-options EXCLUDE_FROM_ALL test/random-options.cpp)
+      target_link_libraries(gecode-random-options PRIVATE gecodedriver ${GECODE_TEST_LINK_LIBS})
+      if(GECODE_ENABLE_FLATZINC)
+        target_compile_definitions(gecode-random-options PRIVATE TEST_RANDOM_FLATZINC)
+      endif()
+      add_dependencies(gecode-test gecode-random-options)
+      add_test(NAME random-options
+        COMMAND ${CMAKE_COMMAND} -DOPTIONS=$<TARGET_FILE:gecode-random-options>
+          -DFLATZINC=${GECODE_ENABLE_FLATZINC}
+          -P ${CMAKE_CURRENT_SOURCE_DIR}/test/random-options.cmake)
+      set_tests_properties(random-options PROPERTIES
+        FIXTURES_REQUIRED gecode-test-built)
+    endif()
     if(GECODE_ENABLE_FAULT_INJECTION)
       add_executable(gecode-fault-test EXCLUDE_FROM_ALL
         ${GECODE_FAULT_TEST_SOURCES})
@@ -1418,6 +1448,9 @@ if(BUILD_TESTING)
     endif()
 
     set(GECODE_CHECK_TESTS
+      Random::Contract
+      Random::BranchReplay
+      Random::CommitBoundary
       Branch::Int::Dense::3
       Int::Arithmetic::Abs
       Int::Arithmetic::ArgMax

Makefile.in

@@ -201,7 +201,6 @@ VARIMP = $(VARIMPHDR)
 
 KERNELSRC0 = \
 	archive core exception gpi \
-	data/rnd \
 	branch/action branch/afc branch/chb branch/function \
 	memory/manager memory/region \
 	trace/recorder trace/filter trace/tracer trace/general \
@@ -896,7 +895,7 @@ INTEXAMPLEHDR0 =						\
 INTEXAMPLESRC0 =						\
 	alpha bacp bibd donald efpa eq20 golomb-ruler		\
 	graph-color grocery ind-set magic-sequence magic-square	\
-	money ortho-latin partition photo queens sudoku sudoku-advanced kakuro  \
+	money ortho-latin partition photo queens random-engine sudoku sudoku-advanced kakuro  \
 	nonogram pentominoes crowded-chess black-hole		\
 	minesweeper domino steel-mill sports-league		\
 	all-interval langford-number warehouses	radiotherapy    \
@@ -1276,7 +1275,7 @@ BLACKBOXEXECSRC = test/flatzinc/blackbox-exec.cpp
 BLACKBOXDLLSRC = test/flatzinc/blackbox-dll.cpp
 BLACKBOXSRC = $(BLACKBOXEXECSRC) $(BLACKBOXDLLSRC)
 
-TESTSRC0 = test/test.cpp test/afc.cpp test/ldsb.cpp test/region.cpp \
+TESTSRC0 = test/test.cpp test/afc.cpp test/ldsb.cpp test/region.cpp test/random.cpp \
 	test/groups.cpp
 # FailPoint is CMake-only; keep the Autoconf test executable fault-free.
 
@@ -1345,6 +1344,7 @@ test: mkcompiledirs $(BLACKBOXFIXTURES)
 	@$(MAKE) $(VARIMP) $(TESTEXE)
 
 CHECKTESTS = Branch::Int::Dense::3 \
+	Random::Contract Random::BranchReplay Random::CommitBoundary \
 	FlatZinc::magic_square \
 	Int::Arithmetic::Abs \
 	Int::Arithmetic::ArgMax \

changelog.in

@@ -67,6 +67,34 @@
 #    optional section in the html page.
 #
 
+[RELEASE]
+Version: 7.0.0
+Date: unreleased
+[DESCRIPTION]
+Development changes for Gecode 7; source, binary, and seeded-sequence
+compatibility with Gecode 6 is not preserved.
+
+[ENTRY]
+Module: kernel
+What:   new
+Rank:   major
+[DESCRIPTION]
+Added modern, user-extensible random number generators with reproducible
+stream splitting. Splittable SplitMix replaces the old default generator;
+xorshift64* is available as a smaller-state alternative. The default is
+configurable at build time, and users can supply their own engines.
+Randomized branching splits the recorded generator state by alternative,
+giving distinct successor states that are reproduced during recomputation.
+Complete-state save/restore and command-line state input support exact replay,
+including test failures.
+[MORE]
+Generators store their compact state directly in their consumers, and copying
+a generator produces independent state. Drivers accept checked 64-bit seeds
+as well as complete state. APIs, seeded sequences, and randomized choice
+archives change; no legacy sequence mode is provided. This design remains
+provisional for a future breaking-change release. See docs/random.md for
+engine contracts, migration, and measured costs.
+
 [RELEASE]
 Version: 6.5.0
 Date: unreleased

cmake/GecodeSources.cmake

@@ -19,7 +19,6 @@ set(GECODE_KERNEL_SOURCES
   gecode/kernel/branch/function.cpp
   gecode/kernel/core.cpp
   gecode/kernel/data/array.cpp
-  gecode/kernel/data/rnd.cpp
   gecode/kernel/exception.cpp
   gecode/kernel/gpi.cpp
   gecode/kernel/memory/manager.cpp
@@ -411,6 +410,7 @@ set(GECODE_TEST_SOURCES
   test/ldsb.cpp
   test/nogoods.cpp
   test/region.cpp
+  test/random.cpp
   test/search.cpp
   test/set.cpp
   test/set/channel.cpp

configure

@@ -821,6 +821,7 @@ SHELL'
 ac_subst_files=''
 ac_user_opts='
 enable_option_checking
+with_random_engine
 with_host_os
 with_compiler_vendor
 enable_resource
@@ -1546,6 +1547,9 @@ Optional Features:
 Optional Packages:
   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
   --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
+  --with-random-engine=ENGINE
+                          default random engine: splitmix (default) or
+                          xorshift64star
   --with-host-os          Override operating system test. Valid values are
                           Linux, Darwin, FreeBSD, NetBSD, and Windows.
   --with-compiler-vendor  Override compiler test. Valid values are gnu, intel,
@@ -3280,6 +3284,27 @@ ac_config_headers="$ac_config_headers gecode/support/config.hpp"
 
 
 
+
+# Check whether --with-random-engine was given.
+if test ${with_random_engine+y}
+then :
+  withval=$with_random_engine;
+else case e in #(
+  e) with_random_engine=splitmix ;;
+esac
+fi
+
+case $with_random_engine in #(
+  splitmix) :
+     ;; #(
+  xorshift64star) :
+
+printf "%s\n" "#define GECODE_RANDOM_XORSHIFT64STAR 1" >>confdefs.h
+ ;; #(
+  *) :
+    as_fn_error $? "random engine must be splitmix or xorshift64star" "$LINENO" 5 ;;
+esac
+
 ac_gecode_soversion=51
 GECODE_SOVERSION=${ac_gecode_soversion}
 

configure.ac

@@ -41,6 +41,16 @@ AC_INIT([GECODE], GECODE_M4_VERSION, [users@gecode.dev])
 AC_CONFIG_HEADERS([gecode/support/config.hpp])
 AC_CONFIG_SRCDIR(gecode/kernel.hh)
 
+AC_ARG_WITH([random-engine],
+  [AS_HELP_STRING([--with-random-engine=ENGINE],
+    [default random engine: splitmix (default) or xorshift64star])],
+  [], [with_random_engine=splitmix])
+AS_CASE([$with_random_engine],
+  [splitmix], [],
+  [xorshift64star], [AC_DEFINE([GECODE_RANDOM_XORSHIFT64STAR], [1],
+    [Use xorshift64* instead of splittable SplitMix as the default random engine.])],
+  [AC_MSG_ERROR([random engine must be splitmix or xorshift64star])])
+
 ac_gecode_soversion=GECODE_M4_SOVERSION
 AC_SUBST(GECODE_SOVERSION, ${ac_gecode_soversion})