User documentation

1. Overview

EPANetLab lets you draw a water distribution network on a real map, set the properties of every element, run a steady-state hydraulic simulation, and see the results color-coded across the map.

Key capabilities

• Draw and edit junctions, pipes, tanks, reservoirs, pumps, valves, meters and demand centers on a MapLibre map.
• Import shapefiles, DXF drawings, and CSV junction lists as editable models.
• Import terrain (TREX / LandXML / DXF) to auto-assign ground elevations.
• Run the EPANET 2.2 steady-state solver in-browser via a Web Worker.
• Visualize pressure (node circles) and flow (link colors) with legends.
• Edit element properties and results in a spreadsheet-style Flex Table.
• Save projects to browser storage, or sign in to sync them to the cloud.
• Export EPANET .inp, project JSON, and node-position CSV.
• Control nearly everything from an AutoCAD-style command line.
• Use an optional AI assistant (free, no key needed) to build, edit, and analyze the model.
• Switch units (SI / US), basemaps (Streets / Satellite / Blank), themes, and label overlays.

What it is not

• EPANetLab runs steady-state analysis only — no extended-period (time-series) simulation yet.
• Results are not stamped or sealed; the tool is not a substitute for engineer review and sign-off.
• No model data is uploaded for ordinary use; the AI assistant talks only to the provider you choose.

2. Quick Start — first network in 60 seconds

1. Open app.epanetlab.com.
2. On the Layout toolbar, click Reservoir and place it on the map.
3. Click Junction and place 3–4 junctions in a line downhill from the reservoir.
4. Click Pipe, then click the reservoir and each junction in turn (a chained run). Press Esc once to finish the run.
5. Click Run (top-right). The map fills with colored results.
6. Open the right-hand Results panel to see min/max pressure, total demand, peak flow, and peak velocity.

The default pipe diameter is 75 mm (SI) or 3 in (US); default roughness is Hazen-Williams C. Change any of these in the Properties panel.

3. Interface Tour

Toolbar (top)

Three tabs — Layout, Project, View — plus a right-side group that is always visible: the AI assistant toggle, Run, and Clear network.

Left panel (Properties / Backgrounds / Symbology / Flex Table)

Switched with the four-icon rail on the far left:Properties (network summary or the selected element's form, plus its simulation results), Backgrounds (non-editable reference layers), Symbology(annotation toggles and pipe color ranges), and Flex Table (all elements in a spreadsheet). At most one panel is open at a time; on small screens they become overlays.

Results panel (right)

Summary cards, pressure legend, simulation status, and Clear results.

Map area

Interactive map with the floating Search box (top-left) and theCommand Line (bottom).

Status bar (bottom)

Current tool, node/link counts, terrain name, ruler readout, selection count, and shortcut hints.

4. Drawing Tools (Layout tab)

Pipes: in the default chain mode, each click places a new junction and chains a pipe to it. Press Esc once to end a run; twice returns to Select. Pipe bends are shown as drag handles; use the BEND, REMOVEBEND, andFLATTEN commands to manage bend vertices.

Snapping: clicks near an existing node snap to it automatically, so pipes connect cleanly and duplicate nodes merge.

5. Setting Properties

Select an element on the map and edit it in the Properties panel:

Values are typed in the units set in the View tab (SI or US) and converted internally. Element IDs use friendly prefixes (J-, M-, DC-, T-, R-, P-, PU-, V-) with incrementing numbers.

6. Hydraulic Simulation

Click Run (top-right) to run a steady-state analysis. The solver has a 30-second timeout; a network needs at least one reservoir or tank and at least one pipe.

Results you get

• Per node: pressure, head, demand (negative demand = inflow at the source).
• Per link: flow, velocity, head loss.
• Results panel cards: Min pressure, Max pressure, Total demand, Peak flow, Peak velocity.
• Status: Ready / Running / Converged / warnings / error; the raw solver report is captured internally.

Map visualization

• Junction colors encode pressure: <20 red, 20–40 orange, 40–70 yellow, 70–100 green, >100 blue.
• Link colors encode flow magnitude (5-step blue ramp).
• Optional thematic pipe coloring (Symbology tab) tints pipes by diameter, velocity, flow, or head loss against user-defined color ranges — otherwise pipes stay kind-colored (blue) or flow-colored after a run.
• Node IDs appear from zoom 14; link IDs from zoom 15.

Reading the results

"Simulation completed with warnings" — a banner appears; open the report or inspect low-pressure nodes. Use the Results panel legend to judge whether pressures fall in an acceptable service range for the scenario being studied.

7. Flex Table (spreadsheet editing)

Open the Flex Table from the left rail. It has tabs forJunctions, Tanks, Reservoirs, Pipes, Pumps, Valves.

• Click any value cell to edit inline.
• Enter / ↓ moves down; Esc cancels.
• Columns show geometry and results (Pipes: Length, Diameter, Roughness C, Flow, Velocity — Junctions: Elevation, Demand, Pressure, Longitude, Latitude).
• Sort any column by its header; use the "Filter rows…" box to find elements.
• Double-click a row to zoom to that element; Shift/Ctrl for multi-select.
• If a terrain surface is loaded, an "Apply elevations" action appears.

8. Import & Positioning

All imports live on the Project tab.

Positioning dialog

Files already in WGS84 lat/lon — shapefiles with a .prj, and KML/KMZ (which are always lon/lat by the Google Earth spec) — import directly and are framed. Projected files (unitless DXF, shapefiles without a .prj, or KML from engineering tools that emit meters) open the Position file dialog: choose a UTM zone 1–60 (or "Use current map location"), hemisphere, and units; then import. Terrain adds a "Fit to network" option and an Apply elevations step later.

You don't have to guess the zone when exporting: EPANetLab derives the zone your drawing sits in, shows it in the status bar (e.g. UTM 43N), and writes the drawing as real UTM meters with that zone tagged in the DXF header. Import that DXF back — even in a fresh session — and the dialog is pre-filled with the zone the file declares, so a network you export here re-imports exactly where it was.

The same commands work from the command line: DXFIN imports a drawing andKMLIN imports a KML/KMZ layout.

Background layers (non-editable)

From the Backgrounds panel you can also add shapefile / DXF layers strictly as reference (water mains, cadastral maps). Each layer has show/hide, a color picker, opacity, zoom-to-layer, and remove. Polygons from imports become ring outlines.

Importing an EPANET .inp file is not yet supported (.inp is generated internally for the solver and available for export). Use a shapefile, DXF, or CSV, or re-draw.

9. Export

EPANET .inp

Project → Export EPANET .inp downloads epanetlab.inp, honoring your unit system (flow keyword LPS for SI, CFS for US). Meters are exported as standard junctions; demand centers are allocated to the nearest pipe end junctions.

Project JSON

Export saves the full project (nodes, links, basemap, backgrounds, units) as a shareable JSON snapshot you can re-import later. Terrain surfaces are not included.

Node positions CSV

Exports Label, X, Y, Type, Elevation_m, Demand_LPS — designed to bring node positions into AutoCAD for labeling.

CAD drawing (DXF)

Export CAD (DXF) in the toolbar — or the DXFOUT command — downloads a DXF R12 drawing in meters. Junctions become POINTs, tanks and reservoirsCIRCLEs, and pipes/pumps/valves LINEs on their own layers. The annotation toggles from the Symbology tab control the TEXT entities: pipe labels ("D 6.0 mm", "L 100.0 m", flow, velocity, head loss) sit at each pipe's midpoint, junction labels/elevation/pressure/demand at each node, each property on its ownANN.* layer. When thematic pipe coloring is active, pipe lines are tinted to the nearest CAD color.

Google Earth (KML / KMZ)

Export KML in the toolbar — or KMLOUT / KMZOUT — downloads the layout as a standard lon/lat .kml (or a zipped.kmz). Every node becomes a Point placemark and every link aLineString placemark. Each placemark's description carries the same annotation text the map shows, and thematic pipe ranges set the line colors — handy for reviewing the model in Google Earth or sharing a layout with non-Hydraulic viewers.

GIS shapefile (SHPIN / SHPOUT)

Export shapefile — the SHPOUT command (or the Export menu) — downloads a zipped pair of ESRI shapefiles: …_points (junctions, meters, demand centers, tanks, reservoirs) and …_lines (pipes — bends become multi-vertex polylines — plus pumps and valves). Each set ships its .shx index, a .dbfattribute table (type, label, and for lines from/to node tags, diameter, length, roughness, and pump power / valve setting), and a .prj written for the network's UTM zone. The coordinates are real easting/northing — the same meter frame as the DXF export — so the layout lands at its true position in QGIS / ArcGIS / AutoCAD Map 3D.

Import shapefile — the toolbar button or SHPIN — accepts a.zip or the .shp/.dbf/.shx/.prj set. When a .prj is present the coordinates are reprojected to lon/lat and placed automatically; a bare.shp without one opens the positioning dialog. A zip from SHPOUTre-imports exactly where it was exported.

10. Save, Load & Cloud Sync

• Autosave: your working session is continuously saved (500 ms debounce, also flushed when you leave the tab) and restored on the next open.
• Named projects: Save prompts for a name; Load lists them; delete from the list. Stored in browser storage.
• Cloud sync: sign in to sync projects to the cloud (Supabase + PostGIS) — Load then merges local and cloud projects.

Signing in

1. Click ☁ Sign in in the toolbar.
2. Enter your email — you receive a 6-digit code / magic link (no password).
3. Signed-in state shows as ☁ your-email; click it to sign out.

Cloud sync is optional; all drawing, simulation, and local save work without an account. Synced networks also enable spatial queries for the AI assistant.

11. Views & Appearance

• Basemaps (View tab): Streets (OSM), Satellite (Esri imagery), or Blank.
• Place-name labels overlay: an optional label layer above the basemap but under the network.
• Units: SI (m, mm, cumec) or US (ft, in, cusec, psi). Stored internally as SI, converted for display; applies to drawing, properties, results, and .inp export.
• Themes: Light / Dark / Auto (system), plus 9 accent presets or a custom color. Persisted and applied before first paint to avoid flashing.

Symbology panel (WaterGEMS-style)

The Symbology panel (fourth icon on the left rail) controls what the map labels and how pipes are colored:

• Pipe annotations: diameter, length, flow, velocity, head loss — each a toggle. Simulation-dependent ones need a completed run.
• Junction annotations: label, elevation, pressure, demand — again all toggles.
• Pipe color by range: pick a property (diameter, length, roughness, velocity, flow, head loss) and define min/max/color bands, like "3 in → blue, 4 in → green, 6 in → yellow". Values outside every band use the "Outside ranges" color.
• Junction color by range: the same for nodes — color them by elevation, pressure, demand, or head over min/max/color bands. This takes over from the automatic pressure gradient, so you see exactly the ranges you defined.
• Auto ranges: instead of typing bands by hand, choose a class count (3–6) and press Auto — the network is split into equal-count classes across the chosen property, with the standard blue→green→yellow→orange→red ramp. A swatch legend under the ranges shows each band and its value, in the current unit system.

The same toggles and color ranges drive the DXF and KML exports, so a drafting sheet or Google Earth file shows exactly the labels and colors you see on screen. A junction theme also puts nodes on a separate JUNCTIONS-THEMED DXF layer so themed elements can be styled or frozen independently in CAD.

12. Searching for Places

Use the Search box (top-left, "Search places (powered by OSM)"). Type a place name, press Enter, and pick one of up to 6 results — the map flies to it. This uses the public OpenStreetMap Nominatim geocoder. The Flex Table has its own "Filter rows…" box for finding elements.

13. The Command Line

An AutoCAD-style prompt sits at the bottom of the map. Press any character (or /) to start typing; Enter runs, ↑ / ↓ scrolls suggestions and history,Tab completes, Esc exits.

Space repeats the last command (AutoCAD behavior); typing most keys opens the command line.

14. Keyboard Shortcuts

Undo history holds up to 50 steps of node + link snapshots.

15. AI Assistant

The chat panel (toolbar chat icon) is an AI modelling copilot. By default it uses EPANetLab free (hosted) mode: no key required — messages are routed through a small server-side proxy holding a shared app-level Gemini key, with a limited daily quota. You can also bring your own key with any other provider.

Providers

• EPANetLab free (hosted) — default; no key required.
• Google Gemini (free tier) — free key from AI Studio.
• OpenRouter (free models) — auto-selects a current free model.
• Ollama (local, no key) — run models on your machine.
• LM Studio (local, no key)
• OpenAI (paid)
• Anthropic Claude (paid)
• Custom OpenAI-compatible — any endpoint (vLLM, LiteLLM, Together, DeepSeek…)

What it can do

• Summarize the current model and its simulation status.
• Build a network (add junctions, tanks, reservoirs, pipes, pumps, valves).
• Edit or delete elements and set properties.
• Run the simulation and interpret results (e.g. "which nodes have low pressure?").
• Run spatial queries against your synced network (elements within a radius, network length within a region).

Try the four example prompts shown in the empty chat. The chat digests the current model automatically, so answers stay grounded in your actual network.

16. Privacy

• The app is private and not open source; the repository is not distributed.
• Drawing, simulation, and saving happen on your device. Autosave and named projects stay in browser storage.
• Basic page-usage analytics (Google Analytics) collect only visit statistics for the site owner; no model data is transmitted.
• Optional email sign-in (magic-link, no password) enables cloud sync via Supabase.
• In EPANetLab free (hosted) chat mode, messages pass through a minimal proxy with a shared app-level key; no personal key is used. With any other provider, keys never leave your browser.

17. FAQ & Troubleshooting

The simulation won't run.

You need at least one reservoir or tank and at least one pipe. An alert appears if either is missing.

"Simulation completed with warnings."

Check the results panel and inspect low-pressure nodes (red) or high velocities. The solver report text is captured internally.

My imported drawing is in the wrong place.

Un-projected files cannot be positioned automatically — use the Positioning dialog (UTM zone / hemisphere / units) or "Use current map location", then drag on the map.

Where did my project go?

Autosave restores your last working session. Named projects are under Load; cloud copies appear there too when signed in.

How do I label nodes in AutoCAD?

Export node positions CSV, or export a DXF (DXFOUT / Export CAD button): it carries annotation text (diameter, length, elevation…) on separate ANN.* layers you can style or freeze.

Can I share the layout with Google Earth?

Yes — KMLOUT / KMZOUT (or Export KML) writes every node and pipe as a placemark with label text and themed colors.

Can I import an .inp file?

Not yet — export is supported; import is planned.

Why is pressure shown in meters rather than psi?

Result units follow the View tab unit system (SI vs US).

18. Getting Help & Roadmap

• Live app: app.epanetlab.com
• Website: epanetlab.com

Export and import, GIS data handling, terrain elevations, and AI-assisted modeling are the fastest-moving areas — check the website for what ships next. For professional, supported, production water-distribution modeling, consider commercial products built on the same toolkit (epanetjs.com).