Recategorize problem models by input structure

.claude/CLAUDE.md

@@ -49,7 +49,12 @@ make release V=x.y.z  # Tag and push a new release (CI publishes to crates.io)
 ## Architecture
 
 ### Core Modules
-- `src/models/` - Problem implementations (SAT, Graph, Set, Optimization)
+- `src/models/` - Problem implementations organized by input structure:
+  - `graph/` - Problems on graphs (MIS, MaxClique, MaxCut, MinVC, MinDS, MaxMatching, MaximalIS, KColoring, TSP, SpinGlass, BicliqueCover)
+  - `formula/` - Logical formulas and circuits (SAT, k-SAT, CircuitSAT)
+  - `set/` - Set systems (MinSetCovering, MaxSetPacking)
+  - `algebraic/` - Matrices, linear systems, lattices (QUBO, ILP, CVP, BMF)
+  - `misc/` - Unique input structures (BinPacking, PaintShop, Factoring)
 - `src/rules/` - Reduction rules + inventory registration
 - `src/solvers/` - BruteForce solver, ILP solver (feature-gated)
 - `src/traits.rs` - `Problem`, `OptimizationProblem`, `SatisfactionProblem` traits
@@ -140,7 +145,7 @@ Reduction graph nodes use variant key-value pairs from `Problem::variant()`:
 
 ### File Naming
 - Reduction files: `src/rules/<source>_<target>.rs` (e.g., `maximumindependentset_qubo.rs`)
-- Model files: `src/models/<category>/<name>.rs` (e.g., `maximum_independent_set.rs`)
+- Model files: `src/models/<category>/<name>.rs` — category is by input structure: `graph/` (graph input), `formula/` (boolean formula/circuit), `set/` (universe + subsets), `algebraic/` (matrix/linear system/lattice), `misc/` (other)
 - Example files: `examples/reduction_<source>_to_<target>.rs` (must have `pub fn run()` + `fn main() { run() }`)
 - Test naming: `test_<source>_to_<target>_closed_loop`
 

README.md

@@ -63,31 +63,20 @@ See the [MCP documentation](https://codingthrust.github.io/problem-reductions/mc
 
 ## Contributing
 
-### Authorship Recognition
+**No programming experience required.** You contribute domain knowledge; we handle the implementation.
 
-**Contribute 10 non-trivial reduction rules and you will be automatically added to the author list of the paper.** AI tools handle the implementation — contributors focus on designing correct reductions and test cases.
+1. **File an issue** — use the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Describe the problem or reduction you have in mind — the template guides you through the details.
+2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested implementation.
+3. **We present it to you** — all issue contributors are invited to community calls (via [Zulip](https://problem-reductions.zulipchat.com/)), where maintainers walk through the implementation — documentation, CLI behavior, correctness — and you provide feedback.
 
-### How to Contribute
+**Authorship:** contribute 10 non-trivial reduction rules and you'll be added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).
 
-1. **Open an issue** using the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Fill in all sections — the templates guide you through the required information (definition, algorithm, size overhead, example instance, etc.).
+> **Tip:** If you use Claude Code / OpenCode / Codex, you can file issues interactively:
+> ```
+> File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
+> ```
 
-   **Hint:** If you use Claude Code / OpenCode / Codex (assume `gh` CLI tool and `superpowers` plugin are installed), you can just type:
-   ```
-   File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
-   ```
-   ```
-   File an issue on CodingThrust/problem-reductions, using the "Rule" issue template, about reduction from Closest Vector Problem to QUBO. Brainstorm with me.
-   ```
-   Then AI agents will guide you to fill in the issue template.
-
-2. Our AI agents will pick up the issue and generate a plan to implement the reduction rule.
-3. You will be mentioned in the pull request, provide feedback to the AI agents. If you are satisfied with the plan, you can merge the PR.
-
-Optionally, if you prefer to **implement yourself**, I will recommend you to use the [superpowers:brainstorming](https://github.com/obra/superpowers) skill to help you write a detailed plan. Create a PR and let maintainers help review and merge the PR.
-
-### Developer Commands
-
-Run `make help` to see all available targets. See [CLAUDE.md](https://codingthrust.github.io/problem-reductions/claude.html) for the full command list and architecture details.
+If you prefer to **implement yourself**, see the [Design](https://codingthrust.github.io/problem-reductions/design.html) guide. Run `make help` to see available developer commands.
 
 ## Acknowledgments
 

benches/solver_benchmarks.rs

@@ -1,11 +1,10 @@
 //! Benchmarks for the BruteForce solver on various problem types.
 
 use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use problemreductions::models::formula::*;
 use problemreductions::models::graph::*;
-use problemreductions::models::optimization::*;
-use problemreductions::models::satisfiability::*;
+use problemreductions::models::misc::*;
 use problemreductions::models::set::*;
-use problemreductions::models::specialized::*;
 use problemreductions::prelude::*;
 use problemreductions::topology::SimpleGraph;
 use problemreductions::variant::K3;

docs/plans/2026-03-01-problem-categorization-design.md

@@ -0,0 +1,84 @@
+# Problem Categorization Redesign
+
+## Problem
+
+The current categorization mixes two axes:
+- **Input structure** (graph, set system, formula)
+- **Problem type** (optimization vs satisfaction)
+
+This creates ambiguity: MIS is both a graph problem and an optimization problem. QUBO is on a matrix but lives in `optimization/`. CircuitSAT is a satisfiability problem but lives in `specialized/`. The `specialized/` folder is a catch-all with no unifying principle.
+
+## Design
+
+**Single axis: primary input structure** — "what data type does the problem operate on?"
+
+The optimization/satisfaction distinction is already captured by the trait hierarchy (`OptimizationProblem` vs `SatisfactionProblem`), so folders should not duplicate it.
+
+### New folder structure
+
+```
+src/models/
+├── graph/          # Input: a graph (optionally weighted)
+│   ├── maximum_independent_set.rs
+│   ├── maximum_clique.rs
+│   ├── max_cut.rs
+│   ├── maximum_matching.rs
+│   ├── minimum_vertex_cover.rs
+│   ├── minimum_dominating_set.rs
+│   ├── maximal_is.rs
+│   ├── kcoloring.rs
+│   ├── traveling_salesman.rs
+│   ├── spin_glass.rs          ← from optimization/
+│   └── biclique_cover.rs      ← from specialized/
+│
+├── formula/        # Input: a logical formula or circuit
+│   ├── sat.rs
+│   ├── ksat.rs
+│   └── circuit.rs             ← from specialized/
+│
+├── set/            # Input: universe + collection of subsets
+│   ├── minimum_set_covering.rs
+│   └── maximum_set_packing.rs
+│
+├── algebraic/      # Input: matrix, linear system, or lattice
+│   ├── qubo.rs                ← from optimization/
+│   ├── ilp.rs                 ← from optimization/
+│   ├── closest_vector_problem.rs  ← from optimization/
+│   └── bmf.rs                 ← from specialized/
+│
+└── misc/           # Problems with unique input structures
+    ├── bin_packing.rs         ← from optimization/
+    ├── paintshop.rs           ← from specialized/
+    └── factoring.rs           ← from specialized/
+```
+
+### Decision rule for new problems
+
+> "What is the primary data structure in the struct definition?"
+> - Graph → `graph/`
+> - Boolean formula or circuit → `formula/`
+> - Universe + subsets → `set/`
+> - Matrix, linear system, or lattice → `algebraic/`
+> - None of the above → `misc/`
+
+### What moves
+
+| Problem | From | To | Reason |
+|---|---|---|---|
+| SpinGlass | optimization/ | graph/ | Parameterized by G, operates on graph edges |
+| BicliqueCover | specialized/ | graph/ | Input is a BipartiteGraph |
+| CircuitSAT | specialized/ | formula/ | Input is a boolean circuit |
+| QUBO | optimization/ | algebraic/ | Input is a Q matrix (no graph param) |
+| ILP | optimization/ | algebraic/ | Input is constraint matrix + objective |
+| CVP | optimization/ | algebraic/ | Input is lattice basis matrix |
+| BMF | specialized/ | algebraic/ | Input is a boolean matrix |
+| BinPacking | optimization/ | misc/ | Input is items + capacity |
+| PaintShop | specialized/ | misc/ | Input is a car sequence |
+| Factoring | specialized/ | misc/ | Input is an integer |
+
+### What doesn't change
+
+- Trait hierarchy (`OptimizationProblem`, `SatisfactionProblem`)
+- All public API, type names, re-exports
+- Only `mod.rs` files, `use` paths, and `#[path]` test references change
+- The `optimization/` and `specialized/` folders are eliminated

docs/src/design.md

@@ -17,7 +17,7 @@ This guide covers the library internals for contributors.
 
 | Module | Purpose |
 |--------|---------|
-| [`src/models/`](#problem-model) | Problem type implementations (SAT, Graph, Set, Optimization) |
+| [`src/models/`](#problem-model) | Problem implementations by input structure: `graph/`, `formula/`, `set/`, `algebraic/`, `misc/` |
 | [`src/rules/`](#reduction-rules) | Reduction rules with `ReduceTo` implementations |
 | [`src/registry/`](#reduction-graph) | Reduction graph metadata (collected via `inventory`) |
 | [`src/solvers/`](#solvers) | BruteForce and ILP solvers |

docs/src/getting-started.md

@@ -39,7 +39,7 @@ A path graph `0–1–2–3` has 4 vertices and 3 edges.
 
 ```rust,ignore
 use problemreductions::prelude::*;
-use problemreductions::models::optimization::ILP;
+use problemreductions::models::algebraic::ILP;
 use problemreductions::solvers::ILPSolver;
 use problemreductions::topology::SimpleGraph;
 

docs/src/introduction.md

@@ -14,10 +14,10 @@
 <div id="cy-controls">
   <div id="legend">
     <span class="swatch" style="background:#c8f0c8;"></span>Graph
+    <span class="swatch" style="background:#c8c8f0;"></span>Formula
     <span class="swatch" style="background:#f0c8c8;"></span>Set
-    <span class="swatch" style="background:#f0f0a0;"></span>Optimization
-    <span class="swatch" style="background:#c8c8f0;"></span>Satisfiability
-    <span class="swatch" style="background:#f0c8e0;"></span>Specialized
+    <span class="swatch" style="background:#f0f0a0;"></span>Algebraic
+    <span class="swatch" style="background:#f0c8e0;"></span>Misc
     <span style="display:inline-block;width:20px;height:0;border-top:2px dashed #bbb;margin-left:10px;margin-right:3px;vertical-align:middle;"></span>Variant Cast
   </div>
   <div>
@@ -62,14 +62,17 @@ This library is the foundation of that effort: an open-source, extensible reduct
 
 ## Call for Contributions
 
-> **Everyone can contribute — no programming experience required.** If you know a computational problem or a reduction rule, just describe it in a GitHub issue. AI will generate a tested pull request for you to review.
->
-> **Contribute 10 non-trivial reduction rules and you will be automatically added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).**
+> **No programming experience required.** You contribute domain knowledge — we handle the implementation.
 
-1. **Open an issue** using the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template
-2. **Fill in all sections** — definition, algorithm, size overhead, example instance
-3. **Review AI-generated code** — AI generates code and you can comment on the pull request
-4. **Merge** — ask maintainers' assistance to merge once you are satisfied
+### How it works
+
+1. **File an issue** — use the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Describe the problem or reduction you have in mind; the template guides you through the details.
+2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested implementation.
+3. **We present it to you** — all issue contributors are invited to community calls (via [Zulip](https://problem-reductions.zulipchat.com/)), where maintainers walk through the implementation — documentation, CLI behavior, correctness — and you provide feedback.
+
+### Authorship
+
+Contribute 10 non-trivial reduction rules and you'll be added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).
 
 For manual implementation, see the [Design](./design.md#contributing) guide.
 

docs/src/reductions/reduction_graph.json

@@ -3,72 +3,72 @@
     {
       "name": "BMF",
       "variant": {},
-      "category": "specialized",
-      "doc_path": "models/specialized/struct.BMF.html",
+      "category": "algebraic",
+      "doc_path": "models/algebraic/struct.BMF.html",
       "complexity": "2^(rows * rank + rank * cols)"
     },
     {
       "name": "BicliqueCover",
       "variant": {},
-      "category": "specialized",
-      "doc_path": "models/specialized/struct.BicliqueCover.html",
+      "category": "graph",
+      "doc_path": "models/graph/struct.BicliqueCover.html",
       "complexity": "2^num_vertices"
     },
     {
       "name": "BinPacking",
       "variant": {
         "weight": "f64"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.BinPacking.html",
+      "category": "misc",
+      "doc_path": "models/misc/struct.BinPacking.html",
       "complexity": "2^num_items"
     },
     {
       "name": "BinPacking",
       "variant": {
         "weight": "i32"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.BinPacking.html",
+      "category": "misc",
+      "doc_path": "models/misc/struct.BinPacking.html",
       "complexity": "2^num_items"
     },
     {
       "name": "CircuitSAT",
       "variant": {},
-      "category": "specialized",
-      "doc_path": "models/specialized/struct.CircuitSAT.html",
+      "category": "formula",
+      "doc_path": "models/formula/struct.CircuitSAT.html",
       "complexity": "2^num_variables"
     },
     {
       "name": "ClosestVectorProblem",
       "variant": {
         "weight": "f64"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.ClosestVectorProblem.html",
+      "category": "algebraic",
+      "doc_path": "models/algebraic/struct.ClosestVectorProblem.html",
       "complexity": "2^num_basis_vectors"
     },
     {
       "name": "ClosestVectorProblem",
       "variant": {
         "weight": "i32"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.ClosestVectorProblem.html",
+      "category": "algebraic",
+      "doc_path": "models/algebraic/struct.ClosestVectorProblem.html",
       "complexity": "2^num_basis_vectors"
     },
     {
       "name": "Factoring",
       "variant": {},
-      "category": "specialized",
-      "doc_path": "models/specialized/struct.Factoring.html",
+      "category": "misc",
+      "doc_path": "models/misc/struct.Factoring.html",
       "complexity": "exp((m + n)^(1/3) * log(m + n)^(2/3))"
     },
     {
       "name": "ILP",
       "variant": {},
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.ILP.html",
+      "category": "algebraic",
+      "doc_path": "models/algebraic/struct.ILP.html",
       "complexity": "num_variables^num_variables"
     },
     {
@@ -126,26 +126,26 @@
       "variant": {
         "k": "K2"
       },
-      "category": "satisfiability",
-      "doc_path": "models/satisfiability/struct.KSatisfiability.html",
+      "category": "formula",
+      "doc_path": "models/formula/struct.KSatisfiability.html",
       "complexity": "num_variables + num_clauses"
     },
     {
       "name": "KSatisfiability",
       "variant": {
         "k": "K3"
       },
-      "category": "satisfiability",
-      "doc_path": "models/satisfiability/struct.KSatisfiability.html",
+      "category": "formula",
+      "doc_path": "models/formula/struct.KSatisfiability.html",
       "complexity": "1.307^num_variables"
     },
     {
       "name": "KSatisfiability",
       "variant": {
         "k": "KN"
       },
-      "category": "satisfiability",
-      "doc_path": "models/satisfiability/struct.KSatisfiability.html",
+      "category": "formula",
+      "doc_path": "models/formula/struct.KSatisfiability.html",
       "complexity": "2^num_variables"
     },
     {
@@ -317,24 +317,24 @@
     {
       "name": "PaintShop",
       "variant": {},
-      "category": "specialized",
-      "doc_path": "models/specialized/struct.PaintShop.html",
+      "category": "misc",
+      "doc_path": "models/misc/struct.PaintShop.html",
       "complexity": "2^num_cars"
     },
     {
       "name": "QUBO",
       "variant": {
         "weight": "f64"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.QUBO.html",
+      "category": "algebraic",
+      "doc_path": "models/algebraic/struct.QUBO.html",
       "complexity": "2^num_vars"
     },
     {
       "name": "Satisfiability",
       "variant": {},
-      "category": "satisfiability",
-      "doc_path": "models/satisfiability/struct.Satisfiability.html",
+      "category": "formula",
+      "doc_path": "models/formula/struct.Satisfiability.html",
       "complexity": "2^num_variables"
     },
     {
@@ -343,8 +343,8 @@
         "graph": "SimpleGraph",
         "weight": "f64"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.SpinGlass.html",
+      "category": "graph",
+      "doc_path": "models/graph/struct.SpinGlass.html",
       "complexity": "2^num_spins"
     },
     {
@@ -353,8 +353,8 @@
         "graph": "SimpleGraph",
         "weight": "i32"
       },
-      "category": "optimization",
-      "doc_path": "models/optimization/struct.SpinGlass.html",
+      "category": "graph",
+      "doc_path": "models/graph/struct.SpinGlass.html",
       "complexity": "2^num_spins"
     },
     {