refactor(pumpkin-core): Extracting branchers as separate crate

CLAUDE.md

@@ -46,11 +46,12 @@ Scripts in `scripts/` (`fmt.sh`, `clippy.sh`, `documentation.sh`, `deny.sh`) mir
 The project is a Cargo workspace (edition 2024, resolver 2). Crates are grouped by role:
 
 ### Core Engine (`pumpkin-crates/`)
-- **`core`** — The main solver engine. Contains the CDCL loop, propagation engine, nogood learning, branching heuristics, and proof logging infrastructure. This is the heart of the solver.
+- **`core`** — The main solver engine. Contains the CDCL loop, propagation engine, nogood learning, and proof logging infrastructure. This is the heart of the solver.
 - **`checking`** — Shared types used by both `core` and `pumpkin-checker` (avoids circular deps).
 - **`propagators`** — Implementations of CP propagators (arithmetic, cumulative, disjunctive, element, etc.).
 - **`conflict-resolvers`** — Pluggable conflict analysis strategies for nogood derivation.
 - **`constraints`** — High-level constraint API built on top of `core`.
+- **`branching`** — Branching heuristics (variable/value selection, tie-breaking) and `Brancher` implementations built on top of `core`.
 
 ### Interfaces
 - **`pumpkin-solver`** — CLI binary. Accepts CNF, WCNF (MaxSAT), and FlatZinc input formats.

README.md

@@ -108,6 +108,7 @@ Pumpkin consists of several different components:
     - [pumpkin-propagators](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-crates/propagators); contains (most of) the propagators used by Pumpkin.
     - [pumpkin-constraints](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-crates/constraints); contains convenient ways to add one or more propagators modelling certain constraints to the solver.
     - [pumpkin-conflict-resolvers](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-crates/conflict-resolvers); contains the conflict resolvers (e.g., 1UIP or All-Decision conflict resolvers) used by Pumpkin.
+    - [pumpkin-branching](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-crates/branching); contains the branching heuristics (e.g., variable/value selection strategies) used by Pumpkin.
     - [pumpkin-checking](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-crates/checking); contains the types used for checking the soundness of propagators in Pumpkin.
 - The CLI contained in [pumpkin-solver](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-solver).
 - The Python bindings contained in [pumpkin-solver-py](https://github.com/ConSol-Lab/Pumpkin/tree/main/pumpkin-solver-py).

pumpkin-crates/branching/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "pumpkin-branching"
+version.workspace = true
+repository.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "The branching heuristics of the Pumpkin constraint programming solver."
+
+[lints]
+workspace = true
+
+[dependencies]
+enum-map = "3.1.0"
+log = "0.4.30"
+pumpkin-core = { version = "0.5.0", path = "../core" }

pumpkin-crates/core/src/branching/branchers/alternating/alternating_brancher.rs → pumpkin-crates/branching/src/branching/alternating/alternating_brancher.rs

@@ -1,17 +1,20 @@
 //! A [`Brancher`] which alternates between the [`DefaultBrancher`] and another [`Brancher`] based
 //! on the strategy specified in [`AlternatingStrategy`].
 
+use pumpkin_core::Solver;
+use pumpkin_core::branching::Brancher;
+use pumpkin_core::branching::BrancherEvent;
+use pumpkin_core::branching::SelectionContext;
+use pumpkin_core::predicates::Predicate;
+use pumpkin_core::results::SolutionReference;
+#[cfg(doc)]
+use pumpkin_core::state::State;
+use pumpkin_core::statistics::StatisticLogger;
+use pumpkin_core::variables::DomainId;
+
 use super::BrancherToUse;
 use crate::DefaultBrancher;
-use crate::Solver;
-use crate::basic_types::SolutionReference;
-use crate::branching::Brancher;
-use crate::branching::SelectionContext;
-use crate::branching::brancher::BrancherEvent;
-use crate::branching::branchers::alternating::strategies::AlternatingStrategy;
-use crate::engine::predicates::predicate::Predicate;
-use crate::engine::variables::DomainId;
-use crate::statistics::StatisticLogger;
+use crate::branching::alternating::strategies::AlternatingStrategy;
 
 /// A [`Brancher`] which switches between its provided brancher and [`DefaultBrancher`] based on the
 /// provided [`AlternatingStrategy`].
@@ -35,9 +38,18 @@ impl<Strategy: AlternatingStrategy, OtherBrancher: Brancher>
     AlternatingBrancher<OtherBrancher, Strategy>
 {
     pub fn new(solver: &Solver, other_brancher: OtherBrancher, strategy: Strategy) -> Self {
+        Self::new_from_domains(solver.get_domains(), other_brancher, strategy)
+    }
+
+    /// Creates a new instance considering all of the provided `domains`.
+    pub(crate) fn new_from_domains(
+        domains: impl IntoIterator<Item = DomainId>,
+        other_brancher: OtherBrancher,
+        strategy: Strategy,
+    ) -> Self {
         Self {
             other_brancher,
-            default_brancher: solver.default_brancher(),
+            default_brancher: DefaultBrancher::new_from_domains(domains),
             strategy,
         }
     }

pumpkin-crates/core/src/branching/branchers/alternating/strategies/every_x_restarts.rs → pumpkin-crates/branching/src/branching/alternating/strategies/every_x_restarts.rs

@@ -1,10 +1,11 @@
-use crate::branching::Brancher;
-use crate::branching::BrancherEvent;
-use crate::branching::SelectionContext;
+use pumpkin_core::branching::Brancher;
+use pumpkin_core::branching::BrancherEvent;
+use pumpkin_core::branching::SelectionContext;
+
 #[cfg(doc)]
-use crate::branching::branchers::alternating::AlternatingBrancher;
-use crate::branching::branchers::alternating::BrancherToUse;
-use crate::branching::branchers::alternating::strategies::AlternatingStrategy;
+use crate::branching::alternating::AlternatingBrancher;
+use crate::branching::alternating::BrancherToUse;
+use crate::branching::alternating::strategies::AlternatingStrategy;
 
 /// Specifies that the [`AlternatingBrancher`] should switch between
 /// [`BrancherToUse::Default`] and the provided brancher every `x`th considered restart.
@@ -82,91 +83,76 @@ impl AlternatingStrategy for EveryXRestarts {
 
 #[cfg(test)]
 mod tests {
-    use crate::Solver;
-    use crate::basic_types::tests::TestRandom;
-    use crate::branching::Brancher;
-    use crate::branching::SelectionContext;
-    use crate::branching::branchers::alternating::alternating_brancher::AlternatingBrancher;
-    use crate::branching::branchers::alternating::every_x_restarts::EveryXRestarts;
-    use crate::engine::Assignments;
+    use pumpkin_core::branching::Brancher;
+    use pumpkin_core::branching::SelectionContext;
+    use pumpkin_core::state::State;
+
+    use crate::DefaultBrancher;
+    use crate::branching::alternating::alternating_brancher::AlternatingBrancher;
+    use crate::branching::alternating::every_x_restarts::EveryXRestarts;
+    use crate::testing::TestRandom;
 
     #[test]
     fn test_every_restart() {
-        let assignments = Assignments::default();
-        let solver = Solver::default();
-        let mut brancher =
-            AlternatingBrancher::new(&solver, solver.default_brancher(), EveryXRestarts::new(1));
+        let state = State::default();
+        let mut test_rng = TestRandom::default();
+        let mut context = SelectionContext::new(&state, &mut test_rng);
+        let mut brancher = AlternatingBrancher::new_from_domains(
+            state.get_domain_ids(),
+            DefaultBrancher::new_from_domains(state.get_domain_ids()),
+            EveryXRestarts::new(1),
+        );
 
         assert!(!brancher.is_using_default_brancher());
         brancher.on_restart();
         // next_decision is called to ensure that the brancher has actually switched
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
         assert!(brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
         assert!(!brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
 
         assert!(brancher.is_using_default_brancher());
     }
 
     #[test]
     fn test_every_other_restart() {
-        let assignments = Assignments::default();
-        let solver = Solver::default();
-        let mut brancher =
-            AlternatingBrancher::new(&solver, solver.default_brancher(), EveryXRestarts::new(2));
+        let state = State::default();
+        let mut test_rng = TestRandom::default();
+        let mut context = SelectionContext::new(&state, &mut test_rng);
+        let mut brancher = AlternatingBrancher::new_from_domains(
+            state.get_domain_ids(),
+            DefaultBrancher::new_from_domains(state.get_domain_ids()),
+            EveryXRestarts::new(2),
+        );
 
         assert!(!brancher.is_using_default_brancher());
 
         brancher.on_restart();
         // next_decision is called to ensure that the brancher has actually switched
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
         assert!(!brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
         assert!(brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
 
         assert!(brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
 
         assert!(!brancher.is_using_default_brancher());
 
         brancher.on_restart();
-        let _ = brancher.next_decision(&mut SelectionContext::new(
-            &assignments,
-            &mut TestRandom::default(),
-        ));
+        let _ = brancher.next_decision(&mut context);
 
         assert!(!brancher.is_using_default_brancher());
     }

pumpkin-crates/core/src/branching/branchers/alternating/strategies/every_x_solutions.rs → pumpkin-crates/branching/src/branching/alternating/strategies/every_x_solutions.rs

@@ -1,10 +1,11 @@
-use crate::branching::BrancherEvent;
-use crate::branching::SelectionContext;
+use pumpkin_core::branching::BrancherEvent;
+use pumpkin_core::branching::SelectionContext;
+use pumpkin_core::results::SolutionReference;
+
 #[cfg(doc)]
-use crate::branching::branchers::alternating::AlternatingBrancher;
-use crate::branching::branchers::alternating::BrancherToUse;
-use crate::branching::branchers::alternating::strategies::AlternatingStrategy;
-use crate::results::SolutionReference;
+use crate::branching::alternating::AlternatingBrancher;
+use crate::branching::alternating::BrancherToUse;
+use crate::branching::alternating::strategies::AlternatingStrategy;
 
 /// Specifies that the [`AlternatingBrancher`] should switch between
 /// [`BrancherToUse::Default`] and the provided brancher every `x`th solution.
@@ -52,30 +53,33 @@ impl AlternatingStrategy for EveryXSolutions {
 
 #[cfg(test)]
 mod tests {
-    use crate::Solver;
-    use crate::branching::Brancher;
-    use crate::branching::branchers::alternating::alternating_brancher::AlternatingBrancher;
-    use crate::branching::branchers::alternating::strategies::every_x_solutions::EveryXSolutions;
-    use crate::engine::Assignments;
-    use crate::results::SolutionReference;
+    use pumpkin_core::Solver;
+    use pumpkin_core::branching::Brancher;
+    use pumpkin_core::results::Solution;
+
+    use crate::DefaultBrancher;
+    use crate::branching::alternating::alternating_brancher::AlternatingBrancher;
+    use crate::branching::alternating::strategies::every_x_solutions::EveryXSolutions;
 
     #[test]
     fn test_every_other_solution() {
         let solver = Solver::default();
-        let mut brancher =
-            AlternatingBrancher::new(&solver, solver.default_brancher(), EveryXSolutions::new(2));
+        let mut brancher = AlternatingBrancher::new(
+            &solver,
+            DefaultBrancher::default_over_all_variables(&solver),
+            EveryXSolutions::new(2),
+        );
 
-        let assignments = Assignments::default();
-        let empty_solution_reference = SolutionReference::new(&assignments);
+        let empty_solution = Solution::default();
 
         assert!(!brancher.is_using_default_brancher());
-        brancher.on_solution(empty_solution_reference);
+        brancher.on_solution(empty_solution.as_reference());
         assert!(!brancher.is_using_default_brancher());
-        brancher.on_solution(empty_solution_reference);
+        brancher.on_solution(empty_solution.as_reference());
         assert!(brancher.is_using_default_brancher());
-        brancher.on_solution(empty_solution_reference);
+        brancher.on_solution(empty_solution.as_reference());
         assert!(brancher.is_using_default_brancher());
-        brancher.on_solution(empty_solution_reference);
+        brancher.on_solution(empty_solution.as_reference());
         assert!(!brancher.is_using_default_brancher());
     }
 }

pumpkin-crates/core/src/branching/branchers/alternating/strategies/mod.rs → pumpkin-crates/branching/src/branching/alternating/strategies/mod.rs

@@ -1,11 +1,12 @@
 use std::fmt::Debug;
 
-use crate::branching::Brancher;
-use crate::branching::BrancherEvent;
-use crate::branching::SelectionContext;
+use pumpkin_core::branching::Brancher;
+use pumpkin_core::branching::BrancherEvent;
+use pumpkin_core::branching::SelectionContext;
+use pumpkin_core::results::SolutionReference;
+
 #[cfg(doc)]
-use crate::branching::branchers::alternating::AlternatingBrancher;
-use crate::results::SolutionReference;
+use crate::branching::alternating::AlternatingBrancher;
 
 /// Defines methods for selecting which of two branching strategies to use; the default or the
 /// other brancher.

pumpkin-crates/core/src/branching/branchers/alternating/strategies/other_only.rs → pumpkin-crates/branching/src/branching/alternating/strategies/other_only.rs

@@ -1,10 +1,11 @@
-use crate::branching::Brancher;
-use crate::branching::BrancherEvent;
-use crate::branching::SelectionContext;
+use pumpkin_core::branching::Brancher;
+use pumpkin_core::branching::BrancherEvent;
+use pumpkin_core::branching::SelectionContext;
+
 #[cfg(doc)]
-use crate::branching::branchers::alternating::AlternatingBrancher;
-use crate::branching::branchers::alternating::AlternatingStrategy;
-use crate::branching::branchers::alternating::BrancherToUse;
+use crate::branching::alternating::AlternatingBrancher;
+use crate::branching::alternating::AlternatingStrategy;
+use crate::branching::alternating::BrancherToUse;
 
 /// Specifies that the [`AlternatingBrancher`] should always use the other strategy.
 #[derive(Default, Debug, Clone, Copy)]