Merge pull request #25 from CodingThrust/feat/problem-variants-and-docs

feat: Add problem variants, documentation improvements, and reduction macro

Author: GiggleLiu

.claude/CLAUDE.md

@@ -23,9 +23,57 @@ make test clippy export-graph  # Must pass before PR
 - `src/models/` - Problem implementations (SAT, Graph, Set, Optimization)
 - `src/rules/` - Reduction rules + inventory registration
 - `src/solvers/` - BruteForce solver, ILP solver (feature-gated)
-- `src/traits/` - `Problem`, `ConstraintSatisfactionProblem`, `ReduceTo<T>` traits
+- `src/traits.rs` - `Problem`, `ConstraintSatisfactionProblem` traits
+- `src/rules/traits.rs` - `ReduceTo<T>`, `ReductionResult` traits
 - `src/registry/` - Compile-time reduction metadata collection
 
+### Trait Hierarchy
+
+```
+Problem (core trait - all problems must implement)
+│
+├── const NAME: &'static str           // Problem name, e.g., "IndependentSet"
+├── type GraphType: GraphMarker        // Graph topology marker
+├── type Weight: NumericWeight         // Weight type (i32, f64, Unweighted)
+├── type Size                          // Objective value type
+│
+├── fn num_variables(&self) -> usize
+├── fn num_flavors(&self) -> usize     // Usually 2 for binary problems
+├── fn problem_size(&self) -> ProblemSize
+├── fn energy_mode(&self) -> EnergyMode
+├── fn solution_size(&self, config) -> SolutionSize
+└── ... (default methods: variables, flavors, is_valid_config)
+
+ConstraintSatisfactionProblem : Problem (extension for CSPs)
+│
+├── fn constraints(&self) -> Vec<LocalConstraint>
+├── fn objectives(&self) -> Vec<LocalSolutionSize>
+├── fn weights(&self) -> Vec<Self::Size>
+├── fn set_weights(&mut self, weights)
+├── fn is_weighted(&self) -> bool
+└── ... (default methods: is_satisfied, compute_objective)
+```
+
+### Problem Implementations
+
+| Problem | `Problem` | `ConstraintSatisfactionProblem` |
+|---------|:---------:|:-------------------------------:|
+| IndependentSet | ✓ | ✓ |
+| VertexCovering | ✓ | ✓ |
+| DominatingSet | ✓ | ✓ |
+| Matching | ✓ | ✓ |
+| MaxCut | ✓ | ✗ |
+| Coloring | ✓ | ✓ |
+| Satisfiability | ✓ | ✓ |
+| KSatisfiability | ✓ | ✓ |
+| SetPacking | ✓ | ✓ |
+| SetCovering | ✓ | ✓ |
+| SpinGlass | ✓ | ✗ |
+| QUBO | ✓ | ✗ |
+| ILP | ✓ | ✗ |
+| CircuitSAT | ✓ | ✗ |
+| Factoring | ✓ | ✗ |
+
 ### Key Patterns
 - Problems parameterized by weight type `W` and graph type `G`
 - `ReductionResult` provides `target_problem()` and `extract_solution()`
@@ -38,22 +86,101 @@ make test clippy export-graph  # Must pass before PR
 - Model files: `src/models/<category>/<name>.rs`
 - Test naming: `test_<source>_to_<target>_closed_loop`
 
-### Reduction Pattern
+### Reduction Pattern (Recommended: Using Macro)
 ```rust
-impl ReduceTo<TargetProblem> for SourceProblem {
+use problemreductions::reduction;
+
+#[reduction(
+    overhead = { ReductionOverhead::new(vec![...]) }
+)]
+impl ReduceTo<TargetProblem<Unweighted>> for SourceProblem<Unweighted> {
     type Result = ReductionSourceToTarget;
     fn reduce_to(&self) -> Self::Result { ... }
 }
+```
+
+The `#[reduction]` macro automatically:
+- Extracts type names from the impl signature
+- Detects weighted vs unweighted from type parameters (`Unweighted` vs `i32`/`f64`)
+- Detects graph types from type parameters (e.g., `GridGraph`, `SimpleGraph`)
+- Generates the `inventory::submit!` call
 
-inventory::submit! { ReductionEntry { source_name, target_name, ... } }
+Optional macro attributes:
+- `source_graph = "..."` - Override detected source graph type
+- `target_graph = "..."` - Override detected target graph type
+- `source_weighted = true/false` - Override weighted detection
+- `target_weighted = true/false` - Override weighted detection
+- `overhead = { ... }` - Specify reduction overhead
+
+### Manual Registration (Alternative)
+```rust
+inventory::submit! {
+    ReductionEntry {
+        source_name: "SourceProblem",
+        target_name: "TargetProblem",
+        source_variant: &[("graph", "SimpleGraph"), ("weight", "Unweighted")],
+        target_variant: &[("graph", "SimpleGraph"), ("weight", "Unweighted")],
+        overhead_fn: || ReductionOverhead::new(...),
+    }
+}
 ```
 
+### Weight Types
+- `Unweighted` - Marker type for unweighted problems (all weights = 1)
+- `i32`, `f64`, etc. - Concrete weight types for weighted problems
+
+### Problem Variant IDs
+Reduction graph nodes use variant IDs: `ProblemName[/GraphType][/Weighted]`
+- Base: `IndependentSet` (SimpleGraph, unweighted)
+- Graph variant: `IndependentSet/GridGraph`
+- Weighted variant: `IndependentSet/Weighted`
+- Both: `IndependentSet/GridGraph/Weighted`
+
 ## Anti-patterns
 - Don't create reductions without closed-loop tests
 - Don't forget `inventory::submit!` registration (graph won't update)
 - Don't hardcode weights - use generic `W` parameter
 - Don't skip `make clippy` before PR
 
+## Documentation Requirements
+
+The technical paper (`docs/paper/reductions.typ`) must include:
+
+1. **Table of Contents** - Auto-generated outline of all sections
+2. **Problem Data Structures** - For each problem definition, include the Rust struct with fields in a code block
+3. **Reduction Examples** - For each reduction theorem, include a minimal working example showing:
+   - Creating the source problem
+   - Reducing to target problem
+   - Solving and extracting solution back
+   - Based on closed-loop tests from `tests/reduction_tests.rs`
+
+### Documentation Pattern
+```typst
+#definition("Problem Name")[
+  Mathematical definition...
+]
+
+// Rust data structure
+```rust
+pub struct ProblemName<W = i32> {
+    field1: Type1,
+    field2: Type2,
+}
+`` `
+
+#theorem[
+  *(Source → Target)* Reduction description...
+]
+
+// Minimal working example
+```rust
+let source = SourceProblem::new(...);
+let reduction = ReduceTo::<TargetProblem>::reduce_to(&source);
+let target = reduction.target_problem();
+// ... solve and extract
+`` `
+```
+
 ## Contributing
 See `.claude/rules/` for detailed guides:
 - `adding-reductions.md` - How to add reduction rules

Cargo.lock

@@ -1,3 +1,6 @@
+[workspace]
+members = [".", "problemreductions-macros"]
+
 [package]
 name = "problemreductions"
 version = "0.1.0"
@@ -23,6 +26,7 @@ good_lp = { version = "1.8", default-features = false, features = ["highs"], opt
 inventory = "0.3"
 ordered-float = "5.0"
 rand = "0.8"
+problemreductions-macros = { path = "problemreductions-macros" }
 
 [dev-dependencies]
 proptest = "1.0"

Cargo.toml

@@ -0,0 +1,22 @@
+# Codecov configuration for problem-reductions
+# https://docs.codecov.com/docs/codecov-yaml
+
+coverage:
+  precision: 2
+  round: down
+  range: "90...100"
+
+  status:
+    project:
+      default:
+        target: 95%
+        threshold: 2%
+    patch:
+      default:
+        target: 95%
+        threshold: 2%
+
+# Exclude proc-macro crate from coverage since it runs at compile time
+# and traditional runtime coverage tools cannot measure it
+ignore:
+  - "problemreductions-macros/**/*"

codecov.yml

@@ -0,0 +1,157 @@
+#import "@preview/fletcher:0.5.8" as fletcher: diagram, node, edge
+#import "@preview/cetz:0.4.2": canvas, draw
+
+#let graph-data = json("reduction_graph.json")
+
+#let category-colors = (
+  "graph": rgb("#e0ffe0"),
+  "set": rgb("#ffe0e0"),
+  "optimization": rgb("#ffffd0"),
+  "satisfiability": rgb("#e0e0ff"),
+  "specialized": rgb("#ffe0f0"),
+  "other": rgb("#f0f0f0"),
+)
+
+#let get-color(category) = {
+  category-colors.at(category, default: rgb("#f0f0f0"))
+}
+
+// Build node ID from name + variant (new JSON format)
+// Format: "Name" for base, "Name/graph/weight" for variants
+#let build-node-id(n) = {
+  if n.variant == (:) or n.variant.keys().len() == 0 {
+    n.name
+  } else {
+    let parts = (n.name,)
+    if "graph" in n.variant and n.variant.graph != "" and n.variant.graph != "SimpleGraph" {
+      parts.push(n.variant.graph)
+    }
+    if "weight" in n.variant and n.variant.weight != "" and n.variant.weight != "Unweighted" {
+      parts.push(n.variant.weight)
+    }
+    parts.join("/")
+  }
+}
+
+// Build display label from name + variant
+#let build-node-label(n) = {
+  if n.variant == (:) or n.variant.keys().len() == 0 {
+    n.name
+  } else {
+    // For variants, show abbreviated form
+    let suffix = ()
+    if "graph" in n.variant and n.variant.graph != "" and n.variant.graph != "SimpleGraph" {
+      suffix.push(n.variant.graph)
+    }
+    // Filter out Unweighted and single-letter generic type params (W, K, T, etc.)
+    if "weight" in n.variant and n.variant.weight != "" and n.variant.weight != "Unweighted" and n.variant.weight.len() != 1 {
+      suffix.push(n.variant.weight)
+    }
+    if suffix.len() > 0 {
+      n.name + "/" + suffix.join("/")
+    } else {
+      n.name
+    }
+  }
+}
+
+// Check if node is a base problem (empty variant)
+#let is-base-problem(n) = {
+  n.variant == (:) or n.variant.keys().len() == 0
+}
+
+// Base problem positions
+#let base-positions = (
+  // Row 0: Root nodes
+  "Satisfiability": (-1.5, 0),
+  "Factoring": (2.5, 0),
+  // Row 1: Direct children of roots
+  "KSatisfiability": (-2.5, 1),
+  "IndependentSet": (-0.5, 1),
+  "Coloring": (0.5, 1),
+  "DominatingSet": (-1.5, 1),
+  "CircuitSAT": (2.5, 1),
+  // Row 2: Next level
+  "VertexCovering": (-0.5, 2),
+  "Matching": (-2, 2),
+  "SpinGlass": (2.5, 2),
+  "ILP": (3.5, 1),
+  // Row 3: Leaf nodes
+  "SetPacking": (-1.5, 3),
+  "SetCovering": (0.5, 3),
+  "MaxCut": (1.5, 3),
+  "QUBO": (3.5, 3),
+  "GridGraph": (0.5, 2),
+)
+
+// Get position for a node
+#let get-node-position(n) = {
+  if is-base-problem(n) {
+    // Base problem - use manual position
+    base-positions.at(n.name, default: (0, 0))
+  } else {
+    // Variant - position below parent with horizontal offset
+    let parent-pos = base-positions.at(n.name, default: (0, 0))
+    // Find variant index among siblings with same base name
+    let siblings = graph-data.nodes.filter(x => x.name == n.name and not is-base-problem(x))
+    let idx = siblings.position(x => build-node-id(x) == build-node-id(n))
+    let offset = if idx == none { 0 } else { idx * 0.4 }
+    (parent-pos.at(0) + offset, parent-pos.at(1) + 0.5)
+  }
+}
+
+// Filter to show only base problems in the main diagram
+#let base-nodes = graph-data.nodes.filter(n => is-base-problem(n))
+
+// Collect unique base problem names
+#let base-names = base-nodes.map(n => n.name)
+
+// Filter edges to only those between base problem names (ignoring variants)
+// This allows us to show the high-level structure even though edges connect variant nodes
+#let base-edges = graph-data.edges.filter(e => {
+  base-names.contains(e.source.name) and base-names.contains(e.target.name)
+})
+
+// Deduplicate edges by (source-name, target-name) pair, keeping bidirectionality
+#let edge-key(e) = if e.source.name < e.target.name {
+  (e.source.name, e.target.name)
+} else {
+  (e.target.name, e.source.name)
+}
+
+// Group edges by their base names and merge bidirectionality
+#let edge-map = (:)
+#for e in base-edges {
+  let key = e.source.name + "->" + e.target.name
+  let rev-key = e.target.name + "->" + e.source.name
+  if rev-key in edge-map {
+    // Reverse edge exists, mark as bidirectional
+    edge-map.at(rev-key).bidirectional = true
+  } else if key not in edge-map {
+    edge-map.insert(key, (source: e.source.name, target: e.target.name, bidirectional: e.bidirectional))
+  }
+}
+
+#let deduped-edges = edge-map.values()
+
+#let reduction-graph(width: 18mm, height: 14mm) = diagram(
+  spacing: (width, height),
+  node-stroke: 0.6pt,
+  edge-stroke: 0.6pt,
+  node-corner-radius: 2pt,
+  node-inset: 3pt,
+  ..base-nodes.map(n => {
+    let color = get-color(n.category)
+    let pos = get-node-position(n)
+    let node-label = build-node-label(n)
+    let node-id = build-node-id(n)
+    node(pos, text(size: 7pt)[#node-label], fill: color, name: label(node-id))
+  }),
+  ..deduped-edges.map(e => {
+    let arrow = if e.bidirectional { "<|-|>" } else { "-|>" }
+    // Use simple name as node ID since we're showing base problems
+    edge(label(e.source), label(e.target), arrow)
+  }),
+)
+
+#reduction-graph()