Skip to content

Commit 6d083f4

Browse files
GiggleLiuclaude
GiggleLiu
and
claude
authored
Recategorize problem models by input structure (#113)
* Design: recategorize problem models by input structure Current categorization mixes input structure (graph, set) with problem type (optimization, satisfaction). Reorganize into orthogonal categories based solely on input structure: graph/, formula/, set/, algebraic/, misc/. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Simplify contributor guide: file an issue, we implement it Lower the understanding barrier for contributors: - Lead with "no programming required" and a 3-step flow - Add community calls section (coming soon via Zulip) - Update reduction graph legend for new model categories - Update design.md module table for new category names Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Clarify contributor role: feedback via community calls, not code review Contributors provide feedback on documentation and CLI behavior during community calls with maintainers, rather than reviewing code on PRs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add Zulip community link Replace placeholder with https://problem-reductions.zulipchat.com/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add implementation plan for problem categorization refactoring 10-task plan covering file moves, mod.rs updates, import fixes across rules/examples/tests/docs, visualization colors, and artifact regeneration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: move model files to input-structure-based categories Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: update mod.rs files for new category structure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: move unit tests to match new category structure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: update rule imports for new model categories Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: update lib.rs prelude and docs for new categories Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: update all imports, tests, examples, and docs for new categories Updates imports across unit tests, integration tests, examples, benchmarks, CLI, solver, and source doc comments from old categories (optimization, satisfiability, specialized) to new ones (algebraic, formula, graph, misc). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: update import paths in getting-started guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: update reduction graph colors for new categories Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: format code and regenerate reduction graph artifacts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: remove completed implementation plan The step-by-step implementation plan has been fully executed. The design doc (2026-03-01-problem-categorization-design.md) remains as it documents the reasoning behind the change. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 88c1635 commit 6d083f4

110 files changed

Lines changed: 367 additions & 286 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,12 @@ make release V=x.y.z # Tag and push a new release (CI publishes to crates.io)
4949
## Architecture
5050

5151
### Core Modules
52-
- `src/models/` - Problem implementations (SAT, Graph, Set, Optimization)
52+
- `src/models/` - Problem implementations organized by input structure:
53+
- `graph/` - Problems on graphs (MIS, MaxClique, MaxCut, MinVC, MinDS, MaxMatching, MaximalIS, KColoring, TSP, SpinGlass, BicliqueCover)
54+
- `formula/` - Logical formulas and circuits (SAT, k-SAT, CircuitSAT)
55+
- `set/` - Set systems (MinSetCovering, MaxSetPacking)
56+
- `algebraic/` - Matrices, linear systems, lattices (QUBO, ILP, CVP, BMF)
57+
- `misc/` - Unique input structures (BinPacking, PaintShop, Factoring)
5358
- `src/rules/` - Reduction rules + inventory registration
5459
- `src/solvers/` - BruteForce solver, ILP solver (feature-gated)
5560
- `src/traits.rs` - `Problem`, `OptimizationProblem`, `SatisfactionProblem` traits
@@ -140,7 +145,7 @@ Reduction graph nodes use variant key-value pairs from `Problem::variant()`:
140145

141146
### File Naming
142147
- Reduction files: `src/rules/<source>_<target>.rs` (e.g., `maximumindependentset_qubo.rs`)
143-
- Model files: `src/models/<category>/<name>.rs` (e.g., `maximum_independent_set.rs`)
148+
- 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)
144149
- Example files: `examples/reduction_<source>_to_<target>.rs` (must have `pub fn run()` + `fn main() { run() }`)
145150
- Test naming: `test_<source>_to_<target>_closed_loop`
146151

‎README.md‎

Lines changed: 10 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -63,31 +63,20 @@ See the [MCP documentation](https://codingthrust.github.io/problem-reductions/mc
6363

6464
## Contributing
6565

66-
### Authorship Recognition
66+
**No programming experience required.** You contribute domain knowledge; we handle the implementation.
6767

68-
**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.
68+
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.
69+
2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested implementation.
70+
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.
6971

70-
### How to Contribute
72+
**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).
7173

72-
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.).
74+
> **Tip:** If you use Claude Code / OpenCode / Codex, you can file issues interactively:
75+
> ```
76+
> File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
77+
> ```
7378
74-
**Hint:** If you use Claude Code / OpenCode / Codex (assume `gh` CLI tool and `superpowers` plugin are installed), you can just type:
75-
```
76-
File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
77-
```
78-
```
79-
File an issue on CodingThrust/problem-reductions, using the "Rule" issue template, about reduction from Closest Vector Problem to QUBO. Brainstorm with me.
80-
```
81-
Then AI agents will guide you to fill in the issue template.
82-
83-
2. Our AI agents will pick up the issue and generate a plan to implement the reduction rule.
84-
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.
85-
86-
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.
87-
88-
### Developer Commands
89-
90-
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.
79+
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.
9180
9281
## Acknowledgments
9382

‎benches/solver_benchmarks.rs‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
//! Benchmarks for the BruteForce solver on various problem types.
22
33
use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
4+
use problemreductions::models::formula::*;
45
use problemreductions::models::graph::*;
5-
use problemreductions::models::optimization::*;
6-
use problemreductions::models::satisfiability::*;
6+
use problemreductions::models::misc::*;
77
use problemreductions::models::set::*;
8-
use problemreductions::models::specialized::*;
98
use problemreductions::prelude::*;
109
use problemreductions::topology::SimpleGraph;
1110
use problemreductions::variant::K3;

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Problem Categorization Redesign
2+
3+
## Problem
4+
5+
The current categorization mixes two axes:
6+
- **Input structure** (graph, set system, formula)
7+
- **Problem type** (optimization vs satisfaction)
8+
9+
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.
10+
11+
## Design
12+
13+
**Single axis: primary input structure** — "what data type does the problem operate on?"
14+
15+
The optimization/satisfaction distinction is already captured by the trait hierarchy (`OptimizationProblem` vs `SatisfactionProblem`), so folders should not duplicate it.
16+
17+
### New folder structure
18+
19+
```
20+
src/models/
21+
├── graph/ # Input: a graph (optionally weighted)
22+
│ ├── maximum_independent_set.rs
23+
│ ├── maximum_clique.rs
24+
│ ├── max_cut.rs
25+
│ ├── maximum_matching.rs
26+
│ ├── minimum_vertex_cover.rs
27+
│ ├── minimum_dominating_set.rs
28+
│ ├── maximal_is.rs
29+
│ ├── kcoloring.rs
30+
│ ├── traveling_salesman.rs
31+
│ ├── spin_glass.rs ← from optimization/
32+
│ └── biclique_cover.rs ← from specialized/
33+
│
34+
├── formula/ # Input: a logical formula or circuit
35+
│ ├── sat.rs
36+
│ ├── ksat.rs
37+
│ └── circuit.rs ← from specialized/
38+
│
39+
├── set/ # Input: universe + collection of subsets
40+
│ ├── minimum_set_covering.rs
41+
│ └── maximum_set_packing.rs
42+
│
43+
├── algebraic/ # Input: matrix, linear system, or lattice
44+
│ ├── qubo.rs ← from optimization/
45+
│ ├── ilp.rs ← from optimization/
46+
│ ├── closest_vector_problem.rs ← from optimization/
47+
│ └── bmf.rs ← from specialized/
48+
│
49+
└── misc/ # Problems with unique input structures
50+
├── bin_packing.rs ← from optimization/
51+
├── paintshop.rs ← from specialized/
52+
└── factoring.rs ← from specialized/
53+
```
54+
55+
### Decision rule for new problems
56+
57+
> "What is the primary data structure in the struct definition?"
58+
> - Graph → `graph/`
59+
> - Boolean formula or circuit → `formula/`
60+
> - Universe + subsets → `set/`
61+
> - Matrix, linear system, or lattice → `algebraic/`
62+
> - None of the above → `misc/`
63+
64+
### What moves
65+
66+
| Problem | From | To | Reason |
67+
|---|---|---|---|
68+
| SpinGlass | optimization/ | graph/ | Parameterized by G, operates on graph edges |
69+
| BicliqueCover | specialized/ | graph/ | Input is a BipartiteGraph |
70+
| CircuitSAT | specialized/ | formula/ | Input is a boolean circuit |
71+
| QUBO | optimization/ | algebraic/ | Input is a Q matrix (no graph param) |
72+
| ILP | optimization/ | algebraic/ | Input is constraint matrix + objective |
73+
| CVP | optimization/ | algebraic/ | Input is lattice basis matrix |
74+
| BMF | specialized/ | algebraic/ | Input is a boolean matrix |
75+
| BinPacking | optimization/ | misc/ | Input is items + capacity |
76+
| PaintShop | specialized/ | misc/ | Input is a car sequence |
77+
| Factoring | specialized/ | misc/ | Input is an integer |
78+
79+
### What doesn't change
80+
81+
- Trait hierarchy (`OptimizationProblem`, `SatisfactionProblem`)
82+
- All public API, type names, re-exports
83+
- Only `mod.rs` files, `use` paths, and `#[path]` test references change
84+
- The `optimization/` and `specialized/` folders are eliminated

‎docs/src/design.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ This guide covers the library internals for contributors.
1717

1818
| Module | Purpose |
1919
|--------|---------|
20-
| [`src/models/`](#problem-model) | Problem type implementations (SAT, Graph, Set, Optimization) |
20+
| [`src/models/`](#problem-model) | Problem implementations by input structure: `graph/`, `formula/`, `set/`, `algebraic/`, `misc/` |
2121
| [`src/rules/`](#reduction-rules) | Reduction rules with `ReduceTo` implementations |
2222
| [`src/registry/`](#reduction-graph) | Reduction graph metadata (collected via `inventory`) |
2323
| [`src/solvers/`](#solvers) | BruteForce and ILP solvers |

‎docs/src/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ A path graph `0–1–2–3` has 4 vertices and 3 edges.
3939

4040
```rust,ignore
4141
use problemreductions::prelude::*;
42-
use problemreductions::models::optimization::ILP;
42+
use problemreductions::models::algebraic::ILP;
4343
use problemreductions::solvers::ILPSolver;
4444
use problemreductions::topology::SimpleGraph;
4545

‎docs/src/introduction.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@
1414
<div id="cy-controls">
1515
<div id="legend">
1616
<span class="swatch" style="background:#c8f0c8;"></span>Graph
17+
<span class="swatch" style="background:#c8c8f0;"></span>Formula
1718
<span class="swatch" style="background:#f0c8c8;"></span>Set
18-
<span class="swatch" style="background:#f0f0a0;"></span>Optimization
19-
<span class="swatch" style="background:#c8c8f0;"></span>Satisfiability
20-
<span class="swatch" style="background:#f0c8e0;"></span>Specialized
19+
<span class="swatch" style="background:#f0f0a0;"></span>Algebraic
20+
<span class="swatch" style="background:#f0c8e0;"></span>Misc
2121
<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
2222
</div>
2323
<div>
@@ -62,14 +62,17 @@ This library is the foundation of that effort: an open-source, extensible reduct
6262

6363
## Call for Contributions
6464

65-
> **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.
66-
>
67-
> **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).**
65+
> **No programming experience required.** You contribute domain knowledge — we handle the implementation.
6866
69-
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
70-
2. **Fill in all sections** — definition, algorithm, size overhead, example instance
71-
3. **Review AI-generated code** — AI generates code and you can comment on the pull request
72-
4. **Merge** — ask maintainers' assistance to merge once you are satisfied
67+
### How it works
68+
69+
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.
70+
2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested implementation.
71+
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.
72+
73+
### Authorship
74+
75+
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).
7376

7477
For manual implementation, see the [Design](./design.md#contributing) guide.
7578

‎docs/src/reductions/reduction_graph.json‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,72 +3,72 @@
33
{
44
"name": "BMF",
55
"variant": {},
6-
"category": "specialized",
7-
"doc_path": "models/specialized/struct.BMF.html",
6+
"category": "algebraic",
7+
"doc_path": "models/algebraic/struct.BMF.html",
88
"complexity": "2^(rows * rank + rank * cols)"
99
},
1010
{
1111
"name": "BicliqueCover",
1212
"variant": {},
13-
"category": "specialized",
14-
"doc_path": "models/specialized/struct.BicliqueCover.html",
13+
"category": "graph",
14+
"doc_path": "models/graph/struct.BicliqueCover.html",
1515
"complexity": "2^num_vertices"
1616
},
1717
{
1818
"name": "BinPacking",
1919
"variant": {
2020
"weight": "f64"
2121
},
22-
"category": "optimization",
23-
"doc_path": "models/optimization/struct.BinPacking.html",
22+
"category": "misc",
23+
"doc_path": "models/misc/struct.BinPacking.html",
2424
"complexity": "2^num_items"
2525
},
2626
{
2727
"name": "BinPacking",
2828
"variant": {
2929
"weight": "i32"
3030
},
31-
"category": "optimization",
32-
"doc_path": "models/optimization/struct.BinPacking.html",
31+
"category": "misc",
32+
"doc_path": "models/misc/struct.BinPacking.html",
3333
"complexity": "2^num_items"
3434
},
3535
{
3636
"name": "CircuitSAT",
3737
"variant": {},
38-
"category": "specialized",
39-
"doc_path": "models/specialized/struct.CircuitSAT.html",
38+
"category": "formula",
39+
"doc_path": "models/formula/struct.CircuitSAT.html",
4040
"complexity": "2^num_variables"
4141
},
4242
{
4343
"name": "ClosestVectorProblem",
4444
"variant": {
4545
"weight": "f64"
4646
},
47-
"category": "optimization",
48-
"doc_path": "models/optimization/struct.ClosestVectorProblem.html",
47+
"category": "algebraic",
48+
"doc_path": "models/algebraic/struct.ClosestVectorProblem.html",
4949
"complexity": "2^num_basis_vectors"
5050
},
5151
{
5252
"name": "ClosestVectorProblem",
5353
"variant": {
5454
"weight": "i32"
5555
},
56-
"category": "optimization",
57-
"doc_path": "models/optimization/struct.ClosestVectorProblem.html",
56+
"category": "algebraic",
57+
"doc_path": "models/algebraic/struct.ClosestVectorProblem.html",
5858
"complexity": "2^num_basis_vectors"
5959
},
6060
{
6161
"name": "Factoring",
6262
"variant": {},
63-
"category": "specialized",
64-
"doc_path": "models/specialized/struct.Factoring.html",
63+
"category": "misc",
64+
"doc_path": "models/misc/struct.Factoring.html",
6565
"complexity": "exp((m + n)^(1/3) * log(m + n)^(2/3))"
6666
},
6767
{
6868
"name": "ILP",
6969
"variant": {},
70-
"category": "optimization",
71-
"doc_path": "models/optimization/struct.ILP.html",
70+
"category": "algebraic",
71+
"doc_path": "models/algebraic/struct.ILP.html",
7272
"complexity": "num_variables^num_variables"
7373
},
7474
{
@@ -126,26 +126,26 @@
126126
"variant": {
127127
"k": "K2"
128128
},
129-
"category": "satisfiability",
130-
"doc_path": "models/satisfiability/struct.KSatisfiability.html",
129+
"category": "formula",
130+
"doc_path": "models/formula/struct.KSatisfiability.html",
131131
"complexity": "num_variables + num_clauses"
132132
},
133133
{
134134
"name": "KSatisfiability",
135135
"variant": {
136136
"k": "K3"
137137
},
138-
"category": "satisfiability",
139-
"doc_path": "models/satisfiability/struct.KSatisfiability.html",
138+
"category": "formula",
139+
"doc_path": "models/formula/struct.KSatisfiability.html",
140140
"complexity": "1.307^num_variables"
141141
},
142142
{
143143
"name": "KSatisfiability",
144144
"variant": {
145145
"k": "KN"
146146
},
147-
"category": "satisfiability",
148-
"doc_path": "models/satisfiability/struct.KSatisfiability.html",
147+
"category": "formula",
148+
"doc_path": "models/formula/struct.KSatisfiability.html",
149149
"complexity": "2^num_variables"
150150
},
151151
{
@@ -317,24 +317,24 @@
317317
{
318318
"name": "PaintShop",
319319
"variant": {},
320-
"category": "specialized",
321-
"doc_path": "models/specialized/struct.PaintShop.html",
320+
"category": "misc",
321+
"doc_path": "models/misc/struct.PaintShop.html",
322322
"complexity": "2^num_cars"
323323
},
324324
{
325325
"name": "QUBO",
326326
"variant": {
327327
"weight": "f64"
328328
},
329-
"category": "optimization",
330-
"doc_path": "models/optimization/struct.QUBO.html",
329+
"category": "algebraic",
330+
"doc_path": "models/algebraic/struct.QUBO.html",
331331
"complexity": "2^num_vars"
332332
},
333333
{
334334
"name": "Satisfiability",
335335
"variant": {},
336-
"category": "satisfiability",
337-
"doc_path": "models/satisfiability/struct.Satisfiability.html",
336+
"category": "formula",
337+
"doc_path": "models/formula/struct.Satisfiability.html",
338338
"complexity": "2^num_variables"
339339
},
340340
{
@@ -343,8 +343,8 @@
343343
"graph": "SimpleGraph",
344344
"weight": "f64"
345345
},
346-
"category": "optimization",
347-
"doc_path": "models/optimization/struct.SpinGlass.html",
346+
"category": "graph",
347+
"doc_path": "models/graph/struct.SpinGlass.html",
348348
"complexity": "2^num_spins"
349349
},
350350
{
@@ -353,8 +353,8 @@
353353
"graph": "SimpleGraph",
354354
"weight": "i32"
355355
},
356-
"category": "optimization",
357-
"doc_path": "models/optimization/struct.SpinGlass.html",
356+
"category": "graph",
357+
"doc_path": "models/graph/struct.SpinGlass.html",
358358
"complexity": "2^num_spins"
359359
},
360360
{

0 commit comments

Comments
 (0)