Merge branch 'develop'

Added --dry-run option to just display problem info
Separated the plot part from the solution calculation: now we first solve and save to json, then free that memory and the plot methods read the json.
This allows to plot in a second moment from a pre existing json.

Author: NicolaPerin

README.md

@@ -7,8 +7,9 @@
 - C extension with OpenMP parallelization for fast solving
 - Handles defects and irregular regions
 - JSON and CSV input support
-- Command-line interface with `benchmark` and `solve` subcommands
+- Command-line interface with `benchmark`, `solve`, and `plot` subcommands
 - Inline problem definition via `--sheet`, `--items`, and `--defects` flags
+- `--dry-run` flag to preview problem stats and memory estimates before solving
 
 ## Installation
 
@@ -48,7 +49,7 @@ print(f"Optimal value: {value}")
 
 ### CLI Usage
 
-The CLI uses two subcommands: `benchmark` and `solve`.
+The CLI uses three subcommands: `benchmark`, `solve`, and `plot`.
 
 ```bash
 # Run the built-in 27x27 benchmark
@@ -57,6 +58,9 @@ guillotine benchmark
 # Run benchmark with visualization and profiling
 guillotine benchmark --plot --profile
 
+# Preview problem stats and memory estimate without solving
+guillotine solve problem.json --dry-run
+
 # Solve from a JSON file
 guillotine solve problem.json
 
@@ -66,22 +70,29 @@ guillotine solve --sheet 27x27 --items 5x5 10x10 12x12 --defects 9,9,2x2
 # Save output to a custom file with a plot
 guillotine solve problem.json -o my_solution.json --plot result.png
 
+# Plot from a previously saved solution (no re-solving needed)
+guillotine plot output/solution.json
+
 # With profiling
 guillotine solve --sheet 27x27 --items 5x5 10x10 --profile
 ```
 
-All outputs (JSON, PNG, profile) are saved to `./output/` by default unless a path with a directory is specified.
+All outputs (JSON, PNG, SVG, profile) are saved to `./output/` by default unless a path with a directory is specified.
 
 #### Subcommand reference
 
-| Flag | `benchmark` | `solve` | Description |
-|---|---|---|---|
-| `--plot [FILE]` | ✓ | ✓ | Save visualization (default: `plot.png`) |
-| `--profile [FILE]` | ✓ | ✓ | Save profiling data (default: `profiling.txt`) |
-| `-o / --output FILE` | ✓ | ✓ | Output JSON file (default: `solution.json`) |
-| `--sheet WxH` | | ✓ | Sheet dimensions for inline mode |
-| `--items WxH ...` | | ✓ | Item sizes for inline mode |
-| `--defects X,Y,WxH ...` | | ✓ | Defect positions/sizes for inline mode |
+| Flag | `benchmark` | `solve` | `plot` | Description |
+|---|---|---|---|---|
+| `--plot [FILE]` | ✓ | ✓ | | Save visualization (default: `plot.png`) |
+| `--profile [FILE]` | ✓ | ✓ | | Save profiling data (default: `profiling.txt`) |
+| `-o / --output FILE` | ✓ | ✓ | ✓ | Output file (default: `solution.json` or `plot.png`) |
+| `--dry-run` | ✓ | ✓ | | Print problem summary and memory estimate, then exit |
+| `--sheet WxH` | | ✓ | | Sheet dimensions for inline mode |
+| `--items WxH ...` | | ✓ | | Item sizes for inline mode |
+| `--defects X,Y,WxH ...` | | ✓ | | Defect positions/sizes for inline mode |
+
+The `plot` subcommand takes a single solution JSON file (which embeds the
+problem definition) and generates a visualization without re-solving.
 
 ### Input Formats
 
@@ -116,8 +127,9 @@ x,y,width,height
 ## Output
 
 The solver generates:
-- **JSON solution** with metrics (utilization, efficiency, cut sequence) saved to `./output/`
-- **PNG visualization** (optional) showing the cutting pattern
+- **JSON solution** with metrics (utilization, efficiency, cut sequence) and
+  the embedded problem definition, saved to `./output/`
+- **PNG + SVG visualization** (optional) showing the cutting pattern
 - **Profile data** (optional) for performance analysis
 
 ## Performance
@@ -136,32 +148,85 @@ Benchmark results on a Ryzen 5 9600X (6 cores, OMP_NUM_THREADS=6):
 
 | Sheet   | Items | Defects | Time   | Memory |
 |---------|-------|---------|--------|--------|
-| 27×27  | 4     | 1       | 0.003s | 34 MB  |
-| 40×40   | 4     | 6       | 0.013s | 58 MB  |
-| 60×60   | 4     | 10      | 0.058s | 182 MB |
-| 80×80   | 6     | 15      | 0.238s | 514 MB |
-| 100×100 | 10    | 20      | 0.703s | 1.2 GB |
+| 27×27   | 4     | 1       | 0.002s | 30 MB  |
+| 40×40   | 4     | 6       | 0.013s | 37 MB  |
+| 60×60   | 4     | 10      | 0.058s | 79 MB  |
+| 80×80   | 6     | 15      | 0.238s | 190 MB |
+| 100×100 | 10    | 20      | 0.703s | 422 MB |
+
+Example output for a 100x100 sheet with 10 item types and 20 defects (in black):
+
+<img src="images/plot.svg" width="800" alt="100x100 solution">
+
+### Memory model
+
+The algorithm stores three categories of data:
 
-Example output for the 40×40 problem (4 item types, 6 defects):
+- **g and F tables** (2D, always allocated): `g_values`, `g_indices`,
+  `F_values`, `F_type`, `F_param` — shape `(W+1) × (H+1)` each. These are
+  small (a few KB to a few hundred KB).
 
-<img src="images/solution_40x40.png" width="600" alt="40×40 solution">
+- **Prefix sum** (2D): `prefix` — shape `(W+1) × (H+1)`, used for O(1)
+  defect overlap queries. Also small.
+
+- **Fd table** (4D, dominates memory): `Fd_values` — shape
+  `(W+1) × (H+1) × (W+1) × (H+1)` in `int32`. This is where nearly all
+  memory goes. Only allocated when the sheet contains defects.
+
+Previously, three 4D arrays were stored (`Fd_values`, `Fd_type`, `Fd_param`,
+each `int32`), totaling 12 bytes per cell. The current implementation stores
+only `Fd_values` (4 bytes per cell) — a **3× reduction**. Decision types and
+parameters are no longer stored; instead, they are re-derived during solution
+reconstruction by checking which candidate cut reproduces the optimal value.
+
+The `--dry-run` flag shows the estimated memory breakdown before solving:
+
+```
+$ guillotine solve examples/problem_100x100.json --dry-run
+============================================================
+DRY RUN — Problem Summary
+============================================================
+
+  Sheet size:    100 x 100  (area: 10,000)
+
+  Item types:    10
+    [0]  5 x 5  (area: 25)
+    ...
+
+  Defects:       20
+    [0]  at (12, 45)  size 8 x 6  (area: 48)
+    ...
+  Total defect area: 1,234  (12.3% of sheet)
+
+  Estimated memory usage:
+    g tables (values + indices):      79.2 KB
+    F tables (values + type + param): 89.2 KB
+    Prefix sum array:                 39.6 KB
+    Fd dense 4D array:                397.0 MB  (104,060,401 cells)
+    ----------------------------------------
+    Total estimated:                  397.2 MB
+
+============================================================
+```
 
-### Memory requirements
+The estimated and actual memory usage for square sheets:
 
-The algorithm stores three 4D arrays of shape `(W+1, H+1, W+1, H+1)` in
-`int32`, giving a memory footprint of approximately `3 × (N+1)^4 × 4` bytes for
-an `N×N` sheet. This grows as the fourth power of sheet size:
+| Sheet     | Fd cells      | Estimated total | Actual RSS |
+|-----------|---------------|-----------------|------------|
+| 27 × 27  | 614,656       | 2.4 MB          | 30 MB      |
+| 40 × 40  | 2,825,761     | 10.8 MB         | 37 MB      |
+| 60 × 60  | 13,845,841    | 52.9 MB         | 79 MB      |
+| 80 × 80  | 42,998,721    | 164.3 MB        | 190 MB     |
+| 100 × 100| 104,060,401   | 397.2 MB        | 422 MB     |
 
-| Sheet   | Memory |
-|---------|--------|
-| 60×60   | 182 MB |
-| 80×80   | 514 MB |
-| 100×100 | 1.2 GB |
-| 120×120 | 2.6 GB |
-| 150×150 | 7.9 GB |
+The ~25 MB gap between estimated and actual is the constant overhead of
+Python, numpy, and the C extension runtime. For large sheets the Fd table
+dominates and the overhead becomes negligible.
 
-The full table is allocated upfront regardless of how many states are actually needed. 
-In the current implementation, memory is therefore the binding constraint for large problems.
+Memory grows as `O((W+1)² × (H+1)²)` — roughly the fourth power of sheet
+size for square sheets. The full table is allocated upfront regardless of how
+many states are actually needed. Memory is therefore the binding constraint
+for large problems.
 
 ## Development
 
@@ -188,7 +253,7 @@ guillotine-cutter/
 │   │   ├── geometry.py      # SheetGeometry: defect prefix sums, O(1) purity queries
 │   │   ├── patterns.py      # CutPatternGenerator: normal pattern cut positions
 │   │   ├── dp_solver.py     # GuillotineDP: DP solver, reconstruction
-│   │   ├── _solver.c        # C extension: fill_Fd hot loop with OpenMP
+│   │   ├── _solver.c        # C extension: fill_g, fill_F, fill_Fd with OpenMP
 │   │   └── constants.py     # DECISION_* constants shared by Python and C
 │   ├── io.py                # JSON/CSV I/O, input validation
 │   ├── visualize.py         # Matplotlib visualization
@@ -200,20 +265,24 @@ guillotine-cutter/
 
 ### Algorithm overview
 
-The solver implements exact guillotine DP in two phases:
+The solver implements exact guillotine DP in three phases:
 
-**Phase 1 — pure rectangles (`_precompute_F`):** For each rectangle size
-`(w,h)`, compute the best tiling assuming no defects. This is a standard 2D
-knapsack DP and only requires a `(W+1)×(H+1)` table.
+**Phase 1 — g-table (`fill_g`):** For each rectangle size `(w,h)`, compute the
+best value achievable by tiling with copies of a single item type. Implemented
+in C with OpenMP parallelization across widths.
 
-**Phase 2 — defected rectangles (`_fill_Fd`):** For each rectangle size `(w,h)`
-and position `(x,y)`, compute the best tiling accounting for defects. Pure
-rectangles reuse Phase 1 results directly. Defected rectangles try all normal
-pattern cuts and all defect boundary cuts, taking the best. This requires a
-`(W+1)×(H+1)×(W+1)×(H+1)` table indexed as `[w,h,x,y]` for cache locality.
+**Phase 2 — F-table (`fill_F`):** For each rectangle size `(w,h)`, compute the
+optimal value assuming no defects (pure rectangle). Tries single-item tiling
+from Phase 1, vertical cuts, and horizontal cuts at normal pattern positions.
+Uses symmetry (only tries cuts up to half the dimension). Implemented in C,
+sequential (bottom-up dependency).
 
-The hot loop of Phase 2 is implemented in `_solver.c` and parallelized with
-OpenMP across `(x,y)` positions at each fixed `(w,h)`.
+**Phase 3 — Fd-table (`fill_Fd`):** For each rectangle size `(w,h)` and
+position `(x,y)`, compute the optimal value accounting for defects. Pure
+positions (detected via O(1) prefix-sum query) reuse Phase 2 results directly.
+Defected positions try all normal pattern cuts and defect-aligned cuts, taking
+the best. Implemented in C with OpenMP parallelization across `(x,y)` positions
+at each fixed `(w,h)`.
 
 ## Citation