Fix #216: Add HamiltonianCircuit model by GiggleLiu · Pull Request #619 · CodingThrust/problem-reductions

GiggleLiu · 2026-03-13T00:36:19Z

Summary

Adds the HamiltonianCircuit satisfaction problem — a classical NP-complete problem (Karp, 1972) asking whether an undirected graph contains a cycle visiting every vertex exactly once.

New model with permutation encoding (dims() = vec![n; n])
SatisfactionProblem trait (Metric = bool)
CLI integration (dispatch, create, aliases)
Unit tests and paper documentation

Fixes #216

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

codecov · 2026-03-13T00:38:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.85%. Comparing base (f75a28c) to head (61714d5).

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #619    +/-   ##
========================================
  Coverage   96.84%   96.85%            
========================================
  Files         262      264     +2     
  Lines       35029    35164   +135     
========================================
+ Hits        33924    34058   +134     
- Misses       1105     1106     +1

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

- New satisfaction problem (Metric = bool) for Hamiltonian circuit detection - Permutation encoding: dims() = vec![n; n] - Evaluate checks valid permutation + consecutive edge existence - Held-Karp complexity: O(n^2 * 2^n) in declare_variants! - CLI integration: dispatch, alias (HC), create, random generation - Unit tests: basic, no-solution, solver, serialization - Paper: problem-def + Bjorklund 2014 bibliography entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

GiggleLiu · 2026-03-13T00:51:42Z

Implementation Summary

Changes

src/models/graph/hamiltonian_circuit.rs — New HamiltonianCircuit model (SatisfactionProblem, permutation encoding)
src/unit_tests/models/graph/hamiltonian_circuit.rs — 4 unit tests (basic, no-solution, solver, serialization)
src/models/graph/mod.rs — Module registration
src/models/mod.rs — Re-export
problemreductions-cli/src/dispatch.rs — CLI dispatch (load + serialize)
problemreductions-cli/src/problem_name.rs — Alias HC + lowercase mapping
problemreductions-cli/src/commands/create.rs — CLI create (manual + random)
problemreductions-cli/src/cli.rs — Help text update
docs/paper/reductions.typ — problem-def entry + display-name
docs/paper/references.bib — Bjorklund 2014 bibliography entry

Deviations from Plan

Added defensive config.len() != n guard in evaluate() (caught during review)

Open Questions

Complexity string uses Held-Karp O(n^2 * 2^n) (deterministic) rather than Bjorklund O*(1.657^n) (randomized) — matches project convention for deterministic bounds

Copilot

Pull request overview

Adds a new NP-complete graph satisfaction model (HamiltonianCircuit) to the core library, integrates it into the CLI (name/alias/dispatch/create), and updates the paper documentation and references.

Changes:

Introduces HamiltonianCircuit<G> model with permutation-based encoding and variant declaration.
Adds CLI support: alias resolution (HC), JSON (de)serialization dispatch, and pred create / random generation wiring.
Adds unit tests plus paper documentation section and bibliography entry.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/models/graph/hamiltonian_circuit.rs	New Hamiltonian circuit satisfaction model + schema registration + variants + tests hook
src/unit_tests/models/graph/hamiltonian_circuit.rs	New unit tests for evaluation, solver enumeration, and serde round-trip
src/models/graph/mod.rs	Exposes the new graph model in the graph module
src/models/mod.rs	Re-exports `HamiltonianCircuit` from the top-level models module
problemreductions-cli/src/problem_name.rs	Adds `HC` alias and resolves `hc` / `hamiltoniancircuit`
problemreductions-cli/src/dispatch.rs	Adds load/serialize support for `HamiltonianCircuit<SimpleGraph>` as a SAT problem
problemreductions-cli/src/commands/create.rs	Adds `pred create HamiltonianCircuit` and random instance generation support
problemreductions-cli/src/cli.rs	Documents CLI flags for `HamiltonianCircuit` and `HC`
docs/paper/references.bib	Adds Björklund 2014 reference
docs/paper/reductions.typ	Adds Hamiltonian Circuit problem definition section in the paper

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/models/graph/hamiltonian_circuit.rs

+    fn evaluate(&self, config: &[usize]) -> bool {
+        let n = self.graph.num_vertices();
+        if config.len() != n {
+            return false;
+        }
+


GiggleLiu · 2026-03-13T00:59:52Z

HC is intentionally a separate model from TSP — it's a SatisfactionProblem (decision: does a Hamiltonian circuit exist?) vs TSP's OptimizationProblem (minimize tour weight). Different traits, different encoding (permutation vs edge-binary), different solver interfaces (find_satisfying vs find_best). See #600 for the full discussion.

Resolve conflicts: keep both HamiltonianCircuit (PR) and main's new models (IsomorphicSpanningTree, HamiltonianPath, etc.). Update HamiltonianCircuit to use current ProblemSchemaEntry fields and declare_variants! syntax. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

A Hamiltonian circuit requires at least 3 vertices. Return false early for degenerate cases, addressing Copilot review comment. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…-circuit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Use 1.657^num_vertices complexity (Björklund 2014), matching HamiltonianPath - Add canonical_model_example_specs for example-db system - Register in graph/mod.rs example specs aggregator - Add trait_consistency entry - Add edge case tests: n<3 graphs, wrong-length config, out-of-range vertex, K3 triangle, K4 complete graph solution count Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…st/problem-reductions into issue-216-hamiltonian-circuit

Resolve conflicts: keep registry-based dispatch from main, add HamiltonianCircuit alongside main's new models. Update HamiltonianCircuit to current declare_variants!/ProblemSchemaEntry patterns.

…dingThrust/problem-reductions into issue-216-hamiltonian-circuit

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…dingThrust/problem-reductions into issue-216-hamiltonian-circuit

GiggleLiu · 2026-03-14T18:27:58Z

Review Pipeline Report

Check	Result
Copilot comments	1 already fixed (n<3 guard)
Issue/human comments	3 checked, 0 action needed
Structural review	18/18 passed
Code quality	OK (DRY/KISS/HC-LC clean)
CI	green
Agentic test	passed — fixed missing prelude export
Board	review-agentic → In Review

Fix applied

Added HamiltonianCircuit to prelude in src/lib.rs (was missing alongside HamiltonianPath)
Regenerated JSON artifacts (problem_schemas.json, reduction_graph.json)

🤖 Generated by review-pipeline

GiggleLiu · 2026-03-14T18:28:47Z

Review Pipeline Report

Check	Result
Copilot comments	1 fixed (n < 3 guard in evaluate)
Issue/human comments	3 checked, 0 actionable
Structural review	18/18 passed
CI	green (Test, Clippy, Coverage all pass)
Agentic test	passed (library API + CLI)
Board	review-agentic → In Review

Fixes applied during review

Merged origin/main and resolved 7 file conflicts
Updated ProblemSchemaEntry to include display_name, aliases, dimensions fields
Updated declare_variants! to use default sat keyword
Added n < 3 guard in evaluate() (Copilot review)
Changed complexity from num_vertices^2 * 2^num_vertices to 1.657^num_vertices (Björklund 2014, matches HamiltonianPath)
Added canonical_model_example_specs() with #[cfg(feature = "example-db")]
Added trait_consistency entry
Added edge case tests: n<3, wrong-length, out-of-range, K3, K4

🤖 Generated by review-pipeline

GiggleLiu · 2026-03-14T18:29:29Z

Review Pipeline Report

Check	Result
Copilot comments	0 (approved, no inline comments)
Issue/human comments	2 checked, 0 new fixes needed (n<3 guard already addressed)
Structural review	18/18 passed (3 fixed: complexity string, canonical example, trait_consistency)
Code quality	OK (DRY minor concern with HamiltonianPath shared permutation logic)
CI	green (Test, Clippy, Codecov all passing)
Agentic test	passed (API + CLI all functional)
Board	review-agentic → In Review

Fixes Applied

Complexity string: "num_vertices^2 * 2^num_vertices" → "1.657^num_vertices" (Björklund 2014, consistent with HamiltonianPath)
Added canonical_model_example_specs + registration in graph/mod.rs
Added trait_consistency entry
Added boundary tests (n=0, n=1, n=2, K3, K4, wrong-length, out-of-range)
Added HamiltonianCircuit to prelude
Regenerated JSON artifacts

Agentic Test Summary

All programmatic API works: create, solve (find_satisfying, find_all_satisfying), evaluate, serialize
All CLI commands work: pred list, pred show HC, pred create HC, pred solve --solver brute-force, pred evaluate, pred create --example HC/SimpleGraph
Minor friction: HC is currently an isolated node (0 reductions), ILP solver unavailable

🤖 Generated by review-pipeline

GiggleLiu · 2026-03-14T18:30:58Z

Review Pipeline Report

Check	Result
Copilot comments	0 actionable (approved)
Issue/human comments	3 checked, 0 unaddressed
Merge with main	Conflicts resolved (registration files, paper, CLI)
Structural review	18/18 passed
Code quality	Approve — no critical or important issues
CI	green (first check)
Agentic test	passed — 7 CLI scenarios + API tests all succeeded
Board	review-agentic → In Review

Notes

Complexity string uses 1.657^num_vertices (Björklund 2014), consistent with HamiltonianPath model
Minor doc suggestions from agentic test: add configuration semantics to pred show output

🤖 Generated by review-pipeline

GiggleLiu · 2026-03-14T18:35:43Z

Review Pipeline Report

Check	Result
Copilot comments	1 checked, already addressed (n < 3 guard exists)
Issue/human comments	3 checked, 0 actionable
Structural review	18/18 passed
CI	green (Test, Clippy, Coverage all pass)
Agentic test	passed (17/17 scenarios)
Board	review-agentic → In Review

Details

Merge with main: 7 conflicts resolved (registry-based dispatch from main preferred over manual dispatch).

Structural completeness: All checks pass — model file, inventory registration, declare_variants!, Problem + SatisfactionProblem traits, unit tests (6), trait_consistency, CLI create support, paper entry, example-db registration.

Quality review: Clean implementation. One formatting fix applied. No critical or important issues.

Agentic feature test: Simulated a grad student using HC via CLI and library API. All CLI commands work (list, show, create, solve, inspect, pipe, evaluate). Solver correctly finds circuits and reports no-solution for infeasible graphs.

🤖 Generated by review-pipeline

Add plan for #216: HamiltonianCircuit model

b229cee

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

GiggleLiu and others added 2 commits March 13, 2026 08:51

chore: remove plan file after implementation

c3d5a0d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

GiggleLiu requested a review from Copilot March 13, 2026 00:51

Copilot started reviewing on behalf of GiggleLiu March 13, 2026 00:52 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

src/models/graph/hamiltonian_circuit.rs

Comment on lines +96 to +101

fn evaluate(&self, config: &[usize]) -> bool {

let n = self.graph.num_vertices();

if config.len() != n {

return false;

}

GiggleLiu mentioned this pull request Mar 13, 2026

[Discussion] Hamiltonian Path, Hamiltonian Circuit, and Traveling Salesman — models and reduction triviality #600

Open

GiggleLiu and others added 11 commits March 15, 2026 01:57

fix: guard against n < 3 in HamiltonianCircuit::evaluate

5c740ed

A Hamiltonian circuit requires at least 3 vertices. Return false early for degenerate cases, addressing Copilot review comment. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into issue-216-hamiltonian…

31b5fe0

…-circuit

Merge remote changes from issue-216-hamiltonian-circuit

b306deb

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'issue-216-hamiltonian-circuit' of github.com:CodingThru…

1b05530

…st/problem-reductions into issue-216-hamiltonian-circuit

Merge origin/main into issue-216-hamiltonian-circuit

c5b0971

Resolve conflicts: keep registry-based dispatch from main, add HamiltonianCircuit alongside main's new models. Update HamiltonianCircuit to current declare_variants!/ProblemSchemaEntry patterns.

Merge branch 'issue-216-hamiltonian-circuit' of https://github.com/Co…

26153c7

…dingThrust/problem-reductions into issue-216-hamiltonian-circuit

Add HamiltonianCircuit to prelude and regenerate JSON artifacts

9e4417e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix formatting and update reduction_graph.json complexity

ba1e534

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'issue-216-hamiltonian-circuit' of https://github.com/Co…

61714d5

…dingThrust/problem-reductions into issue-216-hamiltonian-circuit

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix #216: Add HamiltonianCircuit model#619

Fix #216: Add HamiltonianCircuit model#619
GiggleLiu wants to merge 14 commits intomainfrom
issue-216-hamiltonian-circuit

GiggleLiu commented Mar 13, 2026

Uh oh!

codecov bot commented Mar 13, 2026 •

edited

Loading

Uh oh!

GiggleLiu commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

GiggleLiu commented Mar 13, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

GiggleLiu commented Mar 13, 2026

Summary

Uh oh!

codecov bot commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

GiggleLiu commented Mar 13, 2026

Implementation Summary

Changes

Deviations from Plan

Open Questions

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

GiggleLiu commented Mar 13, 2026

Uh oh!

GiggleLiu commented Mar 14, 2026

Review Pipeline Report

Fix applied

Uh oh!

GiggleLiu commented Mar 14, 2026

Review Pipeline Report

Fixes applied during review

Uh oh!

GiggleLiu commented Mar 14, 2026

Review Pipeline Report

Fixes Applied

Agentic Test Summary

Uh oh!

GiggleLiu commented Mar 14, 2026

Review Pipeline Report

Notes

Uh oh!

GiggleLiu commented Mar 14, 2026

Review Pipeline Report

Details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Mar 13, 2026 •

edited

Loading