feat: add CustomizedSolver with structure-exploiting backends (#766)

* feat: add shared ILP linearization helpers (McCormick, MTZ, flow, big-M, abs-diff, minimax, one-hot)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add customized solver scaffolding

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: expose customized solver in cli dispatch

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add fd subset backend and wire four FD models in customized solver

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add partial feedback edge set backend

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add rooted tree arrangement backend

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: document customized solver behavior and add CLI tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: handle customized solver CLI and MCP paths

* test: harden customized solver parity coverage

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: GiggleLiu

problemreductions-cli/src/cli.rs

@@ -738,6 +738,7 @@ pub struct CreateArgs {
 Examples:
   pred solve problem.json                        # ILP solver (default, auto-reduces to ILP)
   pred solve problem.json --solver brute-force   # brute-force (exhaustive search)
+  pred solve problem.json --solver customized    # customized (structure-exploiting exact solver)
   pred solve reduced.json                        # solve a reduction bundle
   pred solve reduced.json -o solution.json       # save result to file
   pred create MIS --graph 0-1,1-2 | pred solve - # read from stdin when an ILP path exists
@@ -761,14 +762,18 @@ Problems without an ILP reduction path, such as `GroupingBySwapping`,
 `LengthBoundedDisjointPaths`, `MinMaxMulticenter`, and `StringToStringCorrection`,
 currently need `--solver brute-force`.
 
+Customized solver: exact witness recovery for select problems via structure-exploiting
+backends. Currently supports MinimumCardinalityKey, AdditionalKey, PrimeAttributeName,
+BoyceCoddNormalFormViolation, PartialFeedbackEdgeSet, and RootedTreeArrangement.
+
 ILP backend (default: HiGHS). To use a different backend:
   cargo install problemreductions-cli --features coin-cbc
   cargo install problemreductions-cli --features scip
   cargo install problemreductions-cli --no-default-features --features clarabel")]
 pub struct SolveArgs {
     /// Problem JSON file (from `pred create`) or reduction bundle (from `pred reduce`). Use - for stdin.
     pub input: PathBuf,
-    /// Solver: ilp (default) or brute-force
+    /// Solver: ilp (default), brute-force, or customized
     #[arg(long, default_value = "ilp")]
     pub solver: String,
     /// Timeout in seconds (0 = no limit)

problemreductions-cli/src/commands/inspect.rs

@@ -40,16 +40,18 @@ fn inspect_problem(pj: &ProblemJson, out: &OutputConfig) -> Result<()> {
     }
     text.push_str(&format!("Variables: {}\n", problem.num_variables_dyn()));
 
-    let solvers = if problem.supports_ilp_solver() {
-        vec!["ilp", "brute-force"]
-    } else {
-        vec!["brute-force"]
-    };
-    let solver_summary = if solvers.first() == Some(&"ilp") {
-        "ilp (default), brute-force".to_string()
-    } else {
-        "brute-force".to_string()
-    };
+    let solvers = problem.available_solvers();
+    let solver_summary = solvers
+        .iter()
+        .map(|solver| {
+            if *solver == "ilp" {
+                "ilp (default)".to_string()
+            } else {
+                (*solver).to_string()
+            }
+        })
+        .collect::<Vec<_>>()
+        .join(", ");
     text.push_str(&format!("Solvers: {solver_summary}\n"));
 
     // Reductions

problemreductions-cli/src/commands/solve.rs

@@ -66,9 +66,9 @@ fn plain_problem_output(
 }
 
 pub fn solve(input: &Path, solver_name: &str, timeout: u64, out: &OutputConfig) -> Result<()> {
-    if solver_name != "brute-force" && solver_name != "ilp" {
+    if solver_name != "brute-force" && solver_name != "ilp" && solver_name != "customized" {
         anyhow::bail!(
-            "Unknown solver: {}. Available solvers: brute-force, ilp",
+            "Unknown solver: {}. Available solvers: brute-force, ilp, customized",
             solver_name
         );
     }
@@ -145,6 +145,21 @@ fn solve_problem(
             }
             result
         }
+        "customized" => {
+            let result = problem
+                .solve_with_customized()
+                .map_err(add_customized_solver_hint)?;
+            let result = crate::dispatch::SolveResult {
+                config: Some(result.config),
+                evaluation: result.evaluation,
+            };
+            let (text, json) = plain_problem_output(name, "customized", &result);
+            let result = out.emit_with_default_name("", &text, &json);
+            if out.output.is_none() && crate::output::stderr_is_tty() {
+                out.info("\nHint: use -o to save full solution details as JSON.");
+            }
+            result
+        }
         _ => unreachable!(),
     }
 }
@@ -168,6 +183,9 @@ fn solve_bundle(bundle: ReductionBundle, solver_name: &str, out: &OutputConfig)
             )
         })?,
         "ilp" => target.solve_with_ilp().map_err(add_ilp_solver_hint)?,
+        "customized" => target
+            .solve_with_customized()
+            .map_err(add_customized_solver_hint)?,
         _ => unreachable!(),
     };
 
@@ -229,6 +247,17 @@ fn solve_bundle(bundle: ReductionBundle, solver_name: &str, out: &OutputConfig)
     result
 }
 
+fn add_customized_solver_hint(err: anyhow::Error) -> anyhow::Error {
+    let message = err.to_string();
+    if message.contains("unsupported by customized solver") {
+        anyhow::anyhow!(
+            "{message}\n\nHint: the customized solver only supports select problems (FD-based models, PartialFeedbackEdgeSet, RootedTreeArrangement).\nTry `--solver brute-force` or `--solver ilp` instead."
+        )
+    } else {
+        err
+    }
+}
+
 fn add_ilp_solver_hint(err: anyhow::Error) -> anyhow::Error {
     let message = err.to_string();
     if (message.starts_with("No reduction path from ") && message.ends_with(" to ILP"))

problemreductions-cli/src/dispatch.rs

@@ -1,7 +1,7 @@
 use anyhow::{Context, Result};
 use problemreductions::registry::{DynProblem, LoadedDynProblem};
 use problemreductions::rules::{MinimizeSteps, ReductionGraph, ReductionMode};
-use problemreductions::solvers::ILPSolver;
+use problemreductions::solvers::{CustomizedSolver, ILPSolver};
 use problemreductions::types::ProblemSize;
 use serde_json::Value;
 use std::any::Any;
@@ -75,12 +75,29 @@ impl LoadedProblem {
         }
     }
 
+    pub fn supports_customized_solver(&self) -> bool {
+        CustomizedSolver::supports_problem(self.as_any())
+    }
+
+    pub fn solve_with_customized(&self) -> Result<WitnessSolveResult> {
+        let solver = CustomizedSolver::new();
+        let config = solver
+            .solve_dyn(self.as_any())
+            .ok_or_else(|| anyhow::anyhow!("Problem unsupported by customized solver"))?;
+        let evaluation = self.evaluate_dyn(&config);
+        Ok(WitnessSolveResult { config, evaluation })
+    }
+
     #[cfg_attr(not(feature = "mcp"), allow(dead_code))]
     pub fn available_solvers(&self) -> Vec<&'static str> {
-        let mut solvers = vec!["brute-force"];
+        let mut solvers = Vec::new();
         if self.supports_ilp_solver() {
             solvers.push("ilp");
         }
+        solvers.push("brute-force");
+        if self.supports_customized_solver() {
+            solvers.push("customized");
+        }
         solvers
     }
 
@@ -270,6 +287,34 @@ mod tests {
         assert_eq!(result.evaluation, "Sum(56)");
     }
 
+    #[test]
+    fn test_available_solvers_excludes_customized_for_unsupported_problem() {
+        let loaded = load_problem(
+            AGGREGATE_SOURCE_NAME,
+            &BTreeMap::new(),
+            serde_json::to_value(AggregateValueSource::sample()).unwrap(),
+        )
+        .unwrap();
+
+        assert!(!loaded.available_solvers().contains(&"customized"));
+    }
+
+    #[test]
+    fn test_solve_with_customized_rejects_unsupported_problem() {
+        let loaded = load_problem(
+            AGGREGATE_SOURCE_NAME,
+            &BTreeMap::new(),
+            serde_json::to_value(AggregateValueSource::sample()).unwrap(),
+        )
+        .unwrap();
+
+        let err = loaded.solve_with_customized().unwrap_err();
+        assert!(
+            err.to_string().contains("unsupported by customized solver"),
+            "unexpected error: {err}"
+        );
+    }
+
     #[test]
     fn test_solve_with_ilp_rejects_aggregate_only_problem() {
         let loaded = load_problem(

problemreductions-cli/src/mcp/tests.rs

@@ -353,6 +353,27 @@ mod tests {
         assert!(json["solution"].is_array());
     }
 
+    #[test]
+    fn test_solve_customized_supported_problem() {
+        let server = McpServer::new();
+        let problem_json = serde_json::json!({
+            "type": "MinimumCardinalityKey",
+            "variant": {},
+            "data": {
+                "num_attributes": 4,
+                "dependencies": [[[0], [1, 2]], [[1, 2], [3]]],
+                "bound": 2
+            }
+        })
+        .to_string();
+
+        let result = server.solve_inner(&problem_json, Some("customized"), None);
+        assert!(result.is_ok(), "solve failed: {:?}", result);
+        let json: serde_json::Value = serde_json::from_str(&result.unwrap()).unwrap();
+        assert_eq!(json["solver"], "customized");
+        assert!(json["solution"].is_array(), "{json}");
+    }
+
     #[test]
     fn test_solve_unknown_solver() {
         let server = McpServer::new();
@@ -374,6 +395,20 @@ mod tests {
         assert_eq!(json["problem"], "MaximumIndependentSet");
     }
 
+    #[test]
+    fn test_solve_customized_bundle_rejects_unsupported_target_without_panicking() {
+        let server = McpServer::new();
+        let problem_json = create_test_mis(&server);
+        let bundle_json = server.reduce_inner(&problem_json, "QUBO").unwrap();
+        let result = server.solve_inner(&bundle_json, Some("customized"), None);
+        assert!(result.is_err());
+        let err = result.unwrap_err().to_string();
+        assert!(
+            err.contains("unsupported by customized solver"),
+            "unexpected error: {err}"
+        );
+    }
+
     #[test]
     fn test_inspect_bundle() {
         let server = McpServer::new();
@@ -421,6 +456,35 @@ mod tests {
         assert_eq!(solvers, vec!["brute-force"]);
     }
 
+    #[test]
+    fn test_inspect_minimum_cardinality_key_lists_customized_solver() {
+        let server = McpServer::new();
+        let problem_json = serde_json::json!({
+            "type": "MinimumCardinalityKey",
+            "variant": {},
+            "data": {
+                "num_attributes": 4,
+                "dependencies": [[[0], [1, 2]], [[1, 2], [3]]],
+                "bound": 2
+            }
+        })
+        .to_string();
+
+        let result = server.inspect_problem_inner(&problem_json);
+        assert!(result.is_ok(), "inspect failed: {:?}", result);
+        let json: serde_json::Value = serde_json::from_str(&result.unwrap()).unwrap();
+        let solvers: Vec<&str> = json["solvers"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .map(|v| v.as_str().unwrap())
+            .collect();
+        assert!(
+            solvers.contains(&"customized"),
+            "inspect should list customized when supported, got: {json}"
+        );
+    }
+
     #[test]
     fn test_solve_sat_problem() {
         let server = McpServer::new();

problemreductions-cli/src/mcp/tools.rs

@@ -103,7 +103,7 @@ pub struct ReduceParams {
 pub struct SolveParams {
     #[schemars(description = "Problem JSON string (from create_problem or reduce)")]
     pub problem_json: String,
-    #[schemars(description = "Solver: 'ilp' (default) or 'brute-force'")]
+    #[schemars(description = "Solver: 'ilp' (default), 'brute-force', or 'customized'")]
     pub solver: Option<String>,
     #[schemars(description = "Timeout in seconds (0 = no limit, default: 0)")]
     pub timeout: Option<u64>,
@@ -880,9 +880,9 @@ impl McpServer {
         timeout: Option<u64>,
     ) -> anyhow::Result<String> {
         let solver_name = solver.unwrap_or("ilp");
-        if solver_name != "brute-force" && solver_name != "ilp" {
+        if solver_name != "brute-force" && solver_name != "ilp" && solver_name != "customized" {
             anyhow::bail!(
-                "Unknown solver: {}. Available solvers: brute-force, ilp",
+                "Unknown solver: {}. Available solvers: brute-force, ilp, customized",
                 solver_name
             );
         }
@@ -1040,7 +1040,7 @@ impl McpServer {
             .map_err(|e| e.to_string())
     }
 
-    /// Solve a problem instance using brute-force or ILP solver
+    /// Solve a problem instance using brute-force, ILP, or customized solver
     #[tool(
         name = "solve",
         annotations(read_only_hint = true, open_world_hint = false)
@@ -1488,6 +1488,15 @@ fn solve_problem_inner(
             }
             Ok(serde_json::to_string_pretty(&json)?)
         }
+        "customized" => {
+            let result = problem.solve_with_customized()?;
+            let result = crate::dispatch::SolveResult {
+                config: Some(result.config),
+                evaluation: result.evaluation,
+            };
+            let json = solve_result_json(name, "customized", &result);
+            Ok(serde_json::to_string_pretty(&json)?)
+        }
         _ => unreachable!(),
     }
 }
@@ -1509,6 +1518,7 @@ fn solve_bundle_inner(bundle: ReductionBundle, solver_name: &str) -> anyhow::Res
             )
         })?,
         "ilp" => target.solve_with_ilp()?,
+        "customized" => target.solve_with_customized()?,
         _ => unreachable!(),
     };