Fix #492: [Model] 3Partition (#759)

* Add plan for #492: [Model] 3Partition

* Implement #492: [Model] 3Partition

* chore: remove plan file after implementation

* cargo fmt

* Adapt ThreePartition to current API: Value=Or, declare_variants!, find_witness

* Paper: derive 3-Partition example groups from optimal_config instead of hardcoded slices

* Hoist u128 bound conversion out of validation loop

---------

Co-authored-by: Xiwei Pan <xiwei.pan@connect.hkust-gz.edu.cn>

Author: GiggleLiu

docs/paper/reductions.typ

@@ -145,6 +145,7 @@
   "ExactCoverBy3Sets": [Exact Cover by 3-Sets],
   "SubsetSum": [Subset Sum],
   "Partition": [Partition],
+  "ThreePartition": [3-Partition],
   "PartialFeedbackEdgeSet": [Partial Feedback Edge Set],
   "MinimumFeedbackArcSet": [Minimum Feedback Arc Set],
   "MinimumFeedbackVertexSet": [Minimum Feedback Vertex Set],
@@ -4587,6 +4588,43 @@ A classical NP-complete problem from Garey and Johnson @garey1979[Ch.~3, p.~76],
   *Example.* Let $A = {5, 3, 8, 2, 7, 1}$ ($n = 6$) and $K = 3$ groups. The partition $A_1 = {8, 1}$, $A_2 = {5, 2}$, $A_3 = {3, 7}$ gives group sums $9, 7, 10$ and sum of squares $81 + 49 + 100 = 230$. The optimal partition has group sums ${9, 9, 8}$ yielding $81 + 81 + 64 = 226$.
 ]
 
+#{
+  let x = load-model-example("ThreePartition")
+  let sizes = x.instance.sizes
+  let bound = x.instance.bound
+  let config = x.optimal_config
+  let m = int(sizes.len() / 3)
+  // Group elements by their assignment in optimal_config
+  let groups = range(m).map(g => {
+    let indices = range(sizes.len()).filter(i => config.at(i) == g)
+    indices.map(i => sizes.at(i))
+  })
+  [
+    #problem-def("ThreePartition")[
+      Given a set $A = {a_0, dots, a_(3m-1)}$ of $3m$ elements, a bound $B in ZZ^+$, and sizes $s(a) in ZZ^+$ such that $B/4 lt s(a) lt B/2$ for every $a in A$ and $sum_(a in A) s(a) = m B$, determine whether $A$ can be partitioned into $m$ disjoint triples $A_1, dots, A_m$ with $sum_(a in A_i) s(a) = B$ for every $i$.
+    ][
+      3-Partition is Garey and Johnson's strongly NP-complete benchmark SP15 @garey1979. Unlike ordinary Partition, the strict size window forces every feasible block to contain exactly three elements, making the problem the canonical source for strong NP-completeness reductions to scheduling, packing, and layout models. The implementation in this repository uses one group-assignment variable per element, so the exported exact-search baseline is $O^*(3^n)$#footnote[This is the direct worst-case bound induced by the implementation's configuration space and matches the registered catalog expression `3^num_elements`; no sharper general exact bound was independently verified while preparing this entry.].
+
+      *Example.* Let $B = #bound$ and consider the #(sizes.len())-element instance with sizes $(#sizes.map(str).join(", "))$. The witness triples #groups.enumerate().map(((i, g)) => [$A_#(i+1) = {#g.map(str).join(", ")}$]).join([ and ]) both sum to $#bound$, so this instance is satisfiable.
+
+      #pred-commands(
+        "pred create --example ThreePartition -o three-partition.json",
+        "pred solve three-partition.json",
+        "pred evaluate three-partition.json --config " + config.map(str).join(","),
+      )
+
+      #align(center, table(
+        columns: 3,
+        align: center,
+        table.header([Triple], [Elements], [Sum]),
+        ..groups.enumerate().map(((i, g)) => (
+          [$A_#(i+1)$], [$#(g.map(str).join(", "))$], [$#bound$],
+        )).flatten(),
+      ))
+    ]
+  ]
+}
+
 #{
   let x = load-model-example("SequencingWithReleaseTimesAndDeadlines")
   let n = x.instance.lengths.len()

problemreductions-cli/src/cli.rs

@@ -247,6 +247,7 @@ Flags by problem type:
   BinPacking                      --sizes, --capacity
   CapacityAssignment              --capacities, --cost-matrix, --delay-matrix, --delay-budget
   SubsetSum                       --sizes, --target
+  ThreePartition                  --sizes, --bound
   SumOfSquaresPartition           --sizes, --num-groups
   ExpectedRetrievalCost           --probabilities, --num-sectors
   PaintShop                       --sequence

problemreductions-cli/src/commands/create.rs

@@ -29,7 +29,7 @@ use problemreductions::models::misc::{
     SequencingToMinimizeMaximumCumulativeCost, SequencingToMinimizeWeightedCompletionTime,
     SequencingToMinimizeWeightedTardiness, SequencingWithReleaseTimesAndDeadlines,
     SequencingWithinIntervals, ShortestCommonSupersequence, StringToStringCorrection, SubsetSum,
-    SumOfSquaresPartition, TimetableDesign,
+    SumOfSquaresPartition, ThreePartition, TimetableDesign,
 };
 use problemreductions::models::BiconnectivityAugmentation;
 use problemreductions::prelude::*;
@@ -668,6 +668,7 @@ fn example_for(canonical: &str, graph_type: Option<&str>) -> &'static str {
             "--sizes 3,4,2,5,3 --weights 2,3,1,4,2 --deadlines 5,8,4,15,10 --bound 13"
         }
         "SubsetSum" => "--sizes 3,7,1,8,2,4 --target 11",
+        "ThreePartition" => "--sizes 4,5,6,4,6,5 --bound 15",
         "BoyceCoddNormalFormViolation" => {
             "--n 6 --sets \"0,1:2;2:3;3,4:5\" --target 0,1,2,3,4,5"
         }
@@ -2288,6 +2289,33 @@ pub fn create(args: &CreateArgs, out: &OutputConfig) -> Result<()> {
             )
         }
 
+        // ThreePartition
+        "ThreePartition" => {
+            let sizes_str = args.sizes.as_deref().ok_or_else(|| {
+                anyhow::anyhow!(
+                    "ThreePartition requires --sizes and --bound\n\n\
+                     Usage: pred create ThreePartition --sizes 4,5,6,4,6,5 --bound 15"
+                )
+            })?;
+            let bound = args.bound.ok_or_else(|| {
+                anyhow::anyhow!(
+                    "ThreePartition requires --bound\n\n\
+                     Usage: pred create ThreePartition --sizes 4,5,6,4,6,5 --bound 15"
+                )
+            })?;
+            let bound = u64::try_from(bound).map_err(|_| {
+                anyhow::anyhow!(
+                    "ThreePartition requires a positive integer --bound\n\n\
+                     Usage: pred create ThreePartition --sizes 4,5,6,4,6,5 --bound 15"
+                )
+            })?;
+            let sizes: Vec<u64> = util::parse_comma_list(sizes_str)?;
+            (
+                ser(ThreePartition::try_new(sizes, bound).map_err(anyhow::Error::msg)?)?,
+                resolved_variant.clone(),
+            )
+        }
+
         // SumOfSquaresPartition
         "SumOfSquaresPartition" => {
             let sizes_str = args.sizes.as_deref().ok_or_else(|| {
@@ -6501,6 +6529,104 @@ mod tests {
         assert!(example.contains("--requirement"));
     }
 
+    #[test]
+    fn test_example_for_three_partition_mentions_sizes_and_bound() {
+        let example = example_for("ThreePartition", None);
+        assert!(example.contains("--sizes"));
+        assert!(example.contains("--bound"));
+    }
+
+    #[test]
+    fn test_create_three_partition_outputs_problem_json() {
+        let cli = Cli::try_parse_from([
+            "pred",
+            "create",
+            "ThreePartition",
+            "--sizes",
+            "4,5,6,4,6,5",
+            "--bound",
+            "15",
+        ])
+        .expect("parse create command");
+
+        let args = match cli.command {
+            Commands::Create(args) => args,
+            _ => panic!("expected create command"),
+        };
+
+        let output_path = temp_output_path("three_partition_create");
+        let out = OutputConfig {
+            output: Some(output_path.clone()),
+            quiet: true,
+            json: false,
+            auto_json: false,
+        };
+
+        create(&args, &out).expect("create ThreePartition JSON");
+
+        let created: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&output_path).unwrap()).unwrap();
+        fs::remove_file(output_path).ok();
+
+        assert_eq!(created["type"], "ThreePartition");
+        assert_eq!(
+            created["data"]["sizes"],
+            serde_json::json!([4, 5, 6, 4, 6, 5])
+        );
+        assert_eq!(created["data"]["bound"], 15);
+    }
+
+    #[test]
+    fn test_create_three_partition_requires_bound() {
+        let cli =
+            Cli::try_parse_from(["pred", "create", "ThreePartition", "--sizes", "4,5,6,4,6,5"])
+                .expect("parse create command");
+
+        let args = match cli.command {
+            Commands::Create(args) => args,
+            _ => panic!("expected create command"),
+        };
+
+        let out = OutputConfig {
+            output: None,
+            quiet: true,
+            json: false,
+            auto_json: false,
+        };
+
+        let err = create(&args, &out).unwrap_err().to_string();
+        assert!(err.contains("ThreePartition requires --bound"));
+    }
+
+    #[test]
+    fn test_create_three_partition_rejects_invalid_instance() {
+        let cli = Cli::try_parse_from([
+            "pred",
+            "create",
+            "ThreePartition",
+            "--sizes",
+            "4,5,6,4,6,5",
+            "--bound",
+            "14",
+        ])
+        .expect("parse create command");
+
+        let args = match cli.command {
+            Commands::Create(args) => args,
+            _ => panic!("expected create command"),
+        };
+
+        let out = OutputConfig {
+            output: None,
+            quiet: true,
+            json: false,
+            auto_json: false,
+        };
+
+        let err = create(&args, &out).unwrap_err().to_string();
+        assert!(err.contains("must equal m * bound"));
+    }
+
     #[test]
     fn test_create_timetable_design_outputs_problem_json() {
         let cli = Cli::try_parse_from([

problemreductions-cli/src/problem_name.rs

@@ -281,6 +281,8 @@ mod tests {
         assert_eq!(resolve_alias("MVC"), "MinimumVertexCover");
         assert_eq!(resolve_alias("SAT"), "Satisfiability");
         assert_eq!(resolve_alias("X3C"), "ExactCoverBy3Sets");
+        assert_eq!(resolve_alias("3Partition"), "ThreePartition");
+        assert_eq!(resolve_alias("3-partition"), "ThreePartition");
         // 3SAT is no longer a registered alias (removed to avoid confusion with KSatisfiability/KN)
         assert_eq!(resolve_alias("3SAT"), "3SAT"); // pass-through
         assert_eq!(resolve_alias("QUBO"), "QUBO");

src/lib.rs

@@ -78,7 +78,8 @@ pub mod prelude {
         SequencingToMinimizeMaximumCumulativeCost, SequencingToMinimizeWeightedCompletionTime,
         SequencingToMinimizeWeightedTardiness, SequencingWithReleaseTimesAndDeadlines,
         SequencingWithinIntervals, ShortestCommonSupersequence, StackerCrane, StaffScheduling,
-        StringToStringCorrection, SubsetSum, SumOfSquaresPartition, Term, TimetableDesign,
+        StringToStringCorrection, SubsetSum, SumOfSquaresPartition, Term, ThreePartition,
+        TimetableDesign,
     };
     pub use crate::models::set::{
         ComparativeContainment, ConsecutiveSets, ExactCoverBy3Sets, MaximumSetPacking,

src/models/misc/mod.rs

@@ -68,6 +68,7 @@ mod staff_scheduling;
 pub(crate) mod string_to_string_correction;
 mod subset_sum;
 pub(crate) mod sum_of_squares_partition;
+mod three_partition;
 mod timetable_design;
 
 pub use additional_key::AdditionalKey;
@@ -106,6 +107,7 @@ pub use staff_scheduling::StaffScheduling;
 pub use string_to_string_correction::StringToStringCorrection;
 pub use subset_sum::SubsetSum;
 pub use sum_of_squares_partition::SumOfSquaresPartition;
+pub use three_partition::ThreePartition;
 pub use timetable_design::TimetableDesign;
 
 #[cfg(feature = "example-db")]
@@ -146,5 +148,6 @@ pub(crate) fn canonical_model_example_specs() -> Vec<crate::example_db::specs::M
     specs.extend(bin_packing::canonical_model_example_specs());
     specs.extend(knapsack::canonical_model_example_specs());
     specs.extend(subset_sum::canonical_model_example_specs());
+    specs.extend(three_partition::canonical_model_example_specs());
     specs
 }