diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 283d6703..af1be1a9 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -40,6 +40,8 @@ These repo-local skills live under `.claude/skills/*/SKILL.md`. - [verify-reduction](skills/verify-reduction/SKILL.md) -- Standalone mathematical verification of a reduction rule: Typst proof, constructor Python (≥5000 checks), adversary Python (≥5000 independent checks). Reports verdict, no artifacts saved. Also called as a subroutine by `/add-rule` (default behavior). - [tutorial](skills/tutorial/SKILL.md) -- Interactive tutorial — walk through the pred CLI to explore, reduce, and solve NP-hard problems. No Rust internals. - [update-papers](skills/update-papers/SKILL.md) -- Update research paper collection: download new papers from references.bib, retry failed downloads, sync to Google Drive, regenerate index.md. +- [find-solver](skills/find-solver/SKILL.md) -- Interactive guide: match a real-world problem to a library model, explore reduction paths, recommend solvers (built-in + external), and generate a solution doc. +- [find-problem](skills/find-problem/SKILL.md) -- Reverse of find-solver: given a solver for a model, discover what other problems it can handle via incoming reductions, ranked by effective complexity. ## Codex Compatibility - Claude slash commands such as `/issue-to-pr 42 --execute` are aliases for the matching repo-local skill files under `.claude/skills/`. diff --git a/.claude/skills/find-problem/SKILL.md b/.claude/skills/find-problem/SKILL.md new file mode 100644 index 00000000..cd17354c --- /dev/null +++ b/.claude/skills/find-problem/SKILL.md @@ -0,0 +1,186 @@ +--- +name: find-problem +description: Reverse of find-solver — given a solver for a model, discover what other problems it can handle via incoming reductions, ranked by effective complexity +--- + +# Find Problem + +Given a solver for a specific model, discover what other problems it can handle by exploring the reduction graph in the incoming direction. Produces a solution doc ranking all reachable problems by effective complexity. + +## Invocation + +``` +/find-problem — start from Step 1 (identify solver) +/find-problem — skip model identification, ask for complexity +``` + + +Do NOT modify project source files, write Rust code, or create PRs. +Only outputs: `pred` CLI commands executed live, web searches, conversational commentary, and one solution doc in `docs/solutions/`. +If the user asks about contributing code, point them to `/add-model`, `/add-rule`, or `/propose`. + + +## Audience + +Users who have built or have access to a solver for a specific problem model and want to understand the full scope of problems their solver can handle through reductions. + +## Flow Overview + +``` +Step 1: Identify Solver (user provides model + complexity) +Step 2: Discover Reachable Problems (pred from --hops 3, compute effective complexity) +Step 3: Rank and Present (table ranked by effective complexity, web search for applications) +Step 4: Generate Solution Doc (docs/solutions/.md) +``` + +## CRITICAL: Output Visibility + +Bash tool results are hidden from the user in the Claude Code UI. **After every `pred` command, you MUST copy-paste the full stdout/stderr into your response as text.** The pattern for every command is: + +1. Announce the command and why: "Let me run `pred to MIS --hops 3` to discover all problems that can reduce to MIS:" +2. Run the command via the Bash tool +3. Copy the COMPLETE output into your text response inside a fenced code block +4. Then add your brief explanation + +Never skip step 1 or 3. + +--- + +## Step 1: Identify Solver + +**Goal:** Get the user's model name and solver complexity. + +**If invoked as `/find-problem `:** validate with `pred show `. If it exists, show the output (including size fields), then ask for solver complexity. + +**If invoked as `/find-problem`:** ask using `AskUserQuestion`: "Which problem model does your solver handle?" Validate the answer with `pred show`. + +**Ask for complexity** using `AskUserQuestion`: "What is your solver's time complexity? Use the size field names from the output above (e.g., `O(1.1996^num_vertices)`, `O(2^(num_variables/3))`)." + +- Variable names should match the model's size fields shown in `pred show` output +- If the user gives informal notation (e.g., "exponential in n"), help them formalize it using the model's actual size field names + +**Exit condition:** Validated model name + complexity expression with variables matching the model's size fields. Proceed to Step 2. + +--- + +## Step 2: Discover Reachable Problems + +**Goal:** Find all problems that can reduce to the user's model and compute effective complexity for each. + +**Actions:** + +1. **Run `pred to --hops 3`** to find all problems that can reduce to the user's model within 3 hops (incoming direction). Copy-paste the full output. + +2. **For each discovered problem**, run: + - `pred path ` — get the cheapest witness-capable reduction path + - `pred show ` — get best-known brute-force complexity + +3. **Compute effective complexity** for each source problem: + - Take the user's solver complexity expression (e.g., `O(1.1996^num_vertices)`) + - Substitute the overhead expressions from the reduction path into the solver's variables + - Example: if MVC→MIS has overhead `num_vertices = num_vertices`, then solving MVC via MIS costs `O(1.1996^num_vertices)` — same as MIS + - Example: if overhead is `num_vertices = num_clauses * 3`, then effective complexity is `O(1.1996^(3 * num_clauses))` + +4. **Compare to best-known**: for each source, compare effective complexity to the source's own best-known complexity from `pred show`. Classify as: + - **Better** — effective complexity has a smaller base or exponent than best-known + - **Similar** — comparable asymptotic behavior + - **Worse** — effective complexity exceeds best-known (reduction overhead makes it impractical) + +5. **Web search** each discovered source problem + "applications" or "real-world" to find practical use cases. Use `WebSearch` tool. + +**If `--hops 3` returns more than 15 results:** present only the top 10 by effective complexity and mention the rest are available if the user wants to see them. + +**Proceed to Step 3.** + +--- + +## Step 3: Rank and Present + +**Goal:** Show all discovered problems ranked by practical usefulness. + +Present a ranked table (most practical first): + +| # | Problem | Hops | Overhead | Effective Complexity | vs Best-Known | Applications | +|---|---------|------|----------|---------------------|---------------|--------------| +| 1 | MinimumVertexCover | 1 | same size | O(1.1996^n) | Better | Network monitoring | +| 2 | MaximumClique | 2 | complement graph | O(1.1996^n) | Better | Social network cliques | +| 3 | GraphColoring | 3 | n^2 vars | O(1.1996^(n^2)) | Worse | Register allocation | + +Ask using `AskUserQuestion`: "Which problems would you like included in the solution doc? Pick numbers, or 'all practical' for only the Better/Similar ones." + +**Proceed to Step 4 with the selected problems.** + +--- + +## Step 4: Generate Solution Doc + +**Goal:** Write a static reference document listing all selected problems and how to solve them via the user's model. + +**File path:** `docs/solutions/problems-solvable-via--.md` + +Where: +- `` is the library model name (e.g., `MIS`, `QUBO`) +- `` is a short label for the user's solver (e.g., `custom-1.1996`, `ILP`) + +Ask the user to confirm the filename before writing. + +**Doc template — write all sections:** + +```markdown +# Problems Solvable via () + +## Overview + + + +## Summary Table + +| Problem | Hops | Overhead | Effective Complexity | vs Best-Known | Applications | +|---------|------|----------|---------------------|---------------|--------------| +| ... | ... | ... | ... | ... | ... | + +## -> + +- **What it is:** +- **Reduction path:** -> ... -> +- **Overhead:** +- **Effective complexity:** +- **vs best-known:** + +### CLI Commands + +```bash +# Create a source problem instance +pred create -o input.json + +# Reduce to your solver's model +pred reduce input.json --to -o bundle.json + +# Solve (built-in ILP or your external solver) +pred solve bundle.json --solver ilp --timeout 60 +``` + +## -> + +... +``` + +**After writing the doc:** + +1. Show the user the generated filename and a brief summary of what's in it. +2. Ask if they want to make any changes before finishing. + +--- + +## Key Behaviors + +- **One question at a time.** Never ask multiple questions in one message. Use `AskUserQuestion` for every decision point. +- **Web search before presenting applications.** In Step 2, web search each discovered problem for real-world use cases. Never guess applications from internal knowledge alone. +- **Show full output.** After every Bash tool call, copy-paste the COMPLETE output into your text response as a fenced code block. Bash tool results are hidden in the UI. +- **Announce every command.** Before running, say what command you're using and why. +- **Compact formatting.** Write explanations as plain paragraphs. Do not use blockquote `>` syntax for explanations. Keep tight: command announcement, code block output, 1-3 sentence explanation. +- **Conversational tone.** Guided consultation, not a lecture. +- **Live execution.** Every `pred` command runs for real. No fake output. +- **Graceful fallbacks.** If `pred to` returns no results (no incoming reductions), suggest trying with more hops or a different model. If `pred path` fails for a specific source, skip it and note it in the table. +- **Help with complexity notation.** If the user gives informal complexity, show `pred show ` size fields and help them write a formal expression. +- **Cap results at 10.** If discovery returns many problems, show top 10 by effective complexity and offer to show more. diff --git a/.claude/skills/find-solver/SKILL.md b/.claude/skills/find-solver/SKILL.md new file mode 100644 index 00000000..4edbc66d --- /dev/null +++ b/.claude/skills/find-solver/SKILL.md @@ -0,0 +1,287 @@ +--- +name: find-solver +description: Interactive guide — match a real-world problem to a library model, explore reduction paths, recommend solvers (built-in + external), and generate a solution doc +--- + +# Find Solver + +Guide users from a real-world algorithmic problem to a concrete solving strategy. Produces a static solution doc in `docs/solutions/`. + +## Invocation + +``` +/find-solver — start from Step 1 (clarify problem) +/find-solver — skip to Step 3 (explore reductions for a known model) +``` + + +Do NOT modify project source files, write Rust code, or create PRs. +Only outputs: `pred` CLI commands executed live, web searches, conversational commentary, and one solution doc in `docs/solutions/`. +If the user asks about contributing code, point them to `/add-model`, `/add-rule`, or `/propose`. + + +## Audience + +This skill serves two types of users: + +- **Practitioners** who have a fuzzy real-world problem (e.g., "I need to assign tasks to machines minimizing makespan") and need help identifying which NP-hard problem it maps to +- **Researchers** who already know the formal problem name and want to find the best reduction path + solver + +Adapt the flow: if the user provides a formal problem name, validate it with `pred show` and skip directly to Step 3. + +## Flow Overview + +``` +Step 1: Clarify Problem (skip if user knows the formal name) +Step 2: Match to Library Models (web search + pred list) +Step 3: Explore Reduction Paths (auto-explore via pred from --hops 3) +Step 4: Recommend Solvers (web search + pred solve options) +Step 5: Generate Solution Doc (docs/solutions/.md) +``` + +## CRITICAL: Output Visibility + +Bash tool results are hidden from the user in the Claude Code UI. **After every `pred` command, you MUST copy-paste the full stdout/stderr into your response as text.** The pattern for every command is: + +1. Announce the command and why: "Let me run `pred to MIS` to see what MIS can be reduced to:" +2. Run the command via the Bash tool +3. Copy the COMPLETE output into your text response inside a fenced code block +4. Then add your brief explanation + +Never skip step 1 or 3. + +--- + +## Step 1: Clarify Problem + +**Goal:** Understand the user's problem well enough to form a search query for matching models. + +**Researcher shortcut:** If the user invoked `/find-solver ` or describes their problem using a formal name (e.g., "maximum independent set", "graph coloring"), run `pred show ` to validate it exists. If it does, skip directly to Step 3 with that model. If it doesn't exist in the library, tell the user and fall through to Step 2. + +**For practitioners, ask one question at a time:** + +1. "Describe your problem in plain language — what are you trying to optimize, decide, or compute?" + +2. Based on the answer, if the input structure is ambiguous, ask: + "Is your input a graph/network? A set of items? A boolean formula? Numbers/matrices?" + +3. If the objective is unclear: + "What's the objective — minimize something, maximize something, or check feasibility?" + +4. "Roughly how large are your instances? (e.g., 10 nodes, 1000 variables)" + +Use `AskUserQuestion` for each question. Format options as **(a)**/**(b)**/**(c)** when multiple choice is natural. + +**Exit condition:** You have enough context to form a search query like "task scheduling minimize makespan NP-hard" or "maximum weight independent set unit disk graph". Proceed to Step 2. + +--- + +## Step 2: Match to Library Models + +**Goal:** Identify which problem model(s) in the library match the user's problem. + +**Key rule:** Web search happens BEFORE presenting options. Never guess model matches from internal knowledge alone. + +**Actions:** + +1. **Web search** the clarified problem description together with terms like "NP-hard", "computational complexity", or "reduction" to find formal problem names and known relationships in the literature. Use `WebSearch` tool. + +2. **Run `pred list`** to get the full catalog of available models. Copy-paste the full output into your response. + +3. **Cross-reference** the web search results against the `pred list` catalog. For each candidate model that exists in the library (3-5 max), present a table: + +| # | Model | Why it might match | Caveat | +|---|-------|--------------------|--------| +| 1 | ... | ... | ... | +| 2 | ... | ... | ... | +| 3 | ... | ... | ... | + +4. For each candidate, run `pred show ` and show the output — fields, complexity, available reductions. This helps the user see what data they would need to provide. + +5. **Ask the user to pick one** using `AskUserQuestion`. If none fit, ask the user for more detail and re-run the web search with refined keywords. + +**Proceed to Step 3 with the chosen model.** + +--- + +## Step 3: Explore Reduction Paths + +**Goal:** Discover all solver-ready targets reachable from the chosen model and present them ranked. + +**Actions:** + +1. **Run `pred from --hops 3`** to find all problems reachable via outgoing reductions within 3 hops. Copy-paste the full output. + +2. **For each reachable problem**, gather info: + - Run `pred path ` to get the cheapest witness-capable reduction path and composed overhead + - Run `pred show ` to get its best-known complexity + - Check if it's a solver-ready target (ILP, QUBO, SAT) or has a path to one via `pred path ILP` + +3. **Present a ranked table** (most practical paths first — fewest hops, lowest overhead): + + | # | Target | Hops | Composed Overhead | Target Complexity | Solver-Ready? | + |---|--------|------|-------------------|-------------------|---------------| + | 1 | ILP | 2 | num_vars = 2*n + m | O(2^num_vars) | Yes (is ILP) | + | 2 | QUBO | 1 | num_vars = n | O(2^num_vars) | Yes (is QUBO) | + | 3 | MaxSetPacking | 1 | num_sets = n | O(2^num_sets) | Yes (ILP in 2 steps) | + +4. **Ask the user** using `AskUserQuestion`: "Which reduction path would you like to use? Pick a number." + +**If `pred from --hops 3` returns more than 15 results:** present only the top 10 by overhead and mention the rest are available. + +**Proceed to Step 4 with the chosen path.** + +--- + +## Step 4: Recommend Solvers + +**Goal:** Find the best solver options — both built-in and external — for the target problem. + +**Key rule:** Web search happens BEFORE presenting solver options. Do not recommend solvers from internal knowledge alone. + +**Actions:** + +1. **Web search** the final target problem + "solver" + "benchmark" + "library" to find state-of-the-art external tools. Use `WebSearch` tool. Example queries: + - "QUBO solver open source benchmark" + - "integer linear programming solver comparison" + - "maximum independent set practical solver" + +2. **Check built-in solver availability:** + - Run `pred path ILP` — if a path exists, `pred solve --solver ilp` is available + - `pred solve --solver brute-force` is always available (feasible for small instances, ~25 variables) + +3. **Present solver options** in a table: + + | # | Solver | Type | How to Use | Notes | + |---|--------|------|------------|-------| + | 1 | pred solve --solver ilp | Built-in | pred solve reduced.json | HiGHS backend | + | 2 | pred solve --solver brute-force | Built-in | pred solve problem.json --solver brute-force | Exact, small instances only | + | 3 | (from web search) | External | (brief setup) | (strengths/limitations) | + | 4 | (from web search) | External | (brief setup) | (strengths/limitations) | + +4. **Ask the user** which solver(s) to include in the solution doc using `AskUserQuestion`. + +**Proceed to Step 5 with the selected solver(s).** + +--- + +## Step 5: Generate Solution Doc + +**Goal:** Write a static reference document with everything the user needs to solve their problem. + +**File path:** `docs/solutions/-via--.md` + +Where: +- `` is a short kebab-case description of the real-world problem +- `` is the library model name (e.g., `MIS`, `QUBO`) +- `` is the primary solver (e.g., `ILP`, `brute-force`, `gurobi`) + +Ask the user to confirm the filename before writing. + +**Doc template — write all sections:** + +```markdown +# via -> + +## Problem Description + + + +## Matched Model + +- **Name:** {variant} +- **Why this model:** +- **Best-known complexity:** O(...) + +## Input Schema + +`, with field explanations.> + +Example instance: + +```json +` and paste the JSON output> +``` + +## Reduction Path + + + +### Step N: -> + +- **Overhead:** + +```bash +pred reduce input.json --to -o step_N.json +``` + +## Solving + +```bash +pred solve step_N.json --solver ilp --timeout 60 +``` + + + +## Solution Extraction + + + +Using the reduction bundle workflow (recommended): + +```bash +pred reduce input.json --to -o bundle.json +pred solve bundle.json --solver ilp --timeout 60 +``` + +The solver automatically extracts the solution back to the original problem space. + +## External Solver Alternatives + + + +### + +- **What:** +- **When to prefer:** +- **How to use:** + +## Quick Reference + +All commands in sequence: + +```bash +# 1. Create your problem instance +pred create -o input.json + +# 2. Reduce to solver-ready form +pred reduce input.json --to -o bundle.json + +# 3. Solve +pred solve bundle.json --solver ilp --timeout 60 + +# 4. Verify (optional) +pred evaluate input.json --config +``` +``` + +**After writing the doc:** + +1. Show the user the generated filename and a brief summary of what's in it. +2. Ask if they want to make any changes before finishing. + +--- + +## Key Behaviors + +- **One question at a time.** Never ask multiple questions in one message. Use `AskUserQuestion` for every decision point. +- **Web search before recommendations.** In Step 2 (model matching) and Step 4 (solver recommendation), always web search first. Never rely on internal knowledge alone. +- **Show full output.** After every Bash tool call, copy-paste the COMPLETE output into your text response as a fenced code block. Bash tool results are hidden in the UI. +- **Announce every command.** Before running, say what command you're using and why. +- **Compact formatting.** Write explanations as plain paragraphs. Do not use blockquote `>` syntax for explanations. Keep tight: command announcement, code block output, 1-3 sentence explanation. +- **Conversational tone.** Guided consultation, not a lecture. +- **Live execution.** Every `pred` command runs for real. No fake output. +- **Graceful fallbacks.** If a path doesn't exist or a command fails, explain what happened and suggest alternatives (try another model, use brute-force, backtrack). +- **Adapt to user level.** If the user gives a formal problem name, skip clarification. If they describe a fuzzy real-world problem, ask follow-ups one at a time. +- **Use `--timeout 30`** with `pred solve` in any live demos during the session. diff --git a/docs/solutions/README.md b/docs/solutions/README.md new file mode 100644 index 00000000..84fd90cb --- /dev/null +++ b/docs/solutions/README.md @@ -0,0 +1,18 @@ +# Solution Guides + +Each file in this directory is a step-by-step guide for solving a specific +real-world problem using the `pred` CLI. + +Generated interactively via the `/find-solver` skill. + +## Naming Convention + +`-via--.md` + +- ``: short description of the real-world problem (kebab-case) +- ``: the library model used (e.g., `MIS`, `QUBO`) +- ``: the solver target (e.g., `ILP`, `brute-force`, `gurobi`) + +## Example + +`task-scheduling-via-MultiprocessorScheduling-ILP.md` diff --git a/problemreductions-cli/src/commands/create/schema_support.rs b/problemreductions-cli/src/commands/create/schema_support.rs index d30079b6..ce4b6269 100644 --- a/problemreductions-cli/src/commands/create/schema_support.rs +++ b/problemreductions-cli/src/commands/create/schema_support.rs @@ -178,6 +178,16 @@ pub(super) fn create_schema_driven( json_map.insert(field.name.clone(), value); } + // KColoring/KN stores the number of colors at runtime in `num_colors`. + // The schema only declares `graph`, so inject `num_colors` from --k for KN. + if canonical == "KColoring" + && resolved_variant.get("k").map(|s| s.as_str()) == Some("KN") + { + if let Some(k) = args.k { + json_map.insert("num_colors".to_string(), serde_json::json!(k)); + } + } + // Decision

types serialize as {inner: {graph, weights, ...}, bound} but schema // fields are flat (graph, weights, bound). Restructure when the canonical name // indicates a Decision wrapper.