Add adversarial game search framework with Negamax and Alpha-Beta engines

CMakeLists.txt

@@ -156,6 +156,15 @@ set(HLIST
     Dominators.H
     Hungarian.H
     tpl_interval_tree.H
+    search_move_ordering.H
+    state_search_common.H
+    Transposition_Table.H
+    Backtracking.H
+    Branch_And_Bound.H
+    Negamax.H
+    Alpha_Beta.H
+    State_Search.H
+    State_Search_IDA_Star.H
 )
 
 # C++ source files
@@ -227,13 +236,16 @@ install(FILES ${HLIST}
     DESTINATION include/aleph
 )
 
+if(BUILD_TESTS)
+    enable_testing()
+endif()
+
 # Add subdirectories if enabled
 if(BUILD_EXAMPLES)
     add_subdirectory(Examples)
 endif()
 
 if(BUILD_TESTS)
-    enable_testing()
     add_subdirectory(Tests)
 endif()
 

Examples/CMakeLists.txt

@@ -53,6 +53,48 @@ target_link_libraries(polynomial_benchmark PRIVATE Aleph ${ALEPH_SYSTEM_LIBS})
 add_executable(polynomial_reference_probe "${CMAKE_CURRENT_SOURCE_DIR}/polynomial_reference_probe.cc")
 target_link_libraries(polynomial_reference_probe PRIVATE Aleph ${ALEPH_SYSTEM_LIBS})
 
+if(BUILD_TESTS)
+    set(_VERIFY_REFERENCE_EXAMPLE
+        ${CMAKE_CURRENT_SOURCE_DIR}/verify_reference_example.cmake)
+
+    if(TARGET backtracking_nqueens_example)
+        add_test(
+            NAME StateSearchExamples.NQueens
+            COMMAND ${CMAKE_COMMAND}
+                    -DEXAMPLE_PATH=$<TARGET_FILE:backtracking_nqueens_example>
+                    "-DEXPECT_SUBSTRINGS=N-Queens reference example\;Solutions found: 2\;First solution signature: 1302"
+                    -P ${_VERIFY_REFERENCE_EXAMPLE}
+        )
+    endif()
+
+    if(TARGET branch_and_bound_knapsack_example)
+        add_test(
+            NAME StateSearchExamples.Knapsack
+            COMMAND ${CMAKE_COMMAND}
+                    -DEXAMPLE_PATH=$<TARGET_FILE:branch_and_bound_knapsack_example>
+                    "-DEXPECT_SUBSTRINGS=0/1 Knapsack reference example\;Optimal value: 90\;Chosen items: 0 2"
+                    -P ${_VERIFY_REFERENCE_EXAMPLE}
+        )
+    endif()
+
+    if(TARGET negamax_tictactoe_example)
+        add_test(
+            NAME StateSearchExamples.TicTacToe
+            COMMAND ${CMAKE_COMMAND}
+                    -DEXAMPLE_PATH=$<TARGET_FILE:negamax_tictactoe_example>
+                    "-DEXPECT_SUBSTRINGS=Tic-Tac-Toe reference example\;Negamax best move: 4\;Alpha-Beta best move: 4"
+                    -P ${_VERIFY_REFERENCE_EXAMPLE}
+        )
+    endif()
+
+    if(TARGET state_search_benchmark)
+        add_test(
+            NAME StateSearchBenchmark.Validate
+            COMMAND $<TARGET_FILE:state_search_benchmark> --validate
+        )
+    endif()
+endif()
+
 list(LENGTH EXAMPLE_SOURCES _examples_count)
 math(EXPR _total_examples "${_examples_count} + 2")
 message(STATUS "Configured ${CMAKE_PROJECT_NAME} examples (${_total_examples} targets)")

Examples/adversarial_artificial_example.cc

@@ -0,0 +1,160 @@
+/*
+                          Aleph_w
+
+  Data structures & Algorithms
+  version 2.0.0b
+  https://github.com/lrleon/Aleph-w
+
+  This file is part of Aleph-w library
+
+  Copyright (c) 2002-2026 Leandro Rabindranath Leon
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+*/
+
+#include <iostream>
+#include <string>
+
+#include <State_Search.H>
+
+using namespace Aleph;
+
+namespace
+{
+
+struct ArtificialGameState
+{
+  size_t depth = 0;
+  size_t code = 1;
+  int player = 1;
+};
+
+struct ArtificialGameMove
+{
+  size_t next_code = 1;
+  char label = 'A';
+};
+
+class ArtificialGameDomain
+{
+public:
+  using State = ArtificialGameState;
+  using Move = ArtificialGameMove;
+  using Score = int;
+
+  bool is_terminal(const State &state) const
+  {
+    return state.depth == 2;
+  }
+
+  Score evaluate(const State &state) const
+  {
+    return root_score(state.code)*state.player;
+  }
+
+  void apply(State &state, const Move &move) const
+  {
+    state.code = move.next_code;
+    state.player = -state.player;
+    ++state.depth;
+  }
+
+  void undo(State &state, const Move&) const
+  {
+    --state.depth;
+    state.player = -state.player;
+    state.code /= 2;
+  }
+
+  template <typename Visitor>
+  bool for_each_successor(const State &state, Visitor visit) const
+  {
+    if (state.depth >= 2)
+      return true;
+
+    switch (state.code)
+      {
+      case 1:
+        if (not visit(Move{2, 'A'}))
+          return false;
+        return visit(Move{3, 'B'});
+
+      case 2:
+        if (not visit(Move{4, 'a'}))
+          return false;
+        return visit(Move{5, 'b'});
+
+      case 3:
+        if (not visit(Move{6, 'a'}))
+          return false;
+        return visit(Move{7, 'b'});
+
+      default:
+        return true;
+      }
+  }
+
+private:
+  [[nodiscard]] static Score root_score(const size_t code) noexcept
+  {
+    switch (code)
+      {
+      case 2: return 6;
+      case 3: return 1;
+      case 4: return 3;
+      case 5: return 5;
+      case 6: return 2;
+      case 7: return 4;
+      default: return 0;
+      }
+  }
+};
+
+std::string signature(const SearchPath<ArtificialGameMove> &path)
+{
+  std::string out;
+  for (const auto &move : path)
+    out.push_back(move.label);
+  return out;
+}
+
+template <typename Result>
+void print_summary(const char *title, const Result &result)
+{
+  std::cout << title << '\n';
+  std::cout << "  value: " << result.value << '\n';
+  std::cout << "  pv: " << signature(result.principal_variation) << '\n';
+  std::cout << "  visited: " << result.stats.visited_states << '\n';
+  std::cout << "  cutoffs: " << result.stats.alpha_beta_cutoffs << '\n';
+}
+
+} // end namespace
+
+int main()
+{
+  const ArtificialGameState root;
+
+  auto negamax = negamax_search(ArtificialGameDomain{}, root);
+  auto alpha_beta = alpha_beta_search(ArtificialGameDomain{}, root);
+
+  print_summary("Negamax", negamax);
+  print_summary("Alpha-Beta", alpha_beta);
+
+  return 0;
+}