Roadmap

> I have a plan to extend this Rust package to support at least 100 most important NP-complete problems. First, I need to design a best architecture to make it easy for extention. You should search on the web, follow the best practice and help me look at the current status.

# Architecture Design for 100+ NP-Complete Problems

## Executive Summary

This document outlines the architecture redesign needed to scale the `problemreductions` library from 16 problems to 100+ NP-complete problems, optimized for AI-assisted "Vibe Coding" development.

---

## 1. Current State Analysis

### 1.1 Existing Problems (16)

| Category | Problems | Count |
|----------|----------|-------|
| Graph | IndependentSet, MaximalIS, VertexCovering, DominatingSet, Coloring, MaxCut, Matching | 7 |
| Satisfiability | SAT (with k-SAT variant) | 1 |
| Set | SetCovering, SetPacking | 2 |
| Optimization | SpinGlass, QUBO | 2 |
| Specialized | CircuitSAT, Factoring, Paintshop, BicliqueCover, BMF | 5 |

### 1.2 Architecture Strengths

1. **Clean `Problem` trait** - Minimal 5-method interface
2. **Generic `Size` type** - Supports i32, f64, custom numerics
3. **`ConstraintSatisfactionProblem` trait** - Separates constraints from objectives
4. **Categorical module organization** - Clear grouping
5. **Comprehensive testing** - 73% of code is tests

### 1.3 Critical Weaknesses for 100+ Problems

| Issue | Impact | Current LOC Waste |
|-------|--------|-------------------|
| No reduction framework | Cannot transform between problems | N/A |
| Copy-paste graph boilerplate | 7 problems share identical patterns | ~1,600 LOC |
| Test duplication | Each problem repeats test structure | ~5,400 LOC |
| No problem registry | Manual enumeration in prelude.rs | Maintenance burden |
| Only BruteForce solver | Unusable for n > 20 | Performance |
| No problem metadata | Cannot query problem properties | Discovery |

---

## 2. Target Problem Categories (100+ Problems)

Based on the canonical NP-complete problem classification:

### 2.1 Proposed Category Hierarchy

```
models/
├── graph/
│   ├── coloring/           # 3-Coloring, Chromatic Index, Edge Coloring
│   ├── covering/           # Vertex Cover, Dominating Set, Edge Dominating
│   ├── independent/        # Independent Set, Maximal IS, Clique
│   ├── paths/              # Hamiltonian Path/Cycle, Longest Path, TSP
│   ├── structure/          # Graph Partition, Bipartite Subgraph, Cubic Subgraph
│   ├── trees/              # Steiner Tree, Spanning Tree variants
│   └── matching/           # Matching, 3D Matching, Perfect Matching
├── satisfiability/
│   ├── sat/                # SAT, 3-SAT, Max-SAT, Weighted Max-SAT
│   ├── circuit/            # Circuit SAT, Monotone Circuit
│   └── qbf/                # Quantified Boolean Formula (PSPACE-complete)
├── set/
│   ├── covering/           # Set Cover, Exact Cover, X3C
│   ├── packing/            # Set Packing, Bin Packing, Knapsack
│   ├── partition/          # Partition, 3-Partition, Subset Sum
│   └── matching/           # Set Splitting, Hitting Set
├── optimization/
│   ├── quadratic/          # QUBO, Max-Cut, Spin Glass
│   ├── linear/             # Integer Linear Programming, 0-1 ILP
│   └── constraint/         # Constraint Satisfaction, All-Different
├── scheduling/
│   ├── machine/            # Multiprocessor, Job Shop, Flow Shop
│   ├── sequencing/         # Sequencing with Deadlines, Precedence
│   └── resource/           # Resource Allocation, Bandwidth
├── network/
│   ├── flow/               # Network Flow variants
│   ├── routing/            # Shortest Path variants, Rural Postman
│   └── connectivity/       # k-Connected Subgraph, Disjoint Paths
├── string/
│   ├── sequence/           # Shortest Superstring, Longest Common Subsequence
│   ├── matching/           # String Matching with wildcards
│   └── compression/        # Grammar Compression, Run-Length
└── specialized/
    ├── geometry/           # Rectilinear problems, Protein Folding
    ├── number/             # Factoring, Quadratic Diophantine
    └── game/               # Game-theoretic problems
```

### 2.2 Priority Problems (Top 100)

#### Tier 1: Core Problems (Must Have - 25 problems)
These are fundamental and frequently used in reductions:

| # | Problem | Category | Status |
|---|---------|----------|--------|
| 1 | 3-SAT | satisfiability/sat | Partial (SAT exists) |
| 2 | Clique | graph/independent | Not implemented |
| 3 | Vertex Cover | graph/covering | Implemented |
| 4 | Independent Set | graph/independent | Implemented |
| 5 | Dominating Set | graph/covering | Implemented |
| 6 | 3-Coloring | graph/coloring | Partial (k-Coloring exists) |
| 7 | Hamiltonian Path | graph/paths | Not implemented |
| 8 | Hamiltonian Cycle | graph/paths | Not implemented |
| 9 | Subset Sum | set/partition | Not implemented |
| 10 | Partition | set/partition | Not implemented |
| 11 | 3-Partition | set/partition | Not implemented |
| 12 | Bin Packing | set/packing | Not implemented |
| 13 | Knapsack (0/1) | set/packing | Not implemented |
| 14 | Set Cover | set/covering | Implemented |
| 15 | Exact Cover | set/covering | Not implemented |
| 16 | 3D Matching | graph/matching | Not implemented |
| 17 | Graph Partition | graph/structure | Not implemented |
| 18 | Max-Cut | graph/coloring | Implemented |
| 19 | TSP (Decision) | graph/paths | Not implemented |
| 20 | Job Shop Scheduling | scheduling/machine | Not implemented |
| 21 | Integer Linear Programming | optimization/linear | Not implemented |
| 22 | Circuit SAT | satisfiability/circuit | Implemented |
| 23 | Steiner Tree | graph/trees | Not implemented |
| 24 | Max 2-SAT | satisfiability/sat | Not implemented |
| 25 | Chromatic Number | graph/coloring | Not implemented |

#### Tier 2: Important Problems (30 problems)
Common in applications and algorithm design courses.

#### Tier 3: Specialized Problems (45 problems)
Domain-specific or less commonly used.

---

## 3. Proposed Architecture

### 3.1 Core Trait Redesign

```rust
// Enhanced Problem trait with metadata
pub trait Problem: Clone + Send + Sync {
    type Size: ProblemSize;
    type Config: ProblemConfig;

    // Core methods (existing)
    fn num_variables(&self) -> usize;
    fn solution_size(&self, config: &Self::Config) -> SolutionSize<Self::Size>;

    // New metadata methods
    fn problem_info() -> ProblemInfo;
    fn category() -> ProblemCategory;

    // Optional incremental evaluation
    fn solution_size_delta(&self, config: &Self::Config, var: usize, new_val: usize)
        -> Option<SolutionSize<Self::Size>> { None }
}

// Problem metadata for registry and discovery
#[derive(Clone, Debug)]
pub struct ProblemInfo {
    pub name: &'static str,
    pub aliases: &'static [&'static str],
    pub description: &'static str,
    pub complexity_class: ComplexityClass,
    pub decision_version: bool,
    pub optimization_version: bool,
    pub canonical_reduction_from: Option<&'static str>,
}

// Hierarchical category system
pub enum ProblemCategory {
    Graph(GraphSubcategory),
    Satisfiability(SatSubcategory),
    Set(SetSubcategory),
    Optimization(OptSubcategory),
    Scheduling(SchedSubcategory),
    Network(NetSubcategory),
    String(StringSubcategory),
    Specialized(SpecSubcategory),
}
```

### 3.2 Reduction Framework

```rust
/// Core reduction trait - transforms problem A to problem B
pub trait Reduction<From: Problem, To: Problem> {
    /// Transform an instance of problem A to problem B
    fn reduce(&self, from: &From) -> To;

    /// Transform a solution of B back to a solution of A
    fn lift_solution(&self, from: &From, to_solution: &[usize]) -> Vec<usize>;

    /// Verify the reduction preserves the problem structure
    fn verify(&self, from: &From, to: &To) -> bool { true }
}

/// Composable reductions
impl<A, B, C, R1, R2> Reduction<A, C> for ComposedReduction<R1, R2>
where
    R1: Reduction<A, B>,
    R2: Reduction<B, C>,
{
    fn reduce(&self, from: &A) -> C {
        let intermediate = self.first.reduce(from);
        self.second.reduce(&intermediate)
    }

    fn lift_solution(&self, from: &A, c_solution: &[usize]) -> Vec<usize> {
        let intermediate = self.first.reduce(from);
        let b_solution = self.second.lift_solution(&intermediate, c_solution);
        self.first.lift_solution(from, &b_solution)
    }
}

/// Standard reductions library
pub mod reductions {
    pub struct SatToIndependentSet;
    pub struct IndependentSetToVertexCover;
    pub struct VertexCoverToSetCover;
    pub struct ThreeSatToClique;
    pub struct CliqueToDominatingSet;
    // ... 50+ standard reductions
}
```

### 3.3 Graph Problem Template (Reduce Boilerplate)

```rust
/// Generic graph problem builder - eliminates 1,600+ LOC duplication
pub struct GraphProblem<C: GraphConstraint, W = i32> {
    graph: UnGraph<(), ()>,
    weights: Vec<W>,
    constraint: PhantomData<C>,
}

/// Constraint types define problem semantics
pub trait GraphConstraint {
    const NAME: &'static str;
    const ENERGY_MODE: EnergyMode;

    fn check_edge(v1_selected: bool, v2_selected: bool) -> bool;
    fn objective_contribution<W: Num>(v_selected: bool, weight: W) -> W;
}

// Define new graph problems in 10 lines instead of 400
pub struct IndependentSetConstraint;
impl GraphConstraint for IndependentSetConstraint {
    const NAME: &'static str = "Independent Set";
    const ENERGY_MODE: EnergyMode = EnergyMode::Maximize;

    fn check_edge(v1: bool, v2: bool) -> bool { !(v1 && v2) }
    fn objective_contribution<W: Num>(selected: bool, w: W) -> W {
        if selected { w } else { W::zero() }
    }
}

pub type IndependentSet<W> = GraphProblem<IndependentSetConstraint, W>;
pub type VertexCover<W> = GraphProblem<VertexCoverConstraint, W>;
pub type DominatingSet<W> = GraphProblem<DominatingSetConstraint, W>;
```

### 3.4 Problem Registry (Discovery & Introspection)

```rust
/// Global registry for problem discovery
pub struct ProblemRegistry {
    problems: HashMap<&'static str, ProblemEntry>,
    by_category: HashMap<ProblemCategory, Vec<&'static str>>,
    reductions: HashMap<(&'static str, &'static str), Box<dyn DynReduction>>,
}

impl ProblemRegistry {
    /// Get all problems in a category
    pub fn problems_in_category(&self, cat: ProblemCategory) -> &[&'static str];

    /// Find reduction path between two problems
    pub fn find_reduction_path(&self, from: &str, to: &str) -> Option<Vec<&'static str>>;

    /// Get all problems that reduce to this one
    pub fn reduces_to(&self, problem: &str) -> Vec<&'static str>;
}

// Auto-registration via proc macro
#[derive(Problem)]
#[problem(name = "3-SAT", category = "satisfiability/sat")]
#[problem(reduces_from = "SAT")]
pub struct ThreeSat { ... }
```

### 3.5 Parameterized Testing Framework

```rust
/// Macro for generating standard problem tests
macro_rules! problem_tests {
    ($problem:ty, $test_cases:expr) => {
        mod tests {
            use super::*;

            #[test]
            fn test_metadata() {
                let info = <$problem>::problem_info();
                assert!(!info.name.is_empty());
            }

            #[test]
            fn test_solution_validity() {
                for case in $test_cases {
                    let problem = case.create_problem();
                    let size = problem.solution_size(&case.valid_solution);
                    assert!(size.is_valid);
                }
            }

            #[test]
            fn test_brute_force() {
                for case in $test_cases.iter().filter(|c| c.n <= 15) {
                    let problem = case.create_problem();
                    let solver = BruteForce::new();
                    let solutions = solver.find_best(&problem);
                    assert_eq!(solutions[0].objective(), case.optimal_value);
                }
            }

            // ... more standard tests
        }
    };
}

// Usage: 10 lines instead of 300
problem_tests!(IndependentSet<i32>, &[
    TestCase::new(3, vec![(0,1), (1,2)], vec![1,0,1], 2),
    TestCase::new(4, vec![(0,1), (1,2), (2,3), (0,3)], vec![1,0,1,0], 2),
]);
```

---

## 4. Vibe Coding Optimization

### 4.1 AI-Friendly Patterns

To maximize effectiveness of AI-assisted development:

1. **Consistent File Structure**
   ```
   src/models/{category}/{problem}.rs
   ├── Problem struct definition (lines 1-20)
   ├── Problem trait impl (lines 22-60)
   ├── CSP trait impl if applicable (lines 62-100)
   ├── Helper methods (lines 102-150)
   └── #[cfg(test)] mod tests (lines 152-end)
   ```

2. **Template Comments for AI**
   ```rust
   // PROBLEM: {Name}
   // CATEGORY: {graph/satisfiability/set/...}
   // DECISION: Given {input}, is there {output} such that {constraint}?
   // OPTIMIZATION: Find {output} that {maximizes/minimizes} {objective}
   // REDUCES_FROM: {source problem}
   // REDUCTION_SKETCH: {brief description}
   ```

3. **Standardized Constructor Patterns**
   ```rust
   impl Problem {
       pub fn new(/* minimal params */) -> Self;
       pub fn with_weights(/* params + weights */) -> Self;
       pub fn from_instance(instance: ProblemInstance) -> Self;
       pub fn builder() -> ProblemBuilder<Self>;
   }
   ```

### 4.2 Code Generation Opportunities

| Component | Generation Strategy | Estimated Savings |
|-----------|---------------------|-------------------|
| Graph problems | Trait + constraint type | 80% reduction |
| Set problems | Macro + configuration | 70% reduction |
| Tests | Parameterized macro | 90% reduction |
| Documentation | Template + metadata | 60% reduction |
| Reductions | Pattern matching | 50% reduction |

### 4.3 Prompt Templates for Adding New Problems

```markdown
## Add Problem Template

I need to add the {PROBLEM_NAME} problem to the library.

**Definition**: {formal definition}
**Category**: {category/subcategory}
**Variables**: {what the variables represent}
**Constraints**: {what makes a solution valid}
**Objective**: {what to minimize/maximize}
**Known Reduction**: {PROBLEM_NAME} reduces from {SOURCE} via {transformation}

Please implement following the existing patterns in src/models/{category}/.
```

---

## 5. Implementation Roadmap

### Phase 1: Foundation (Weeks 1-2)
- [ ] Implement `ProblemInfo` and `ProblemCategory` types
- [ ] Add `problem_info()` and `category()` to Problem trait
- [ ] Create `GraphProblem<C>` generic template
- [ ] Migrate existing 7 graph problems to use template
- [ ] Set up `problem_tests!` macro

### Phase 2: Reduction Framework (Weeks 3-4)
- [ ] Implement `Reduction` trait
- [ ] Add 10 core reductions (SAT→IS, IS→VC, etc.)
- [ ] Create `ComposedReduction` for chaining
- [ ] Add reduction verification tests

### Phase 3: Problem Registry (Week 5)
- [ ] Implement `ProblemRegistry`
- [ ] Add `#[derive(Problem)]` proc macro
- [ ] Migrate existing problems to use registry
- [ ] Add discovery API

### Phase 4: Tier 1 Problems (Weeks 6-10)
- [ ] Implement 25 core problems (see list above)
- [ ] Add reductions between them
- [ ] Comprehensive testing

### Phase 5: Tier 2 Problems (Weeks 11-16)
- [ ] Implement 30 important problems
- [ ] Add scheduling category
- [ ] Add network category

### Phase 6: Tier 3 Problems (Weeks 17-24)
- [ ] Implement remaining 45 problems
- [ ] Add string category
- [ ] Add specialized/geometry problems

### Phase 7: Solvers & Optimization (Ongoing)
- [ ] Add branch-and-bound solver
- [ ] Add constraint propagation
- [ ] Add incremental evaluation
- [ ] Performance benchmarks

---

## 6. File Organization After Redesign

```
src/
├── lib.rs
├── prelude.rs
├── traits/
│   ├── mod.rs
│   ├── problem.rs          # Core Problem trait
│   ├── csp.rs              # ConstraintSatisfactionProblem
│   ├── reduction.rs        # Reduction trait
│   └── solver.rs           # Solver trait
├── registry/
│   ├── mod.rs
│   ├── registry.rs         # ProblemRegistry
│   ├── category.rs         # ProblemCategory enum
│   └── info.rs             # ProblemInfo struct
├── models/
│   ├── mod.rs
│   ├── graph/
│   │   ├── mod.rs
│   │   ├── template.rs     # GraphProblem<C> template
│   │   ├── coloring/
│   │   ├── covering/
│   │   ├── independent/
│   │   ├── paths/
│   │   ├── structure/
│   │   ├── trees/
│   │   └── matching/
│   ├── satisfiability/
│   ├── set/
│   ├── optimization/
│   ├── scheduling/
│   ├── network/
│   ├── string/
│   └── specialized/
├── reductions/
│   ├── mod.rs
│   ├── sat_reductions.rs
│   ├── graph_reductions.rs
│   └── set_reductions.rs
├── solvers/
│   ├── mod.rs
│   ├── brute_force.rs
│   ├── branch_bound.rs
│   └── local_search.rs
└── testing/
    ├── mod.rs
    ├── macros.rs           # problem_tests! macro
    └── fixtures.rs         # Common test graphs/instances
```

---

## 7. Success Metrics

| Metric | Current | Target |
|--------|---------|--------|
| Problem count | 16 | 100+ |
| LOC per new problem | ~400 | <100 |
| Test LOC per problem | ~300 | <50 (via macro) |
| Reduction coverage | 0% | 80%+ core problems |
| Time to add problem (AI-assisted) | N/A | <30 min |

---

## Sources

- [List of NP-complete problems - Wikipedia](https://en.wikipedia.org/wiki/List_of_NP-complete_problems)
- [Annotated List of Selected NP-complete Problems](https://www.csc.liv.ac.uk/~ped/teachadmin/COMP202/annotated_np.html)
- [Key NP-Complete Problems - Fiveable](https://fiveable.me/lists/key-np-complete-problems)
- Garey & Johnson (1979) - "Computers and Intractability"


Category	Problems	Count
Graph	IndependentSet, MaximalIS, VertexCovering, DominatingSet, Coloring, MaxCut, Matching	7
Satisfiability	SAT (with k-SAT variant)	1
Set	SetCovering, SetPacking	2
Optimization	SpinGlass, QUBO	2
Specialized	CircuitSAT, Factoring, Paintshop, BicliqueCover, BMF	5

Issue	Impact	Current LOC Waste
No reduction framework	Cannot transform between problems	N/A
Copy-paste graph boilerplate	7 problems share identical patterns	~1,600 LOC
Test duplication	Each problem repeats test structure	~5,400 LOC
No problem registry	Manual enumeration in prelude.rs	Maintenance burden
Only BruteForce solver	Unusable for n > 20	Performance
No problem metadata	Cannot query problem properties	Discovery

#	Problem	Category	Status
1	3-SAT	satisfiability/sat	Partial (SAT exists)
2	Clique	graph/independent	Not implemented
3	Vertex Cover	graph/covering	Implemented
4	Independent Set	graph/independent	Implemented
5	Dominating Set	graph/covering	Implemented
6	3-Coloring	graph/coloring	Partial (k-Coloring exists)
7	Hamiltonian Path	graph/paths	Not implemented
8	Hamiltonian Cycle	graph/paths	Not implemented
9	Subset Sum	set/partition	Not implemented
10	Partition	set/partition	Not implemented
11	3-Partition	set/partition	Not implemented
12	Bin Packing	set/packing	Not implemented
13	Knapsack (0/1)	set/packing	Not implemented
14	Set Cover	set/covering	Implemented
15	Exact Cover	set/covering	Not implemented
16	3D Matching	graph/matching	Not implemented
17	Graph Partition	graph/structure	Not implemented
18	Max-Cut	graph/coloring	Implemented
19	TSP (Decision)	graph/paths	Not implemented
20	Job Shop Scheduling	scheduling/machine	Not implemented
21	Integer Linear Programming	optimization/linear	Not implemented
22	Circuit SAT	satisfiability/circuit	Implemented
23	Steiner Tree	graph/trees	Not implemented
24	Max 2-SAT	satisfiability/sat	Not implemented
25	Chromatic Number	graph/coloring	Not implemented

Component	Generation Strategy	Estimated Savings
Graph problems	Trait + constraint type	80% reduction
Set problems	Macro + configuration	70% reduction
Tests	Parameterized macro	90% reduction
Documentation	Template + metadata	60% reduction
Reductions	Pattern matching	50% reduction

Metric	Current	Target
Problem count	16	100+
LOC per new problem	~400	<100
Test LOC per problem	~300	<50 (via macro)
Reduction coverage	0%	80%+ core problems
Time to add problem (AI-assisted)	N/A	<30 min

Roadmap #1

Description

Architecture Design for 100+ NP-Complete Problems

Executive Summary

1. Current State Analysis

1.1 Existing Problems (16)

1.2 Architecture Strengths

1.3 Critical Weaknesses for 100+ Problems

2. Target Problem Categories (100+ Problems)

2.1 Proposed Category Hierarchy

2.2 Priority Problems (Top 100)

Tier 1: Core Problems (Must Have - 25 problems)

Tier 2: Important Problems (30 problems)

Tier 3: Specialized Problems (45 problems)

3. Proposed Architecture

3.1 Core Trait Redesign

3.2 Reduction Framework

3.3 Graph Problem Template (Reduce Boilerplate)

3.4 Problem Registry (Discovery & Introspection)

3.5 Parameterized Testing Framework

4. Vibe Coding Optimization

4.1 AI-Friendly Patterns

4.2 Code Generation Opportunities

4.3 Prompt Templates for Adding New Problems

5. Implementation Roadmap

Phase 1: Foundation (Weeks 1-2)

Phase 2: Reduction Framework (Weeks 3-4)

Phase 3: Problem Registry (Week 5)

Phase 4: Tier 1 Problems (Weeks 6-10)

Phase 5: Tier 2 Problems (Weeks 11-16)

Phase 6: Tier 3 Problems (Weeks 17-24)

Phase 7: Solvers & Optimization (Ongoing)

6. File Organization After Redesign

7. Success Metrics

Sources

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions