LexFlow: Code, Benchmark Data, and Reproducible Results for Deterministic Lexicographic Flow Allocation on Lossy, Capacitated Rooted Trees

Description

This dataset and software package provides the reproducibility materials for a study of deterministic three-stage lexicographic flow allocation on lossy, capacitated rooted trees. It contains the Python implementation, mathematical model documentation, six deterministic benchmark instances, a scale-verification instance with up to 500 users and 1022 edges, automated tests, source tables, generated numerical results, and provenance metadata. The package also includes a bilingual Uzbek/English desktop graphical user interface based on the same computational core as the command-line analysis pipeline. The implementation verifies the closed-form Stage-1 max–min fairness value against a HiGHS linear-programming solution, checks the equivalence of the path operator and node-balance formulation using exact rational arithmetic, preserves higher-priority objectives through the three lexicographic stages, and minimizes temporal allocation variation at Stage 3. Five synthetic benchmarks isolate specific mathematical properties. The Gone Abat Jap benchmark is a deterministic controlled-scenario adaptation of openly cited input data and does not represent field calibration, historical scarcity validation, or operational performance. The results can be reproduced by installing the documented Python dependencies and running python main.py analysis. Mathematical and implementation checks can be executed with python -m pytest -p no:cacheprovider. The private manuscript, licensed journal template, and internal review files are not included in this public package.

Steps to reproduce

1. Download the complete LexFlow_v0.4.1 dataset without changing the directory structure or filenames. Work from the package root containing main.py, pyproject.toml, requirements-lock.txt, Data/, src/, tests/, and results/. 2. Use Python 3.11 or newer. The reference results were generated with CPython 3.13.5. Create an isolated environment and install the audited dependency versions. On Windows PowerShell, run: python -m venv my-env my-env\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -r requirements-lock.txt python -m pip install -e . --no-deps On macOS or Linux, activate the environment with: source my-env/bin/activate 3. Before execution, the integrity of the deposited files may be checked against checksums_sha256.txt. Input variables and output fields are defined in DATA_DICTIONARY.md. The mathematical stages, verification gates, solver tolerances, and acceptance criteria are specified in Model/EXACT_EXPERIMENT_PROTOCOL.md and Model/IMPLEMENTATION_SPEC.md. 4. Regenerate the numerical results, machine-readable tables, Excel mirrors, and publication figures by running: python main.py analysis The pipeline loads and validates the deterministic rooted-tree JSON benchmarks, constructs the path-loss and capacity constraints, solves the three lexicographic stages sequentially, checks the Stage-1 closed-form value against the HiGHS linear-programming solution, verifies the path-operator/node-balance equivalence, and writes the results under results/. 5. Run the complete automated verification suite: python -m pytest -p no:cacheprovider 6. A successful reproduction must report "verification_status": "PASS" in results/RESULTS_SUMMARY.json, with every verification gate equal to true. The regenerated CSV and JSON numerical outputs should agree with the deposited results. Exact rational quantities must agree exactly, while floating-point LP comparisons must satisfy the tolerances declared in the experiment protocol. Environment-dependent entries in results/manifests/run_manifest.json, such as the UTC generation time, platform, and Python version, may differ. 7. The optional bilingual desktop interface can be started with: python main.py gui Select Uzbek or English in the GUI. Both language interfaces and the command-line workflow use the same computational solver. The benchmarks are deterministic controlled scenarios. The results provide mathematical and computational verification and should not be interpreted as field calibration, historical scarcity validation, or operational validation of a particular irrigation system.

Institutions

• Karakalpak State University

  Karakalpakstan, Nukus
• National University of Uzbekistan

  Tashkent, Tashkent
• Tashkent Institute of Irrigation and Agricultural Mechanization Engineers

  Tashkent, Tashkent

Categories

Related Links

Licence