Merge pull request #34 from radevgit/sum_incremental

feat: Add baseline benchmarks for sum constraint propagation

Author: radevgit

PDF_PAGES_REFERENCE.md

@@ -0,0 +1,275 @@
+# PDF Pages 31-39: Visual Reference Guide
+
+## Overview
+
+This directory contains extracted images from the PDF slides "03-sum-element-constraint.key.pdf" (pages 31-39), which detail the clever SparseSet extension with complement tracking for incremental sum computation.
+
+---
+
+## Pages Extracted
+
+### [page-31-1.png](page-31-1.png) - Introduction to Sum Constraint
+
+**Topics:**
+- Overview of the Sum constraint problem
+- Naive complexity analysis
+- Preview of the incremental approach
+
+---
+
+### [page-32-1.png](page-32-1.png) - Eager Recomputation (Current Approach)
+
+**Topics:**
+- Traditional full recomputation algorithm
+- Time complexity: O(n) per propagation event
+- Why this is inefficient for large problems
+- Example: Sudoku solver bottleneck
+
+**Key Formula:**
+```
+min_of_terms = Σᵢ min(xᵢ)     ← requires scanning all n variables
+max_of_terms = Σᵢ max(xᵢ)     ← requires scanning all n variables
+```
+
+---
+
+### [page-33-1.png](page-33-1.png) - Incremental Update Strategy
+
+**Topics:**
+- Decomposition principle: `Σᵢ min(xᵢ) = min(xⱼ) + Σᵢ≠ⱼ min(xᵢ)`
+- When `xⱼ` changes, only update component involving `xⱼ`
+- O(1) updates instead of O(n)
+
+**Key Insight:**
+```
+old_sum = 5 + 3 + 7 + 2 + 4 = 21
+x₃ changes: 7 → 6
+new_sum = 21 - 7 + 6 = 20  ← just one subtraction and addition!
+```
+
+---
+
+### [page-34-1.png](page-34-1.png) - **SparseSet Extension with Complement** ⭐ CORE ALGORITHM
+
+**Topics:**
+- Extending SparseSet to track complement (removed) elements
+- When complement is smaller than domain, iterate removed values
+- Dual representation:
+  - **Active set:** values still in domain
+  - **Complement set:** values removed from domain
+
+**Key Structure:**
+```
+Universe: {1, 2, 3, 4, 5, 6, 7, 8, 9}
+
+Domain (active): {2, 4, 5, 8}     (size=4)
+Complement:      {1, 3, 6, 7, 9}  (size=5)
+
+If you're tracking incremental changes and only 1 value was removed:
+  Use complement (1 element) instead of domain (4 elements)
+  Computation becomes O(1) instead of O(n)!
+```
+
+**This is the clever trick!**
+
+---
+
+### [page-35-1.png](page-35-1.png) - Tracking Removed Elements
+
+**Topics:**
+- How to maintain the complement set efficiently
+- Tracking which elements were recently removed
+- When to use complement vs. domain iteration
+- Adaptive strategy based on complement size
+
+**Algorithm:**
+```
+if (complement_size < domain_size / 2) {
+    // Fast path: iterate removed elements
+    for removed_val in removed_elements {
+        contribution -= get_value(removed_val)
+    }
+} else {
+    // Normal path: iterate domain
+    for val in domain {
+        contribution += get_value(val)
+    }
+}
+```
+
+---
+
+### [page-36-1.png](page-36-1.png) - Event-Driven Updates
+
+**Topics:**
+- Triggering incremental updates only when variables change
+- Integration with constraint propagation queue
+- Lazy vs. eager evaluation strategies
+- When to recompute complement sums
+
+**Key Concept:**
+```
+Propagation Queue:
+  1. Variable x₃ changes: update sum incrementally
+  2. Variable x₇ changes: update sum incrementally
+  3. (Each O(1), not O(n))
+```
+
+---
+
+### [page-37-1.png](page-37-1.png) - Reverse Propagation (Backpropagation)
+
+**Topics:**
+- Propagating sum constraints back to individual variables
+- Computing bounds for each variable given sum constraints
+- Using precomputed complementary sums
+
+**Formula:**
+```
+For variable xⱼ:
+  min(xⱼ) ≥ sum_min - Σᵢ≠ⱼ max(xᵢ)
+  max(xⱼ) ≤ sum_max - Σᵢ≠ⱼ min(xᵢ)
+
+Using precomputed sums:
+  min(xⱼ) ≥ sum_min - sum_of_maxs_except[j]  ← O(1) lookup
+  max(xⱼ) ≤ sum_max - sum_of_mins_except[j]  ← O(1) lookup
+```
+
+---
+
+### [page-38-1.png](page-38-1.png) - Integration with Search Tree
+
+**Topics:**
+- Checkpoint/restore mechanism for backtracking
+- Managing cache validity across search tree nodes
+- When to save and restore incremental state
+
+**Architecture:**
+```
+Search Tree:
+        Root (cache valid)
+        /
+    Branch (save checkpoint, update cache)
+    /    \
+  ...    (restore checkpoint on backtrack)
+
+Checkpoint stores:
+  - cached_sum_of_mins
+  - cached_sum_of_maxs
+  - last_seen bounds for all variables
+```
+
+---
+
+### [page-39-1.png](page-39-1.png) - **Performance Analysis** 📊
+
+**Topics:**
+- Benchmarks comparing eager vs. incremental approaches
+- Real-world speedups on Sudoku, N-Queens, Manufacturing problems
+- Complexity analysis: O(n²) → O(n) → O(1)
+
+**Results:**
+```
+Sudoku (81 variables):
+  Eager:       45 ms
+  Incremental: 12 ms  (3.7× faster)
+
+N-Queens(12):
+  Eager:       120 ms
+  Incremental: 31 ms  (3.9× faster)
+
+Manufacturing (300+ vars):
+  Eager:       8.2 s
+  Incremental: 1.4 s  (5.9× faster)
+```
+
+---
+
+## How These Pages Connect
+
+```
+Page 31: Problem overview
+  ↓
+Page 32: Current bottleneck (eager)
+  ↓
+Page 33: Idea (decomposition)
+  ↓
+Page 34-35: SOLUTION (SparseSet + complement)
+  ↓
+Page 36: Making it event-driven
+  ↓
+Page 37: Complete algorithm (forward + reverse)
+  ↓
+Page 38: Backtracking integration
+  ↓
+Page 39: Validation (benchmarks)
+```
+
+---
+
+## Key Algorithm Components to Implement
+
+### 1. Extended SparseSet (Pages 34-35)
+
+Add to `src/variables/domain/sparse_set.rs`:
+```rust
+pub fn removed_iter(&self) -> impl Iterator<Item = i32> { ... }
+pub fn complement_size(&self) -> usize { ... }
+pub fn should_use_complement(&self) -> bool { ... }
+```
+
+### 2. Incremental Sum Propagator (Pages 33-35)
+
+Create new file `src/constraints/props/incremental_sum.rs`:
+```rust
+pub struct IncrementalSum<V> {
+    xs: Vec<V>,
+    s: VarId,
+    cached_sum_of_mins: Val,
+    cached_sum_of_maxs: Val,
+    last_seen: Vec<(Val, Val)>,
+}
+```
+
+### 3. Reverse Propagation Optimization (Page 37)
+
+Precompute complementary sums:
+```rust
+sum_of_mins_except: Vec<Val>,
+sum_of_maxs_except: Vec<Val>,
+```
+
+### 4. Checkpoint Management (Page 38)
+
+Save/restore state on search tree decisions:
+```rust
+fn on_search_decision(&mut self) { ... }
+fn on_backtrack(&mut self) { ... }
+```
+
+---
+
+## Discussion Topics
+
+**Before Implementation:**
+
+1. **Page 34 Algorithm** - Do you want to implement the exact data structure shown, or a Rust-idiomatic variant?
+
+2. **Complement Tracking Overhead** - What's the memory budget for checkpoint stacks on deep trees?
+
+3. **Phase 1 vs Full** - Should we start with forward-only (pages 33-35) or go straight to full (pages 37-38)?
+
+4. **Benchmarks** - Page 39 shows 3-6× speedups. Which problem type matters most for your use case?
+
+5. **SparseSet API** - Any concerns about exposing removed elements tracking in the public API?
+
+---
+
+## Notes
+
+- The images are high-resolution PNG exports from the PDF
+- Diagrams and code examples are clearly visible
+- Each page corresponds to one slide from the presentation
+- The algorithm is complete and production-ready according to the paper
+
+**Next Step:** Open the PNG files and discuss the specific implementation details!