X-WHAT

X-WHAT is an open-source Excel and WebGUI workflow for steady-state analysis and preliminary design optimization of looped water distribution networks. The repository combines the Excel engine, browser tools for network preparation and result inspection, a printable user manual, the manual source, and the reference preprint that documents the formulation and validation.

Quick links

• Live site: https://marcusnobrega-eng.github.io/X-WHAT/
• Project description: https://marcusnobrega-eng.github.io/X-WHAT/description.html
• User manual (HTML): https://marcusnobrega-eng.github.io/X-WHAT/manual.html
• User manual (PDF): https://marcusnobrega-eng.github.io/X-WHAT/Docs/X-WHAT_User_Manual.pdf
• Theoretical framework: https://marcusnobrega-eng.github.io/X-WHAT/theory.html
• Reference preprint: https://arxiv.org/abs/2405.09044

What the current release does

• Water Flow Problem (WFP/HSP): solves steady-state pipe discharges and flow directions by enforcing mass conservation at nodes and energy conservation in loops.
• Design Optimization Modeling (DOM): adjusts tank water depth and tower elevation while enforcing nodal pressure limits.
• Browser workflow: prepares network inputs in the Network Builder, exports versioned .xwhat.xml packages, and reads solved workbooks in the Results viewer.
• Transparent workbook: keeps the equations, tables, and constraints visible in X-WHAT_Model_V1.5.xlsm.

Typical workflow

1. Draw the network in canvas.html, or load a tutorial case.
2. Export the versioned .xwhat.xml package.
3. Import the package into X-WHAT_Model_V1.5.xlsm.
4. Run Excel's GRG Nonlinear solver for WFP/HSP or DOM.
5. Save the solved workbook and upload it to results.html.

Intended use

• Teaching looped water-distribution-network concepts.
• Reproducible screening and worked examples.
• Preliminary design comparison for small to medium steady-state systems.
• Inspection of the governing equations in a visible spreadsheet environment.

Current limitations

• The current formulation is steady-state only. It does not represent transients, water age, leakage, pressure-dependent demand, or extended-period storage dynamics.
• Pumps and control valves located inside loops are outside the current Excel implementation.
• Pipe diameters are treated as user-selected inputs, not optimization variables, in the shipped workbook.
• Excel's GRG solver is local and gradient-based, so convergence depends on initialization, scaling, and constraint conditioning.
• Cost coefficients are suitable for preliminary comparison and should be recalibrated before project-specific professional use.

Repository layout

• index.html: project landing page.
• description.html: direct summary of scope, workflow, validation, and limitations.
• manual.html: step-by-step online manual.
• theory.html: governing equations, cost model, validation notes, and preprint links.
• canvas.html: browser-based network builder.
• results.html: browser-based results viewer for solved workbooks.
• Docs/: printable manual and public preprint.
• Images/: logos and static figures used by the site.
• Videos/: narrated tutorials and supporting poster assets.
• manual-source/: LaTeX source for the manual.
• X-WHAT_Model_V1.5.xlsm: Excel engine used for hydraulic simulation and design runs.

Validation summary

The public materials report validation against EPANET and published reference cases for three networks of increasing complexity. In the reported design-optimization case study for the largest tutorial network, the optimized configuration reduced total cost by 151,790 USD, about 9.8% relative to the standard design used in the paper.

Citation

If you use X-WHAT in teaching, analysis, or research, please cite the project paper:

@article{gomes2024xwhat,
  title   = {Modeling and Design Optimization of Looped Water Distribution Networks using MS Excel: Developing the Open-Source X-WHAT Model},
  author  = {Gomes Jr., Marcus N. and Benites, Igor M. and Elsherif, Salma M. and Taha, Ahmad F. and Giacomoni, Marcio H.},
  journal = {arXiv preprint arXiv:2405.09044},
  year    = {2024},
  doi     = {10.48550/arXiv.2405.09044},
  url     = {https://arxiv.org/abs/2405.09044}
}

Authors

• Marcus N. Gomes Jr.
• Igor M. Benites
• Salma M. Elsherif
• Ahmad F. Taha
• Marcio H. Giacomoni

License

This repository is released under the MIT License. See LICENSE.