Fix #118: [Rule] GraphPartitioning to ILP

[GiggleLiu]

Summary

Add the implementation plan for the GraphPartitioning -> ILP reduction and execute it in follow-up commits.

Fixes #118

[GiggleLiu]

Implementation Summary

Changes

• Added GraphPartitioning -> ILP in src/rules/graphpartitioning_ilp.rs using binary vertex variables plus edge-crossing indicators, with correct odd-vertex infeasibility via the fractional balance equality.
• Added focused rule coverage in src/unit_tests/rules/graphpartitioning_ilp.rs for ILP structure, closed-loop solving, odd-vertex behavior, solution extraction, and solve_reduced.
• Registered the rule in src/rules/mod.rs and exported a canonical example witness for the paper/example-db pipeline.
• Documented the reduction in docs/paper/reductions.typ and added the corrected Chopra-Rao 1993 citation in docs/paper/references.bib.

Deviations from Plan

• None.

Open Questions

• None.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.56%. Comparing base (bb726f8) to head (341cccf).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #705      +/-   ##
==========================================
+ Coverage   97.53%   97.56%   +0.02%     
==========================================
  Files         373      377       +4     
  Lines       47182    47418     +236     
==========================================
+ Hits        46020    46263     +243     
+ Misses       1162     1155       -7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: rule graphpartitioning_ilp

Structural Completeness

#	Check	Status
1	Rule file exists	PASS — src/rules/graphpartitioning_ilp.rs added
2	#[reduction(...)], ReductionResult, and ReduceTo are present	PASS — reduction registration and round-trip types are implemented in src/rules/graphpartitioning_ilp.rs
3	Test link and dedicated rule test file exist	PASS — #[path = "../unit_tests/rules/graphpartitioning_ilp.rs"] plus src/unit_tests/rules/graphpartitioning_ilp.rs
4	Closed-loop and edge-case tests exist	PASS — tests cover ILP structure, closed-loop solving, odd-vertex infeasibility, extraction, and solve_reduced
5	Registered in src/rules/mod.rs	PASS — module and canonical example are wired in
6	Canonical rule example exists	PASS — canonical_rule_example_specs() provides a witness pair
7	Example-db coverage tests exist	PASS — src/unit_tests/example_db.rs contains rule-db uniqueness / coverage / round-trip tests
8	Paper reduction-rule entry exists	PASS — docs/paper/reductions.typ includes #reduction-rule("GraphPartitioning", "ILP", ...)
9	Blacklisted auto-generated files absent	PASS — none of the forbidden generated artifacts appear in the diff
10	Deterministic file whitelist	FAIL — docs/paper/references.bib is outside the current rule-PR whitelist even though it is the citation added for the paper entry

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• Reduction correctness: OK — the ILP encodes balanced bisection with one binary partition variable per vertex and one binary crossing indicator per edge; minimizing sum y_e with the two linking inequalities forces y_e = |x_u - x_v| in optimal solutions.
• Odd-vertex behavior: OK — the equality sum x_v = n/2 becomes fractional when n is odd, making the binary ILP infeasible exactly when the source problem is invalid.
• extract_solution: OK — returning the first n variables correctly projects the auxiliary ILP solution back to the source partition vector.
• Overhead accuracy: OK — reduce_to() creates n + m variables and 2m + 1 constraints, matching the declared overhead expressions.
• Example quality: OK — the canonical witness and paper example use the same 6-vertex / 9-edge instance and the target witness has the expected 15 variables, 19 constraints, and objective value 3.
• Paper quality: OK — the proof sketch matches the implementation, and the updated Chopra-Rao citation matches an integer-programming formulation paper for graph partitioning.

Issue Compliance

#	Check	Status
1	Source/target match issue	OK — GraphPartitioning -> ILP
2	Reduction algorithm matches	OK — balance equality plus two crossing-detection inequalities per edge
3	Solution extraction matches	OK — source partition is read from the vertex variables
4	Correctness preserved	OK — objective value equals cut size for extracted balanced partitions
5	Overhead expressions match	OK — num_vars = n + m, num_constraints = 2m + 1
6	Example matches	OK — canonical example agrees with the issue’s 6-vertex witness and optimum 3

Summary

• 9/10 structural checks passed; the only failure is the deterministic whitelist rejecting docs/paper/references.bib
• 6/6 issue-compliance checks passed
• No functional, mathematical, registration, or testing defects found in the rule implementation
• Tooling note: current rule-PR whitelist likely needs to allow docs/paper/references.bib for citation updates

---

Quality Check

Quality Review

Design Principles

• DRY: OK — the rule logic is compact and does not duplicate existing abstractions unnecessarily.
• KISS: OK — the implementation uses the straightforward textbook binary-ILP formulation without extra indirection.
• HC/LC: OK — the rule file owns only reduction logic and example wiring; tests stay in the dedicated rule test module.

HCI (if CLI/MCP changed)

• Not applicable — no CLI or MCP files changed.

Test Quality

• Naive test detection: OK
  • The new tests check structure (num_vars, constraints, objective), semantic round-trip correctness, odd-n infeasibility, extraction, and solve_reduced.
  • The canonical example is also exercised indirectly by the existing example-db suite.

Issues

Critical (Must Fix)

None.

Important (Should Fix)

None.

Minor (Nice to Have)

None.

Summary

• No code-quality or test-quality issues found in this PR.

---

Agentic Feature Tests

Feature Test Report: problem-reductions

Project type: CLI + library
Features tested: GraphPartitioning -> ILP rule through pred
Profile: ephemeral
Use Case: A downstream CLI user wants to discover the new rule, create the canonical example, reduce it to ILP, and solve it end-to-end from the command line.
Expected Outcome: The rule appears in the catalog, pred show exposes it on both sides, example creation works for both source and target, reduction to ILP succeeds, and solving either the source instance or the reduced bundle returns the optimal cut value 3.
Verdict: pass
Critical Issues: 0

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
GraphPartitioning -> ILP via pred	yes	yes	yes	yes	good

Per-Feature Details

GraphPartitioning -> ILP

• Role: downstream CLI user validating a newly added reduction
• Use Case: discover the rule, create canonical examples, reduce to ILP, and solve the instance
• What they tried:
  • cargo build -p problemreductions-cli
  • ./target/debug/pred list --rules --json
  • ./target/debug/pred show GraphPartitioning
  • ./target/debug/pred show ILP
  • ./target/debug/pred create --example GraphPartitioning --to ILP
  • ./target/debug/pred create --example GraphPartitioning --to ILP --example-side target
  • ./target/debug/pred reduce <source.json> --to ILP
  • ./target/debug/pred solve <source.json>
  • ./target/debug/pred solve <bundle.json>
• Discoverability: pred list --rules --json contains GraphPartitioning/SimpleGraph -> ILP/bool, and pred show GraphPartitioning / pred show ILP both surface the new edge.
• Setup: building pred in the review worktree succeeded without extra steps.
• Functionality: all exercised commands succeeded. The target example contains 15 variables and 19 constraints, the reduction bundle targets ILP, and both solve paths return evaluation Valid(3).
• Expected vs Actual Outcome: matched.
• Blocked steps: none.
• Friction points: none found.
• Doc suggestions: none required for this workflow.

Issues Found

None.

Suggestions

• Consider updating the deterministic review whitelist to permit docs/paper/references.bib in rule PRs that add new citations.

---

Generated by review-pipeline