Fix #248: Add RuralPostman model

[zazabap]

Summary

Add the Rural Postman Problem (RPP) as a satisfaction problem model. Given a graph G=(V,E) with edge lengths, a subset E' of required edges, and a bound B, determine if there exists a circuit covering all required edges with total length at most B.

Fixes #248

[codecov]

Codecov Report

❌ Patch coverage is 98.85496% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.79%. Comparing base (6401e7d) to head (1c701ac).
⚠️ Report is 1 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #608      +/-   ##
==========================================
+ Coverage   96.77%   96.79%   +0.02%     
==========================================
  Files         228      230       +2     
  Lines       30048    30310     +262     
==========================================
+ Hits        29079    29339     +260     
- Misses        969      971       +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.

[zazabap]

Implementation Summary

Changes

• src/models/graph/rural_postman.rs — New RuralPostman satisfaction problem (struct, Problem/SatisfactionProblem traits, declare_variants, inventory schema)
• src/unit_tests/models/graph/rural_postman.rs — 16 unit tests (creation, accessors, valid/invalid circuits, brute force, serialization, edge cases)
• src/models/graph/mod.rs — Module registration + re-export
• src/models/mod.rs — Re-export RuralPostman
• src/lib.rs — Added to prelude
• problemreductions-cli/src/dispatch.rs — load_problem + serialize_any_problem arms
• problemreductions-cli/src/problem_name.rs — resolve_alias (ruralpostman/rpp) + ALIASES (RPP)
• problemreductions-cli/src/commands/create.rs — Create handler with --graph, --edge-weights, --required-edges, --bound
• problemreductions-cli/src/cli.rs — New --required-edges and --bound flags, help table entry
• docs/paper/reductions.typ — display-name + problem-def entry
• docs/src/reductions/problem_schemas.json — Regenerated (25 schemas)

Deviations from Plan

• None

Open Questions

• None

[zazabap]

Implementation Summary

Changes

• src/models/graph/rural_postman.rs — New RuralPostman<G, W> satisfaction problem model
• src/unit_tests/models/graph/rural_postman.rs — 16 unit tests (creation, evaluation, brute force, serialization)
• src/models/graph/mod.rs — Module registration and re-export
• src/models/mod.rs — Re-export RuralPostman
• src/lib.rs — Add to prelude
• problemreductions-cli/src/dispatch.rs — load_problem + serialize_any_problem arms
• problemreductions-cli/src/problem_name.rs — "ruralpostman"/"rpp" alias + RPP short alias
• problemreductions-cli/src/commands/create.rs — Create handler with --required-edges and --bound flags
• problemreductions-cli/src/cli.rs — New CLI flags + help table entry
• docs/paper/reductions.typ — problem-def entry with formal definition and example

Deviations from Plan

• None

Open Questions

• None

[Copilot]

Pull request overview

Adds a new graph satisfaction model for the Rural Postman Problem (RPP) and wires it into the library exports, CLI instance creation/serialization, and documentation/schema generation.

Changes:

• Introduces RuralPostman model with registry schema entry, variants, and evaluation logic.
• Adds unit tests for model behavior plus CLI dispatch + pred create support and name/alias resolution.
• Updates docs (problem schemas JSON and paper) to include the new problem.

Reviewed changes

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

Show a summary per file

File	Description
src/models/graph/rural_postman.rs	New RuralPostman model, registry schema entry, evaluation logic, and variant declaration.
src/unit_tests/models/graph/rural_postman.rs	Unit tests covering construction, evaluation cases, brute-force satisfiability, serialization, and accessors.
src/models/graph/mod.rs	Registers the new graph model module and re-exports RuralPostman.
src/models/mod.rs	Re-exports RuralPostman from the top-level models module.
src/lib.rs	Exposes RuralPostman via the crate prelude.
problemreductions-cli/src/problem_name.rs	Adds RPP alias and resolves ruralpostman/rpp to RuralPostman.
problemreductions-cli/src/dispatch.rs	Enables CLI load/serialize dispatch for RuralPostman<SimpleGraph,i32>.
problemreductions-cli/src/commands/create.rs	Adds pred create RuralPostman ... support and usage examples.
problemreductions-cli/src/cli.rs	Adds --required-edges and --bound CLI flags and updates help text.
docs/src/reductions/problem_schemas.json	Adds the RuralPostman schema entry for docs/tooling.
docs/paper/reductions.typ	Adds a Rural Postman definition section for the paper.

---

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

[Copilot]

The current model/evaluation encodes a connected Eulerian subgraph (binary select edges, even degrees, connected) and sums each selected edge length once. This is stricter than the Rural Postman definition in the PR/issue, where a circuit may traverse edges (especially non-required connectors) multiple times. As a result, instances that are feasible only by repeating edges will be incorrectly rejected. Consider changing the representation to allow per-edge traversal counts (dims > 2 derived from the bound / edge length) or otherwise updating the problem definition/description and docs to match the implemented (Eulerian-subgraph) problem.

[Copilot]

ProblemSchemaEntry declares the flag/field name as edge_lengths, but the CLI pred create RuralPostman implementation parses --edge-weights (CreateArgs has edge_weights, not edge_lengths). Because schema-driven help prints flags from these field names, users will be told to pass --edge-lengths, which won't work. Please align naming (e.g., rename schema field to edge_weights and consider renaming the struct field/accessor for consistency with other graph models).

Suggested change

	FieldInfo { name: "edge_lengths", type_name: "Vec<W>", description: "Edge lengths l(e) for each e in E" },
	FieldInfo { name: "edge_weights", type_name: "Vec<W>", description: "Edge lengths l(e) for each e in E" },

[Copilot]

The definition mixes subset symbols: it introduces $E' \subset.eq E$ but later says "For general $E' subset E$" (strict subset). This reads like a typo/inconsistency in the mathematical statement; consider using $\subseteq$ consistently unless strictness is intended.

Suggested change

The Rural Postman Problem (RPP) is a fundamental NP-complete arc-routing problem @lenstra1976 that generalizes the Chinese Postman Problem. When $E' = E$, the problem reduces to finding an Eulerian circuit with minimum augmentation (polynomial-time solvable via $T$-join matching). For general $E' subset E$, exact algorithms use dynamic programming over subsets of required edges in $O(n^2 dot 2^r)$ time, where $r = |E'|$ and $n = |V|$, analogous to the Held-Karp algorithm for TSP. The problem admits a $3 slash 2$-approximation for metric instances @frederickson1979.

The Rural Postman Problem (RPP) is a fundamental NP-complete arc-routing problem @lenstra1976 that generalizes the Chinese Postman Problem. When $E' = E$, the problem reduces to finding an Eulerian circuit with minimum augmentation (polynomial-time solvable via $T$-join matching). For general $E' subset.eq E$, exact algorithms use dynamic programming over subsets of required edges in $O(n^2 dot 2^r)$ time, where $r = |E'|$ and $n = |V|$, analogous to the Held-Karp algorithm for TSP. The problem admits a $3 slash 2$-approximation for metric instances @frederickson1979.

[GiggleLiu]

Review Pipeline Report

Check	Result
Merge with main	Resolved 6 additive conflicts (imports, CLI args, paper)
Copilot comments	3 fixed (schema naming, paper symbol, model semantics)
Issue/human comments	2 checked, 0 actionable
CI	green (all 5 checks pass)
Agentic test	passed (16/16 tests, CLI create/evaluate verified)
Board	review-agentic → In Review

Copilot Fixes Applied

1. Schema field naming: edge_lengths → edge_weights for CLI consistency
2. Paper symbol: $E' subset E$ → $E' subset.eq E$ (consistent ⊆)
3. Model semantics: Changed from binary edge selection to multiplicity {0,1,2} to correctly model circuits that may traverse edges multiple times

🤖 Generated by review-pipeline