Add experimental A* and CABS search for Gecode 6.5

.github/ci/generated-source-freshness.sh

@@ -225,7 +225,7 @@ normalize_generated_whitespace() {
   # Ignore any autom4te cache so output matches a clean source release.
   autoconf --force
   # Autoconf 2.72 appends blank lines after the generated script body; source
-  # releases retain exactly one final newline.
+  # releases have exactly one final newline.
   normalize_generated_whitespace configure
   uv run --script ./misc/genvarimp.py -typehpp "${vis_files[@]}" \
     > gecode/kernel/var-type.hpp

.github/workflows/build.yml

@@ -69,7 +69,7 @@ jobs:
 
     - name: Configure
       shell: bash
-      run: ./configure
+      run: ./configure --enable-experimental
 
     - name: Build
       shell: bash
@@ -220,6 +220,7 @@ jobs:
       shell: bash
       run: >
         cmake -S "$GITHUB_WORKSPACE" -B "$GITHUB_WORKSPACE/build-ninja"
+        -DGECODE_ENABLE_EXPERIMENTAL=ON
         -G Ninja
         -DCMAKE_BUILD_TYPE=$BUILD_TYPE
         -DGECODE_ENABLE_QT=OFF
@@ -402,6 +403,7 @@ jobs:
         -DGECODE_ENABLE_MPFR=OFF
         -DGECODE_BUILD_SHARED=${{ matrix.build_shared }}
         -DGECODE_BUILD_STATIC=${{ matrix.build_static }}
+        -DGECODE_ENABLE_EXPERIMENTAL=${{ matrix.build_shared }}
 
     - name: Build
       shell: pwsh
@@ -513,6 +515,7 @@ jobs:
           -DGECODE_ENABLE_MPFR=OFF \
           -DGECODE_BUILD_SHARED=OFF \
           -DGECODE_BUILD_STATIC=ON \
+          -DGECODE_ENABLE_EXPERIMENTAL=ON \
           -DGECODE_ENABLE_EXAMPLES=OFF \
           -DGECODE_ENABLE_FLATZINC=OFF
 
@@ -581,7 +584,7 @@ jobs:
       shell: msys2 {0}
       run: |
         export PATH="$UV_DIR:$PATH"
-        CC=gcc CXX=g++ ./configure --with-host-os=Windows --disable-qt --disable-gist --disable-mpfr
+        CC=gcc CXX=g++ ./configure --with-host-os=Windows --disable-qt --disable-gist --disable-mpfr --enable-experimental
 
     - name: Build
       shell: msys2 {0}

CMakeLists.txt

@@ -107,6 +107,7 @@ endif()
 set(GECODE_ENABLE_GIST "${GECODE_ENABLE_GIST_DEFAULT}" CACHE STRING "Enable Gist (AUTO, ON, or OFF)")
 set_property(CACHE GECODE_ENABLE_GIST PROPERTY STRINGS AUTO ON OFF)
 option(GECODE_ENABLE_CPPROFILER "Enable CPProfiler support" ON)
+option(GECODE_ENABLE_EXPERIMENTAL "Enable experimental preview APIs" OFF)
 option(GECODE_ENABLE_CBS "Enable counting-based search support" OFF)
 set(GECODE_ENABLE_EXAMPLES_DEFAULT ${PROJECT_IS_TOP_LEVEL})
 option(GECODE_ENABLE_EXAMPLES "Build examples" ${GECODE_ENABLE_EXAMPLES_DEFAULT})
@@ -691,6 +692,9 @@ endif()
 if(GECODE_ENABLE_CPPROFILER)
   set(GECODE_HAS_CPPROFILER "/**/")
 endif()
+if(GECODE_ENABLE_EXPERIMENTAL)
+  set(GECODE_HAS_EXPERIMENTAL "/**/")
+endif()
 if(GECODE_ENABLE_CBS)
   set(GECODE_HAS_CBS "/**/")
 endif()
@@ -1784,6 +1788,7 @@ include(FeatureSummary)
 foreach(gecode_option IN ITEMS
     GECODE_BUILD_SHARED GECODE_BUILD_STATIC
     GECODE_ENABLE_THREAD GECODE_ENABLE_CPPROFILER GECODE_ENABLE_CBS
+    GECODE_ENABLE_EXPERIMENTAL
     GECODE_ENABLE_EXAMPLES GECODE_INSTALL
     GECODE_ENABLE_SEARCH GECODE_ENABLE_INT_VARS GECODE_ENABLE_SET_VARS
     GECODE_ENABLE_FLOAT_VARS GECODE_ENABLE_MINIMODEL GECODE_ENABLE_DRIVER

Makefile.in

@@ -272,16 +272,20 @@ SEARCHHDR0 = \
 	support.hh worker.hh worker-control.hh exception.hpp engine.hpp base.hpp \
 	nogoods.hh nogoods.hpp build.hpp traits.hpp sebs.hpp \
 	seq/path.hh seq/path.hpp seq/dfs.hh seq/dfs.hpp \
-	seq/bab.hh seq/bab.hpp seq/lds.hh seq/lds.hpp \
-	seq/rbs.hh seq/rbs.hpp seq/dead.hh \
+	seq/bab.hh seq/bab.hpp seq/astar.hh seq/cabs.hh seq/lds.hh seq/lds.hpp \
+	seq/rbs.hh seq/rbs.hpp seq/dead.hh seq/choice-expansion.hh \
 	seq/pbs.hh seq/pbs.hpp \
 	par/path.hh par/path.hpp par/engine.hh par/engine.hpp \
 	par/dfs.hh par/dfs.hpp par/bab.hh par/bab.hpp \
 	par/pbs.hh par/pbs.hpp \
-	dfs.hpp bab.hpp lds.hpp rbs.hpp pbs.hpp \
+	dfs.hpp bab.hpp astar.hpp cabs.hpp lds.hpp rbs.hpp pbs.hpp \
 	relax.hh tracer.hpp trace-recorder.hpp \
 	cpprofiler/message.hpp cpprofiler/connector.hpp
 
+ifeq "@enable_experimental@" "yes"
+SEARCHSRC0 += astar cabs
+endif
+
 SEARCHSRC	= $(SEARCHSRC0:%=gecode/search/%.cpp)
 SEARCHHDR	= gecode/search.hh $(SEARCHHDR0:%=gecode/search/%)
 SEARCHOBJ	= $(SEARCHSRC:%.cpp=%$(OBJSUFFIX))
@@ -912,7 +916,12 @@ INTEXAMPLESRC0 =						\
 	qcp job-shop open-route common-pattern fifteen-puzzle
 
 
-INTEXAMPLEHDR  = $(INTEXAMPLEHDR0:%=examples/%.hpp)
+ifeq "@enable_experimental@" "yes"
+INTEXAMPLESRC0 += tsptw
+endif
+
+INTEXAMPLEHDR  = $(INTEXAMPLEHDR0:%=examples/%.hpp) \
+	examples/tsptw-data.hh examples/tsptw-transition.hh
 INTEXAMPLESRC  = $(INTEXAMPLESRC0:%=examples/%.cpp)
 ifeq "@enable_examples@" "yes"
 INSTALLEXAMPLEHDR = $(INTEXAMPLEHDR)

README.md

@@ -45,6 +45,7 @@ state.
 | `--enable-qt` | `GECODE_ENABLE_QT` | Supported directly | `AUTO` by default; Qt 6 preferred; Qt 5.15+ supported |
 | `--enable-gist` | `GECODE_ENABLE_GIST` | Supported directly | `AUTO` by default except macOS; disabled automatically if Qt GUI support is unavailable |
 | `--enable-cpprofiler` | `GECODE_ENABLE_CPPROFILER` | Supported directly | Default `ON` |
+| `--enable-experimental` | `GECODE_ENABLE_EXPERIMENTAL` | Supported directly | Default `OFF`; experimental 6.5.0 preview APIs |
 | `--enable-cbs` | `GECODE_ENABLE_CBS` | Supported directly | Default `OFF` |
 | `--enable-examples` | `GECODE_ENABLE_EXAMPLES` | Supported directly | Default `ON` for top-level builds, `OFF` for subprojects |
 | `--enable-search` | `GECODE_ENABLE_SEARCH` | Supported directly | Default `ON` |
@@ -117,6 +118,24 @@ build that supports the active macOS SDK; recent Qt 6 releases are the safest
 choice. Gist is opt-in for CMake builds on macOS. Use `-DGECODE_ENABLE_GIST=ON`
 when Qt is installed and its framework link interface is usable.
 
+## Experimental search preview
+
+Gecode 6.5.0 includes an opt-in preview of `AStar` and `CABS`, with bound/rank
+guidance. `AStar` offers bound-first and rank-first queue ordering.
+Enable it when building the library with `-DGECODE_ENABLE_EXPERIMENTAL=ON`
+for CMake or `--enable-experimental` for Autoconf. Both builds disable the
+preview by default. The installed configuration defines
+`GECODE_HAS_EXPERIMENTAL` only when the library includes these APIs.
+Applications can use this macro to check availability; defining it in an
+application does not enable the library feature.
+
+Experimental APIs may change or be removed in future feature releases.
+Their documented search correctness contracts still apply. Native preview
+engines work directly with ordinary `Space` subclasses and do not require
+Model or portfolio setup. The `fifteen-puzzle` and `tsptw` examples demonstrate
+the engines. Ordinary DFS/BAB and shared kernel/OpenCP APIs remain
+available independently of the preview option.
+
 ## CMake Package Consumption
 
 For CMake build/install workflows and downstream `find_package(Gecode)` usage,

changelog.in

@@ -56,6 +56,8 @@
 #     driver|iter|support|example|test|gist|flatzinc|other
 #   What:   bug|documentation|performance|new|removed|change
 #   Rank:   minor|major
+#   Experimental: true|false <optional, defaults to false>
+#     True entries appear under Experimental changes within each release.
 #   Bug:    <optional, for number from bugzilla>
 #   Issue:  <optional, for number from github>
 #   Thanks: <optional, who reported etc>
@@ -73,6 +75,20 @@ Date: unreleased
 [DESCRIPTION]
 This is the development changelog for the next Gecode release.
 
+[ENTRY]
+Module: search
+What:   new
+Rank:   major
+Experimental: true
+[DESCRIPTION]
+Add experimental AStar and CABS search for 6.5.0, with bound and rank guidance
+and optional rank-first ordering for AStar. Enable with
+--enable-experimental or GECODE_ENABLE_EXPERIMENTAL=ON; the preview is disabled
+by default. Preview APIs may change or be removed in future feature releases;
+their documented search correctness contracts still apply.
+CABS accepts an optional model-defined dominance predicate for live candidates
+in the next layer. The TSPTW transition example enables it by default for CABS.
+
 [ENTRY]
 Module: int
 What:   new
@@ -150,7 +166,7 @@ What:   performance
 Rank:   major
 [DESCRIPTION]
 Reduce construction memory for regular constraints by building the layered
-graph from sparse forward frontiers and retaining only backward co-reachable
+graph from sparse forward frontiers and including only backward co-reachable
 states. This avoids allocating one temporary state for every automaton state
 at every sequence position while preserving the persistent graph.
 
@@ -160,7 +176,7 @@ What:   new
 Rank:   major
 [DESCRIPTION]
 Add DFA::nfa factories for finite automata with nondeterministic transitions.
-The factories retain nondeterminism without determinization or minimization;
+The factories support nondeterminism without determinization or minimization;
 epsilon transitions are not supported. Regular propagation now preserves
 branching assigned prefixes when cloning such automata.
 
@@ -171,7 +187,7 @@ Rank:   major
 [DESCRIPTION]
 Add self-declared check, standard, and sweep tags to the public test harness.
 The standard check targets use a focused integrity selection, while standard
-testing retains broad coverage without the exhaustive multi-hour sweeps.
+testing provides broad coverage without the exhaustive multi-hour sweeps.
 
 [ENTRY]
 Module: test
@@ -228,7 +244,7 @@ Issue:  166
 Thanks: Mats Carlsson
 [DESCRIPTION]
 Fix domain-level global cardinality propagation losing solutions by counting
-assigned variables twice and retaining stale conflict marks when cardinality
+assigned variables twice and leaving stale conflict marks when cardinality
 bounds shrink.
 
 [ENTRY]

cmake/GecodeSources.cmake

@@ -51,6 +51,13 @@ set(GECODE_SEARCH_SOURCES
   gecode/search/worker-control.cpp
 )
 
+if(GECODE_ENABLE_EXPERIMENTAL)
+  list(APPEND GECODE_SEARCH_SOURCES
+    gecode/search/astar.cpp
+    gecode/search/cabs.cpp
+  )
+endif()
+
 set(GECODE_INT_SOURCES
   gecode/int/arithmetic.cpp
   gecode/int/arithmetic/mult.cpp

configure

@@ -680,6 +680,7 @@ HAVEFLEX
 enable_cpprofiler
 LINKCPPROFILER
 enable_cbs
+enable_experimental
 enable_gist
 enable_qt
 QTLIBS
@@ -859,6 +860,7 @@ with_mpfr_include
 with_mpfr_lib
 enable_qt
 enable_gist
+enable_experimental
 enable_cbs
 enable_cpprofiler
 enable_driver
@@ -1531,6 +1533,7 @@ Optional Features:
   --enable-qt             build with Qt support, requires Qt 5.15 or newer
                           [default=yes]
   --enable-gist           build Gecode Interactive Search Tool [default=yes]
+  --enable-experimental   build experimental preview APIs [default=no]
   --enable-cbs            build with support for counting-based search
                           [default=no]
   --enable-cpprofiler     build with support for CPProfiler [default=yes]
@@ -3407,6 +3410,8 @@ GECODE_SOVERSION=${ac_gecode_soversion}
 
 
 
+
+
 
 
 
@@ -13888,6 +13893,32 @@ printf "%s\n" "no" >&6; }
   fi
 
 
+  # Check whether --enable-experimental was given.
+if test ${enable_experimental+y}
+then :
+  enableval=$enable_experimental;
+else case e in #(
+  e) enable_experimental=no ;;
+esac
+fi
+
+  { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether to build experimental preview APIs" >&5
+printf %s "checking whether to build experimental preview APIs... " >&6; }
+  case $enable_experimental in #(
+  yes) :
+
+printf "%s\n" "#define GECODE_HAS_EXPERIMENTAL /**/" >>confdefs.h
+ ;; #(
+  no) :
+     ;; #(
+  *) :
+    as_fn_error $? "--enable-experimental accepts only yes or no" "$LINENO" 5 ;;
+esac
+  { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $enable_experimental" >&5
+printf "%s\n" "$enable_experimental" >&6; }
+
+
+
   # Check whether --enable-cbs was given.
 if test ${enable_cbs+y}
 then :

configure.ac

@@ -275,6 +275,7 @@ dnl ------------------------------------------------------------------
 AC_GECODE_MPFR
 AC_GECODE_QT
 AC_GECODE_GIST
+AC_GECODE_EXPERIMENTAL
 AC_GECODE_CBS
 AC_GECODE_CPPROFILER
 AC_GECODE_FLEXBISON

doxygen/doxygen.conf.in

@@ -1007,6 +1007,7 @@ PREDEFINED             = "GECODE_SET_EXPORT=" \
                          "GECODE_HAS_FLOAT_VARS=1" \
                          "GECODE_HAS_GIST=1" \
                          "GECODE_HAS_CPPROFILER=1" \
+                         "GECODE_HAS_EXPERIMENTAL=1" \
                          "GECODE_THREADS_PTHREADS=1" \
                          "GECODE_HAS_THREADS=1" \
                          "GECODE_HAS_MPFR=1" \

examples/CMakeLists.txt

@@ -115,3 +115,9 @@ endfunction()
 foreach(example_source IN LISTS GECODE_EXAMPLE_SOURCES)
   gecode_add_example("${example_source}")
 endforeach()
+
+if(GECODE_ENABLE_EXPERIMENTAL)
+  add_executable(tsptw tsptw.cpp)
+  target_link_libraries(tsptw PRIVATE gecodesearch gecodeint)
+  set_property(TARGET tsptw PROPERTY FOLDER "Examples")
+endif()