Replace hardcoded canonical rule examples with ILPSolver calls (#775)

* Replace hardcoded canonical rule examples with ILPSolver calls

Convert 46 ILP reduction rules from hardcoded SolutionPair to dynamic
ILPSolver::new().solve() calls, ensuring canonical examples actually
verify the ILP solver can solve the reduction.

Also adds a z upper bound constraint in MinMaxMulticenter ILP formulation
to prevent HiGHS from stalling on unbounded [0, 2^31) domain.

Closes #772

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: extract rule_example_via_ilp helper, eliminating 60x boilerplate

Add `rule_example_via_ilp<S, V>()` to `example_db::specs` that performs
reduce → ILP solve → extract → assemble in one call. This replaces
the 8-line block that was copy-pasted across 60 ILP rule files, and
also eliminates the double `reduce_to()` call (once explicit, once
inside `rule_example_with_witness`).

Also fixes stale docstring on `build_example_db()` which incorrectly
claimed no solver is called.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address PR #775 review comments

- Fix indentation in ~32 canonical_rule_example_specs functions (cargo fmt)
- Fix incorrect overhead in minmaxmulticenter_ilp: num_constraints
  formula was 2n²+4n+2, correct is 2n²+3n+2 (matching actual constraint
  count: 1 cardinality + n assignment + n² link + n x-bounds + n² y-bounds
  + 1 z-bound + n minimax)
- Fix Vec::with_capacity hint to match corrected formula
- Remove 6 unused `use crate::rules::ReduceTo as _;` imports in files
  that switched to rule_example_via_ilp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: zazabap <sweynan@icloud.com>

Author: 3 people

src/example_db/mod.rs

@@ -53,8 +53,8 @@ fn validate_model_uniqueness(models: &[ModelExample]) -> Result<()> {
 
 /// Build the full example database from specs.
 ///
-/// Fast — specs store concrete instances and pre-computed solutions,
-/// no solver is called.
+/// ILP rule examples call the ILP solver at build time to compute solutions
+/// dynamically (feature-gated behind `ilp-solver`).
 pub fn build_example_db() -> Result<ExampleDb> {
     let model_db = build_model_db()?;
     let rule_db = build_rule_db()?;

src/example_db/specs.rs

@@ -62,3 +62,32 @@ where
     let target = reduction.target_problem();
     assemble_rule_example(&source, target, vec![solution])
 }
+
+/// Reduce the source to an ILP, solve it, and assemble the rule example.
+///
+/// This is the standard pattern for canonical ILP rule examples: reduce once,
+/// solve the ILP, extract the source config, and build the example — avoiding
+/// the double `reduce_to()` that would occur with `rule_example_with_witness`.
+#[cfg(feature = "ilp-solver")]
+pub fn rule_example_via_ilp<S, V>(source: S) -> RuleExample
+where
+    S: Problem + Serialize + ReduceTo<crate::models::algebraic::ILP<V>>,
+    V: crate::models::algebraic::VariableDomain,
+    <S as ReduceTo<crate::models::algebraic::ILP<V>>>::Result:
+        ReductionResult<Source = S, Target = crate::models::algebraic::ILP<V>>,
+{
+    use crate::export::SolutionPair;
+    let reduction = source.reduce_to();
+    let ilp_solution = crate::solvers::ILPSolver::new()
+        .solve(reduction.target_problem())
+        .expect("canonical example must be ILP-solvable");
+    let source_config = reduction.extract_solution(&ilp_solution);
+    assemble_rule_example(
+        &source,
+        reduction.target_problem(),
+        vec![SolutionPair {
+            source_config,
+            target_config: ilp_solution,
+        }],
+    )
+}

src/rules/bmf_ilp.rs

@@ -114,34 +114,12 @@ impl ReduceTo<ILP<bool>> for BMF {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "bmf_to_ilp",
         build: || {
             // 2x2 identity matrix, rank 2
             let source = BMF::new(vec![vec![true, false], vec![false, true]], 2);
-            // B = [[1,0],[0,1]], C = [[1,0],[0,1]]
-            // b: [1,0,0,1], c: [1,0,0,1]
-            let source_config = vec![1, 0, 0, 1, 1, 0, 0, 1];
-            let reduction: ReductionBMFToILP = ReduceTo::<ILP<bool>>::reduce_to(&source);
-            // Build target config by encoding:
-            // p_{0,0,0}=1, p_{0,0,1}=0, p_{0,1,0}=0, p_{0,1,1}=0
-            // p_{1,0,0}=0, p_{1,0,1}=0, p_{1,1,0}=0, p_{1,1,1}=1
-            // w: [1,0,0,1], e: [0,0,0,0]
-            let target_config = vec![
-                1, 0, 0, 1, // B
-                1, 0, 0, 1, // C
-                1, 0, 0, 0, 0, 0, 0, 1, // P
-                1, 0, 0, 1, // W
-                0, 0, 0, 0, // E
-            ];
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<bool>>(
-                source,
-                SolutionPair {
-                    source_config,
-                    target_config,
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, bool>(source)
         },
     }]
 }

src/rules/bottlenecktravelingsalesman_ilp.rs

@@ -174,7 +174,6 @@ impl ReduceTo<ILP<i32>> for BottleneckTravelingSalesman {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "bottlenecktravelingsalesman_to_ilp",
         build: || {
@@ -183,18 +182,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                 crate::topology::SimpleGraph::new(4, vec![(0, 1), (1, 2), (2, 3), (3, 0)]),
                 vec![1, 2, 3, 4],
             );
-            let reduction = ReduceTo::<ILP<i32>>::reduce_to(&source);
-            let ilp_solution = crate::solvers::ILPSolver::new()
-                .solve(reduction.target_problem())
-                .expect("canonical example must be solvable");
-            let source_config = reduction.extract_solution(&ilp_solution);
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<i32>>(
-                source,
-                SolutionPair {
-                    source_config,
-                    target_config: ilp_solution,
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, i32>(source)
         },
     }]
 }

src/rules/capacityassignment_ilp.rs

@@ -101,8 +101,6 @@ impl ReduceTo<ILP<bool>> for CapacityAssignment {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
-
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "capacityassignment_to_ilp",
         build: || {
@@ -121,15 +119,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                 vec![vec![8, 4], vec![7, 3]],
                 12,
             );
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<bool>>(
-                source,
-                SolutionPair {
-                    // link 0 → cap 1, link 1 → cap 0
-                    source_config: vec![1, 0],
-                    // x_{0,0}=0, x_{0,1}=1, x_{1,0}=1, x_{1,1}=0
-                    target_config: vec![0, 1, 1, 0],
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, bool>(source)
         },
     }]
 }

src/rules/consecutiveblockminimization_ilp.rs

@@ -113,7 +113,6 @@ impl ReduceTo<ILP<bool>> for ConsecutiveBlockMinimization {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "consecutiveblockminimization_to_ilp",
         build: || {
@@ -122,62 +121,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                 vec![vec![true, false, true], vec![false, true, true]],
                 2,
             );
-            // Permutation [2,0,1] => columns reordered as [2,0,1]
-            // Row 0: A[0,2]=1, A[0,0]=1, A[0,1]=0 => [1,1,0] => 1 block
-            // Row 1: A[1,2]=1, A[1,0]=0, A[1,1]=1 => [1,0,1] => 2 blocks
-            // Total = 3 > 2, try [0,2,1]:
-            // Row 0: A[0,0]=1, A[0,2]=1, A[0,1]=0 => [1,1,0] => 1 block
-            // Row 1: A[1,0]=0, A[1,2]=1, A[1,1]=1 => [0,1,1] => 1 block
-            // Total = 2 <= 2. Good.
-            let source_config = vec![0, 2, 1];
-            let reduction: ReductionCBMToILP = ReduceTo::<ILP<bool>>::reduce_to(&source);
-            // Encode x_{c,p}: column c at position p
-            // c=0 at p=0: x_{0*3+0}=1, c=2 at p=1: x_{2*3+1}=1, c=1 at p=2: x_{1*3+2}=1
-            let n = 3;
-            let mut target_config = vec![0; reduction.target.num_vars];
-            // x_{0,0} = 1
-            target_config[0 * n + 0] = 1;
-            // x_{2,1} = 1
-            target_config[2 * n + 1] = 1;
-            // x_{1,2} = 1
-            target_config[1 * n + 2] = 1;
-            // a values
-            let a_offset = n * n;
-            let m = 2;
-            let matrix = vec![vec![true, false, true], vec![false, true, true]];
-            let perm = [0, 2, 1];
-            for r in 0..m {
-                for p in 0..n {
-                    if matrix[r][perm[p]] {
-                        target_config[a_offset + r * n + p] = 1;
-                    }
-                }
-            }
-            // b values
-            let b_offset = n * n + m * n;
-            for r in 0..m {
-                for p in 0..n {
-                    let a_cur = if matrix[r][perm[p]] { 1 } else { 0 };
-                    let a_prev = if p > 0 && matrix[r][perm[p - 1]] {
-                        1
-                    } else {
-                        0
-                    };
-                    if p == 0 {
-                        target_config[b_offset + r * n + p] = a_cur;
-                    } else if a_cur > a_prev {
-                        target_config[b_offset + r * n + p] = 1;
-                    }
-                }
-            }
-
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<bool>>(
-                source,
-                SolutionPair {
-                    source_config,
-                    target_config,
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, bool>(source)
         },
     }]
 }

src/rules/consistencyofdatabasefrequencytables_ilp.rs

@@ -55,7 +55,7 @@ impl ReductionCDFTToILP {
     }
 
     /// Encode a satisfying source assignment as a concrete ILP variable vector.
-    #[cfg_attr(not(any(test, feature = "example-db")), allow(dead_code))]
+    #[cfg_attr(not(test), allow(dead_code))]
     pub(crate) fn encode_source_solution(&self, source_solution: &[usize]) -> Vec<usize> {
         let mut target_solution = vec![0usize; self.target.num_vars];
         let num_attributes = self.source.num_attributes();
@@ -204,7 +204,6 @@ impl ReduceTo<ILP<bool>> for ConsistencyOfDatabaseFrequencyTables {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
     use crate::models::misc::{FrequencyTable, KnownValue};
 
     vec![crate::example_db::specs::RuleExampleSpec {
@@ -223,16 +222,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                     KnownValue::new(1, 2, 1),
                 ],
             );
-            let source_config = vec![0, 0, 0, 0, 1, 1, 0, 2, 1, 1, 0, 1, 1, 1, 1, 1, 2, 0];
-            let reduction = source.clone().reduce_to();
-            let target_config = reduction.encode_source_solution(&source_config);
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<bool>>(
-                source,
-                SolutionPair {
-                    source_config,
-                    target_config,
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, bool>(source)
         },
     }]
 }

src/rules/directedtwocommodityintegralflow_ilp.rs

@@ -147,7 +147,6 @@ impl ReduceTo<ILP<i32>> for DirectedTwoCommodityIntegralFlow {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
     use crate::topology::DirectedGraph;
 
     vec![crate::example_db::specs::RuleExampleSpec {
@@ -178,16 +177,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                 1,
                 1,
             );
-            // first 8 = f1, next 8 = f2
-            // f1: arc(0,2)=1, arc(2,4)=1, rest=0 → [1,0,0,0,1,0,0,0]
-            // f2: arc(1,3)=1, arc(3,5)=1, rest=0 → [0,0,0,1,0,0,0,1]
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<i32>>(
-                source,
-                SolutionPair {
-                    source_config: vec![1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1],
-                    target_config: vec![1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1],
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, i32>(source)
         },
     }]
 }

src/rules/disjointconnectingpaths_ilp.rs

@@ -170,9 +170,6 @@ impl ReduceTo<ILP<bool>> for DisjointConnectingPaths<SimpleGraph> {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
-    use crate::rules::ReduceTo as _;
-
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "disjointconnectingpaths_to_ilp",
         build: || {
@@ -181,18 +178,7 @@ pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::Ru
                 SimpleGraph::new(6, vec![(0, 1), (1, 2), (3, 4), (4, 5)]),
                 vec![(0, 2), (3, 5)],
             );
-            let reduction = ReduceTo::<ILP<bool>>::reduce_to(&source);
-            let ilp_solution = crate::solvers::ILPSolver::new()
-                .solve(reduction.target_problem())
-                .expect("canonical example must be solvable");
-            let source_config = reduction.extract_solution(&ilp_solution);
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<bool>>(
-                source,
-                SolutionPair {
-                    source_config,
-                    target_config: ilp_solution,
-                },
-            )
+            crate::example_db::specs::rule_example_via_ilp::<_, bool>(source)
         },
     }]
 }

src/rules/factoring_ilp.rs

@@ -223,20 +223,11 @@ impl ReduceTo<ILP<i32>> for Factoring {
 
 #[cfg(feature = "example-db")]
 pub(crate) fn canonical_rule_example_specs() -> Vec<crate::example_db::specs::RuleExampleSpec> {
-    use crate::export::SolutionPair;
-
     vec![crate::example_db::specs::RuleExampleSpec {
         id: "factoring_to_ilp",
         build: || {
-            crate::example_db::specs::rule_example_with_witness::<_, ILP<i32>>(
-                Factoring::new(3, 3, 35),
-                SolutionPair {
-                    source_config: vec![1, 0, 1, 1, 1, 1],
-                    target_config: vec![
-                        1, 0, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 0,
-                    ],
-                },
-            )
+            let source = Factoring::new(3, 3, 35);
+            crate::example_db::specs::rule_example_via_ilp::<_, i32>(source)
         },
     }]
 }