Output Files

Hydra produces three output files. Only one of them holds full time-series results; the other two are summaries of the same run.

Only the .out file contains time series. The .rpt and .json reports are two serialisations of the same summary information — neither includes per-node or per-link result tables.

How each is produced:

• CLI — the report path (.rpt or .json) selects the text or JSON report; --output writes the .out file. See CLI.
• GUI — every run writes results.out into the scenario folder; CSV and GeoJSON exports are available from the command palette. See GUI.
• SDK — io::out_writer::write_binary_output, io::rpt_writer::build_text_report, and io::rpt_writer::build_json_report. See SDK Examples.

.out — Binary results

The .out file is the EPANET 2.3 binary output layout (format version 20012), so tools that read EPANET output files read Hydra’s. Hydra records its own metadata — such as the topology digest that detects a since-edited model — in a run.json beside the results rather than inside them, so the results file stays a format EPANET defines. Values are stored as 32-bit floats (REAL4) and 32-bit integers (INT4), little-endian; IDs and strings are fixed-width, zero-padded.

The file is written in five sections:

1. Prolog — a 15-integer header (magic number, format version, element counts, quality mode, trace node, flow-unit code, pressure-unit code, report start/step, duration) followed by the network’s static data: title lines, input/report filenames, chemical name and units, node and link IDs, link end-node indices and type codes, tank node indices and cross-section areas, and node elevations, link lengths, and link diameters.
2. Energy — per-pump summary: percent online, average efficiency, average energy per unit flow, average and peak power, and average cost, plus the network demand charge.
3. Dynamic results — one record per reporting period (not per hydraulic step), stored column-major. Each record holds, for that period:
   • Node quantities (4): demand, head, pressure, quality
   • Link quantities (8): flow, velocity, head loss, quality, status, setting, reaction rate, friction factor
4. Network reactions — average bulk, wall, tank, and source reaction rates over the run.
5. Epilog — the number of reporting periods, a warning flag, a network content digest, and a closing magic number.

Units

All numeric values are written in the unit system chosen at write time (output_units). The CLI and GUI default to the model’s declared flow units; the SDK writer takes an explicit FlowUnits argument (pass sim.net().options.flow_units for the model’s units). Pressures are written in metres (SI) or PSI (US customary).

Two categories are not unit-converted: tank cross-section areas (always internal m²) and all quality/reaction-rate values (written in their native quality units).

.rpt — Text report

A human-readable summary in EPANET report style. It contains, in order:

• A date stamp and the Hydra banner with the version number
• The network title lines
• An input summary: counts of junctions, reservoirs, tanks, pipes, pumps, and valves; head-loss formula; demand model (DDA/PDA); hydraulic timestep; hydraulic accuracy; maximum trials; the quality-analysis mode (with constituent name, quality timestep, and tolerance where applicable); specific gravity; demand multiplier; total duration; and report timestep
• An “Analysis begun” timestamp
• Warnings raised during the run, grouped by simulation time (unbalanced hydraulics, negative pressures, pump-exceeds-maximum-head)
• An “Analysis ended” timestamp

It does not contain per-node or per-link result tables. For full results, read the .out file. For the catalogue of warning types, see Diagnostics & Errors.

.json — JSON report

The same summary data as the .rpt report, in a structured form suited to scripts and pipelines. Top-level keys:

{
  "input": {
    "junctions": 92, "reservoirs": 1, "tanks": 2,
    "pipes": 117, "pumps": 2, "valves": 0,
    "headloss_formula": "Hazen-Williams", "demand_model": "DDA",
    "hydraulic_timestep_s": 3600.0, "quality_timestep_s": 360.0,
    "duration_s": 86400.0, "report_timestep_s": 3600.0
  },
  "warnings": [
    { "time": 3600.0, "code": "warning/negative_pressure", "message": "...", "object_id": "J1" }
  ],
  "energy": {
    "pumps": [
      { "pump_id": "PU1", "kwh": 120.0, "total_cost": 14.4,
        "avg_efficiency": 0.75, "max_kw": 8.1, "time_online_s": 86400.0 }
    ],
    "peak_demand_kw": 12.3
  },
  "flow_balance": {
    "total_inflow": 0.0, "total_outflow": 0.0,
    "tank_change": 0.0, "unaccounted": 0.0, "ratio": 1.0
  },
  "mass_balance": {
    "initial": 0.0, "added": 0.0, "demand": 0.0,
    "reacted": 0.0, "reacted_bulk": 0.0, "reacted_wall": 0.0,
    "reacted_tank": 0.0, "source": 0.0, "final_mass": 0.0, "ratio": 1.0
  },
  "analysis": { "begun_epoch": "1615687166", "ended_epoch": "1615687167" }
}

Notes:

• warnings[].time is the simulation time in seconds; object_id is the affected node/link ID or null.
• avg_efficiency is a fraction in [0, 1].
• flow_balance is null if unavailable, and mass_balance is null when no quality analysis was run. Balance volumes are in m³; mass values are in mg.
• begun_epoch / ended_epoch are strings holding raw seconds since the Unix epoch (or null) — not formatted datetimes.