perf: optimize pathdecomposition and add ground truth tests (#54)

* docs: add documentation improvements design plan

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add documentation improvements implementation plan

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* perf: optimize pathdecomposition and add ground truth tests

Build adjacency list once and pass by reference instead of rebuilding
from edge list in every function call during recursive branch-and-bound.
Also eliminate duplicate vsep_updated computation by reusing sorted costs.

Add pathwidth ground truth JSON dataset (21 standard graphs) and 4 new
tests that verify correctness against it. Mark tutte (46v, ~10s B&B) and
tutte MIS overhead (1232v grid, ~10s ILP) as #[ignore] for routine runs.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: add reduction workflow diagram

Add a visual diagram illustrating the core reduction workflow:
Problem A -> reduce_to() -> Problem B -> find_best() -> Solution B -> extract_solution() -> Solution A

Includes both light and dark theme SVG variants for mdBook.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add module overview diagram

Add a diagram showing how the main modules in the codebase relate:
- models/ contains problem type implementations
- rules/ contains reduction rules that import models
- registry/ collects reduction metadata at compile time
- solvers/ solve problem instances

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: add trait hierarchy diagram

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: rewrite Getting Started page with reduction workflow diagram

Rewrites the Getting Started page to:
- Start with "what this library does" overview
- Include the reduction workflow diagram (light/dark variants)
- Show a complete example with step-by-step comments
- Document chaining reductions pattern
- Add solvers section with links to API docs
- Document JSON resources (reduction_graph.json, problem_schemas.json)
- Update Next Steps section with relevant links

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: update Architecture with diagrams and current API

- Add intro text and Module Overview section with SVG diagram
- Add Trait Hierarchy section with diagram and code examples
- Fix outdated API: solution_size() -> evaluate()
- Update method table with Metric, dims(), evaluate()
- Remove reference to deleted ConstraintSatisfactionProblem trait
- Fix ReduceTo syntax: problem.reduce_to::<T>() -> ReduceTo::<T>::reduce_to(&problem)
- Add Contributing section with issue-based workflow

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: regenerate reduction_graph.json

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: single source location for JSON schemas

- Export examples now write directly to docs/src/reductions/
- Paper uses --root flag to access files via relative path
- Remove duplicate files from docs/paper/
- Update doc comments with correct paths

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: resolve rustdoc and mdbook warnings

- Escape `Weighted<i32>` in doc comment to avoid HTML tag warning
- Remove orphan </details> tag in arch.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs: make arch.md orthogonal with getting-started.md

- Remove duplicated workflow/usage explanations
- Focus on implementation details for contributors
- Rename sections to "Implementing X" for clarity
- Reference getting-started.md for usage examples
- Streamline JSON schema examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* update

* diagrams

* refactor: Solver::find_best returns Option, polish docs

- Change Solver::find_best to return Option<Vec<usize>> (was Vec<Vec<usize>>)
  for symmetry with find_satisfying
- Make BruteForce::find_all_best public for multi-solution queries
- Migrate all call sites: tests use find_all_best, examples use find_all_best
- Polish getting-started.md, arch.md, introduction.md
- Align arch.md sections with module overview (Models, Rules, Registry, Solvers)
- Add "Call for Contributions" section to introduction with authorship incentive

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: remove stale docs/src/claude.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address PR review comments

- Move HashSet import to top of file (pathdecomposition test)
- Pretty-print pathwidth_ground_truth.json for readability

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: GiggleLiu

.claude/CLAUDE.md

@@ -72,7 +72,8 @@ enum Direction { Maximize, Minimize }
 ### Key Patterns
 - Problems parameterized by weight type `W` and graph type `G`
 - `ReductionResult` provides `target_problem()` and `extract_solution()`
-- `Solver::find_best()` for optimization problems, `Solver::find_satisfying()` for `Metric = bool`
+- `Solver::find_best()` → `Option<Vec<usize>>` for optimization problems; `Solver::find_satisfying()` → `Option<Vec<usize>>` for `Metric = bool`
+- `BruteForce::find_all_best()` / `find_all_satisfying()` return `Vec<Vec<usize>>` for all optimal/satisfying solutions
 - Graph types: SimpleGraph, GridGraph, UnitDiskGraph, Hypergraph
 - Weight types: `Unweighted` (marker), `i32`, `f64`
 - Weight management via inherent methods (`weights()`, `set_weights()`, `is_weighted()`), not traits

.claude/rules/testing.md

@@ -20,8 +20,10 @@ New code must have >95% test coverage. Run `make coverage` to check.
 
 Follow the reference files above for exact API usage. Summary:
 
-- `solver.find_best(&problem)` — for optimization problems (`OptimizationProblem`, `Metric = SolutionSize<W>`)
-- `solver.find_satisfying(&problem)` — for satisfaction problems (`Metric = bool`)
+- `solver.find_best(&problem)` → `Option<Vec<usize>>` — one optimal solution for optimization problems
+- `solver.find_satisfying(&problem)` → `Option<Vec<usize>>` — one satisfying assignment
+- `solver.find_all_best(&problem)` → `Vec<Vec<usize>>` — all optimal solutions (BruteForce only)
+- `solver.find_all_satisfying(&problem)` → `Vec<Vec<usize>>` — all satisfying assignments (BruteForce only)
 - `problem.evaluate(&config)` — returns `SolutionSize::Valid(value)` / `SolutionSize::Invalid` for optimization, `bool` for satisfaction
 
 ## File Organization

Makefile

@@ -1,6 +1,6 @@
 # Makefile for problemreductions
 
-.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release run-plan
+.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release run-plan diagrams
 
 # Default target
 help:
@@ -11,6 +11,7 @@ help:
 	@echo "  fmt-check    - Check code formatting"
 	@echo "  clippy       - Run clippy lints"
 	@echo "  doc          - Build mdBook documentation"
+	@echo "  diagrams     - Generate SVG diagrams from Typst (light + dark)"
 	@echo "  mdbook       - Build and serve mdBook (with live reload)"
 	@echo "  paper        - Build Typst paper (requires typst)"
 	@echo "  coverage     - Generate coverage report (requires cargo-llvm-cov)"
@@ -47,16 +48,26 @@ clippy:
 # Build mdBook documentation
 doc:
 	cargo run --example export_graph
-	cp docs/paper/reduction_graph.json docs/src/reductions/
+	cargo run --example export_schemas
 	mdbook build docs
 	RUSTDOCFLAGS="--default-theme=dark" cargo doc --all-features --no-deps
 	rm -rf docs/book/api
 	cp -r target/doc docs/book/api
 
+# Generate SVG diagrams from Typst sources (light + dark themes)
+TYPST_DIAGRAMS := $(wildcard docs/src/static/*.typ)
+diagrams:
+	@for src in $(TYPST_DIAGRAMS); do \
+		base=$$(basename $$src .typ); \
+		echo "Compiling $$base..."; \
+		typst compile $$src --input dark=false docs/src/static/$$base.svg; \
+		typst compile $$src --input dark=true docs/src/static/$$base-dark.svg; \
+	done
+
 # Build and serve mdBook with API docs
 mdbook:
 	cargo run --example export_graph
-	cp docs/paper/reduction_graph.json docs/src/reductions/
+	cargo run --example export_schemas
 	RUSTDOCFLAGS="--default-theme=dark" cargo doc --all-features --no-deps
 	mdbook build
 	rm -rf book/api
@@ -84,7 +95,7 @@ export-schemas:
 paper: examples
 	cargo run --example export_graph
 	cargo run --example export_schemas
-	cd docs/paper && typst compile reductions.typ reductions.pdf
+	cd docs/paper && typst compile --root .. reductions.typ reductions.pdf
 
 # Generate coverage report (requires: cargo install cargo-llvm-cov)
 coverage: