treecf 0.2.0__tar.gz → 0.2.2__tar.gz

{treecf-0.2.0 → treecf-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treecf
-Version: 0.2.0
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -48,7 +48,7 @@ Provides-Extra: sklearn
 Provides-Extra: viz
 Provides-Extra: xgboost
 License-File: LICENSE
-Summary: Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) on a bundled Rust genetic engine.
+Summary: Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions.
 Keywords: counterfactual,xai,interpretability,recourse,gbdt,xgboost,lightgbm,catboost,credit-risk
 Author-email: Daniel Wlazlo <wlazlo.daniel@gmail.com>
 License: MIT
@@ -67,7 +67,7 @@ Project-URL: Issues, https://github.com/wlazlod/treecf/issues
 that the model's raw output lands in a target interval?"* — for XGBoost, LightGBM, CatBoost
 and scikit-learn tree ensembles.
 
-> Status: v0.1.0 on [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
+> On [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
 
 ## Why another counterfactual package?
 
@@ -81,6 +81,12 @@ and scikit-learn tree ensembles.
   counterfactual in a median 0.24s versus 0.005s for the genetic heuristic, closing a
   median 14.33% cost gap the heuristic leaves on the table — measured on a 4-core dev
   machine (`scripts/bench_exact.py`).
+- **Certified "no".** A completed exact search returns `Infeasible(proof="certified")` —
+  "no recourse exists within these constraints" becomes a provable statement, not a shrug
+  after a timeout.
+- **Recourse regions.** Any verified counterfactual widens into a certified box — "reduce
+  utilization to ≤ 0.40", not "to 0.3972" — with every point in the box provably in-target
+  and constraint-feasible; works with every backend.
 - **Decision thresholds are first-class.** Targets are intervals on the raw model output —
   custom probability cutoffs, regression targets, and whole rating-grade ladders in one call.
 - **Real-world constraints.** Declarative layer for immutability, directionality, ranges,
@@ -113,6 +119,9 @@ exp = Explainer(
     ],
 )
 res = exp.explain(x, target=Target.probability(range=(0.0, 0.04)), seed=0)
+
+proved = exp.explain(x, target=t, backend="exact")      # proof="optimal", a certified "no", or a warned degrade
+boxed = exp.explain(x, target=t, region=True)            # res.region.describe() -> "utilization <= 0.4"
 ```
 
 ## License

{treecf-0.2.0 → treecf-0.2.2}/README.md

@@ -6,7 +6,7 @@
 that the model's raw output lands in a target interval?"* — for XGBoost, LightGBM, CatBoost
 and scikit-learn tree ensembles.
 
-> Status: v0.1.0 on [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
+> On [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
 
 ## Why another counterfactual package?
 
@@ -20,6 +20,12 @@ and scikit-learn tree ensembles.
   counterfactual in a median 0.24s versus 0.005s for the genetic heuristic, closing a
   median 14.33% cost gap the heuristic leaves on the table — measured on a 4-core dev
   machine (`scripts/bench_exact.py`).
+- **Certified "no".** A completed exact search returns `Infeasible(proof="certified")` —
+  "no recourse exists within these constraints" becomes a provable statement, not a shrug
+  after a timeout.
+- **Recourse regions.** Any verified counterfactual widens into a certified box — "reduce
+  utilization to ≤ 0.40", not "to 0.3972" — with every point in the box provably in-target
+  and constraint-feasible; works with every backend.
 - **Decision thresholds are first-class.** Targets are intervals on the raw model output —
   custom probability cutoffs, regression targets, and whole rating-grade ladders in one call.
 - **Real-world constraints.** Declarative layer for immutability, directionality, ranges,
@@ -52,6 +58,9 @@ exp = Explainer(
     ],
 )
 res = exp.explain(x, target=Target.probability(range=(0.0, 0.04)), seed=0)
+
+proved = exp.explain(x, target=t, backend="exact")      # proof="optimal", a certified "no", or a warned degrade
+boxed = exp.explain(x, target=t, region=True)            # res.region.describe() -> "utilization <= 0.4"
 ```
 
 ## License

{treecf-0.2.0 → treecf-0.2.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "treecf"
-version = "0.2.0"
-description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) on a bundled Rust genetic engine."
+version = "0.2.2"
+description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions."
 readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "Daniel Wlazlo", email = "wlazlo.daniel@gmail.com" }]

{treecf-0.2.0 → treecf-0.2.2}/rust/Cargo.lock

@@ -419,7 +419,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "treecf-core"
-version = "0.2.0"
+version = "0.2.2"
 dependencies = [
  "numpy",
  "pyo3",

{treecf-0.2.0 → treecf-0.2.2}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.2.0"
+version = "0.2.2"
 edition = "2021"
 # f64::next_down (cells.rs) stabilized in 1.86; pyo3 0.29 needs 1.83
 rust-version = "1.86"

{treecf-0.2.0 → treecf-0.2.2}/rust/src/exact/mod.rs

@@ -24,6 +24,12 @@
 //!    all depend on the order nodes are visited in, so the search is
 //!    single-threaded by construction and no rayon call may enter it. The
 //!    RNG-free stages that `ga.rs` fans out have no analogue here.
+//!    The interrupt probe the search polls does not weaken this: it is asked
+//!    a question that depends on nothing in the search, it is asked on a
+//!    schedule fixed by the node counter alone, and the only thing it can do
+//!    is replace the whole answer with `Interrupted`. It never changes a
+//!    value that is returned — the same reasoning that already makes the
+//!    `time_budget_s` early break parity-neutral.
 //! 2. **Full re-summation.** Assigning a feature re-walks the trees that split
 //!    on it from their roots, then the ensemble bracket is re-summed over every
 //!    tree in ascending index (`base + tree_0 + tree_1 + ...`), never patched
@@ -70,6 +76,7 @@ pub(crate) mod search;
 #[cfg(test)]
 pub(crate) mod test_support;
 
+pub use crate::interrupt::SearchOutcome;
 pub use domains::constraint_cells;
 pub use search::{solve_exact, ExactParams, ExactResult, ExactStats};
 

{treecf-0.2.0 → treecf-0.2.2}/rust/src/exact/search.rs

@@ -15,12 +15,18 @@ use crate::exact::domains::{
 use crate::exact::orderpairs::{achievable_bounds, boundary_candidates, intersect_cell};
 use crate::exact::propagation::{PropFrame, Propagation};
 use crate::exact::ValuePolicy;
+use crate::interrupt::{InterruptProbe, SearchOutcome};
 use crate::ir::Ensemble;
 
 /// The tolerance `check_matrix` allows a linear constraint; an order pair counts
 /// as broken exactly when the arbiter would reject it.
 const LINEAR_SLACK: f64 = 1e-9;
 
+/// How many expanded nodes between two interrupt polls. Asking is cheap but not
+/// free, and a search that gets nowhere near this many nodes finishes fast
+/// enough that nobody reaches for the keyboard.
+const SIGNAL_CHECK_INTERVAL: u64 = 1 << 18;
+
 /// The exact set of counters `solve_exact` reports — the seven keys of Python's
 /// `_stats`. `nodes_pruned_score` counts branches the ensemble can no longer
 /// bring into the target (the plausibility bound counts here too); every other
@@ -661,7 +667,13 @@ fn stats(
 /// `completed` false only means the search never settled the whole space.
 ///
 /// `Err` mirrors Python's `ConstraintValidationError` for a multi-feature Linear
-/// outside the canonical order-pair shape.
+/// outside the canonical order-pair shape — it stays validation-only, so a
+/// caller can keep telling a bad constraint apart from a stopped search.
+///
+/// `probe` is asked every `SIGNAL_CHECK_INTERVAL` expanded nodes whether to
+/// stop. Answering yes throws the search away, incumbent included, and returns
+/// `SearchOutcome::Interrupted`; answering no leaves every returned number
+/// exactly as it would be without a probe at all.
 #[allow(clippy::too_many_arguments)]
 pub fn solve_exact(
     ens: &Ensemble,
@@ -675,7 +687,8 @@ pub fn solve_exact(
     plausibility: Option<(&Ensemble, f64)>,
     params: &ExactParams,
     incumbent: Option<(f64, &[f64])>,
-) -> Result<ExactResult, String> {
+    probe: InterruptProbe<'_>,
+) -> Result<SearchOutcome<ExactResult>, String> {
     let start = Instant::now();
     let order_pairs = validate(cons)?;
     let (lo_t, hi_t) = interval;
@@ -685,13 +698,13 @@ pub fn solve_exact(
 
     // (a) The factual itself: nothing is ever cheaper than not moving at all.
     if accepts(ens, if_ens, min_total_path, cons, x, lo_t, hi_t, x) {
-        return Ok(ExactResult {
+        return Ok(SearchOutcome::Done(ExactResult {
             x_cf: Some(x.to_vec()),
             proof: "optimal",
             stats: stats(0, 0, 0, 0.0, gap, true, false),
             snapped: Vec::new(),
             distance: Some(0.0),
-        });
+        }));
     }
 
     let ensembles: Vec<&Ensemble> = match if_ens {
@@ -704,13 +717,13 @@ pub fn solve_exact(
     if order.iter().any(|&j| domains[j].is_empty()) {
         // Contradictory constraints left a feature with no legal value at all:
         // nothing to search, and nothing can be feasible.
-        return Ok(ExactResult {
+        return Ok(SearchOutcome::Done(ExactResult {
             x_cf: None,
             proof: "optimal",
             stats: stats(0, 0, 0, f64::INFINITY, gap, true, false),
             snapped: Vec::new(),
             distance: None,
-        });
+        }));
     }
     let h_suffix = h_suffix(&order, &domains);
 
@@ -892,6 +905,12 @@ pub fn solve_exact(
             completed = false;
             break;
         }
+        // Every node reaching this line is expanded below, so each count is
+        // asked about at most once and a search of fewer than
+        // SIGNAL_CHECK_INTERVAL nodes is never asked at all.
+        if nodes_expanded > 0 && nodes_expanded % SIGNAL_CHECK_INTERVAL == 0 && probe() {
+            return Ok(SearchOutcome::Interrupted);
+        }
 
         nodes_expanded += 1;
         let j = ctx.order[k];
@@ -1081,7 +1100,7 @@ pub fn solve_exact(
         }
     }
 
-    Ok(ExactResult {
+    Ok(SearchOutcome::Done(ExactResult {
         distance: incumbent_row.as_ref().map(|_| incumbent_cost),
         x_cf: incumbent_row,
         proof,
@@ -1095,7 +1114,7 @@ pub fn solve_exact(
             warm_start_used,
         ),
         snapped,
-    })
+    }))
 }
 
 #[cfg(test)]
@@ -1104,6 +1123,95 @@ mod tests {
     use crate::constraints::{LinearC, LIN_LE, POLICY_SATISFIED};
     use crate::exact::test_support::*;
 
+    // -------------------------------------------------------- interrupt probe ---
+
+    /// A search that stays under the polling interval is never asked anything,
+    /// so a probe that would have said stop changes nothing: the answer is the
+    /// same bits the plain solve gives.
+    #[test]
+    fn a_short_search_is_never_asked_and_answers_the_same_bits() {
+        let ens = stumps(&[(0, 1.0, true, 0.0, 1.0), (1, 0.5, true, 0.0, 0.5)], 2);
+        let cons = cons_base(2);
+        let x = [0.0, 0.0];
+        let plain = solve(
+            &ens,
+            &x,
+            (1.0, 2.0),
+            &cons,
+            0.0,
+            &no_policies(2),
+            &ExactParams::default(),
+            None,
+        );
+        let mut polls = 0usize;
+        let outcome = solve_probed(
+            &ens,
+            &x,
+            (1.0, 2.0),
+            &cons,
+            0.0,
+            &no_policies(2),
+            &ExactParams::default(),
+            None,
+            &mut || {
+                polls += 1;
+                true // would stop the search — if it were ever asked
+            },
+        );
+        let SearchOutcome::Done(probed) = outcome else {
+            panic!("a search of a few nodes must not be interrupted")
+        };
+        assert_eq!(polls, 0);
+        assert!(probed.stats.nodes_expanded > 0);
+        assert_eq!(
+            bits_of(probed.x_cf.as_ref().unwrap()),
+            bits_of(plain.x_cf.as_ref().unwrap())
+        );
+        assert_eq!(
+            probed.distance.unwrap().to_bits(),
+            plain.distance.unwrap().to_bits()
+        );
+        assert_eq!(probed.proof, plain.proof);
+        assert_eq!(probed.stats, plain.stats);
+        assert_eq!(probed.snapped, plain.snapped);
+    }
+
+    /// Twenty levers, each worth one point, and a target halfway between two
+    /// whole numbers: no assignment can ever land in it, so no incumbent is
+    /// found, nothing is cut on cost, and the search runs well past the
+    /// polling interval. The warm start it was handed is a result it could
+    /// have returned — a probe that says stop drops that too and reports only
+    /// that it stopped.
+    #[test]
+    fn a_long_search_drops_even_its_warm_start_when_the_probe_says_stop() {
+        let specs: Vec<(i32, f64, bool, f64, f64)> =
+            (0..20).map(|j| (j, 1.0, true, 0.0, 1.0)).collect();
+        let ens = stumps(&specs, 20);
+        let cons = cons_base(20);
+        let x = vec![0.0; 20];
+        let params = ExactParams {
+            time_budget_s: 1e9, // the probe, not the clock, must end this one
+            ..ExactParams::default()
+        };
+        let mut polls = 0usize;
+        let outcome = solve_probed(
+            &ens,
+            &x,
+            (10.5, 10.5),
+            &cons,
+            0.0,
+            &no_policies(20),
+            &params,
+            Some((1e12, x.as_slice())), // too dear to prune anything with
+            &mut || {
+                polls += 1;
+                true
+            },
+        );
+        assert!(matches!(outcome, SearchOutcome::Interrupted));
+        assert_eq!(polls, 1);
+    }
+
     // ---------------------------------------------------- ensemble bounds ---
 
     #[test]
@@ -1760,7 +1868,7 @@ mod tests {
         let ens = stumps(&[(0, 1.0, true, 0.0, 1.0)], 2);
         let if_ens = stumps(&[(1, 0.5, true, 2.0, 5.0)], 2);
         let cons = cons_base(2);
-        let result = solve_exact(
+        let outcome = solve_exact(
             &ens,
             &[0.0, 0.0],
             (1.0, 2.0),
@@ -1772,8 +1880,12 @@ mod tests {
             Some((&if_ens, 4.0)),
             &ExactParams::default(),
             None,
+            &mut || false,
         )
         .unwrap();
+        let SearchOutcome::Done(result) = outcome else {
+            unreachable!("no-op probe never interrupts")
+        };
         assert_eq!(
             bits_of(result.x_cf.as_ref().unwrap()),
             vec![0x3ff0000000000000, 0x3fe0000000000000]

{treecf-0.2.0 → treecf-0.2.2}/rust/src/exact/test_support.rs

@@ -6,6 +6,7 @@ use crate::constraints::Constraints;
 use crate::exact::domains::{build_domains, constraint_cells, State};
 use crate::exact::search::solve_exact;
 use crate::exact::{ExactParams, ExactResult, ValuePolicy};
+use crate::interrupt::{InterruptProbe, SearchOutcome};
 use crate::ir::{Ensemble, Link};
 
 // ------------------------------------------------------------ builders ---
@@ -139,6 +140,36 @@ pub(crate) fn solve(
     params: &ExactParams,
     incumbent: Option<(f64, &[f64])>,
 ) -> ExactResult {
+    match solve_probed(
+        ens,
+        x,
+        interval,
+        cons,
+        lam,
+        policies,
+        params,
+        incumbent,
+        &mut || false,
+    ) {
+        SearchOutcome::Done(result) => result,
+        SearchOutcome::Interrupted => unreachable!("no-op probe never interrupts"),
+    }
+}
+
+/// `solve` with a probe of the caller's own — for the tests that care what the
+/// probe is asked and what happens when it says yes.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn solve_probed(
+    ens: &Ensemble,
+    x: &[f64],
+    interval: (f64, f64),
+    cons: &Constraints,
+    lam: f64,
+    policies: &[Option<ValuePolicy>],
+    params: &ExactParams,
+    incumbent: Option<(f64, &[f64])>,
+    probe: InterruptProbe<'_>,
+) -> SearchOutcome<ExactResult> {
     let p = ens.n_features;
     solve_exact(
         ens,
@@ -152,6 +183,7 @@ pub(crate) fn solve(
         None,
         params,
         incumbent,
+        probe,
     )
     .unwrap()
 }

{treecf-0.2.0 → treecf-0.2.2}/rust/src/ga.rs

@@ -5,6 +5,10 @@
 //! Rayon parallelizes only RNG-free stages (fitness/check/repair), so results
 //! are identical across thread counts by construction — the audit showed child
 //! creation is 1-4 % of wall time, so sequential variation costs little.
+//! `solve_genetic_batch` fans its tasks out a chunk at a time rather than all
+//! at once; that argument is untouched, since each task carries its own seed
+//! and reads nothing from its neighbours, so which tasks travel together and
+//! on which thread cannot change any of their answers.
 
 use std::time::Instant;
 
@@ -14,8 +18,14 @@ use rand_distr::{Distribution, Normal};
 use rand_pcg::Pcg64Mcg;
 
 use crate::constraints::Constraints;
+use crate::interrupt::{InterruptProbe, SearchOutcome};
 use crate::ir::Ensemble;
 
+/// How many batch tasks are fanned out between two interrupt polls. Big enough
+/// that the rayon fan-out still has plenty to chew on, small enough that a
+/// large batch comes back to the calling thread often.
+const SIGNAL_CHECK_CHUNK: usize = 256;
+
 pub struct GaParams {
     pub population: usize,
     pub max_generations: usize,
@@ -241,6 +251,11 @@ pub fn solve_genetic(
 /// Independent GA searches for a batch of `(row_index, seed)` tasks, fanned
 /// out with rayon. Every task is independently seeded, so the output is
 /// thread-count-independent by construction; order follows `tasks`.
+///
+/// The fan-out runs a chunk of `SIGNAL_CHECK_CHUNK` tasks at a time and asks
+/// `probe` on the calling thread before each chunk. Answering yes drops the
+/// chunks already finished and returns `SearchOutcome::Interrupted`; answering
+/// no gives the same vector, task for task, as one undivided fan-out.
 #[allow(clippy::too_many_arguments)]
 pub fn solve_genetic_batch(
     ens: &Ensemble,
@@ -255,30 +270,39 @@ pub fn solve_genetic_batch(
     background: Option<(&[f64], usize)>,
     plausibility: Option<(&Ensemble, f64)>,
     params: &GaParams,
-) -> Vec<GaResult> {
+    probe: InterruptProbe<'_>,
+) -> SearchOutcome<Vec<GaResult>> {
     use rayon::prelude::*;
     let p = ens.n_features;
     // Warm the cell caches up front so parallel tasks don't build them twice.
     let _ = ens.feature_cells();
-    tasks
-        .par_iter()
-        .map(|&(row, seed)| {
-            solve_genetic(
-                ens,
-                &xs[row * p..(row + 1) * p],
-                lo_t,
-                hi_t,
-                cons,
-                sigma,
-                weights,
-                lam,
-                background,
-                plausibility,
-                Some(seed),
-                params,
-            )
-        })
-        .collect()
+    let mut results: Vec<GaResult> = Vec::with_capacity(tasks.len());
+    for chunk in tasks.chunks(SIGNAL_CHECK_CHUNK) {
+        if probe() {
+            return SearchOutcome::Interrupted;
+        }
+        let done: Vec<GaResult> = chunk
+            .par_iter()
+            .map(|&(row, seed)| {
+                solve_genetic(
+                    ens,
+                    &xs[row * p..(row + 1) * p],
+                    lo_t,
+                    hi_t,
+                    cons,
+                    sigma,
+                    weights,
+                    lam,
+                    background,
+                    plausibility,
+                    Some(seed),
+                    params,
+                )
+            })
+            .collect();
+        results.extend(done);
+    }
+    SearchOutcome::Done(results)
 }
 
 fn pin_fixed(pop: &mut [f64], n_rows: usize, p: usize, fixed: &[bool], x: &[f64]) {
@@ -516,7 +540,7 @@ mod tests {
         let cons = empty_constraints(2);
         let xs = [0.0, 0.0, -1.0, 2.0];
         let tasks = [(0usize, 1u64), (0, 2), (1, 3), (1, 1)];
-        let batch = solve_genetic_batch(
+        let outcome = solve_genetic_batch(
             &ens,
             &xs,
             &tasks,
@@ -529,7 +553,11 @@ mod tests {
             None,
             None,
             &params(),
+            &mut || false,
         );
+        let SearchOutcome::Done(batch) = outcome else {
+            unreachable!("no-op probe never interrupts")
+        };
         for (result, &(row, seed)) in batch.iter().zip(&tasks) {
             let single = solve_genetic(
                 &ens,
@@ -550,6 +578,96 @@ mod tests {
         }
     }
 
+    /// The batch asks before it starts, so a probe that says stop right away
+    /// costs one question and no search at all.
+    #[test]
+    fn batch_stops_before_the_first_chunk_when_the_probe_says_stop() {
+        let ens = stump();
+        let cons = empty_constraints(2);
+        let xs = [0.0, 0.0];
+        let tasks = [(0usize, 1u64), (0, 2)];
+        let mut polls = 0usize;
+        let outcome = solve_genetic_batch(
+            &ens,
+            &xs,
+            &tasks,
+            0.5,
+            f64::INFINITY,
+            &cons,
+            &[1.0, 1.0],
+            &[1.0, 1.0],
+            0.05,
+            None,
+            None,
+            &params(),
+            &mut || {
+                polls += 1;
+                true
+            },
+        );
+        assert!(matches!(outcome, SearchOutcome::Interrupted));
+        assert_eq!(polls, 1);
+    }
+
+    /// Chunking is a polling schedule and nothing else: 300 tasks are two
+    /// chunks and therefore two questions, and every task still comes back
+    /// with exactly what its own single solve produces.
+    #[test]
+    fn batch_polls_once_per_chunk_and_answers_task_for_task() {
+        let ens = stump();
+        let cons = empty_constraints(2);
+        let xs = [0.0, 0.0, -1.0, 2.0];
+        let tasks: Vec<(usize, u64)> = (0..300).map(|i| (i % 2, i as u64 + 1)).collect();
+        let small = GaParams {
+            population: 8,
+            max_generations: 3,
+            stall_generations: 2,
+            ..params()
+        };
+        let mut polls = 0usize;
+        let outcome = solve_genetic_batch(
+            &ens,
+            &xs,
+            &tasks,
+            0.5,
+            f64::INFINITY,
+            &cons,
+            &[1.0, 1.0],
+            &[1.0, 1.0],
+            0.05,
+            None,
+            None,
+            &small,
+            &mut || {
+                polls += 1;
+                false
+            },
+        );
+        let SearchOutcome::Done(batch) = outcome else {
+            unreachable!("this probe never says stop")
+        };
+        assert_eq!(polls, 2);
+        assert_eq!(batch.len(), tasks.len());
+        for (result, &(row, seed)) in batch.iter().zip(&tasks) {
+            let single = solve_genetic(
+                &ens,
+                &xs[row * 2..(row + 1) * 2],
+                0.5,
+                f64::INFINITY,
+                &cons,
+                &[1.0, 1.0],
+                &[1.0, 1.0],
+                0.05,
+                None,
+                None,
+                Some(seed),
+                &small,
+            );
+            assert_eq!(result.generations, single.generations);
+            assert_eq!(result.x_cf, single.x_cf);
+        }
+    }
+
     #[test]
     fn frozen_target_is_infeasible() {
         let ens = stump();

treecf-0.2.2/rust/src/interrupt.rs

@@ -0,0 +1,27 @@
+//! The stop question a long-running search polls, and the answer shape it
+//! reports back with.
+//!
+//! A probe is a caller-supplied closure that takes no arguments, reads no
+//! search state and returns no value beyond "stop now?". A search polls it on
+//! a schedule fixed by its own work counters — never on anything derived from
+//! the data it is searching — and the only thing a `true` answer can do is
+//! abandon the search. So a probe that always answers `false` leaves every
+//! number a search computes exactly as it was before the probe existed.
+
+/// The stop question: `true` means abandon the search.
+///
+/// It is a `FnMut` because the real one carries state of its own (the pending
+/// error a caller wants to raise afterwards); nothing here depends on that.
+pub type InterruptProbe<'a> = &'a mut dyn FnMut() -> bool;
+
+/// What a probed search answers with.
+///
+/// `Interrupted` deliberately carries nothing. Whatever the search had found
+/// when the probe fired — an incumbent, a half-grown box, the results of the
+/// chunks already done — is dropped here, so no caller can mistake an
+/// abandoned search for a finished one.
+#[derive(Debug)]
+pub enum SearchOutcome<T> {
+    Done(T),
+    Interrupted,
+}

{treecf-0.2.0 → treecf-0.2.2}/rust/src/lib.rs

@@ -4,6 +4,7 @@ pub mod cells;
 pub mod constraints;
 pub mod exact;
 pub mod ga;
+pub mod interrupt;
 pub mod ir;
 pub mod regions;