epanet-js scripting API

A point on the map.

type Position = [lng: number, lat: number];

A bounding box.

type BBox = [minLng: number, minLat: number, maxLng: number, maxLat: number];

The open project. source is where it came from: a saved project, an imported INP, or a new one.

interface ProjectInfo {
  name: string;
  fileName: string | null;
  source: "project" | "inp" | "new";
  isDemo: boolean;
  unitSystem: string;
  headlossFormula: "H-W" | "D-W" | "C-M";
}

Counts per type and the network's extent.

interface NetworkStats {
  junctions: number;
  reservoirs: number;
  tanks: number;
  pipes: number;
  pumps: number;
  valves: number;
  customerPoints: number;
  bounds: BBox | null;
}

Quantity → unit for every value the API hands out.

type Units = Readonly<Record<string, string | null>>;

The simulation settings the next run would use, with unset hydraulic options resolved to what EPANET uses.

interface SimulationSettings {
  version: string;
  duration: number;
  hydraulicTimestep: number;
  reportTimestep: number;
  patternTimestep: number;
  qualityTimestep: number | null;
  ruleTimestep: number | null;
  globalDemandMultiplier: number;
  demandModel: "DDA" | "PDA";
  minimumPressure: number;
  requiredPressure: number;
  pressureExponent: number;
  emitterExponent: number;
  backflowAllowed: boolean;
  trials: number;
  accuracy: number;
  unbalancedMode: "STOP" | "CONTINUE";
  unbalancedExtraTrials: number;
  headError: number;
  flowChange: number;
  checkFreq: number;
  maxCheck: number;
  dampLimit: number;
  viscosity: number;
  specificGravity: number;
  quality: "none" | "chemical" | "age" | "trace";
  qualityChemicalName: string;
  qualityMassUnit: "mg/L" | "ug/L";
  qualityTraceNode: string | null;
  tolerance: number;
  diffusivity: number;
  reactionBulkOrder: number;
  reactionWallOrder: number;
  reactionTankOrder: number;
  reactionGlobalBulk: number;
  reactionGlobalWall: number;
  reactionLimitingPotential: number;
  reactionRoughnessCorrelation: number;
  reportEnergy: boolean;
  energyGlobalEfficiency: number;
  energyGlobalPrice: number;
  energyGlobalPattern: string | null;
  energyDemandCharge: number;
  statusReport: "YES" | "NO" | "FULL";
}

The six asset types.

type AssetType = "junction" | "reservoir" | "tank" | "pipe" | "pump" | "valve";

One demand category: a base demand and the label of its pattern, absent when it has none.

interface Demand { base: number; pattern?: string }

A pump's structured control from the app. Times are in seconds.

type PumpControl =
  | {
      type: "timed-setting";
      steps: { time: number; status: "on" | "off"; setting: number }[];
    }
  | {
      type: "level-setting";
      tank: Tank;
      on: { level: number; setting: number };
      off: { level: number };
    }
  | {
      type: "variable-speed-pump";
      quantity: "pressure" | "level" | "flow";
      targetAsset: Asset;
      target: number;
      minSpeed: number;
      maxSpeed: number;
      laggedPumps: Pump[];
      schedule: { time: number; target: number }[];
      tankLevels: { tank: Tank; onLevel: number; offLevel: number } | null;
    };

A junction's simulation results at one timestep.

interface JunctionResults {
  pressure: number;
  head: number;
  demand: number;
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this junction at another timestep; a negative index counts from the end */
  at(index: number): JunctionResults | null;
  /** one value per entry of network.results.timesteps */
  series(property: "pressure" | "head" | "demand" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
  /** lowest and highest over the run; the same at every timestep */
  readonly stats: { minPressure: number; maxPressure: number; minHead: number; maxHead: number } | null;
}

A reservoir's simulation results at one timestep.

interface ReservoirResults {
  pressure: number;
  head: number;
  netFlow: number;
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this reservoir at another timestep; a negative index counts from the end */
  at(index: number): ReservoirResults | null;
  /** one value per entry of network.results.timesteps */
  series(property: "pressure" | "head" | "netFlow" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
  /** lowest and highest over the run; the same at every timestep */
  readonly stats: { minPressure: number; maxPressure: number; minHead: number; maxHead: number } | null;
}

A tank's simulation results at one timestep.

interface TankResults {
  pressure: number;
  head: number;
  level: number;
  volume: number;
  netFlow: number;
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this tank at another timestep; a negative index counts from the end */
  at(index: number): TankResults | null;
  /** one value per entry of network.results.timesteps */
  series(property: "pressure" | "head" | "level" | "volume" | "netFlow" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
  /** lowest and highest over the run; the same at every timestep */
  readonly stats: { minPressure: number; maxPressure: number; minHead: number; maxHead: number } | null;
}

A pipe's simulation results at one timestep.

interface PipeResults {
  flow: number;
  velocity: number;
  headloss: number;
  unitHeadloss: number;
  status: "open" | "closed";
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this pipe at another timestep; a negative index counts from the end */
  at(index: number): PipeResults | null;
  /** `status` at each entry of network.results.timesteps */
  series(property: "status"): ("open" | "closed")[] | null;
  /** one value per entry of network.results.timesteps */
  series(property: "flow" | "velocity" | "headloss" | "unitHeadloss" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
}

A pump's simulation results at one timestep.

interface PumpResults {
  flow: number;
  head: number;
  setting: number;
  status: "on" | "off";
  statusWarning: "cannot-deliver-flow" | "cannot-deliver-pressure" | "cannot-deliver-head" | null;
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this pump at another timestep; a negative index counts from the end */
  at(index: number): PumpResults | null;
  /** `status` at each entry of network.results.timesteps */
  series(property: "status"): ("on" | "off")[] | null;
  /** `statusWarning` at each entry of network.results.timesteps */
  series(property: "statusWarning"): ("cannot-deliver-flow" | "cannot-deliver-head" | null)[] | null;
  /** one value per entry of network.results.timesteps */
  series(property: "flow" | "head" | "setting" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
  /** energy use over the run, as EPANET reports it; the same at every timestep */
  readonly energy: { utilization: number; averageEfficiency: number; averageKwPerFlowUnit: number; averageKw: number; peakKw: number; averageCostPerDay: number; demandCharge: number } | null;
}

A valve's simulation results at one timestep.

interface ValveResults {
  flow: number;
  velocity: number;
  headloss: number;
  setting: number;
  status: "active" | "open" | "closed";
  statusWarning: "cannot-deliver-flow" | "cannot-deliver-pressure" | "cannot-deliver-head" | null;
  /** when the run had that water quality analysis */
  waterAge?: number;
  waterTrace?: number;
  chemicalConcentration?: number;
  /** this valve at another timestep; a negative index counts from the end */
  at(index: number): ValveResults | null;
  /** `status` at each entry of network.results.timesteps */
  series(property: "status"): ("active" | "open" | "closed")[] | null;
  /** `statusWarning` at each entry of network.results.timesteps */
  series(property: "statusWarning"): ("cannot-deliver-flow" | "cannot-deliver-pressure" | null)[] | null;
  /** one value per entry of network.results.timesteps */
  series(property: "flow" | "velocity" | "headloss" | "setting" | "waterAge" | "waterTrace" | "chemicalConcentration"): number[] | null;
}

A time pattern.

interface Pattern {
  label: string;
  type: "demand" | "reservoirHead" | "pumpSpeed" | "qualitySourceStrength" | "energyPrice";
  multipliers: number[];
}

A shared curve.

interface Curve {
  label: string;
  type: "pump" | "efficiency" | "volume" | "valve" | "headloss";
  points: { x: number; y: number }[];
}

A pipe library material: the roughness it has at each age.

interface PipeMaterial { label: string; entries: { age: number; roughness: number }[] }

A custom attribute defined for an asset type.

interface CustomAttribute { name: string; type: "text" | "number" }

A customer point allocation rule.

interface AllocationRule { maxDistance: number; maxDiameter: number }

Where to look: a polygon, a multipolygon, a feature of one, a box or a ring of positions. A node is inside when its point is; a link only when the whole line is, so one crossing a hole is left out.

type Area =
  | GeoJSON.Polygon
  | GeoJSON.MultiPolygon
  | GeoJSON.Feature<GeoJSON.Polygon | GeoJSON.MultiPolygon>
  | BBox
  | Position[];

The closest point on a line, how far it is, how far along the line, and the fraction of the line.

interface NearestPoint { point: Position; distance: number; chainage: number; fraction: number }

A link on the rim of a set of nodes. For a PRV on the rim, inside is the zone end.

interface BoundaryLink { link: LinkAsset; inside: NodeAsset; outside: NodeAsset }

Named barriers for trace's stopAt. controlValves is every valve except an open TCV; cv is check-valve pipes; closed is closed pipes and valves and pumps that are off, for mode: "connected".

type StopPreset =
  | "tanks" | "reservoirs" | "pumps"
  | "valves" | "controlValves" | "cv" | "closed"
  | "prv" | "psv" | "fcv" | "pbv" | "tcv" | "gpv" | "pcv";

Where a trace stopped and why: the barrier, and the node it was reached from.

interface TraceStop {
  asset: Asset;
  reason: "stopAt" | "closed" | "direction" | "limit";
  from: NodeAsset;
  via: LinkAsset | null;
}

The zone a trace reached, the links on its rim, every barrier it stopped at, and how far along the pipes each node is.

interface TraceResult { nodes: NodeAsset[]; links: LinkAsset[]; boundaryLinks: BoundaryLink[]; stoppedAt: TraceStop[]; distance(node: NodeAsset | string): number }

A path between two nodes.

interface Path { nodes: NodeAsset[]; links: LinkAsset[]; totalLength: number }

What network.validate() found.

interface ValidationReport {
  status: "ok" | "warning" | "error";
  checks: ("orphanAssets" | "connectivityTrace" | "modelAttributesValidation")[];
  counts: { findings: number; errors: number; warnings: number; assets: number };
  findings: Finding[];
}

One rule and everything that failed it.

interface Finding {
  check: "orphanAssets" | "connectivityTrace" | "modelAttributesValidation";
  code: string;
  severity: "error" | "warning";
  entityType: string | null;
  field: string | null;
  assets: (Asset | CustomerPoint)[];
  details: { nodes: NodeAsset[]; links: LinkAsset[] } | null;
}

A connected part of the network. One with supplySourceCount === 0 has no reservoir or tank.

interface Subnetwork {
  nodes: NodeAsset[];
  links: LinkAsset[];
  supplySourceCount: number;
  pipeCount: number;
  bounds: BBox;
}

A node close to a pipe it is not connected to.

interface ProximityAnomaly { node: NodeAsset; pipe: Pipe; distance: number; nearestPointOnPipe: Position }

Two pipes that cross with no junction where they meet. The smaller pipe is pipe1.

interface CrossingPipe { pipe1: Pipe; pipe2: Pipe; intersectionPoint: Position }

How the run ended. A failure or a stopped run has no timesteps; report says why.

type SimulationStatus = "success" | "warning" | "failure" | "stopped";

Something a zone can contain: a position, an asset or its label, or a customer point.

type ZoneTarget = Position | Asset | string | CustomerPoint;