Learn to Use X-WHAT

The Network Builder is an interactive canvas where the topology and the input data of the model are defined. The toolbar on the left holds the drawing tools, the panel on the right edits the properties of the selected element, and the top bar gives access to the project settings, the analysis mode, and the workflow roadmap.

1. Place the nodes

   Activate the Junction tool and click the canvas to place each junction. Use the Tank tool for reservoirs and tanks. Nodes receive a continuous numbering in the order of creation.

   Sketch the system on paper first and reproduce a similar layout on the canvas. A clean drawing makes the loops easier to trace and the results easier to interpret.

2. Connect the pipes

   Activate the Pipe tool, click the upstream node, then click the downstream node. The drawing order defines the positive flow direction of the pipe. To fix a pipe drawn backwards, select it and press Reverse Direction in the properties panel.

3. Edit the element properties

   With the Select tool, click any element and fill its fields in the right panel. Junctions take an elevation in meters and a demand in L/s, positive when water leaves the network at that node. Pipes take a length, a diameter, and the friction data of the chosen model, the roughness for Darcy-Weisbach or the coefficient C for Hazen-Williams.

   Tanks additionally take the head hr above the ground, the tower height hb, and the pump data, daily working hours, efficiency, and the head loss coefficient kp of the supply line.

4. Define the loops

   Activate the Loop tool and click, one by one, the pipes that close each loop, following the clockwise convention. Every independent loop of the network must be defined because the loops generate the energy balance matrix.

   Open Matrix Preview at the bottom of the screen to inspect the incidence matrices produced by the drawing. Checking them before the export saves a round trip to Excel.

5. Set the boundary conditions

   Every tank requires a fixed head. A junction with known pressure can also be fixed by ticking Fixed Head Node in its properties and typing the pressure head in meters.

6. Choose the analysis mode

   In the top bar, keep Mode: WFP / HSP for a hydraulic simulation or switch to Mode: DOM (Optimization) for a cost optimization. The mode is stored in the exported package and adjusts the guidance shown in the Roadmap.

7. Review the project settings

   Open Settings to define the global parameters, the friction method, the fluid properties, the energy price, the interest and energy increase rates, the demand factors, the wind data, and the pipe cost catalog. Default values suitable for a first run are already loaded.

8. Export the network package

   Press Export Network Package and keep the recommended .xwhat.xml format. The file carries the node table, the pipe geometry, both incidence matrices, and the global parameters, ready for the workbook import.

   Save JSON stores an editable copy of the drawing itself. Load it back later with Load JSON to continue the work where it stopped.

The Water Flow Problem determines the discharge and the direction of flow in every pipe of a network with known diameters and fixed tank heads. The Solver searches a flow vector that closes the mass balance at all nodes and the energy balance in all loops, with no objective function involved.

1. Open the workbook and enable macros

   Open X-WHAT_Model_V1.5.xlsm and click Enable Content in the security bar. The macro is used only by the import feature. The hydraulic model itself runs on regular worksheet formulas.

2. Import the network package

   Click Import Network and select the .xwhat.xml file exported from the Network Builder. The Memory, Mass_Balance, and Energy_Balance sheets are populated automatically.

   White cells receive user input and gray cells hold automatic calculations. After importing, sweep the white cells once to confirm the data arrived as expected.

3. Open the Solver

   Go to Data and click Solver. If the command is missing, enable the Solver Add-in following the FAQ at the bottom of this page.

4. Configure the Solver

   For a network with P links, N nodes, and L loops, the setup is

   Set Objective: leave blank (feasibility search) Changing Cells: Memory!AI50:AI(49+P) pipe discharges q Constraints: Memory!BE51:BE(50+N) = 0 mass balance residuals Memory!BH51:BH(50+L) = 0 energy balance residuals Method: GRG Nonlinear

   As a concrete example, the Huddleston (2004) tutorial network has 21 links, 14 nodes, and 8 loops, which gives the ranges AI50:AI70, BE51:BE64, and BH51:BH58.

   
   With a tutorial network loaded, the Roadmap window in the Network Builder prints the exact ranges for that case, so they can be copied straight into the Solver dialog.

5. Solve and verify the convergence

   Click Solve. When the Solver reports that all constraints are satisfied, accept the solution and inspect the flow column. Confirm that the residuals in BE and BH are effectively zero and that the flow directions are physically sensible.

   If the Solver stops before converging, run it again from the current values, or enable Multistart in the GRG options. Distant initial flow values are the most common cause of early stops.

6. Save the solved workbook

   Save with Ctrl + S. The saved file feeds the Results page, covered in Tutorial 4.

Design Optimization Modeling extends the simulation by letting the Solver adjust design variables, typically the tank water depths and tower heights, in search of the lowest total cost. The objective gathers pipelines, pumping energy in present value, tank material, and the foundation under wind loading, while every nodal pressure must stay inside the allowed band.

1. Prepare the network in DOM mode

   In the Network Builder, switch the selector to Mode: DOM (Optimization) before exporting. In this mode the tank heads and tower heights typed in the properties panel act as starting values, so give them reasonable initial estimates.

2. Complete the economic parameters

   A DOM run uses the full parameter set of the project settings, the energy price, the interest and energy increase rates, the lifespan, the demand factors, the tank material cost, the design wind speed with its exponent, and the pipe cost catalog. These fields map one to one onto the parameter block of the Memory sheet.

3. Import and audit the cost cells

   Import the package as in Tutorial 2 and check that the cost cells of the Memory sheet react to the imported parameters. The total cost in Memory!BT51 gathers the pipeline, pumping, tank material, and foundation components.

4. Configure the Solver

   Set Objective: Memory!BT51 (Min) total network cost Changing Cells: Memory!AI50:AI(49+P) pipe discharges q tank head cells (col AA) and tower heights (col T) Constraints: Memory!BE51:BE(50+N) = 0 mass balance residuals Memory!BH51:BH(50+L) = 0 energy balance residuals pressure heads (col BK) between p_min and p_max Method: GRG Nonlinear

   In the audited Huddleston (2004) DOM case, the changing cells are AI50:AI70, AA63, and T62:T63, with the pressures BK51:BK62 bounded between 10 and 30 m, the tank head above 5 m, and the tower heights between 0 and 39.5 m. The head of the second reservoir stays formula-linked 3.66 m above the first one.

   

5. Solve, restart, and compare

   The DOM problem is non-convex, so a single run may land on a local minimum. Solve several times from different starting points, or activate Multistart in the GRG options, record the objective of each run, and keep the best design.

   A useful benchmark is the standard design cost, obtained by running the same network in WFP mode with manually chosen tank depths. In the paper, the optimization of case (c) cut the total cost by 151,790 USD, about 9.8%.

6. Save the solved workbook

   Save the file and continue to Tutorial 4 to visualize the optimized design.

The Results page reads a solved workbook directly in the browser and mounts an interactive dashboard. The file is processed locally by the page, nothing is sent to a server.

1. Upload the solved workbook

   Drag the saved .xlsm or .xlsx file onto the upload area, or click Choose Solved Workbook and browse to it.

2. Read the flow diagram

   The Network Flow tab draws the network with the pipe width proportional to the flow magnitude. Blue pipes follow the drawn direction and red pipes carry reversed flow.

3. Check the node pressures

   The Node Pressures tab lists the head and the pressure at every node. Confirm that all values sit inside the design band, commonly 10 to 30 mH₂O for distribution networks.

4. Inspect the link flows

   The Link Flows tab tabulates each pipe with its length, diameter, discharge, direction, and cost, a convenient format for reports and for comparisons with EPANET.

5. Analyze the cost breakdown

   The Cost Breakdown tab splits the total cost into pipelines, pumping energy, tank material, and foundation. In DOM studies this chart is the natural place to compare candidate designs.

The workbook can also be filled entirely by hand, with no help from the Network Builder. This path suits the classroom especially well, because typing the incidence matrices consolidates the understanding of network topology. The workbook holds three sheets. Memory receives the parameters and the element tables, Mass_Balance receives the node incidence matrix, and Energy_Balance receives the loop incidence matrix.

1. Define the global parameters

   At the top of the Memory sheet, choose the head loss method, D-W for Darcy-Weisbach or H-W for Hazen-Williams, and type the number of links, nodes, and loops. These three counts size every table and matrix in the workbook. For a plain simulation, the counts and the fluid properties are enough. The remaining parameters serve the cost model in DOM runs.

   Parameter	Description
   ν	Kinematic viscosity of the fluid in m²/s
   ρ	Density of the fluid in kg/m³
   Links, Nodes, Loops	Totals of the network, they size all tables
   Pc	Energy price in USD/kWh
   ir	Annual increase rate of the energy price
   Years	Lifespan of the system in years
   Rate	Interest rate of the project
   α	Operational cost rate for maintenance and operation
   k1, k2	Day and hour demand factors
   Dtr	Duration to fill the reservoir, in days
   Material Cost	Tank material cost per square meter
   Vk, p	Design wind speed and wind profile exponent

2. Enter the node data

   For each node, type the ground elevation and select the type, Manhole or Reservoir/Tank. Type the demand in L/s, positive when water is withdrawn. Set the Fixed Head flag to 1 for nodes with a pressure boundary condition and type the pressure head. Every node marked as Reservoir/Tank requires a fixed head.

3. Enter the tank and pump data

   In the rows marked as Reservoir/Tank, type the bottom elevation, the height above the ground, and the pump data, daily working hours, efficiency, pump elevation, and the head loss coefficient of the supply line. The sheet then computes the pump flow, the manometric head, the power, and the daily and annual energy costs.

4. Enter the link data

   For each link, pick the upstream and downstream nodes from the dropdown lists and type the length and the internal diameter. The pipe cost is evaluated automatically by the fitted cost function. The flow column is the decision variable, so any initial guess can be typed there.

5. Fill the mass balance matrix

   In the Mass_Balance sheet, each row is a node and each column is a link. Type +1 where the pipe enters the node, -1 where the pipe leaves it, and 0 elsewhere. For instance, a node fed by pipe 20 that discharges through pipes 1 and 9 receives +1 in column 20 and -1 in columns 1 and 9, with zeros in the rest of the row.

6. Fill the energy balance matrix

   In the Energy_Balance sheet, each row is a loop and each column is a link. Type +1 when the pipe direction agrees with the clockwise circulation of the loop, -1 when it opposes it, and 0 when the pipe does not belong to the loop.

   The matrix dimensions follow the totals declared in step 1, so always define the counts first and the matrices last.

7. Run the Solver

   Follow Tutorial 2 for a simulation or Tutorial 3 for an optimization. The Solver setup is identical regardless of how the data entered the workbook.