Recategorize problem models by input structure

[GiggleLiu]

Summary

• Recategorize problem models by input structure (what data type the problem operates on)
• Replaces optimization/, satisfiability/, specialized/ with graph/, formula/, set/, algebraic/, misc/
• Moves source files, unit tests, updates all imports (rules, solvers, examples, CLI, benchmarks)
• Updates documentation (mdBook, reduction graph visualization, CLAUDE.md architecture docs)
• Design doc with full migration table at docs/plans/2026-03-01-problem-categorization-design.md

Details

The old categorization mixed input structure (graph, set) with problem type (optimization, satisfaction). For example, MIS is both a graph problem and an optimization problem, QUBO operates on a matrix but lived in optimization/, and specialized/ was a catch-all.

The new scheme categorizes solely by primary input structure:

Category	Decision rule	Problems
graph/	Input is a graph	MIS, MaxClique, MaxCut, MinVC, MinDS, MaxMatching, MaximalIS, KColoring, TSP, SpinGlass, BicliqueCover
formula/	Input is a boolean formula/circuit	SAT, k-SAT, CircuitSAT
set/	Input is universe + subsets	MinSetCovering, MaxSetPacking
algebraic/	Input is matrix/linear system/lattice	QUBO, ILP, CVP, BMF
misc/	None of the above	BinPacking, PaintShop, Factoring

This is a breaking API change — downstream users importing from models::optimization, models::satisfiability, or models::specialized will need to update their imports. All types remain re-exported from models:: directly.

Test plan

• make check passes (fmt + clippy + tests)
• All 200+ tests pass
• Reduction graph JSON regenerated with new categories
• mdBook builds successfully with updated visualization colors
• Coverage ≥96% (no regression)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.88%. Comparing base (88c1635) to head (5e951d0).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #113      +/-   ##
==========================================
- Coverage   96.88%   96.88%   -0.01%     
==========================================
  Files         200      200              
  Lines       27544    27537       -7     
==========================================
- Hits        26687    26680       -7     
  Misses        857      857              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

clean up this implementation plan.

[Copilot]

Pull request overview

This PR refactors the problemreductions Rust crate’s problem model organization to be categorized by input structure (graph/, formula/, set/, algebraic/, misc/) and updates code, tests, examples, CLI, and docs to match.

Changes:

• Replaces the prior optimization/, satisfiability/, and specialized/ model module groupings with algebraic/, formula/, and misc/, and relocates/rewires affected models (e.g., SpinGlass → graph, QUBO/ILP → algebraic, CircuitSAT → formula).
• Updates reductions, solvers, unit/integration tests, benchmarks, CLI, and examples to import models from the new module paths and to assert the new category strings.
• Updates docs (architecture docs, mdBook content, visualization assets, and reduction graph JSON) and adds design/implementation plan documents for the migration.

Reviewed changes

Copilot reviewed 99 out of 111 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/suites/reductions.rs	Updates ILP imports to new models::algebraic module.
tests/suites/integration.rs	Updates test suite wildcard imports to new category modules.
src/unit_tests/variant.rs	Updates model imports used by variant tests to new modules.
src/unit_tests/unitdiskmapping_algorithms/weighted.rs	Updates ILP imports to models::algebraic.
src/unit_tests/unitdiskmapping_algorithms/common.rs	Updates ILP imports to models::algebraic.
src/unit_tests/trait_consistency.rs	Updates wildcard imports to new category modules.
src/unit_tests/solvers/ilp/solver.rs	Updates ILP type imports for ILP solver unit tests.
src/unit_tests/solvers/brute_force.rs	Updates SAT imports to models::formula.
src/unit_tests/rules/sat_minimumdominatingset.rs	Updates CNFClause import to models::formula.
src/unit_tests/rules/sat_maximumindependentset.rs	Updates CNFClause import to models::formula.
src/unit_tests/rules/sat_coloring.rs	Updates CNFClause import to models::formula.
src/unit_tests/rules/sat_circuitsat.rs	Consolidates SAT/CircuitSAT imports under models::formula.
src/unit_tests/rules/registry.rs	Updates Factoring import to models::misc.
src/unit_tests/rules/reduction_path_parity.rs	Updates QUBO/SpinGlass/Factoring imports to new modules.
src/unit_tests/rules/ksatisfiability_qubo.rs	Updates CNFClause import to models::formula.
src/unit_tests/rules/ilp_qubo.rs	Updates ILP-related imports to models::algebraic.
src/unit_tests/rules/graph.rs	Updates category derivation tests and imports for new modules/categories.
src/unit_tests/rules/circuit_spinglass.rs	Updates Circuit-related imports to models::formula.
src/unit_tests/rules/circuit_ilp.rs	Updates Circuit-related imports to models::formula.
src/unit_tests/reduction_graph.rs	Updates KSAT/CNFClause/Factoring imports to new modules.
src/unit_tests/problem_size.rs	Updates wildcard imports and CNFClause/ILP-related imports.
src/unit_tests/models/misc/paintshop.rs	Adds/moves PaintShop unit tests under misc/.
src/unit_tests/models/misc/factoring.rs	Adds/moves Factoring unit tests under misc/.
src/unit_tests/models/misc/bin_packing.rs	Adds/moves BinPacking unit tests under misc/.
src/unit_tests/models/graph/spin_glass.rs	Adds/moves SpinGlass unit tests under graph/.
src/unit_tests/models/graph/biclique_cover.rs	Adds/moves BicliqueCover unit tests under graph/.
src/unit_tests/models/formula/sat.rs	Adds/moves SAT unit tests under formula/.
src/unit_tests/models/formula/ksat.rs	Adds/moves K-SAT unit tests under formula/.
src/unit_tests/models/formula/circuit.rs	Adds/moves Circuit/CircuitSAT unit tests under formula/.
src/unit_tests/models/algebraic/qubo.rs	Adds/moves QUBO unit tests under algebraic/.
src/unit_tests/models/algebraic/ilp.rs	Adds/moves ILP unit tests under algebraic/.
src/unit_tests/models/algebraic/closest_vector_problem.rs	Adds/moves CVP unit tests under algebraic/.
src/unit_tests/models/algebraic/bmf.rs	Adds/moves BMF unit tests under algebraic/.
src/unit_tests/jl_helpers.rs	Updates helper type paths to models::formula CNFClause.
src/solvers/ilp/solver.rs	Updates solver imports and doc example to models::algebraic.
src/solvers/ilp/mod.rs	Updates module doc example to models::algebraic.
src/rules/travelingsalesman_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/spinglass_qubo.rs	Splits imports: QUBO from algebraic, SpinGlass from graph.
src/rules/spinglass_maxcut.rs	Updates SpinGlass import to models::graph.
src/rules/spinglass_casts.rs	Updates SpinGlass import to models::graph.
src/rules/sat_minimumdominatingset.rs	Updates Satisfiability import to models::formula.
src/rules/sat_maximumindependentset.rs	Updates Satisfiability import to models::formula.
src/rules/sat_ksat.rs	Updates SAT/K-SAT imports to models::formula.
src/rules/sat_coloring.rs	Updates Satisfiability import to models::formula.
src/rules/sat_circuitsat.rs	Updates SAT + CircuitSAT-related imports to models::formula.
src/rules/qubo_ilp.rs	Updates QUBO/ILP imports to models::algebraic.
src/rules/minimumvertexcover_qubo.rs	Updates QUBO import to models::algebraic.
src/rules/minimumvertexcover_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/minimumsetcovering_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/minimumdominatingset_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/maximumsetpacking_qubo.rs	Updates QUBO import to models::algebraic.
src/rules/maximumsetpacking_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/maximummatching_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/maximumindependentset_qubo.rs	Updates QUBO import to models::algebraic.
src/rules/maximumindependentset_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/maximumclique_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/ksatisfiability_qubo.rs	Updates QUBO import to models::algebraic and K-SAT/CNFClause paths to formula.
src/rules/ksatisfiability_casts.rs	Updates KSatisfiability import to models::formula.
src/rules/ilp_qubo.rs	Updates ILP/QUBO imports to models::algebraic.
src/rules/factoring_ilp.rs	Updates Factoring to models::misc and ILP imports to models::algebraic.
src/rules/factoring_circuit.rs	Updates Factoring to models::misc and circuit types to models::formula.
src/rules/coloring_qubo.rs	Updates QUBO import to models::algebraic.
src/rules/coloring_ilp.rs	Updates ILP imports to models::algebraic.
src/rules/circuit_spinglass.rs	Updates CircuitSAT-related imports to models::formula and SpinGlass to models::graph.
src/rules/circuit_ilp.rs	Updates circuit types to models::formula and ILP types to models::algebraic.
src/models/specialized/mod.rs	Removes the old specialized model module.
src/models/mod.rs	Defines new top-level model modules and updates re-exports for new structure.
src/models/misc/paintshop.rs	Updates docs + test path wiring for PaintShop under misc/.
src/models/misc/mod.rs	Introduces misc module and re-exports BinPacking/Factoring/PaintShop.
src/models/misc/factoring.rs	Updates docs + test path wiring for Factoring under misc/.
src/models/misc/bin_packing.rs	Updates docs + test path wiring for BinPacking under misc/.
src/models/graph/spin_glass.rs	Updates docs + test path wiring for SpinGlass under graph/.
src/models/graph/mod.rs	Expands graph module to include SpinGlass and BicliqueCover; updates module docs.
src/models/graph/biclique_cover.rs	Updates docs + test path wiring for BicliqueCover under graph/.
src/models/formula/sat.rs	Updates docs + test path wiring for SAT under formula/.
src/models/formula/mod.rs	Renames/repurposes module to formula/circuit-based problems; exports CircuitSAT.
src/models/formula/ksat.rs	Updates docs + test path wiring for K-SAT under formula/.
src/models/formula/circuit.rs	Updates docs + test path wiring for Circuit/CircuitSAT under formula/.
src/models/algebraic/qubo.rs	Updates docs + test path wiring for QUBO under algebraic/.
src/models/algebraic/mod.rs	Introduces algebraic module and re-exports QUBO/ILP/CVP/BMF types.
src/models/algebraic/ilp.rs	Updates docs + test path wiring for ILP under algebraic/.
src/models/algebraic/closest_vector_problem.rs	Updates VarBounds import and test wiring for CVP under algebraic/.
src/models/algebraic/bmf.rs	Updates docs + test path wiring for BMF under algebraic/.
src/lib.rs	Updates crate docs + prelude exports for the new model categorization.
problemreductions-cli/src/mcp/tools.rs	Updates CLI MCP tool imports for moved models.
problemreductions-cli/src/dispatch.rs	Updates CLI dispatch imports (BinPacking → misc; ILP/CVP → algebraic).
examples/reduction_travelingsalesman_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_qubo_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_minimumvertexcover_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_minimumsetcovering_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_minimumdominatingset_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_maximumsetpacking_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_maximummatching_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_maximumindependentset_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_maximumclique_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_kcoloring_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_ilp_to_qubo.rs	Updates ILP-related imports to models::algebraic.
examples/reduction_factoring_to_ilp.rs	Updates ILP import to models::algebraic.
examples/reduction_factoring_to_circuitsat.rs	Updates Circuit import to models::formula.
examples/reduction_circuitsat_to_spinglass.rs	Updates Circuit-related imports to models::formula.
examples/reduction_circuitsat_to_ilp.rs	Updates ILP import to models::algebraic and Circuit imports to models::formula.
docs/src/static/reduction-graph.js	Updates category color maps to new category names.
docs/src/reductions/reduction_graph.json	Updates stored graph metadata categories + doc paths to new module layout.
docs/src/introduction.md	Updates legend/categories and contribution text to match new structure and docs.
docs/src/getting-started.md	Updates ILP import path in getting-started code snippet.
docs/src/design.md	Updates architecture description to new model layout.
docs/plans/2026-03-01-problem-categorization-impl.md	Adds detailed implementation plan for the recategorization work.
docs/plans/2026-03-01-problem-categorization-design.md	Adds design doc describing the new categorization axis and migration table.
benches/solver_benchmarks.rs	Updates benchmark imports to new model categories.
README.md	Updates contributing section to new messaging and references.
.claude/CLAUDE.md	Updates architecture docs and naming guidance to new model categorization.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

PR description says this PR is “design doc and documentation updates only — file moves will follow”, but this diff includes broad Rust refactors (new modules, removed old modules, updated imports/tests/examples). Please update the PR description + test plan to reflect the actual scope (or split docs vs refactor into separate PRs) so reviewers know what they’re approving.

[Copilot]

This change removes the public problemreductions::models::{optimization,satisfiability,specialized} modules entirely. That’s a breaking API change for downstream users that import types via those module paths (even though many types are still re-exported elsewhere). Consider keeping thin #[deprecated] shim modules that re-export the new locations (e.g., pub mod optimization { pub use crate::models::algebraic::*; pub use crate::models::graph::SpinGlass; ... }) to preserve compatibility for at least one release.