Restore augmentation ILP overhead predictions from numeric magnitudes

[isPANN]

Superseded by #1174. This PR’s changes were included in the combined squash commit 8bdddd45 on fix/exact-reduction-parameters. Continue review and fixes in #1174. The original description below is retained for reference.

---

Motivation

This PR restores QUBO size predictions for BiconnectivityAugmentation and StrongConnectivityAugmentation, including paths that start at HamiltonianCircuit. It adds one computed source parameter to each augmentation model and supplies the missing formulas on their incoming and outgoing reduction rules.

What is currently missing?

The reduction graph should predict the size of a reduced problem from the source instance's parameters, before constructing intermediate problems. On the base branch, both augmentation → ILP<bool> rules can predict the number of ILP variables and constraints, but leave max_constraint_magnitude_bits unavailable. As a result, the existing paths below have unavailable predictions for both QUBO variables and quadratic terms:

HamiltonianCircuit → BiconnectivityAugmentation      → ILP<bool> → QUBO
HamiltonianCircuit → StrongConnectivityAugmentation → ILP<bool> → QUBO

The same gap affects paths starting directly at either augmentation model.

Why do weights and the budget affect target size?

Both reductions copy candidate weights and the budget into an ILP constraint of the form sum(weight[j] * selected[j]) <= budget. The subsequent ILP → QUBO reduction encodes inequality slack using extra Boolean variables. The number of these variables depends on the magnitudes of the coefficients and right-hand sides, as well as the ILP's structural size. Its existing bound is N + M * (N + H), where N is the ILP variable count, M is its constraint count, and H is its maximum constraint magnitude in bits.

Vertex, edge, and candidate counts do not describe those numeric magnitudes: the same graph and candidate set can carry different weights and budgets. The augmentation models therefore need a numeric source parameter to supply an input-dependent bound for H. Measuring the constructed ILP would not provide a prediction from source parameters alone.

Why one parameter, and why update the incoming rules?

A single intrinsic statistic, max_numeric_magnitude_bits, covers every candidate weight and the budget. It is computed from existing input data. Separate weight and budget parameters are unnecessary because the outgoing rule only needs their maximum magnitude. This statistic is exactly the target ILP's max_constraint_magnitude_bits, so the existing ILP → QUBO formulas can then compose.

Adding the statistic only to the augmentation models would still leave paths starting at HamiltonianCircuit incomplete. This PR also gives each incoming rule an explicit bound for that new target parameter: num_vertices + 1. Every formula remains local to its reduction and uses only that rule's source parameters.

Stacked on #1182; the comparison base is fix/flow-ilp-overhead.

Changes

• Add computed max_numeric_magnitude_bits to both augmentation models: the smallest h >= 1 bounding the magnitudes of every candidate weight and the budget strictly by 2^h. Reuse the existing magnitude helper, including its handling of i64::MIN.
• Declare the exact local relation ILP.max_constraint_magnitude_bits = max_numeric_magnitude_bits. The budget row copies these values; all other coefficients, right-hand sides, and Boolean endpoints have magnitude at most one.
• Propagate max_numeric_magnitude_bits <= num_vertices + 1 on both incoming HamiltonianCircuit rules. Their weights are 1 or 2 and budget is the source vertex count; small inputs produce fixed infeasible instances with budget zero.
• Document these relations and correct stale paper descriptions of the existing Boolean targets and small-instance handling.

This adds one canonical parameter per model, with no new constructor inputs. The statistic includes the budget, avoiding both a separate budget parameter and normalization code. Reduction constructions, accepted signed biconnectivity inputs, variants, and witness mappings are unchanged. Every formula uses only its rule's source parameters.

Verified examples

Previously, both QUBO fields were unavailable on each direct augmentation → ILP → QUBO route. CLI checks now produce sound upper bounds and recover valid source witnesses:

Input	Source magnitude bits	Predicted QUBO variables / off-diagonal terms	Measured variables / terms	Recovered result
Two isolated vertices, candidate edge weight -3, budget -2	2	≤568 / ≤322624	16 / 8	Select the edge; Or(true)
Base arc 0→1, candidate arc 1→0 of weight 2, budget 8	4	≤217 / ≤47089	16 / 19	Select the arc; Or(true)

The bounds deliberately remain coarse. Incomplete direct integer-coefficient ILP contracts decrease from 22 to 20; this is not a count of every possible graph path.

Validation

Three regression tests were observed failing before implementation and passing afterward:

• Magnitude metadata and exact ILP relations, covering weight-dominated and budget-dominated inputs, power-of-two boundaries, signed extrema, and empty candidate lists.
• Both HamiltonianCircuit → augmentation → ILP → QUBO chains, comparing predicted and measured sizes and checking recovered witnesses on feasible and infeasible graphs.

Checks:

• Full workspace suite with examples and ignored tests: 6,896 passed.
• Focused augmentation suite: 84 passed.
• Formatting, workspace Clippy with all targets/features, and make paper: passed.
• LLVM coverage: 14/14 added executable production lines covered.
• CLI inspection, path prediction, reduction, solving, and recovered source evaluation: passed for both examples above.

Extreme-value tests verify metadata and ILP construction, not numerical solvability of every extreme instance by the backend.

Stack refresh

Merged the updated parent #1182, carrying the construction-derived bounds and validation fixes from #1174 through the stack. Preserved this PR's bounded ILP types, numeric-magnitude fields, and algorithms; no instance fixtures were added. The PR remains based on its immediate parent.

Validation of the updated head: make check passed (formatting, all-target/all-feature Clippy, and workspace tests including ignored tests). GitHub CI is restricted to PRs targeting main or develop, so these stack branches were checked locally.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (fix/flow-ilp-overhead@2841e0c). Learn more about missing BASE report.

Additional details and impacted files

@@                   Coverage Diff                    @@
##             fix/flow-ilp-overhead    #1183   +/-   ##
========================================================
  Coverage                         ?   96.76%           
========================================================
  Files                            ?     1072           
  Lines                            ?   140769           
  Branches                         ?        0           
========================================================
  Hits                             ?   136216           
  Misses                           ?     4553           
  Partials                         ?        0           

☔ View full report in Codecov by Harness.
📢 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[isPANN]

Merged to #1174.