feat: Feature parity with ProblemReductions.jl

[GiggleLiu]

Summary

This PR implements feature parity with ProblemReductions.jl, adding comprehensive reduction infrastructure, topology types, and utilities.

Changes

Core Reduction Framework

• Add ReductionResult and ReduceTo traits for type-safe problem reductions
• Implement bidirectional reductions: IndependentSet ↔ VertexCovering, IndependentSet ↔ SetPacking, SpinGlass ↔ QUBO, SpinGlass ↔ MaxCut
• Add ReductionGraph for discovering reduction paths between problem types

Topology Types

• HyperGraph: Graphs with hyperedges connecting multiple vertices
• UnitDiskGraph: Geometric graphs based on distance thresholds

Utilities

• TruthTable: Logic gadget generation (AND, OR, XOR, NAND, NOR, XNOR, IMPLIES, NOT)
• File I/O with JSON serialization for all problem types

Testing & Documentation

• 29 comprehensive reduction integration tests
• 95%+ code coverage
• mdBook user guide documentation
• CI/CD workflows for testing and docs deployment
• README with status badges

Stats

• 479 tests passing (417 unit + 33 integration + 29 reduction)
• 95.20% code coverage
• 28 files changed, 1993 insertions

Test plan

• All existing tests pass (cargo test)
• New reduction tests pass
• Code coverage meets 95% threshold
• Documentation builds (mdbook build)
• Clippy passes with no warnings

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR brings the Rust crate to feature parity with ProblemReductions.jl by introducing a typed reduction framework, runtime reduction path discovery, new topology and utility modules, and substantial new documentation and integration tests.

Changes:

• Added core reduction traits (ReduceTo, ReductionResult) plus concrete reductions and a runtime ReductionGraph for path discovery.
• Introduced new topology/utilities (HyperGraph, UnitDiskGraph, TruthTable, JSON I/O helpers) and exposed them via the crate API/prelude.
• Added extensive integration tests and mdBook documentation, plus CI workflows and README/book updates.

Reviewed changes

Copilot reviewed 51 out of 53 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
tests/reduction_tests.rs	New integration tests covering reduction correctness, chaining, topology, truth tables, and JSON roundtrips.
src/truth_table.rs	Adds TruthTable utility (bitvec-backed) with logic-gate constructors and serde support.
src/topology/unit_disk_graph.rs	Adds UnitDiskGraph topology type with derived edges + helpers.
src/topology/mod.rs	Exposes topology module APIs.
src/topology/hypergraph.rs	Adds HyperGraph topology type and helpers.
src/rules/vertexcovering_independentset.rs	Implements IndependentSet ↔ VertexCovering reductions.
src/rules/traits.rs	Introduces core reduction traits (ReduceTo, ReductionResult).
src/rules/spinglass_qubo.rs	Implements SpinGlass ↔ QUBO reductions.
src/rules/spinglass_maxcut.rs	Implements SpinGlass ↔ MaxCut reductions (ancilla for onsite fields).
src/rules/mod.rs	Wires up and re-exports rules modules.
src/rules/independentset_setpacking.rs	Implements IndependentSet ↔ SetPacking reductions.
src/rules/graph.rs	Adds runtime ReductionGraph with path discovery helpers.
src/models/set/set_packing.rs	Adds weights_ref accessor to support reductions without cloning via trait method.
src/models/graph/vertex_covering.rs	Adds weights_ref accessor.
src/models/graph/max_cut.rs	Adds with_weights constructor and edge_weights accessor.
src/models/graph/independent_set.rs	Adds weights_ref accessor.
src/lib.rs	Exposes new modules and exports reduction traits in the prelude.
src/io.rs	Adds JSON/string/file IO helpers and tests.
src/error.rs	Adds IO/serialization error variants.
docs/src/topology.md	Documents topology types and sample usage.
docs/src/solvers.md	Documents solver usage and configuration.
docs/src/reductions/using.md	Documents basic and chained reduction usage.
docs/src/reductions/index.md	Documents reduction overview and trait contracts.
docs/src/reductions/graph.md	Documents ReductionGraph usage and API.
docs/src/reductions/available.md	Documents available reductions and examples.
docs/src/problems/specialized.md	Documents specialized problems.
docs/src/problems/set.md	Documents set problems and SetPacking relationship.
docs/src/problems/satisfiability.md	Documents satisfiability problems.
docs/src/problems/optimization.md	Documents optimization problems.
docs/src/problems/index.md	Documents problem categories and core interface.
docs/src/problems/graph.md	Documents graph problems and relationships.
docs/src/io.md	Documents JSON I/O helpers.
docs/src/introduction.md	Adds mdBook introduction.
docs/src/getting-started.md	Adds mdBook getting started guide.
docs/src/contributing.md	Adds contributing guide.
docs/src/api.md	Adds mdBook API entry points and links.
docs/src/SUMMARY.md	Adds mdBook table of contents.
docs/plans/2025-01-25-feature-parity-implementation.md	Adds implementation plan documentation.
docs/plans/2025-01-25-feature-parity-design.md	Adds design documentation.
book.toml	Adds mdBook configuration.
README.md	Updates README with badges, overview, examples, and docs links.
Cargo.toml	Adds serde_json dependency.
Cargo.lock	Locks serde_json transitive updates.
.github/workflows/docs.yml	Adds GitHub Pages docs deployment (mdBook + rustdoc).
.github/workflows/ci.yml	Adds CI (test/fmt/clippy/coverage) workflow.

---

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