Skip to main content

Complete EPANET Input File (*.inp) Format Specification

Overview​

This document provides a comprehensive specification of the EPANET input file format (*.inp) based on analysis of the EPANET 2.3 source code, documentation, and example files. EPANET input files are organized into sections, each beginning with a keyword enclosed in brackets [SECTION_NAME].

File Structure​

  • Comments: Lines starting with ; or text after ; on data lines
  • Blank lines: Can appear anywhere
  • Maximum line length: 1024 characters
  • ID labels: Up to 31 characters and numbers for nodes, links, curves, and patterns
  • Section order: Not important, but network components should be defined before being referenced

Complete Section Reference​

1. [TITLE] - Project Title​

Purpose: Attaches descriptive title to the network Format: Up to 3 lines of text, max 79 characters each Data Type: String Required: No

Example:

[TITLE]
EPANET Example Network 1
A simple example of modeling chlorine decay

2. [JUNCTIONS] - Junction Nodes​

Purpose: Defines junction nodes in the network Format: One line per junction Required: Yes (at least one junction required)

Fields:

  • ID: Junction identifier (string, max 31 chars)
  • Elevation: Node elevation in ft (m) (float)
  • Demand: Base demand flow in flow units (float, optional)
  • Pattern: Demand pattern ID (string, optional)

Data Types: String, Float, Float, String

Example:

[JUNCTIONS]
;ID    Elev.   Demand   Pattern
J1     100     50       Pat1
J2     120     10              ;Uses default pattern
J3     115                      ;No demand

3. [RESERVOIRS] - Reservoir Nodes​

Purpose: Defines reservoir nodes (constant head sources) Format: One line per reservoir Required: At least one reservoir or tank required

Fields:

  • ID: Reservoir identifier (string)
  • Head: Hydraulic head in ft (m) (float)
  • Pattern: Head pattern ID (string, optional)

Data Types: String, Float, String

Example:

[RESERVOIRS]
;ID    Head      Pattern
R1     512               ;Constant head
R2     120      Pat1     ;Variable head

4. [TANKS] - Tank Nodes​

Purpose: Defines storage tank nodes Format: One line per tank Required: At least one tank or reservoir required

Fields:

  • ID: Tank identifier (string)
  • Elevation: Bottom elevation in ft (m) (float)
  • InitLevel: Initial water level in ft (m) (float)
  • MinLevel: Minimum water level in ft (m) (float)
  • MaxLevel: Maximum water level in ft (m) (float)
  • Diameter: Nominal diameter in ft (m) (float)
  • MinVol: Minimum volume in cubic ft (m³) (float)
  • VolCurve: Volume curve ID (string, optional)
  • Overflow: Overflow indicator YES/NO (string, optional)

Data Types: String, Float, Float, Float, Float, Float, Float, String, String

Example:

[TANKS]
;ID   Elev.  InitLvl  MinLvl  MaxLvl  Diam  MinVol  VolCurve  Overflow
T1    100    15       5       25      120   0       *         YES
T2    100    15       5       25      1     0       VC1

5. [PIPES] - Pipe Links​

Purpose: Defines pipe links in the network Format: One line per pipe Required: No (but network needs links)

Fields:

  • ID: Pipe identifier (string)
  • Node1: Start node ID (string)
  • Node2: End node ID (string)
  • Length: Length in ft (m) (float)
  • Diameter: Diameter in inches (mm) (float)
  • Roughness: Roughness coefficient (float)
  • MinorLoss: Minor loss coefficient (float, optional)
  • Status: OPEN/CLOSED/CV (string, optional)

Data Types: String, String, String, Float, Float, Float, Float, String

Example:

[PIPES]
;ID   Node1  Node2   Length   Diam.  Roughness  Mloss   Status
P1    J1     J2     1200      12      120       0.2     OPEN
P2    J3     J2      600       6      110       0       CV
P3    J1     J10    1000      12      120              ;Defaults to OPEN

6. [PUMPS] - Pump Links​

Purpose: Defines pump links in the network Format: One line per pump with keyword-value pairs Required: No

Fields:

  • ID: Pump identifier (string)
  • Node1: Start node ID (string)
  • Node2: End node ID (string)
  • Keywords: POWER, HEAD, SPEED, PATTERN (string-value pairs)

Keywords:

  • POWER: Power for constant energy pump in hp (kw) (float)
  • HEAD: ID of head vs flow curve (string)
  • SPEED: Relative speed setting (float, default 1.0)
  • PATTERN: Time pattern ID for speed variation (string)

Data Types: String, String, String, Mixed (String-Float/String pairs)

Example:

[PUMPS]
;ID    Node1    Node2   Properties
Pump1  N12      N32     HEAD Curve1
Pump2  N121     N55     HEAD Curve1  SPEED 1.2
Pump3  N22      N23     POWER 100

7. [VALVES] - Control Valve Links​

Purpose: Defines control valve links Format: One line per valve Required: No

Fields:

  • ID: Valve identifier (string)
  • Node1: Start node ID (string)
  • Node2: End node ID (string)
  • Diameter: Diameter in inches (mm) (float)
  • Type: Valve type (string)
  • Setting: Valve setting (float/string)
  • MinorLoss: Minor loss coefficient when fully open (float, optional)
  • Curve: Characteristic curve ID for PCVs (string, optional)

Valve Types:

  • PRV: Pressure reducing valve - Setting: pressure (float)
  • PSV: Pressure sustaining valve - Setting: pressure (float)
  • PBV: Pressure breaker valve - Setting: pressure (float)
  • FCV: Flow control valve - Setting: flow (float)
  • TCV: Throttle control valve - Setting: loss coefficient (float)
  • PCV: Positional control valve - Setting: percent open (float)
  • GPV: General purpose valve - Setting: head loss curve ID (string)

Data Types: String, String, String, Float, String, Mixed, Float, String

Example:

[VALVES]
;ID   Node1  Node2   Diameter  Type  Setting  MinorLoss  Curve
V1    N1     N2      12        PRV   50       0.1
V2    N3     N4      8         FCV   100      0.2
V3    N5     N6      10        PCV   75       0.1        C1

8. [PATTERNS] - Time Patterns​

Purpose: Defines time patterns for varying parameters Format: Multiple lines per pattern Required: No (default pattern "1" created if none specified)

Fields:

  • ID: Pattern identifier (string)
  • Multipliers: One or more multiplier values (float)

Data Types: String, Float (multiple)

Example:

[PATTERNS]
;Pattern P1
P1    1.1   1.4   0.9   0.7
P1    0.6   0.5   0.8   1.0
;Pattern P2
P2    1     1     1     1
P2    0     0     1

9. [CURVES] - Data Curves​

Purpose: Defines X,Y data curves Format: One line per X,Y point Required: No

Fields:

  • ID: Curve identifier (string)
  • X-Value: X coordinate (float)
  • Y-Value: Y coordinate (float)

Curve Types (from comments):

  • PUMP: Head vs Flow for pumps
  • EFFICIENCY: Efficiency vs Flow for pumps
  • VOLUME: Volume vs Depth for tanks
  • VALVE: Flow vs Position for valves
  • HEADLOSS: Head Loss vs Flow for GPVs

Data Types: String, Float, Float

Example:

[CURVES]
;ID   Flow    Head
;PUMP: Curve for Pump 1
C1    0       200
C1    1000    100
C1    3000    0

10. [DEMANDS] - Multiple Demands​

Purpose: Defines multiple demand categories per junction Format: One line per demand category Required: No (supplements [JUNCTIONS] section)

Fields:

  • ID: Junction identifier (string)
  • Demand: Base demand in flow units (float)
  • Pattern: Demand pattern ID (string, optional)
  • Category: Demand category name (string, optional)

Data Types: String, Float, String, String

Example:

[DEMANDS]
;ID    Demand   Pattern   Category
J1     100       101     ;Domestic
J1     25        102     ;School
J256   50        101     ;Domestic

11. [CONTROLS] - Simple Controls​

Purpose: Defines simple controls for links Format: One line per control Required: No

Fields: Control statements with keywords

Control Formats:

  • LINK linkID status IF NODE nodeID ABOVE/BELOW value
  • LINK linkID status AT TIME time
  • LINK linkID status AT CLOCKTIME clocktime

Keywords: LINK, IF, NODE, ABOVE, BELOW, AT, TIME, CLOCKTIME, DISABLED Data Types: Mixed (String-Float combinations)

Example:

[CONTROLS]
LINK 12 CLOSED IF NODE 23 ABOVE 20
LINK 12 OPEN IF NODE 130 BELOW 30
LINK PUMP02 1.5 AT TIME 16 DISABLED
LINK 12 CLOSED AT CLOCKTIME 10 AM

12. [RULES] - Rule-Based Controls​

Purpose: Defines complex rule-based controls Format: Multiple lines per rule Required: No

Fields: Rule statements with conditions and actions

Rule Structure:

RULE ruleID
IF condition_1
AND condition_2
OR condition_3
THEN action_1
AND action_2
ELSE action_3
PRIORITY value

Condition Objects: NODE, JUNCTION, TANK, RESERVOIR, LINK, PIPE, PUMP, VALVE, SYSTEM Condition Attributes: DEMAND, HEAD, PRESSURE, LEVEL, FILLTIME, DRAINTIME, FLOW, STATUS, SETTING, TIME, CLOCKTIME Relations: =, IS, <>, NOT, <, BELOW, >, ABOVE, <=, >= Actions: STATUS IS OPEN/CLOSED, SETTING IS value

Data Types: Mixed (String-Float combinations)

Example:

[RULES]
RULE 1
IF   TANK   1 LEVEL ABOVE 19.1
THEN PUMP 335 STATUS IS CLOSED
AND  PIPE 330 STATUS IS OPEN

RULE 2
IF   SYSTEM CLOCKTIME >= 8 AM
AND  SYSTEM CLOCKTIME < 6 PM
AND  TANK 1 LEVEL BELOW 12
THEN PUMP 335 STATUS IS OPEN

13. [SOURCES] - Water Quality Sources​

Purpose: Defines water quality source locations Format: One line per source Required: No

Fields:

  • ID: Node identifier (string)
  • Type: Source type (string)
  • Strength: Baseline source strength (float)
  • Pattern: Time pattern ID (string, optional)

Source Types:

  • CONCEN: Concentration source (concentration units)
  • MASS: Mass source (mass flow per minute)
  • FLOWPACED: Flow-paced source (concentration units)
  • SETPOINT: Setpoint source (concentration units)

Data Types: String, String, Float, String

Example:

[SOURCES]
;Node  Type    Strength  Pattern
N1     CONCEN  1.2       Pat1
N44    MASS    12

14. [EMITTERS] - Emitter Nodes​

Purpose: Defines junctions as emitters Format: One line per emitter Required: No

Fields:

  • ID: Junction identifier (string)
  • Coefficient: Flow coefficient (float)

Data Types: String, Float

Example:

[EMITTERS]
;Junction  Coefficient
J1         0.5
J2         1.2

15. [LEAKAGE] - Pipe Leakage​

Purpose: Assigns leakage parameters to pipes Format: One line per leaking pipe Required: No

Fields:

  • ID: Pipe identifier (string)
  • Area: Crack area in sq. mm per 100 units length (float)
  • Expansion: Crack expansion rate in sq. mm per unit pressure (float)

Data Types: String, Float, Float

Example:

[LEAKAGE]
;Pipe  Area    Expansion
P1     0.1     0.0005
P2     0.2     0.001

16. [QUALITY] - Initial Water Quality​

Purpose: Defines initial water quality at nodes Format: One line per node Required: No

Fields:

  • ID: Node identifier (string)
  • InitQual: Initial quality value (float)

Data Types: String, Float

Example:

[QUALITY]
;Node  InitQual
N1     0.5
N2     1.0

17. [STATUS] - Link Status​

Purpose: Defines initial status of selected links Format: One line per link Required: No

Fields:

  • ID: Link identifier (string)
  • Status: Status or setting (string/float)

Status Values: OPEN, CLOSED, ACTIVE, or numeric setting Data Types: String, Mixed

Example:

[STATUS]
;Link  Status/Setting
L22    CLOSED
P14    1.5
PRV1   OPEN

18. [ENERGY] - Energy Parameters​

Purpose: Defines pumping energy and cost parameters Format: Keyword-value pairs Required: No

Fields: Various energy-related parameters

Keywords:

  • GLOBAL PRICE: Global energy price (float)
  • GLOBAL PATTERN: Global price pattern ID (string)
  • GLOBAL EFFIC: Global pump efficiency (float)
  • PUMP pumpID PRICE: Pump-specific price (float)
  • PUMP pumpID PATTERN: Pump-specific pattern (string)
  • PUMP pumpID EFFIC: Pump-specific efficiency (float/string)
  • DEMAND CHARGE: Demand charge (float)

Data Types: Mixed (String-Float/String combinations)

Example:

[ENERGY]
GLOBAL PRICE      0.05
GLOBAL PATTERN    PAT1
PUMP   23  PRICE  0.10
PUMP   23  EFFIC  E23
DEMAND CHARGE     0.02

19. [REACTIONS] - Chemical Reactions​

Purpose: Defines chemical reaction parameters Format: Keyword-value pairs Required: No

Fields: Various reaction parameters

Keywords:

  • ORDER BULK/WALL/TANK: Reaction order (float)
  • GLOBAL BULK/WALL: Global reaction coefficient (float)
  • BULK/WALL pipeID: Pipe-specific coefficient (float)
  • TANK tankID: Tank-specific coefficient (float)
  • LIMITING POTENTIAL: Limiting potential value (float)
  • ROUGHNESS CORRELATION: Roughness correlation factor (float)

Data Types: Mixed (String-Float combinations)

Example:

[REACTIONS]
ORDER WALL    0
GLOBAL BULK  -0.5
GLOBAL WALL  -1.0
WALL   P220  -0.5
WALL   P244  -0.7

20. [MIXING] - Tank Mixing Models​

Purpose: Identifies mixing models for storage tanks Format: One line per tank Required: No

Fields:

  • ID: Tank identifier (string)
  • Model: Mixing model (string)
  • Volume: Compartment volume fraction (float, optional)

Mixing Models:

  • MIXED: Single compartment, complete mix
  • 2COMP: Two-compartment complete mix
  • FIFO: Plug flow, first in, first out
  • LIFO: Stacked plug flow, last in, first out

Data Types: String, String, Float

Example:

[MIXING]
;Tank  Model
T12    LIFO
T23    2COMP     0.2

21. [TIMES] - Time Parameters​

Purpose: Defines simulation time parameters Format: Keyword-value pairs Required: No

Fields: Various time-related parameters

Keywords:

  • DURATION: Simulation duration (float + units)
  • HYDRAULIC TIMESTEP: Hydraulic time step (float + units)
  • QUALITY TIMESTEP: Quality time step (float + units)
  • RULE TIMESTEP: Rule time step (float + units)
  • PATTERN TIMESTEP: Pattern time step (float + units)
  • PATTERN START: Pattern start time (float + units)
  • REPORT TIMESTEP: Report time step (float + units)
  • REPORT START: Report start time (float + units)
  • START CLOCKTIME: Start clock time (time + AM/PM)
  • STATISTIC: Report statistic type (string)

Time Units: SEC, MIN, HOU, DAY Statistic Types: NONE, AVERAGE, MINIMUM, MAXIMUM, RANGE Data Types: Mixed (String-Float-String combinations)

Example:

[TIMES]
DURATION           240 HOURS
QUALITY TIMESTEP   3 MIN
REPORT START       120
START CLOCKTIME    6:00 AM
STATISTIC          NONE

22. [OPTIONS] - Analysis Options​

Purpose: Defines various simulation options Format: Keyword-value pairs Required: No

Fields: Extensive list of analysis options

Key Options:

  • UNITS: Flow units (CFS, GPM, MGD, IMGD, AFD, LPS, LPM, MLD, CMS, CMH, CMD)
  • PRESSURE: Pressure units (PSI, KPA, METERS, FEET, BAR)
  • HEADLOSS: Head loss formula (H-W, D-W, C-M)
  • HYDRAULICS: Hydraulics file option (USE/SAVE filename)
  • VISCOSITY: Kinematic viscosity (float)
  • SPECIFIC GRAVITY: Specific gravity (float)
  • TRIALS: Maximum trials (integer)
  • ACCURACY: Convergence accuracy (float)
  • FLOWCHANGE: Flow change limit (float)
  • HEADERROR: Head error limit (float)
  • CHECKFREQ: Status check frequency (integer)
  • MAXCHECK: Maximum status checks (integer)
  • DAMPLIMIT: Damping limit (float)
  • UNBALANCED: Unbalanced action (STOP/CONTINUE/CONTINUE n)
  • DEMAND MODEL: Demand model (DDA/PDA)
  • MINIMUM PRESSURE: Minimum pressure (float)
  • REQUIRED PRESSURE: Required pressure (float)
  • PRESSURE EXPONENT: Pressure exponent (float)
  • PATTERN: Default pattern ID (string)
  • DEMAND MULTIPLIER: Demand multiplier (float)
  • EMITTER EXPONENT: Emitter exponent (float)
  • EMITTER BACKFLOW: Emitter backflow (YES/NO)
  • QUALITY: Quality analysis type (NONE/CHEMICAL/AGE/TRACE nodeID)
  • DIFFUSIVITY: Chemical diffusivity (float)
  • TOLERANCE: Quality tolerance (float)
  • MAP: Map file name (string)

Data Types: Mixed (String-Float/String combinations)

Example:

[OPTIONS]
UNITS              CFS
HEADLOSS           D-W
DEMAND MODEL       PDA
REQUIRED PRESSURE  40
QUALITY            TRACE Tank23
UNBALANCED         CONTINUE 10

23. [REPORT] - Report Options​

Purpose: Describes output report contents Format: Keyword-value pairs Required: No

Fields: Various report options

Keywords:

  • PAGESIZE: Lines per page (integer)
  • FILE: Report file name (string)
  • STATUS: Status report (YES/NO/FULL)
  • SUMMARY: Summary report (YES/NO)
  • MESSAGES: Error messages (YES/NO)
  • ENERGY: Energy report (YES/NO)
  • NODES: Node reporting (NONE/ALL/node list)
  • LINKS: Link reporting (NONE/ALL/link list)
  • Variable options: YES/NO/BELOW/ABOVE/PRECISION value

Report Variables:

  • Node: Elevation, Demand, Head, Pressure, Quality
  • Link: Length, Diameter, Flow, Velocity, Headloss, State, Setting, Reaction, F-Factor

Data Types: Mixed (String-Float/String combinations)

Example:

[REPORT]
NODES N1 N2 N3 N17
LINKS ALL
FLOW YES
VELOCITY PRECISION 4
VELOCITY ABOVE 3.0

24. [COORDINATES] - Node Coordinates​

Purpose: Assigns map coordinates to nodes Format: One line per node Required: No (GUI support only)

Fields:

  • ID: Node identifier (string)
  • X-Coord: X coordinate (float)
  • Y-Coord: Y coordinate (float)

Data Types: String, Float, Float

Example:

[COORDINATES]
;Node  X-Coord  Y-Coord
N1     20.00    70.00
N2     30.00    70.00

25. [VERTICES] - Link Vertices​

Purpose: Assigns interior vertex points for links Format: One line per vertex Required: No (GUI support only)

Fields:

  • ID: Link identifier (string)
  • X-Coord: X coordinate (float)
  • Y-Coord: Y coordinate (float)

Data Types: String, Float, Float

Example:

[VERTICES]
;Link  X-Coord  Y-Coord
P1     25.00    75.00
P1     35.00    80.00

26. [LABELS] - Map Labels​

Purpose: Assigns coordinates to map labels Format: One line per label Required: No (GUI support only)

Fields:

  • X-Coord: X coordinate (float)
  • Y-Coord: Y coordinate (float)
  • Text: Label text in quotes (string)
  • Anchor: Anchor node ID (string, optional)

Data Types: Float, Float, String, String

Example:

[LABELS]
;X-Coord  Y-Coord  Label & Anchor Node
6.99      73.63    "Source"
13.48     68.13    "Pump"

27. [BACKDROP] - Backdrop Image​

Purpose: Identifies backdrop image and dimensions Format: Keyword-value pairs Required: No (GUI support only)

Fields:

  • DIMENSIONS: LLx LLy URx URy (four floats)
  • UNITS: FEET/METERS/DEGREES/NONE (string)
  • FILE: Backdrop file name (string)
  • OFFSET: X Y offset (two floats)

Data Types: Mixed (String-Float combinations)

Example:

[BACKDROP]
DIMENSIONS  7.00  6.00  73.00  94.00
UNITS       None
FILE        map.bmp
OFFSET      0.00  0.00

28. [TAGS] - Node/Link Tags​

Purpose: Associates category labels with nodes and links Format: One line per tagged object Required: No

Fields:

  • Object: NODE or LINK (string)
  • ID: Object identifier (string)
  • Tag: Tag label (string)

Data Types: String, String, String

Example:

[TAGS]
;Object  ID    Tag
NODE     1001  Zone_A
NODE     1002  Zone_A
LINK     201   UNCI-1960

29. [ROUGHNESS] - Pipe Roughness​

Purpose: Assigns roughness values to pipes (deprecated) Format: One line per pipe Required: No (use [PIPES] section instead)

Fields:

  • ID: Pipe identifier (string)
  • Roughness: Roughness coefficient (float)

Data Types: String, Float

Note: This section is deprecated; use the roughness field in [PIPES] instead.

30. [END] - End of File​

Purpose: Marks end of input file Format: Just the section header Required: No (but recommended)

Example:

[END]

Data Type Summary​

Primitive Data Types​

  • String: Text identifiers, names, keywords (max 31 chars for IDs)
  • Float: Numeric values (elevations, flows, pressures, etc.)
  • Integer: Count values (trials, timesteps, etc.)
  • Boolean: YES/NO values
  • Time: Time values with units (SEC, MIN, HOU, DAY) or clock time (HH:MM AM/PM)

Complex Data Types​

  • Mixed: Combinations of strings and numbers (e.g., "LINK 12 CLOSED")
  • Lists: Space-separated values (e.g., node lists in [REPORT])
  • Key-Value Pairs: Keyword followed by value (e.g., "UNITS GPM")
  • Coordinates: X,Y coordinate pairs
  • Curves: X,Y data point pairs
  • Patterns: Multiplier value sequences

Validation Rules​

General Rules​

  1. ID Uniqueness: All IDs must be unique within their category
  2. Reference Validity: Referenced nodes/links must be defined before use
  3. Numeric Validation: Numeric values must be valid floats/integers
  4. Range Validation: Some values have valid ranges (e.g., pressures > 0)
  5. Required Sections: [JUNCTIONS] required, at least one [RESERVOIRS] or [TANKS] required

Error Codes​

  • 200: One or more errors in input file
  • 201: Syntax error
  • 202: Illegal numeric value
  • 203: Undefined node
  • 204: Undefined link
  • 205: Undefined time pattern
  • 206: Undefined curve
  • 214: Too many characters in input line
  • 215: Duplicate ID label
  • 299: Invalid section keyword

Flow Units​

US Customary Units​

  • CFS: Cubic feet per second
  • GPM: Gallons per minute
  • MGD: Million gallons per day
  • IMGD: Imperial million gallons per day
  • AFD: Acre-feet per day

Metric Units​

  • LPS: Liters per second
  • LPM: Liters per minute
  • MLD: Million liters per day
  • CMS: Cubic meters per second
  • CMH: Cubic meters per hour
  • CMD: Cubic meters per day

Pressure Units​

  • PSI: Pounds per square inch
  • KPA: Kilopascals
  • METERS: Meters of water column
  • FEET: Feet of water column
  • BAR: Bar

Head Loss Formulas​

  • H-W: Hazen-Williams
  • D-W: Darcy-Weisbach
  • C-M: Chezy-Manning

Analysis Sources​

This specification is based on comprehensive analysis of:

  1. Documentation: doc/toolkit-input.dox - Complete section documentation

  2. Source Code:

    • src/text.h - All keywords and constants
    • src/input2.c and src/input3.c - Input parsing logic
    • src/errors.dat - Error codes and validation rules

  3. Examples:

    • example-networks/Net1.inp, Net2.inp, Net3.inp - Real usage examples
    • tests/data/ - Test validation examples

  4. Parsing Functions: All xxxdata() functions in src/input3.c

Conclusion​

This specification provides complete coverage of the EPANET input file format, including every supported section, field, data type, validation rule, and usage pattern. It serves as a definitive reference for understanding, creating, validating, or parsing EPANET input files based on the actual source code implementation in EPANET 2.3.

Last updated on by Jake