diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c414fae9..9d567178 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -56,7 +56,7 @@ Problem (core trait — all problems must implement) ├── type Metric: Clone // SolutionSize for optimization, bool for satisfaction ├── fn dims(&self) -> Vec // config space: [2, 2, 2] for 3 binary variables ├── fn evaluate(&self, config) -> Metric -├── fn variant() -> Vec<(&str, &str)> // [("graph","SimpleGraph"), ("weight","i32")] +├── fn variant() -> Vec<(&str, &str)> // e.g., [("graph","SimpleGraph"), ("weight","i32")] └── fn num_variables(&self) -> usize // default: dims().len() OptimizationProblem : Problem> (extension for optimization) @@ -74,7 +74,7 @@ enum Direction { Maximize, Minimize } ``` ### Key Patterns -- Problems parameterized by weight type `W` and graph type `G` +- Problems parameterized by graph type `G` and optionally weight type `W` (problem-dependent) - `ReductionResult` provides `target_problem()` and `extract_solution()` - `Solver::find_best()` → `Option>` for optimization problems; `Solver::find_satisfying()` → `Option>` for `Metric = bool` - `BruteForce::find_all_best()` / `find_all_satisfying()` return `Vec>` for all optimal/satisfying solutions @@ -111,90 +111,6 @@ Reduction graph nodes use variant IDs: `ProblemName[/GraphType][/Weighted]` - Completeness warnings auto-check that all JSON graph nodes/edges are covered in the paper - `display-name` dict maps `ProblemName` to display text -## Adding a Reduction Rule (A -> B) - -**Reference implementations — read these first:** -- **Reduction rule:** `src/rules/minimumvertexcover_maximumindependentset.rs` — `ReductionResult` + `ReduceTo` + `#[reduction]` macro -- **Unit test:** `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs` — closed-loop + edge cases -- **Example program:** `examples/reduction_minimumvertexcover_to_maximumindependentset.rs` — create, reduce, solve, extract, verify, export -- **Paper entry:** `docs/paper/reductions.typ` (search for `MinimumVertexCover` `MaximumIndependentSet`) -- **Traits:** `src/rules/traits.rs` — `ReductionResult` and `ReduceTo` trait definitions - -### 0. Before Writing Code - -1. **Ensure you have enough information** - - The reduction algorithm, from reliable source, e.g. a paper or a famous website. - - Which example instance to use in `examples/`, example is expected for human reading. - - The method to generate test data in `tests/data//` as json files. - - otherwise use `superpowers:brainstorming` to discuss with the user. -2. **Write plan** — save to `docs/plans/` using `superpowers:writing-plans`. - -### 1. Implement - -Create `src/rules/_.rs` following the reference. Key pieces: - -- **`ReductionResult` struct + impl** — `target_problem()` + `extract_solution()` (see reference) -- **`ReduceTo` impl with `#[reduction(...)]` macro** — auto-generates `inventory::submit!`; only `overhead` attribute needed (graph/weight types are inferred, defaulting to `SimpleGraph`/`Unweighted`) -- **`#[cfg(test)] #[path = ...]`** linking to unit tests - -Register in `src/rules/mod.rs`. - -### 2. Test - -- **Unit tests** in `src/unit_tests/rules/_.rs` — closed-loop + edge cases (see reference test). -- **Integration tests** in `tests/suites/reductions.rs` — compare against JSON ground truth. - -### 3. Example Program - -Add `examples/reduction__to_.rs` — create, reduce, solve, extract, verify, export JSON (see reference example). - -Examples must expose `pub fn run()` with `fn main() { run() }` so they can be tested directly via `include!` (no subprocess). Use regular comments (`//`) not inner doc comments (`//!`), and hardcode the example name instead of using `env!("CARGO_BIN_NAME")`. - -Register the example in `tests/suites/examples.rs` by adding: -```rust -example_test!(reduction__to_); -example_fn!(test__to_, reduction__to_); -``` - -### 4. Document - -Update `docs/paper/reductions.typ` — add `reduction-rule("Source", "Target", ...)` with proof sketch (see Documentation Requirements section below). - -### 5. Regenerate Graph - -```bash -cargo run --example export_graph -``` - -## Adding a Model (Problem Type) - -**Reference implementations — read these first:** -- **Optimization problem:** `src/models/graph/maximum_independent_set.rs` — `Problem` + `OptimizationProblem` with `Metric = SolutionSize` -- **Satisfaction problem:** `src/models/satisfiability/sat.rs` — `Problem` with `Metric = bool` -- **Reference test:** `src/unit_tests/models/graph/maximum_independent_set.rs` - -### Steps - -1. **Create** `src/models//.rs` — follow the reference for struct definition, `Problem` impl, and `OptimizationProblem` impl (if applicable). -2. **Register** in `src/models//mod.rs`. -3. **Add tests** in `src/unit_tests/models//.rs` (linked via `#[path]`). -4. **Document** in `docs/paper/reductions.typ`: add `display-name` entry and `#problem-def("Name")[definition...]`. - -### Trait Implementations - -See Trait Hierarchy above for `Problem` and `OptimizationProblem` members. Weight management (`weights()`, `set_weights()`, `is_weighted()`) goes on inherent `impl` blocks, not traits. See the reference implementation for the pattern. - -### Categories - -- `src/models/satisfiability/` — Satisfiability, KSatisfiability -- `src/models/graph/` — MaximumIndependentSet, MinimumVertexCover, KColoring, etc. -- `src/models/set/` — MinimumSetCovering, MaximumSetPacking -- `src/models/optimization/` — SpinGlass, QUBO, ILP -- `src/models/specialized/` — CircuitSAT, Factoring, PaintShop, BicliqueCover, BMF - -Naming convention: see Problem Names above. - ## Testing Requirements **Reference implementations — read these first:** @@ -219,7 +135,7 @@ See Key Patterns above for solver API signatures. Follow the reference files for ### File Organization -Unit tests in `src/unit_tests/` linked via `#[path]` (see Core Modules above). Integration tests in `tests/suites/`, consolidated through `tests/main.rs`. Example tests in `tests/suites/examples.rs` (see Example Program in Adding a Reduction above). +Unit tests in `src/unit_tests/` linked via `#[path]` (see Core Modules above). Integration tests in `tests/suites/`, consolidated through `tests/main.rs`. Example tests in `tests/suites/examples.rs` using `include!` for direct invocation. ## Documentation Requirements diff --git a/.claude/skills/issue-to-pr.md b/.claude/skills/issue-to-pr.md index 29de3b64..bf50be6a 100644 --- a/.claude/skills/issue-to-pr.md +++ b/.claude/skills/issue-to-pr.md @@ -72,7 +72,74 @@ If the reference is a paper or textbook, search for accessible summaries, lectur ### 5. Write Plan -Write plan to `docs/plans/YYYY-MM-DD-.md` using `superpowers:writing-plans`: +Write plan to `docs/plans/YYYY-MM-DD-.md` using `superpowers:writing-plans`. + +The plan MUST include an **action pipeline** section with concrete steps based on issue type. + +#### For `[Rule]` issues (A -> B reduction) + +**Reference implementations — read these first:** +- Reduction rule: `src/rules/minimumvertexcover_maximumindependentset.rs` +- Unit test: `src/unit_tests/rules/minimumvertexcover_maximumindependentset.rs` +- Example program: `examples/reduction_minimumvertexcover_to_maximumindependentset.rs` +- Paper entry: search `docs/paper/reductions.typ` for `MinimumVertexCover` `MaximumIndependentSet` +- Traits: `src/rules/traits.rs` + +**Action pipeline:** + +1. **Implement reduction** — Create `src/rules/_.rs`: + - `ReductionResult` struct + impl (`target_problem()` + `extract_solution()`) + - `ReduceTo` impl with `#[reduction(...)]` macro (only `overhead` attribute needed) + - `#[cfg(test)] #[path = ...]` linking to unit tests + - Register in `src/rules/mod.rs` + +2. **Write unit tests** — Create `src/unit_tests/rules/_.rs`: + - Closed-loop test: create source → reduce → solve target → extract → verify + - Edge cases + +3. **Write example program** — Create `examples/reduction__to_.rs`: + - Must have `pub fn run()` + `fn main() { run() }` + - Use regular comments (`//`), hardcode example name + - Create, reduce, solve, extract, verify, export JSON + - Register in `tests/suites/examples.rs` + +4. **Document in paper** — Update `docs/paper/reductions.typ`: + - Add `reduction-rule("Source", "Target", ...)` with proof sketch + - Present example in tutorial style (see KColoring→QUBO section for reference) + +5. **Regenerate graph** — `cargo run --example export_graph` + +**Rules for solver implementation:** +- Make sure at least one solver is provided in the issue template. Check if the solving strategy is valid. If not, reply under issue to ask for clarification. +- If the solver uses integer programming, implement the model and ILP reduction rule together. +- Otherwise, ensure the information provided is enough to implement a solver. + +**Rules for example writing:** +- Implement the user-provided example instance as an example program in `examples/`. +- Run the example; verify JSON output against user-provided information. +- Present in `docs/paper/reductions.typ` in tutorial style with clear intuition (see KColoring→QUBO section for reference). + +#### For `[Model]` issues + +**Reference implementations — read these first:** +- Optimization problem: `src/models/graph/maximum_independent_set.rs` +- Satisfaction problem: `src/models/satisfiability/sat.rs` +- Reference test: `src/unit_tests/models/graph/maximum_independent_set.rs` + +**Action pipeline:** + +1. **Implement model** — Create `src/models//.rs`: + - Struct definition, `Problem` impl, `OptimizationProblem` impl (if applicable) + - Weight management via inherent methods (`weights()`, `set_weights()`, `is_weighted()`), not traits + - Register in `src/models//mod.rs` + +2. **Write tests** — Create `src/unit_tests/models//.rs`: + - Basic evaluation tests, serialization tests + - Link via `#[path]` + +3. **Document** — Update `docs/paper/reductions.typ`: + - Add `display-name` entry + - Add `#problem-def("Name")[definition...]` ### 6. Create PR diff --git a/.github/ISSUE_TEMPLATE/problem.md b/.github/ISSUE_TEMPLATE/problem.md index 0ed94f5b..47763dbc 100644 --- a/.github/ISSUE_TEMPLATE/problem.md +++ b/.github/ISSUE_TEMPLATE/problem.md @@ -55,10 +55,10 @@ Connect fields to the symbols defined above. ## How to solve +- [ ] It can be solved by (existing) bruteforce. +- [ ] It can be solved by reducing the integer programming, through #issue-number (please file a new issue it is not exist). +- [ ] Other, refer to ... ## Example Instance diff --git a/.github/ISSUE_TEMPLATE/rule.md b/.github/ISSUE_TEMPLATE/rule.md index dd387a41..6395d33a 100644 --- a/.github/ISSUE_TEMPLATE/rule.md +++ b/.github/ISSUE_TEMPLATE/rule.md @@ -43,7 +43,7 @@ E.g. - Use external solver to cross-check --> -## Example Source Instance +## Example