Reduce exported functions (closes #77) (#80)

* refactor: internalize reduction structs and gadgets in rules module

Remove public re-exports of ~30 ReductionXToY structs, 6 gadget
functions, BoolVar, LogicGadget, and JSON serialization types
(EdgeJson, NodeJson, ReductionGraphJson) from rules/mod.rs. Users
interact with reductions via the ReduceTo trait or ReductionGraph,
never referencing these structs by name.

Also remove unused ReductionColoringToILP type alias and suppress
dead_code warnings on LogicGadget fields only read in tests.

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

* refactor: internalize unitdiskmapping implementation details

Change internal type re-exports (CopyLine, MappingGrid, CellState,
Pattern, etc.) from pub to pub(crate) in unitdiskmapping/mod.rs.
Change alpha_tensor and pathdecomposition modules to pub(crate).

Add #[cfg(test)] guards on re-exports only needed by unit tests.
Add #[doc(hidden)] _internal module for the export_mapping_stages
example which needs these types.

Keep ksg, triangular modules and GridKind/MappingResult as pub.

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

* refactor: internalize polynomial/truth_table, delete unused graph_types module

- Change polynomial and truth_table modules from pub to pub(crate)
  since they are only used internally via crate:: imports.
- Delete graph_types.rs and its unit test file (zero internal imports,
  confirmed by codebase audit; actual graph types live in topology/).
- Remove truth_table integration tests from tests/suites/reductions.rs
  (equivalent coverage exists in src/unit_tests/truth_table.rs).
- Remove doc example from TruthTable since the module is now internal.

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

* feat: add is_valid_solution methods to graph problem types

Add public is_valid_solution(&self, config: &[usize]) -> bool methods to
all graph problem types, delegating to existing private validation helpers.
Also add cut_size method to MaxCut for computing partition cut sizes.

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

* feat: add is_valid_solution methods to set and specialized problems

Add public is_valid_solution methods to MaximumSetPacking,
MinimumSetCovering, BicliqueCover, CircuitSAT, and Factoring.
Each delegates to existing validation logic. PaintShop already
has count_switches and BMF is skipped per design.

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

* refactor: internalize validation free functions, keep as problem methods

Change standalone validation free functions (is_independent_set,
is_vertex_cover, is_clique, etc.) from pub to pub(crate) with #[cfg(test)]
for test-only functions. Functions still used in non-test code
(is_valid_coloring, is_hamiltonian_cycle, cut_size) remain pub(crate)
without #[cfg(test)].

- Change 17 validation functions from pub to pub(crate)
- Add #[cfg(test)] to 14 functions only used in tests
- Remove validation function re-exports from graph/set/specialized mod.rs
- Make submodules pub(crate) for crate-internal test access
- Update graph_models.rs imports to use full module paths

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

* refactor: internalize config_to_bits and bits_to_config

Change these utility functions from pub to pub(crate) with #[cfg(test)]
since they are only used in unit tests. This reduces the public API
surface of the config module.

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

* refactor: slim down prelude to essential items

Remove from prelude: config utilities, registry types, variant types,
ILP/optimization internals, NumericSize, and WeightElement. These items
remain accessible via their full module paths.

Add explicit imports to 16 examples, 2 integration test files that
previously relied on the broader prelude:
- ILP type: 13 examples + 1 test file
- K3/K2 variant types: 7 examples + 2 test files
- LinearConstraint/ObjectiveSense: 1 example + 1 test file

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

* fix: restore PlanarGraph and BipartiteGraph VariantParam tests

These tests were dropped when graph_types.rs was deleted but had no
equivalent coverage elsewhere. Added them to variant.rs where similar
graph type VariantParam tests already exist.

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

* test: add is_valid_solution and cut_size method tests

Cover all 15 new public methods with both valid and invalid cases:
- 14 is_valid_solution tests across all problem types
- 1 cut_size method test for MaxCut

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: GiggleLiu

src/unit_tests/models/graph/kcoloring.rs

@@ -178,3 +178,13 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_sat, jl_best, "KColoring satisfying solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Path graph: 0-1-2, 3-coloring
+    let problem = KColoring::<K3, _>::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]));
+    // Valid: neighbors have different colors
+    assert!(problem.is_valid_solution(&[0, 1, 0]));
+    // Invalid: adjacent vertices 0 and 1 have same color
+    assert!(!problem.is_valid_solution(&[0, 0, 1]));
+}

src/unit_tests/models/graph/max_cut.rs

@@ -128,3 +128,12 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "MaxCut best solutions mismatch");
     }
 }
+
+#[test]
+fn test_cut_size_method() {
+    let problem = MaxCut::new(SimpleGraph::new(3, vec![(0, 1), (1, 2), (0, 2)]), vec![1, 2, 3]);
+    // Partition {0} vs {1, 2}: cuts edges (0,1)=1 and (0,2)=3
+    assert_eq!(problem.cut_size(&[0, 1, 1]), 4);
+    // All same partition: no edges cut
+    assert_eq!(problem.cut_size(&[0, 0, 0]), 0);
+}

src/unit_tests/models/graph/maximal_is.rs

@@ -163,3 +163,13 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "MaximalIS best solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Path graph: 0-1-2
+    let problem = MaximalIS::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]), vec![1i32; 3]);
+    // Valid: {0, 2} is maximal (independent and no vertex can be added)
+    assert!(problem.is_valid_solution(&[1, 0, 1]));
+    // Invalid: {0} is independent but not maximal (vertex 2 can be added)
+    assert!(!problem.is_valid_solution(&[1, 0, 0]));
+}

src/unit_tests/models/graph/maximum_clique.rs

@@ -269,3 +269,18 @@ fn test_clique_problem() {
     assert_eq!(p.evaluate(&[1, 0, 0]), SolutionSize::Valid(1));
     assert_eq!(p.direction(), Direction::Maximize);
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Triangle: 0-1-2 all connected
+    let problem = MaximumClique::new(
+        SimpleGraph::new(3, vec![(0, 1), (1, 2), (0, 2)]),
+        vec![1i32; 3],
+    );
+    // Valid: all three form a clique
+    assert!(problem.is_valid_solution(&[1, 1, 1]));
+    // Now path graph: 0-1-2 (no 0-2 edge)
+    let problem2 = MaximumClique::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]), vec![1i32; 3]);
+    // Invalid: {0, 2} not adjacent
+    assert!(!problem2.is_valid_solution(&[1, 0, 1]));
+}

src/unit_tests/models/graph/maximum_independent_set.rs

@@ -161,3 +161,13 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "IS best solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Path graph: 0-1-2
+    let problem = MaximumIndependentSet::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]), vec![1i32; 3]);
+    // Valid: {0, 2} is independent
+    assert!(problem.is_valid_solution(&[1, 0, 1]));
+    // Invalid: {0, 1} are adjacent
+    assert!(!problem.is_valid_solution(&[1, 1, 0]));
+}

src/unit_tests/models/graph/maximum_matching.rs

@@ -153,3 +153,16 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "Matching best solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Triangle: edges (0,1), (1,2), (0,2) — config is per edge
+    let problem = MaximumMatching::new(
+        SimpleGraph::new(3, vec![(0, 1), (1, 2), (0, 2)]),
+        vec![1i32; 3],
+    );
+    // Valid: select edge (0,1) only — no shared vertices
+    assert!(problem.is_valid_solution(&[1, 0, 0]));
+    // Invalid: select edges (0,1) and (1,2) — vertex 1 shared
+    assert!(!problem.is_valid_solution(&[1, 1, 0]));
+}

src/unit_tests/models/graph/minimum_dominating_set.rs

@@ -158,3 +158,13 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "DS best solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Path graph: 0-1-2
+    let problem = MinimumDominatingSet::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]), vec![1i32; 3]);
+    // Valid: {1} dominates all vertices (0 and 2 are neighbors of 1)
+    assert!(problem.is_valid_solution(&[0, 1, 0]));
+    // Invalid: {0} doesn't dominate vertex 2
+    assert!(!problem.is_valid_solution(&[1, 0, 0]));
+}

src/unit_tests/models/graph/minimum_vertex_cover.rs

@@ -144,3 +144,13 @@ fn test_jl_parity_evaluation() {
         assert_eq!(rust_best, jl_best, "VC best solutions mismatch");
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // Path graph: 0-1-2
+    let problem = MinimumVertexCover::new(SimpleGraph::new(3, vec![(0, 1), (1, 2)]), vec![1i32; 3]);
+    // Valid: {1} covers both edges
+    assert!(problem.is_valid_solution(&[0, 1, 0]));
+    // Invalid: {0} doesn't cover edge (1,2)
+    assert!(!problem.is_valid_solution(&[1, 0, 0]));
+}

src/unit_tests/models/graph/traveling_salesman.rs

@@ -222,3 +222,16 @@ fn test_brute_force_triangle_weighted() {
     assert_eq!(solutions[0], vec![1, 1, 1]);
     assert_eq!(problem.evaluate(&solutions[0]), SolutionSize::Valid(30));
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // K3 triangle: edges (0,1), (0,2), (1,2) — config is per edge
+    let problem = TravelingSalesman::new(
+        SimpleGraph::new(3, vec![(0, 1), (0, 2), (1, 2)]),
+        vec![1, 2, 3],
+    );
+    // Valid: select all 3 edges forms Hamiltonian cycle 0-1-2-0
+    assert!(problem.is_valid_solution(&[1, 1, 1]));
+    // Invalid: select only 2 edges — not a cycle
+    assert!(!problem.is_valid_solution(&[1, 1, 0]));
+}

src/unit_tests/models/satisfiability/sat.rs

@@ -194,3 +194,16 @@ fn test_jl_parity_evaluation() {
         }
     }
 }
+
+#[test]
+fn test_is_valid_solution() {
+    // (x1 OR x2) AND (NOT x1 OR x3)
+    let problem = Satisfiability::new(
+        3,
+        vec![CNFClause::new(vec![1, 2]), CNFClause::new(vec![-1, 3])],
+    );
+    // Valid: x1=F, x2=T, x3=T → (T) AND (T) = T
+    assert!(problem.is_valid_solution(&[0, 1, 1]));
+    // Invalid: x1=T, x2=F, x3=F → (T) AND (F) = F
+    assert!(!problem.is_valid_solution(&[1, 0, 0]));
+}