Build a model from GIS

This is the first of the three jobs people arrive with. You have GIS layers of the network, and no hydraulic model. The layers are pipes, and usually some point layers for valves, pumps, tanks and reservoirs. The model builder takes those layers, works out the topology from the geometry, and gives back an epanet-js project you can run.

If instead you already have an INP or a project file, go to Open an existing model. If you have a model and want to test changes against it, go to Scenario work.

A recorded walkthrough shows the whole job on real utility data: GIS to EPANET tutorial: Building the Rosebery water model with epanet-js. It runs about 25 minutes. The written version of the same build is Worked example: Rosebery.

What you need

You need an account on the Pro or Teams plan. On one of those plans, two entries open the builder straight away: Import from GIS on the welcome dialog, and File > New project > From GIS data.

On any other plan, the same entries open Choose your model builder first. That dialog offers Upgrade on one side and Continue with Legacy on the other. A guest is treated as a free plan. See Plans.

The legacy builder is not this page

Continue with Legacy opens a different app, the one that the builder replaced. That dialog marks it Maintenance only, and lists what it costs you: no Pipe year and materials, WGS 84 output rather than your own projection, English only, and no Custom attributes. If you get to it while signed out, Early access feature and Get early access appear first. This page does not describe that app. Every step, every label and every frame here is the builder that the Pro and Teams plans open.

You need your layers as GeoJSON or Shapefile. The dropzone reads Supports Shapefiles, GeoJSON, and ZIP archives. You can drop a Shapefile as its loose parts. The .shp, .dbf, .prj and .cpg files regroup into one entry. An entry with no .shp yet waits, and shows Waiting for .shp (base geometry).

A .zip can hold either kind, or a whole folder of layers. The builder expands archives in the browser, flattens folders to their file names, and reads one level of nested zip. Two layers with the same file name in different folders collide, so rename one before you zip them. The builder reports anything it cannot read as a single ignored-files summary, not as one error per file.

Note

The builder starts a blank project first. If the project you have open has unsaved changes, Unsaved changes appears before the builder. It offers Save and continue and Discard changes.

What the builder works out for itself

Most of the preparation people expect to do by hand is unnecessary here. Knowing which parts are unnecessary is most of the work of a clean build.

• Connectivity is derived, not read. There are no from-node and to-node fields to map. The builder creates a node at each end of every pipe, and at every point in the layers you assign. It merges points within about 0.1 m of one another into a single node. That tolerance is the one number to know before you start. Pipe ends that must connect have to coincide in the data, because a gap wider than 0.1 m leaves two nodes and a break in the network.
• Points split pipes. A point that lies on a pipe splits it. A tank, reservoir, valve or pump digitized on a main becomes a node on that main, with the pipe split on each side of it.
• Valves and pumps become links. EPANET needs a valve or a pump to be a link between two nodes, and your data has them as points. The builder converts each one into a short link, and shortens the pipe it sits on to make room. These are the Converting nodes to links and Expanding short links stages of the build.
• Lengths are measured, not mapped. Pipe length comes from the geometry, in meters or in feet according to the flow units you chose. The builder deletes pipes that end up with no length, at Removing zero-length pipes.
• Elevations are fetched. Where the geometry carries a Z value, the builder uses it. Otherwise it reads node elevations from a terrain service, at Getting elevations. A node that the service cannot answer for is left without an elevation, not set to zero, because zero is sea level. The build warns you with a count of these nodes. See Elevations for how to compute them again afterwards.
• Nothing unmapped is invented. An attribute you leave unmapped is imported empty, except for the few rows whose selector reads Use default value. An unmapped reservoir Head, tank level or diameter arrives blank, not as a placeholder. Once the model opens, the Model attributes check in Network review reports the blanks.
• Identifiers come from your data or from the builder. If your data has an identifier, map that property to ID. The builder then makes duplicates unique with a suffix. If you leave the row on Auto-generate, the builder numbers by type instead: J1, J2 for junctions, and R, T, P, V and PU for reservoirs, tanks, pipes, valves and pumps. Your choice becomes the asset’s label in the app.

Projection

The builder reads the projection from the data, file by file. It reads the .prj of a Shapefile, or a CRS declared on the GeoJSON. Coordinates that are already latitude and longitude need nothing, even when you drop that file with projected layers. A WGS 84 layer rides along as it is, because each file is reprojected, or left alone, on its own.

If the builder cannot identify the system of projected coordinates, Projection required appears. Until you choose one from the list, the dropzone does not let you assign anything. It says Select a projection to continue mapping files, and the footer warns Projection required to continue. You can search by code or by name. The hint suggests 27700 or British National Grid.

The projection you choose is written into the project. The model then comes into the app in your own coordinate system, rather than in WGS 84. See Projections.

The four steps

The frames that follow come from one real build: the watermains, tank and water treatment works of Rosebery, in Tasmania. That build is written up in full as Worked example: Rosebery.

1. Model settings

   Unit system switches between US customary and SI metric. Your choice sets the list that Flow units offers. Headloss formula chooses between Hazen-Williams, Darcy-Weisbach and Chezy-Manning.

   These settings decide the units of every later step, including the units that your diameters and levels are assumed to be in. Set them before you load anything. The panel beside them holds the Model builder tutorial video.

   

2. Data assignment

   Drop your files. Then assign each one to an element with Assign to element…. The six elements are Pipes, Junctions, Valves, Pumps, Tanks and Reservoirs. Pipes take line geometry, and the other five take points. A file whose geometry does not fit an element is not offered for it.

   Each element takes exactly one file, and an element that already has one is no longer offered. A file that has no element left to go to reads No compatible, unassigned elements. Unassigning returns a file to the unassigned list unchanged.

   The pipe layer is the one the build works from, and it is the only one the builder truly needs. Junctions are created at pipe ends, with or without a junction layer. Assign a junction layer when your junction attributes matter, or when there are nodes that no pipe end lands on.

   Network preview draws what you assigned, as you go. A wrong projection shows at once as a network in the wrong place, or at the wrong scale. Clear projection unassigns everything and starts that choice again.

   

3. Attribute mapping

   Each assigned element gets one tab, with the feature count beside its name. Each tab has two columns: Recommended attributes and Optional attributes. For each row, choose the property from your data that holds it.

   

   What is recommended differs by element:

   • Pipes ask for ID and Diameter. Minor loss, Status, Material, Year of installation and Roughness are optional.
   • Valves ask for ID, Diameter, Type and Setting.
   • Tanks ask for ID, Initial level, Min level, Max level and Diameter. Min volume is optional.
   • Junctions, pumps and reservoirs ask only for ID. Status is optional on pumps, and Head on reservoirs.

   

   Leaving a row unmapped is a decision, and the selector says which decision it is. It reads Auto-generate on an ID, and Use default value where the builder has a default for that row. Where it has no default, it reads Empty, which is what pipe Roughness shows. A row offers the list of columns in that layer, not the values in them. The values are in Data preview, under the mapping.

   

   Custom attributes on each tab takes any number of further properties, and carries them into the model as they are. A material class, an asset reference or a survey date survives the build this way. See Custom attributes.

   Data preview under the mapping shows the first 100 features as they will be imported, with defaulted values in italics. It also shows bad values. A year, a status, a valve type or a valve setting that the builder cannot read is flagged there, with what it will be imported as instead. Fix those values in the source data, or map a different property. Do not leave them to be found later.

   Build model on the last tab starts the build.

4. Model build

   Build progress lists each stage as it completes, with its duration. Nothing here needs an answer from you. The warnings are what to read. An elevation warning names how many nodes went unresolved, and why. Either the terrain service could not be reached, or it has no data for that area.

   A build that warns waits for you, and does not close over the message. After you read the warning, press Open model. A build that does not warn hands the model to the app by itself.

   

   A build that fails ends on Build error with the message, and Show more expands it. Back returns to the mapping, with everything you set still in place.

What you get

The model opens in the app as an unsaved project, named after the build. Network Review opens beside it without being asked, because a new model is where its checks earn their keep. Orphan assets and Connectivity trace show where the 0.1 m tolerance left real breaks in the network.

Save the model before anything else. Save writes an .ejsdb project file to a location you choose. Until then, the model exists only in the browser. See Projects.

Then add the operational data that the GIS did not have. A built model arrives with geometry, connectivity, elevations and the attributes you mapped, and nothing else. There is no demand to map, no pump curve, no pattern and no control. The simulation duration is zero, which is a single-period run.

• Demands, one junction at a time or in bulk — see Junctions and demands and Data tables. A service-point layer gives them too — see Customer points.
• Pump duty points — see Pumps and Curves.
• Patterns and Controls. Then set a duration in Simulation settings to make it an extended-period run.
• When the review is clean, press Simulate. See Running a simulation.

Next

• Network review — the five checks, and which ones block a run.
• The interface — where everything is in the window you now see.
• Drawing and editing — how to fix the breaks the review finds.
• Projections — how to change the projection after the build.
• Plans — what the Pro and Teams plans include.