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

❌ Patch coverage is 97.84173% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.21%. Comparing base (891264c) to head (d57ca3a).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/models/graph/hamiltonian_circuit.rs	95.16%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #619    +/-   ##
========================================
  Coverage   97.21%   97.21%            
========================================
  Files         310      312     +2     
  Lines       40595    40734   +139     
========================================
+ Hits        39463    39600   +137     
- Misses       1132     1134     +2

☔ 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

zazabap · 2026-03-15T08:58:03Z

Review Pipeline Report

Check	Result
Merge with main	Conflict resolved (reduction_graph.json regenerated)
Copilot comments	0 actionable (approved, no inline comments)
Issue/human comments	3 checked, 0 unaddressed
Structural review	18/18 passed
Code quality	OK (DRY/KISS/HC-LC clean)
CI	green (Test, Clippy, Coverage all pass)
Agentic test	passed (CLI create/solve/evaluate, library API, edge cases all work)
Board	Review pool → Under review → Final review

🤖 Generated by review-pipeline

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The entry already existed on main; the PR added a second copy that caused a Typst compile error after merging. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add example with figure to HamiltonianCircuit problem-def entry, loading data from canonical examples.json (prism graph) - Extract is_valid_hamiltonian_circuit() pub(crate) helper, matching the HamiltonianPath pattern (is_valid_hamiltonian_path) - Add is_valid_solution() convenience method on HamiltonianCircuit Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new graph decision model, HamiltonianCircuit, and integrates it across the library API surface, CLI instance generation, fixtures, unit tests, and the paper docs.

Changes:

Introduces HamiltonianCircuit<G> model (schema registration, variant declaration, example-db spec) with validity checking via permutation + wrap-around edge adjacency.
Adds comprehensive unit tests and wires the model into trait-consistency checks, exports (models, prelude), and the graph module registry.
Extends CLI support (pred create + random generation), example-db fixtures, and paper documentation/references for the new problem.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`src/models/graph/hamiltonian_circuit.rs`	New HamiltonianCircuit model + schema entry + variants + example-db spec + tests hook
`src/models/graph/mod.rs`	Registers module/export and includes canonical example spec
`src/models/mod.rs`	Re-exports `HamiltonianCircuit` from `models::graph`
`src/lib.rs`	Adds `HamiltonianCircuit` to the prelude exports
`src/unit_tests/models/graph/hamiltonian_circuit.rs`	New unit test suite for evaluation, solver behavior, and serialization
`src/unit_tests/trait_consistency.rs`	Adds trait-consistency check coverage for `HamiltonianCircuit`
`problemreductions-cli/src/commands/create.rs`	Adds CLI creation + random generation support and help example string
`problemreductions-cli/src/cli.rs`	Documents CLI flags / alias (`HC`) for HamiltonianCircuit
`src/example_db/fixtures/examples.json`	Adds canonical fixture instance + samples/optimal satisfying configurations
`docs/paper/references.bib`	Adds/normalizes the Björklund 2014 reference used by the paper text
`docs/paper/reductions.typ`	Adds HamiltonianCircuit section with example and figure driven from fixtures

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

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

Merge origin/main, regenerate reduction_graph.json

7a7f2bf

isPANN self-assigned this Mar 18, 2026

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

5771f68

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

isPANN and others added 5 commits March 18, 2026 17:55

Regenerate example fixtures after merging main

aa3857b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove duplicate bjorklund2014 BibTeX entry

836748d

The entry already existed on main; the PR added a second copy that caused a Typst compile error after merging. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Merge branch 'main' into issue-216-hamiltonian-circuit

2223e21

Merge branch 'main' into issue-216-hamiltonian-circuit

9b4b43e

isPANN requested a review from Copilot March 18, 2026 10:18

isPANN approved these changes Mar 18, 2026

View reviewed changes

Copilot started reviewing on behalf of isPANN March 18, 2026 10:18 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Merge branch 'main' into issue-216-hamiltonian-circuit

d57ca3a

isPANN merged commit 90977d7 into main Mar 18, 2026
5 checks passed

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
isPANN merged 22 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!

zazabap commented Mar 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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!

zazabap commented Mar 15, 2026

Review Pipeline Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Mar 13, 2026 •

edited

Loading