Add experimental A* and CABS search

.github/workflows/build.yml

@@ -69,7 +69,7 @@ jobs:
 
     - name: Configure
       shell: bash
-      run: ./configure
+      run: ./configure --enable-experimental
 
     - name: Build
       shell: bash
@@ -233,6 +233,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
@@ -486,6 +487,7 @@ jobs:
       shell: pwsh
       run: cmake -E make_directory "${{ github.workspace }}\\build"
 
+    # Experimental APIs follow build_shared, so both settings are built
     - name: Configure CMake
       shell: pwsh
       run: >
@@ -496,6 +498,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
@@ -607,6 +610,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
 
@@ -675,7 +679,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})
@@ -692,6 +693,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()
@@ -1815,6 +1819,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

@@ -269,19 +269,25 @@ SEARCHSRC0 = \
 	cpprofiler/tracer worker-control
 SEARCHHDR0 = \
 	statistics.hpp stop.hpp options.hpp cutoff.hpp \
-	support.hh worker.hh worker-control.hh exception.hpp engine.hpp base.hpp \
+	support.hh heuristic.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/bab.hh seq/bab.hpp seq/astar.hh seq/cabs.hh seq/choice-expansion.hh \
+	seq/lds.hh seq/lds.hpp \
 	seq/rbs.hh seq/rbs.hpp seq/dead.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 \
+	par/pbs.hh par/pbs.hpp par/frontier.hh \
+	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 par/frontier
+endif
+
 SEARCHSRC	= $(SEARCHSRC0:%=gecode/search/%.cpp)
 SEARCHHDR	= gecode/search.hh $(SEARCHHDR0:%=gecode/search/%)
 SEARCHOBJ	= $(SEARCHSRC:%.cpp=%$(OBJSUFFIX))
@@ -912,7 +918,8 @@ INTEXAMPLESRC0 =						\
 	word-square crossword open-shop car-sequencing sat      \
 	bin-packing knights tsp perfect-square schurs-lemma     \
 	dominating-queens colored-matrix multi-bin-packing	\
-	qcp job-shop open-route common-pattern fifteen-puzzle
+	qcp job-shop open-route common-pattern fifteen-puzzle	\
+	tsptw
 
 
 INTEXAMPLEHDR  = $(INTEXAMPLEHDR0:%=examples/%.hpp) \

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>
@@ -116,6 +118,31 @@ Rank:   minor
 Honor propagation annotations in cumulative and unary scheduling bindings,
 including the unary specializations of cumulative constraints.
 
+[ENTRY]
+Module: search
+What:   new
+Rank:   major
+Experimental: true
+[DESCRIPTION]
+Add experimental A* (AStar) and complete anytime beam search (CABS).
+[MORE]
+Both engines take an objective bound and an optional rank from
+Search::Options::guidance. They support parallel search, dynamic worker
+control, and portfolios with BAB. CABS also supports model-defined dominance.
+Enable with --enable-experimental or GECODE_ENABLE_EXPERIMENTAL=ON; the
+preview is disabled by default and its APIs may change in future releases.
+The fifteen-puzzle and tsptw examples demonstrate both engines.
+
+[ENTRY]
+Module: search
+What:   bug
+Rank:   minor
+[DESCRIPTION]
+Fix sequential portfolio search ignoring stop objects after a slice has
+ended. In sequential and parallel portfolios, an asset that stops at a local
+limit (the width or node limit of CABS) no longer stops the portfolio; it is
+removed and the portfolio reports that it has stopped once all assets are done.
+
 [ENTRY]
 Module: int
 What:   new

cmake/GecodeSources.cmake

@@ -51,6 +51,14 @@ 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
+    gecode/search/par/frontier.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]
@@ -3409,6 +3412,8 @@ GECODE_SOVERSION=${ac_gecode_soversion}
 
 
 
+
+
 
 
 
@@ -13593,6 +13598,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

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

docs/worker-control.md

@@ -3,7 +3,8 @@
 ## Purpose
 
 `Search::WorkerControl` lets an external scheduler change how many workers a
-running DFS or BAB engine may use. A portfolio with a fixed thread budget can
+running DFS or BAB engine may use. Experimental AStar and CABS engines also
+support worker control. A portfolio with a fixed thread budget can
 move workers among its engines at runtime.
 
 The engine still starts with a fixed maximum:
@@ -26,8 +27,8 @@ control.request(1); // Resume
 Gecode resolves the `threads` option when it constructs the engine. The result
 is the fixed worker capacity. A request must be between zero and that capacity,
 inclusive. Zero pauses the engine without discarding its search state.
-This also applies when the resolved capacity is one: sequential DFS and BAB
-wait at search boundaries until the control resumes them.
+This also applies when the resolved capacity is one: sequential DFS, BAB,
+AStar, and CABS wait at search boundaries until the control resumes them.
 Pausing requires a build with thread support. Without thread support, attaching
 an initially paused control or calling `request(0)` raises
 `Search::InvalidWorkerRequest`; controls must be used from one thread.
@@ -80,8 +81,9 @@ An empty default-constructed handle means that worker adjustment is disabled.
 Calling `request` on an empty handle raises
 `Search::UninitializedWorkerControl`.
 
-A shared identity can be bound to only one leaf engine at a time. It cannot be
-shared by two DFS/BAB engines or attached directly to an enclosing meta-engine.
+A shared identity can be bound to only one leaf engine at a time (DFS, BAB,
+AStar, or CABS). It cannot be shared by two engines or attached directly to an
+enclosing meta-engine.
 Ordinary reuse for a replacement engine after destruction is also rejected.
 These uses raise `Search::WorkerControlInUse`.
 

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

@@ -61,6 +61,7 @@ set(GECODE_EXAMPLE_SOURCES
   sudoku-advanced.cpp
   sudoku.cpp
   tsp.cpp
+  tsptw.cpp
   warehouses.cpp
   word-square.cpp)