|
| 1 | +# CLI Tool Design: `pred` |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +A command-line tool for researchers and students to explore NP-hard problem reductions and solve problem instances without writing Rust code. Implemented as a separate workspace crate (`problemreductions-cli`), binary name `pred`. |
| 6 | + |
| 7 | +## Audience |
| 8 | + |
| 9 | +Researchers and students studying NP-hard reductions who want to explore and visualize without writing any Rust code. |
| 10 | + |
| 11 | +## Command Structure |
| 12 | + |
| 13 | +Subcommand-based CLI with two top-level groups: `graph` (exploration) and solve/reduce/evaluate (computation). |
| 14 | + |
| 15 | +### Graph Exploration |
| 16 | + |
| 17 | +``` |
| 18 | +pred graph list # List all registered problems |
| 19 | +pred graph show <Problem> # Show problem details, variants, reductions |
| 20 | +pred graph show MIS --variants # List all variants |
| 21 | +pred graph path <Source> <Target> # Find cheapest reduction path |
| 22 | +pred graph path MIS QUBO --cost minimize:num_vars # Custom cost function |
| 23 | +pred graph export [--output path] # Export reduction_graph.json |
| 24 | +``` |
| 25 | + |
| 26 | +### Computation |
| 27 | + |
| 28 | +``` |
| 29 | +pred solve <input.json> --via <Target> # Reduce + solve + map solution back |
| 30 | +pred solve --problem MIS --edges 0-1,1-2 --via QUBO # Inline input |
| 31 | +pred reduce <input.json> --to <Target> # Reduce only, output target as JSON |
| 32 | +pred evaluate <input.json> --config 1,0,1 # Evaluate a configuration |
| 33 | +pred schema <Problem> # Show JSON schema for a problem type |
| 34 | +``` |
| 35 | + |
| 36 | +### Global Flags |
| 37 | + |
| 38 | +- `--json` — structured JSON output, saved to file (default filename derived from command) |
| 39 | +- `--output <path>` — custom output file path (used with `--json`) |
| 40 | +- `--help` / `-h` — per-command help |
| 41 | + |
| 42 | +## Problem Name Resolution |
| 43 | + |
| 44 | +Case-insensitive matching with common aliases: |
| 45 | + |
| 46 | +| Input | Resolves to | |
| 47 | +|-------|-------------| |
| 48 | +| `MIS`, `mis` | `MaximumIndependentSet` | |
| 49 | +| `MVC` | `MinimumVertexCover` | |
| 50 | +| `SAT` | `Satisfiability` | |
| 51 | +| `3SAT` | `KSatisfiability` (K=3) | |
| 52 | +| `QUBO` | `QUBO` | |
| 53 | +| `MaxCut` | `MaxCut` | |
| 54 | + |
| 55 | +Unambiguous prefix matching: `MaximumI` → `MaximumIndependentSet`, but `Maximum` is rejected (ambiguous). |
| 56 | + |
| 57 | +## Variant Syntax |
| 58 | + |
| 59 | +Slash-based positional notation after the problem name. Order follows `Problem::variant()` key order. Partial specification fills from the left; no skipping. |
| 60 | + |
| 61 | +``` |
| 62 | +MIS → defaults (SimpleGraph, One) |
| 63 | +MIS/UnitDiskGraph → UnitDiskGraph, default weight |
| 64 | +MIS/SimpleGraph/f64 → must spell out graph to set weight |
| 65 | +KColoring/K3 → SimpleGraph, K=3 |
| 66 | +3SAT → alias for KSatisfiability/K3 |
| 67 | +QUBO → no variants |
| 68 | +``` |
| 69 | + |
| 70 | +## Input Formats |
| 71 | + |
| 72 | +### JSON Files |
| 73 | + |
| 74 | +Reuses the library's existing serde serialization: |
| 75 | + |
| 76 | +```json |
| 77 | +{ |
| 78 | + "problem": "MaximumIndependentSet", |
| 79 | + "graph": {"edges": [[0,1], [1,2], [2,0]], "num_vertices": 3}, |
| 80 | + "weights": [1, 1, 1] |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +### Inline Arguments |
| 85 | + |
| 86 | +For simple cases without a JSON file: |
| 87 | + |
| 88 | +``` |
| 89 | +pred solve --problem MIS --edges 0-1,1-2,2-0 --weights 1,1,1 --via QUBO |
| 90 | +``` |
| 91 | + |
| 92 | +## Output |
| 93 | + |
| 94 | +- **Human-readable (default):** plain text to stdout |
| 95 | +- **`--json`:** structured JSON saved to file (default name derived from command, e.g., `pred_path_MIS_QUBO.json`) |
| 96 | +- **`--json --output custom.json`:** custom output path |
| 97 | +- **Errors:** always to stderr |
| 98 | +- **Exit codes:** non-zero on any error |
| 99 | + |
| 100 | +## Architecture |
| 101 | + |
| 102 | +### Crate Layout |
| 103 | + |
| 104 | +Separate workspace crate: `problemreductions-cli/` |
| 105 | + |
| 106 | +``` |
| 107 | +src/ |
| 108 | + main.rs # Cli::parse(), dispatch to commands |
| 109 | + cli.rs # Clap derive structs (Cli, Commands, GraphCommands) |
| 110 | + commands/ |
| 111 | + graph.rs # list, show, path, export |
| 112 | + solve.rs # reduce + solve + extract solution |
| 113 | + reduce.rs # reduce only, output target problem |
| 114 | + evaluate.rs # evaluate a config |
| 115 | + schema.rs # show JSON schema for a problem type |
| 116 | + output.rs # OutputMode enum, write_json_file(), print_human() |
| 117 | + problem_name.rs # Alias resolution + variant parsing (slash notation) |
| 118 | +``` |
| 119 | + |
| 120 | +### Dependencies |
| 121 | + |
| 122 | +- `clap` (derive) — argument parsing |
| 123 | +- `anyhow` — error handling |
| 124 | +- `serde_json` — JSON I/O |
| 125 | +- `problemreductions` — the library (all features) |
| 126 | + |
| 127 | +### Dynamic Dispatch |
| 128 | + |
| 129 | +- **Graph commands:** use `ReductionGraph` directly — already works with string names |
| 130 | +- **Solve/reduce/evaluate:** dispatch table — a `match` over known problem names that constructs concrete types from JSON. ~20 match arms, one per problem type. |
| 131 | + |
| 132 | +### Error Handling |
| 133 | + |
| 134 | +`anyhow::Result` throughout, with `.context()` for actionable error messages. Non-zero exit code on any error. |
| 135 | + |
| 136 | +## V1 Scope |
| 137 | + |
| 138 | +### In scope |
| 139 | + |
| 140 | +- `pred graph list` |
| 141 | +- `pred graph show <Problem>` (with `--variants`) |
| 142 | +- `pred graph path <Source> <Target>` (with `--cost`) |
| 143 | +- `pred graph export` |
| 144 | +- `pred solve` (JSON file and inline input, brute-force solver) |
| 145 | +- `pred reduce` (reduce only) |
| 146 | +- `pred evaluate` |
| 147 | +- `pred schema` |
| 148 | +- `--json` output to file |
| 149 | + |
| 150 | +### Out of scope (v2+) |
| 151 | + |
| 152 | +See GitHub issue for future plans. |
0 commit comments