Fix #440: [Model] GroupingBySwapping (#758)

* Add plan for #440: [Model] GroupingBySwapping

* Implement #440: [Model] GroupingBySwapping

* chore: remove plan file after implementation

---------

Co-authored-by: Xiwei Pan <90967972+isPANN@users.noreply.github.com>

Author: GiggleLiu

docs/paper/reductions.typ

@@ -145,6 +145,7 @@
   "IntegralFlowWithMultipliers": [Integral Flow With Multipliers],
   "MinMaxMulticenter": [Min-Max Multicenter],
   "FlowShopScheduling": [Flow Shop Scheduling],
+  "GroupingBySwapping": [Grouping by Swapping],
   "MinimumCutIntoBoundedSets": [Minimum Cut Into Bounded Sets],
   "MinimumDummyActivitiesPert": [Minimum Dummy Activities in PERT Networks],
   "MinimumSumMulticenter": [Minimum Sum Multicenter],
@@ -4381,6 +4382,67 @@ A classical NP-complete problem from Garey and Johnson @garey1979[Ch.~3, p.~76],
   ]
 }
 
+#{
+  let x = load-model-example("GroupingBySwapping")
+  let source = x.instance.string
+  let alpha-size = x.instance.alphabet_size
+  let budget = x.instance.budget
+  let config = x.optimal_config
+  let alpha-map = range(alpha-size).map(i => str.from-unicode(97 + i))
+  let fmt-str(s) = s.map(c => alpha-map.at(c)).join("")
+  let source-str = fmt-str(source)
+  let step1 = (0, 1, 0, 2, 1, 2)
+  let step2 = (0, 0, 1, 2, 1, 2)
+  let step3 = (0, 0, 1, 1, 2, 2)
+  let step3-str = fmt-str(step3)
+  [
+    #problem-def("GroupingBySwapping")[
+      Given a finite alphabet $Sigma$, a string $x in Sigma^*$, and a positive integer $K$, determine whether there exists a sequence of at most $K$ adjacent symbol interchanges that transforms $x$ into a string $y in Sigma^*$ in which every symbol $a in Sigma$ appears in a single contiguous block. Equivalently, $y$ contains no subsequence $a b a$ with distinct $a, b in Sigma$.
+    ][
+      Grouping by Swapping is the storage-and-retrieval problem SR21 in Garey and Johnson @garey1979. It asks whether a string can be locally reorganized, using only adjacent transpositions, until equal symbols coalesce into blocks. The implementation in this crate uses a fixed-length swap program with one slot per allowed operation, so the direct brute-force search explores $O(|x|^K)$ configurations.#footnote[This is the exact search bound induced by the fixed-length witness encoding implemented in the codebase; no sharper exact worst-case bound is claimed here.]
+
+      *Example.* Let $Sigma = {#alpha-map.join(", ")}$, $x = #source-str$, and $K = #budget$. The configuration $p = (#config.map(str).join(", "))$ performs adjacent swaps at positions $(2, 3)$, $(1, 2)$, and $(3, 4)$, then uses two trailing no-op slots. The resulting string is $y = #step3-str$, so every symbol now appears in one contiguous block and the verifier returns YES.
+
+      #pred-commands(
+        "pred create --example " + problem-spec(x) + " -o grouping-by-swapping.json",
+        "pred solve grouping-by-swapping.json --solver brute-force",
+        "pred evaluate grouping-by-swapping.json --config " + x.optimal_config.map(str).join(","),
+      )
+
+      #figure({
+        let blue = graph-colors.at(0)
+        let cell(ch, highlight: false) = {
+          let fill = if highlight { blue.transparentize(72%) } else { white }
+          box(width: 0.55cm, height: 0.55cm, fill: fill, stroke: 0.5pt + luma(120),
+            align(center + horizon, text(9pt, weight: "bold", ch)))
+        }
+        align(center, stack(dir: ttb, spacing: 0.45cm,
+          stack(dir: ltr, spacing: 0pt,
+            box(width: 2.2cm, height: 0.5cm, align(right + horizon, text(8pt)[$x: quad$])),
+            ..source.map(c => cell(alpha-map.at(c))),
+          ),
+          stack(dir: ltr, spacing: 0pt,
+            box(width: 2.2cm, height: 0.5cm, align(right + horizon, text(8pt)[swap$(2,3)$: quad])),
+            ..step1.enumerate().map(((i, c)) => cell(alpha-map.at(c), highlight: i == 2 or i == 3)),
+          ),
+          stack(dir: ltr, spacing: 0pt,
+            box(width: 2.2cm, height: 0.5cm, align(right + horizon, text(8pt)[swap$(1,2)$: quad])),
+            ..step2.enumerate().map(((i, c)) => cell(alpha-map.at(c), highlight: i == 1 or i == 2)),
+          ),
+          stack(dir: ltr, spacing: 0pt,
+            box(width: 2.2cm, height: 0.5cm, align(right + horizon, text(8pt)[swap$(3,4)$: quad])),
+            ..step3.enumerate().map(((i, c)) => cell(alpha-map.at(c), highlight: i == 3 or i == 4)),
+          ),
+        ))
+      },
+      caption: [Grouping by Swapping on $x = #source-str$: three effective adjacent swaps turn the alternating string into $y = #step3-str$. The remaining two slots in $p = (#config.map(str).join(", "))$ are no-ops at position 5.],
+      ) <fig:grouping-by-swapping>
+
+      The final row has exactly one block of $a$, one block of $b$, and one block of $c$, so it satisfies the grouping constraint within the allotted budget.
+    ]
+  ]
+}
+
 #{
   let x = load-model-example("LongestCommonSubsequence")
   let strings = x.instance.strings

problemreductions-cli/src/cli.rs

@@ -287,6 +287,7 @@ Flags by problem type:
   AdditionalKey                   --num-attributes, --dependencies, --relation-attrs [--known-keys]
   ConsistencyOfDatabaseFrequencyTables --num-objects, --attribute-domains, --frequency-tables [--known-values]
   SubgraphIsomorphism             --graph (host), --pattern (pattern)
+  GroupingBySwapping             --string, --bound [--alphabet-size]
   LCS                             --strings, --bound [--alphabet-size]
   FAS                             --arcs [--weights] [--num-vertices]
   FVS                             --arcs [--weights] [--num-vertices]
@@ -331,6 +332,7 @@ Examples:
   pred create GeneralizedHex --graph 0-1,0-2,0-3,1-4,2-4,3-4,4-5 --source 0 --sink 5
   pred create IntegralFlowWithMultipliers --arcs \"0>1,0>2,1>3,2>3\" --capacities 1,1,2,2 --source 0 --sink 3 --multipliers 1,2,3,1 --requirement 2
   pred create MultipleChoiceBranching/i32 --arcs \"0>1,0>2,1>3,2>3,1>4,3>5,4>5,2>4\" --weights 3,2,4,1,2,3,1,3 --partition \"0,1;2,3;4,7;5,6\" --bound 10
+  pred create GroupingBySwapping --string \"0,1,2,0,1,2\" --bound 5 | pred solve - --solver brute-force
   pred create StringToStringCorrection --source-string \"0,1,2,3,1,0\" --target-string \"0,1,3,2,1\" --bound 2 | pred solve - --solver brute-force
   pred create MIS/KingsSubgraph --positions \"0,0;1,0;1,1;0,1\"
   pred create MIS/UnitDiskGraph --positions \"0,0;1,0;0.5,0.8\" --radius 1.5
@@ -551,7 +553,7 @@ pub struct CreateArgs {
     /// Required edge indices for RuralPostman (comma-separated, e.g., "0,2,4")
     #[arg(long)]
     pub required_edges: Option<String>,
-    /// Bound parameter (lower bound for LongestCircuit; upper or length bound for BoundedComponentSpanningForest, LengthBoundedDisjointPaths, LongestCommonSubsequence, MultipleCopyFileAllocation, MultipleChoiceBranching, OptimalLinearArrangement, RootedTreeArrangement, RuralPostman, ShortestCommonSupersequence, or StringToStringCorrection)
+    /// Bound parameter (lower bound for LongestCircuit; upper or length bound for BoundedComponentSpanningForest, GroupingBySwapping, LengthBoundedDisjointPaths, LongestCommonSubsequence, MultipleCopyFileAllocation, MultipleChoiceBranching, OptimalLinearArrangement, RootedTreeArrangement, RuralPostman, ShortestCommonSupersequence, or StringToStringCorrection)
     #[arg(long, allow_hyphen_values = true)]
     pub bound: Option<i64>,
     /// Upper bound on expected retrieval latency for ExpectedRetrievalCost
@@ -578,6 +580,9 @@ pub struct CreateArgs {
     /// Input strings for LCS (e.g., "ABAC;BACA" or "0,1,0;1,0,1") or SCS (e.g., "0,1,2;1,2,0")
     #[arg(long)]
     pub strings: Option<String>,
+    /// Input string for GroupingBySwapping (comma-separated symbol indices, e.g., "0,1,2,0,1,2")
+    #[arg(long)]
+    pub string: Option<String>,
     /// Task costs for SequencingToMinimizeMaximumCumulativeCost (comma-separated, e.g., "2,-1,3,-2,1,-3")
     #[arg(long, allow_hyphen_values = true)]
     pub costs: Option<String>,
@@ -671,7 +676,7 @@ pub struct CreateArgs {
     /// Task availability rows for TimetableDesign (semicolon-separated 0/1 rows)
     #[arg(long)]
     pub task_avail: Option<String>,
-    /// Alphabet size for LCS, SCS, StringToStringCorrection, or TwoDimensionalConsecutiveSets (optional; inferred from the input strings if omitted)
+    /// Alphabet size for GroupingBySwapping, LCS, SCS, StringToStringCorrection, or TwoDimensionalConsecutiveSets (optional; inferred from the input strings if omitted)
     #[arg(long)]
     pub alphabet_size: Option<usize>,
 
@@ -736,6 +741,7 @@ Examples:
   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
+  pred create GroupingBySwapping --string \"0,1,2,0,1,2\" --bound 5 | pred solve - --solver brute-force
   pred create StringToStringCorrection --source-string \"0,1,2,3,1,0\" --target-string \"0,1,3,2,1\" --bound 2 | pred solve - --solver brute-force
   pred create TwoDimensionalConsecutiveSets --alphabet-size 6 --sets \"0,1,2;3,4,5;1,3;2,4;0,5\" | pred solve - --solver brute-force
   pred solve problem.json --timeout 10           # abort after 10 seconds
@@ -751,8 +757,9 @@ Solve via explicit reduction:
 Input: a problem JSON from `pred create`, or a reduction bundle from `pred reduce`.
 When given a bundle, the target is solved and the solution is mapped back to the source.
 The ILP solver auto-reduces non-ILP problems before solving.
-Problems without an ILP reduction path, such as `LengthBoundedDisjointPaths`,
-`MinMaxMulticenter`, and `StringToStringCorrection`, currently need `--solver brute-force`.
+Problems without an ILP reduction path, such as `GroupingBySwapping`,
+`LengthBoundedDisjointPaths`, `MinMaxMulticenter`, and `StringToStringCorrection`,
+currently need `--solver brute-force`.
 
 ILP backend (default: HiGHS). To use a different backend:
   cargo install problemreductions-cli --features coin-cbc

problemreductions-cli/src/commands/create.rs

@@ -22,7 +22,7 @@ use problemreductions::models::graph::{
 use problemreductions::models::misc::{
     AdditionalKey, BinPacking, BoyceCoddNormalFormViolation, CapacityAssignment, CbqRelation,
     ConjunctiveBooleanQuery, ConsistencyOfDatabaseFrequencyTables, EnsembleComputation,
-    ExpectedRetrievalCost, FlowShopScheduling, FrequencyTable, KnownValue,
+    ExpectedRetrievalCost, FlowShopScheduling, FrequencyTable, GroupingBySwapping, KnownValue,
     LongestCommonSubsequence, MinimumTardinessSequencing, MultiprocessorScheduling, PaintShop,
     PartiallyOrderedKnapsack, QueryArg, RectilinearPictureCompression,
     ResourceConstrainedScheduling, SchedulingWithIndividualDeadlines,
@@ -125,6 +125,7 @@ fn all_data_flags_empty(args: &CreateArgs) -> bool {
         && args.delay_budget.is_none()
         && args.pattern.is_none()
         && args.strings.is_none()
+        && args.string.is_none()
         && args.costs.is_none()
         && args.arc_costs.is_none()
         && args.arcs.is_none()
@@ -680,6 +681,7 @@ fn example_for(canonical: &str, graph_type: Option<&str>) -> &'static str {
         "LongestCommonSubsequence" => {
             "--strings \"010110;100101;001011\" --bound 3 --alphabet-size 2"
         }
+        "GroupingBySwapping" => "--string \"0,1,2,0,1,2\" --bound 5",
         "MinimumCardinalityKey" => {
             "--num-attributes 6 --dependencies \"0,1>2;0,2>3;1,3>4;2,4>5\" --bound 2"
         }
@@ -809,6 +811,7 @@ fn help_flag_hint(
         ("LongestCommonSubsequence", "strings") => {
             "raw strings: \"ABAC;BACA\" or symbol lists: \"0,1,0;1,0,1\""
         }
+        ("GroupingBySwapping", "string") => "symbol list: \"0,1,2,0,1,2\"",
         ("ShortestCommonSupersequence", "strings") => "symbol lists: \"0,1,2;1,2,0\"",
         ("MultipleChoiceBranching", "partition") => "semicolon-separated groups: \"0,1;2,3\"",
         ("IntegralFlowHomologousArcs", "homologous_pairs") => {
@@ -2942,6 +2945,56 @@ pub fn create(args: &CreateArgs, out: &OutputConfig) -> Result<()> {
             )
         }
 
+        // GroupingBySwapping
+        "GroupingBySwapping" => {
+            let usage =
+                "Usage: pred create GroupingBySwapping --string \"0,1,2,0,1,2\" --bound 5 [--alphabet-size 3]";
+            let string_str = args.string.as_deref().ok_or_else(|| {
+                anyhow::anyhow!("GroupingBySwapping requires --string\n\n{usage}")
+            })?;
+            let bound = parse_nonnegative_usize_bound(
+                args.bound.ok_or_else(|| {
+                    anyhow::anyhow!("GroupingBySwapping requires --bound\n\n{usage}")
+                })?,
+                "GroupingBySwapping",
+                usage,
+            )?;
+
+            let string = if string_str.trim().is_empty() {
+                Vec::new()
+            } else {
+                string_str
+                    .split(',')
+                    .map(|value| {
+                        value
+                            .trim()
+                            .parse::<usize>()
+                            .context("invalid symbol index")
+                    })
+                    .collect::<Result<Vec<_>>>()?
+            };
+            let inferred = string.iter().copied().max().map_or(0, |value| value + 1);
+            let alphabet_size = args.alphabet_size.unwrap_or(inferred);
+            anyhow::ensure!(
+                alphabet_size >= inferred,
+                "--alphabet-size {} is smaller than max symbol + 1 ({}) in the input string",
+                alphabet_size,
+                inferred
+            );
+            anyhow::ensure!(
+                alphabet_size > 0 || string.is_empty(),
+                "GroupingBySwapping requires a positive alphabet for non-empty strings.\n\n{usage}"
+            );
+            anyhow::ensure!(
+                !string.is_empty() || bound == 0,
+                "GroupingBySwapping requires --bound 0 when --string is empty.\n\n{usage}"
+            );
+            (
+                ser(GroupingBySwapping::new(alphabet_size, string, bound))?,
+                resolved_variant.clone(),
+            )
+        }
+
         // ClosestVectorProblem
         "ClosestVectorProblem" => {
             let basis_str = args.basis.as_deref().ok_or_else(|| {
@@ -7245,6 +7298,7 @@ mod tests {
             delay_budget: None,
             pattern: None,
             strings: None,
+            string: None,
             arc_costs: None,
             arcs: None,
             values: None,

problemreductions-cli/src/problem_name.rs

@@ -17,6 +17,9 @@ pub fn resolve_alias(input: &str) -> String {
     if input.eq_ignore_ascii_case("UndirectedFlowLowerBounds") {
         return "UndirectedFlowLowerBounds".to_string();
     }
+    if input.eq_ignore_ascii_case("GroupingBySwapping") {
+        return "GroupingBySwapping".to_string();
+    }
     if let Some(pt) = problemreductions::registry::find_problem_type_by_alias(input) {
         return pt.canonical_name.to_string();
     }

problemreductions-cli/tests/cli_tests.rs

@@ -3548,6 +3548,69 @@ fn test_create_string_to_string_correction_rejects_negative_bound() {
     assert!(stderr.contains("nonnegative --bound"), "stderr: {stderr}");
 }
 
+#[test]
+fn test_create_grouping_by_swapping() {
+    let output = pred()
+        .args([
+            "create",
+            "GroupingBySwapping",
+            "--string",
+            "0,1,2,0,1,2",
+            "--bound",
+            "5",
+        ])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8(output.stdout).unwrap();
+    let json: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    assert_eq!(json["type"], "GroupingBySwapping");
+    assert_eq!(json["data"]["alphabet_size"], 3);
+    assert_eq!(
+        json["data"]["string"],
+        serde_json::json!([0, 1, 2, 0, 1, 2])
+    );
+    assert_eq!(json["data"]["budget"], 5);
+}
+
+#[test]
+fn test_create_model_example_grouping_by_swapping() {
+    let output = pred()
+        .args(["create", "--example", "GroupingBySwapping"])
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "stderr: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8(output.stdout).unwrap();
+    let json: serde_json::Value = serde_json::from_str(&stdout).unwrap();
+    assert_eq!(json["type"], "GroupingBySwapping");
+    assert_eq!(json["data"]["alphabet_size"], 3);
+    assert_eq!(
+        json["data"]["string"],
+        serde_json::json!([0, 1, 2, 0, 1, 2])
+    );
+    assert_eq!(json["data"]["budget"], 5);
+}
+
+#[test]
+fn test_create_grouping_by_swapping_help_uses_cli_flags() {
+    let output = pred()
+        .args(["create", "GroupingBySwapping"])
+        .output()
+        .unwrap();
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("--string"), "stderr: {stderr}");
+    assert!(stderr.contains("--bound"), "stderr: {stderr}");
+}
+
 #[test]
 fn test_create_spinglass() {
     let output_file = std::env::temp_dir().join("pred_test_create_sg.json");

src/lib.rs

@@ -71,14 +71,14 @@ pub mod prelude {
     pub use crate::models::misc::{
         AdditionalKey, BinPacking, BoyceCoddNormalFormViolation, CapacityAssignment, CbqRelation,
         ConjunctiveBooleanQuery, ConjunctiveQueryFoldability, ConsistencyOfDatabaseFrequencyTables,
-        EnsembleComputation, ExpectedRetrievalCost, Factoring, FlowShopScheduling, Knapsack,
-        LongestCommonSubsequence, MinimumTardinessSequencing, MultiprocessorScheduling, PaintShop,
-        Partition, QueryArg, RectilinearPictureCompression, ResourceConstrainedScheduling,
-        SchedulingWithIndividualDeadlines, SequencingToMinimizeMaximumCumulativeCost,
-        SequencingToMinimizeWeightedCompletionTime, SequencingToMinimizeWeightedTardiness,
-        SequencingWithReleaseTimesAndDeadlines, SequencingWithinIntervals,
-        ShortestCommonSupersequence, StackerCrane, StaffScheduling, StringToStringCorrection,
-        SubsetSum, SumOfSquaresPartition, Term, TimetableDesign,
+        EnsembleComputation, ExpectedRetrievalCost, Factoring, FlowShopScheduling,
+        GroupingBySwapping, Knapsack, LongestCommonSubsequence, MinimumTardinessSequencing,
+        MultiprocessorScheduling, PaintShop, Partition, QueryArg, RectilinearPictureCompression,
+        ResourceConstrainedScheduling, SchedulingWithIndividualDeadlines,
+        SequencingToMinimizeMaximumCumulativeCost, SequencingToMinimizeWeightedCompletionTime,
+        SequencingToMinimizeWeightedTardiness, SequencingWithReleaseTimesAndDeadlines,
+        SequencingWithinIntervals, ShortestCommonSupersequence, StackerCrane, StaffScheduling,
+        StringToStringCorrection, SubsetSum, SumOfSquaresPartition, Term, TimetableDesign,
     };
     pub use crate::models::set::{
         ComparativeContainment, ConsecutiveSets, ExactCoverBy3Sets, MaximumSetPacking,