AppliedMath LexFlow: Deterministic Lexicographic Flow Allocation on Lossy Capacitated Trees

Abstract

Exact, reproducible software for deterministic lexicographic flow allocation on lossy, capacitated rooted trees, and for the inverse rehabilitation-design problem posed on the same model. The allocation module implements the three-stage lexicographic model of the AppliedMath article Three-Stage Lexicographic Allocation on Directed Irrigation Trees with Conveyance Losses and Capacity Constraints: A Closed-Form Stage-1 Fairness Guarantee and Operator–Balance Equivalence: the closed-form Stage-1 bottleneck value, the loss-aware net-to-gross operator and its node–balance equivalent, the weighted Stage-2 and smoothing Stage-3 linear programs, the exact progressive-filling leximin selector, the invariant variation range and the price of fairness. It ships the five exact rational benchmarks, the 36-node, 16-period Gone Abat Jap controlled scenario, the deterministic scaling generator up to 500 users and 1022 edges, and the scripts that regenerate every published table and figure. The design module implements the inverse problem behind the conference paper Bottleneck-Targeted Rehabilitation Planning for Lossy Irrigation Canal Networks: An Exact Guarantee–Budget Curve: the closed-form minimum-cost widening plan and its budget function, the epsilon-bottleneck-set ascent for lining, and exact-rational relief sets and minimum-cost transversals with a laminarity certificate. Version 0.5.0 added bench/scale_timing.py, which measures the runtime and peak working memory of the closed-form Stage-1 evaluation against the equivalent sparse HiGHS linear program, and revised the published figures following peer review. Version 0.5.1 adds bench/robustness_suite.py, a randomized suite of 200 instances in seven families that re-evaluates every acceptance gate outside the fixed benchmark construction, and bench/weight_sweep.py, which sweeps the Stage-2 service weights geometrically and applies three auditable weighting rules to the controlled canal scenario. It also redraws the surveyed canal network as the linear canal scheme used by the operating organisation, with every offtake on the bank from which it actually takes water. Version 0.5.2 answers the second report of the third reviewer. The randomized suite now has 400 instances in ten families, 200 of them with source and reach capacities drawn independently of the loads; on every instance the bottleneck named by the closed form is confirmed by the Stage-1 linear program alone, and the suite records whether the Stage-2 optimum is unique and whether Stage 3 changes the allocation. New modules compare the hierarchy with total-delivery maximization, equal proportional allocation, a weighted single objective and full leximin (comparison.py), solve Stage 3 with four smoothness criteria and block-specific variation limits (smoothing.py), perturb demands, efficiencies and capacities of the controlled scenario (perturbation.py, bench/perturbation.py) and apply five weighting rules with per-block winners and losers (weights.py). bench/scale_timing.py now times each phase separately in 30 runs and records the environment. Data/README.md states, for every shipped instance, which parameters come from the published Gone Abat Jap dataset (doi:10.17632/xt3gsf89n9.1) and which were imposed by the authors, and Data/design/ holds the scripts that re-derive every imposed parameter from the rule stated in the article; the test suite requires them to reproduce the shipped instance files exactly. All arithmetic on the small benchmarks is exact rational; inputs, outputs and the environment carry SHA-256 hashes.