Fix #91: [Rule] ClosestVectorProblem to QUBO

[GiggleLiu]

Summary

Add implementation plan for issue #91.

Fixes #91

[GiggleLiu]

Implementation Summary

Changes

• src/models/algebraic/closest_vector_problem.rs: added exact bounded binary encoding helpers and a num_encoding_bits() getter so reductions can size QUBO instances from the actual CVP bounds.
• src/rules/closestvectorproblem_qubo.rs: implemented the ClosestVectorProblem -> QUBO reduction, including the canonical example and solution extraction back to CVP configurations.
• src/unit_tests/models/algebraic/closest_vector_problem.rs and src/unit_tests/rules/closestvectorproblem_qubo.rs: added encoding tests, closed-loop rule tests, coefficient checks, and duplicate-encoding checks.
• src/rules/mod.rs: registered the new rule examples.
• docs/paper/reductions.typ and docs/paper/references.bib: documented the reduction and added the supporting citation.

Deviations from Plan

• Replaced the planned invalid-range penalty approach with an exact bounded encoding per source variable, so every target bitstring decodes to an in-range CVP offset and the reduction remains exact without extra penalty terms.
• extract_solution() returns CVP configuration offsets rather than reconstructed lattice coordinates, matching the source model's configuration space.
• The reduction overhead is expressed in terms of num_encoding_bits instead of a fixed multiple of variables because the target size depends on the actual source bounds.

Open Questions

• None.

[GiggleLiu]

Agentic Review Report

Note: The PR's failing Code Coverage job appears unrelated to this diff. The failure is a compile error in unchanged problemreductions-cli/src/commands/create.rs:4183 (CreateArgs initializer missing cut_bound and size_bound) during the coverage build.

Structural Check

Structural Review: rule closestvectorproblem_qubo

Structural Completeness

#	Check	Status
1	Rule file exists	PASS — src/rules/closestvectorproblem_qubo.rs is present.
2	#[reduction(...)] macro present	PASS — found at src/rules/closestvectorproblem_qubo.rs:115.
3	ReductionResult impl present	PASS — found at src/rules/closestvectorproblem_qubo.rs:25.
4	ReduceTo impl present	PASS — found at src/rules/closestvectorproblem_qubo.rs:116.
5	#[cfg(test)] + #[path = ...] test link	PASS — found at src/rules/closestvectorproblem_qubo.rs:192-194.
6	Test file exists	PASS — src/unit_tests/rules/closestvectorproblem_qubo.rs exists.
7	Closed-loop test present	PASS — test_closestvectorproblem_to_qubo_closed_loop exists at src/unit_tests/rules/closestvectorproblem_qubo.rs:21-32.
8	Registered in rules/mod.rs	PASS — module + canonical example registration found at src/rules/mod.rs:10 and src/rules/mod.rs:89.
9	Canonical rule example registered	PASS — canonical_rule_example_specs() is implemented at src/rules/closestvectorproblem_qubo.rs:177-190 and aggregated through src/rules/mod.rs.
10	Example-db lookup tests exist	PASS — find_rule_example / build_rule_db coverage exists in src/unit_tests/example_db.rs:118-199.
11	Paper reduction-rule entry	PASS — found at docs/paper/reductions.typ:3845-3878.
12	File whitelist	FAIL — docs/paper/references.bib is outside the current rule-PR whitelist reported by the deterministic check.
13	Blacklisted file check	PASS — no generated blacklist files appear in the diff.

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• extract_solution: OK — it sums the selected exact-range weights back into source configuration offsets, which matches the ClosestVectorProblem model’s configuration space.
• overhead: OK — num_vars = num_encoding_bits matches the emitted total bit count from encoding_spans(), including the zero-bit case for fixed variables.
• example quality: OK — the canonical example is wired into the rule example DB and exercises the intended duplicate-encoding witness.
• paper quality: ISSUE — the proof currently states that substituting the encoding into the CVP objective yields z^T Q z + const, but the repo’s ClosestVectorProblem definition minimizes ||Bx - t||_2, not its square (docs/paper/reductions.typ:2128). The reduction is still valid because squaring is monotone on nonnegative distances, but that step needs to be stated explicitly in the proof around docs/paper/reductions.typ:3870-3876.

Issue Compliance

#	Check	Status
1	Source/target match issue	OK — implements ClosestVectorProblem<i32> -> QUBO<f64>.
2	Reduction algorithm matches	OK — the implementation follows the later issue-thread decision to use exact-range capped encodings instead of the original penalty sketch.
3	Solution extraction matches	OK — returns source offsets, which is the source model’s actual configuration format.
4	Correctness preserved	ISSUE — implementation/tests support correctness, but the paper proof omits the norm-to-squared-norm monotonicity step described above.
5	Overhead expressions match	OK — exported overhead is num_vars = num_encoding_bits.
6	Example matches	OK — canonical 2D example and witness are wired into tests and docs.

Summary

• 12/13 structural checks passed.
• 5/6 issue compliance checks passed.
• ISSUE — docs/paper/reductions.typ:3870-3876 needs an explicit argument that minimizing squared distance preserves the minimizers of the repo’s unsquared CVP objective.
• FAIL — deterministic whitelist check flags docs/paper/references.bib as outside the current rule-PR whitelist.
• Note — the failing coverage job appears unrelated to this PR diff.

---

Quality Check

Quality Review

Design Principles

• DRY: OK — the reduction factors encoding-span construction, Gram matrix construction, and A^T t computation into focused helpers instead of duplicating the math.
• KISS: OK — the exact-range encoding keeps the rule simpler than a penalty-based invalid-range scheme and the implementation follows that directly.
• HC/LC: OK — the model only exposes the minimal encoding helpers, while the reduction-specific matrix construction remains localized to the rule module.

Test Quality

• Naive test detection: ISSUE
  • Minor — the new rule has a dedicated total_bits == 0 branch for fully fixed CVP instances at src/rules/closestvectorproblem_qubo.rs:127-132, but there is no rule-level test exercising the empty-QUBO path or a mixed fixed/unfixed case. The current tests cover the main bounded example well, but this edge branch remains unverified.

Issues

Critical (Must Fix)

• None.

Important (Should Fix)

• None.

Minor (Nice to Have)

• Add a reduction test for the zero-bit/fixed-variable case so the special empty-QUBO branch is covered (src/rules/closestvectorproblem_qubo.rs:127-132).

Summary

• Minor — the fixed-variable / empty-QUBO branch is not exercised by the new rule tests.

---

Agentic Feature Tests

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
ClosestVectorProblem -> QUBO	yes	yes	yes	yes	good; the rule is visible in pred list --rules and the canonical example is wired

Per-Feature Details

• Role: downstream CLI user following docs/examples only.
• Use Case: discover the new rule, create the canonical CVP example, reduce it to QUBO, and solve/compare source vs target.
• What I tried: pred list --rules, pred show ClosestVectorProblem, pred create --example ClosestVectorProblem, pred solve ... --solver brute-force, pred reduce ... --to QUBO, and pred solve on the reduced bundle.
• Discoverability: good. pred list --rules shows ClosestVectorProblem/i32 -> QUBO/f64, and pred show ClosestVectorProblem surfaces the outgoing reduction and size field.
• Setup: no extra setup friction in this worktree. cargo run -p problemreductions-cli --bin pred -- ... worked directly.
• Functionality: source solve returned [3, 3] with Valid(0.5385164807134505). Reduction produced a 6-variable QUBO bundle, and solving the bundle returned intermediate QUBO solution [0, 0, 1, 0, 0, 1] and mapped back to the same source solution [3, 3].
• Expected vs Actual: matched. The reduced target solved successfully, and the mapped-back source solution agreed with the direct source solve. The raw QUBO energy differs from the CVP norm, which is expected because the rule encodes squared distance up to an additive constant.
• Blocked steps: none.
• Friction points: pred show ClosestVectorProblem resolves to the default i32 variant. That is fine here because the reduction exists on that variant, but it is a nuance users may miss if they try to inspect the f64 variant directly.
• Doc suggestions: add a short CVP-specific CLI example to docs/src/cli.md or cross-link the paper example so the new rule is easier to discover from the CLI docs alone.

Expected vs Actual Outcome
All minimum checklist items passed in the current worktree. The CVP example was discoverable, creation worked, reduction produced a valid QUBO target, and both source and reduced solves succeeded with consistent source-level results.

Issues Found

• None confirmed in the current worktree.

Suggestions

• Add a ClosestVectorProblem example to the CLI docs, alongside the existing MIS/MVC examples, so users can discover the new rule without reading the paper first.
• Clarify in the CLI docs that pred show <Name> resolves to the default variant for multi-variant problems unless a suffix is provided.

---

Generated by review-pipeline

[GiggleLiu]

Follow-up items (recorded during final review):

• Paper proof: add explicit note that minimizing squared distance is equivalent to minimizing distance (monotonicity of squaring on non-negative values) — around the correctness paragraph
• Optional: add edge-case test for fully-fixed CVP instance (all bounds have lo=hi) to cover the total_bits == 0 branch

[codecov]

Codecov Report

❌ Patch coverage is 97.52066% with 6 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@6e5843c). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/rules/closestvectorproblem_qubo.rs	96.99%	4 Missing ⚠️
src/models/algebraic/closest_vector_problem.rs	91.66%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #703   +/-   ##
=======================================
  Coverage        ?   97.54%           
=======================================
  Files           ?      371           
  Lines           ?    46958           
  Branches        ?        0           
=======================================
  Hits            ?    45803           
  Misses          ?     1155           
  Partials        ?        0           

☔ 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.