SurgeSpaceDocsCommand API

Command API

The SurgeSpace command layer: every command the interface, scripts and the AI copilot use to build, edit, run and read models.

SurgeSpace command API

Every change to a model goes through these commands — the menus, the AI copilot and scripts (Tools → Script console: await ss.<name>({…})) use the same set, so every change is one undo step and every number comes from the engines. Units are SI as named in each parameter.

Generated from src/app/commands.ts by scripts/gen-api.ts.

get_model (read only)#

Read the current model: nodes, pipes, pumps, valves, operations and run settings (SI units, as named). Call this first.

list_elements (read only)#

List elements of one type with all their editable fields (for large models, page with offset).

Parameter Type Required Description
type string (node, pipe, pump, valve) yes Element type
offset number First row (default 0)
limit number Rows (default 100, max 500)

new_model#

Start a new empty model (the current one can be restored with undo).

Parameter Type Required Description
name string yes Project name
description string Short description

load_example#

Open a built-in example: rising, rising-bare, gravity, loop, elhazek, hydro, town, bwsn1.

Parameter Type Required Description
id string (rising, rising-bare, gravity, loop, elhazek, hydro, town, bwsn1) yes Example id

add_node#

Add a junction or a fixed-level source (reservoir, sump, tank).

Parameter Type Required Description
id string Id (optional)
kind string (junction, reservoir) yes junction or reservoir
x number yes X, m
y number yes Y, m
elevation_m number yes Ground / centreline level, m
water_level_m number Reservoir water level, m
demand_lps number Junction demand, L/s

add_pipe#

Add a pipe between two existing nodes. Length defaults to the drawn distance.

Parameter Type Required Description
id string Id (optional)
from string yes Start node id
to string yes End node id
length_m number Length, m
diameter_mm number yes Internal diameter, mm
roughness number ε mm (Darcy–Weisbach) or C (Hazen–Williams)
wavespeed_mps number Wave speed, m/s
pressure_class_m number Pressure class, m head
material string Material name

build_line#

Build a whole pipeline from a long section in one step: points by chainage and level, joined by pipes of one size. Optionally make the first and/or last point a fixed-level source. Use for rising mains and transmission lines.

Parameter Type Required Description
points array of object yes Long-section points in order
diameter_mm number yes Internal diameter, mm
wavespeed_mps number Wave speed, m/s
roughness number ε mm or C
pressure_class_m number Pressure class, m head
material string Material
start_water_level_m number If given, the first point is a source with this water level
end_water_level_m number If given, the last point is a source with this water level
x0 number X of the first point (default: right of the existing model)
y0 number Y of the first point

add_pump_station#

Add identical pumps in parallel between a suction node and a discharge node, from the duty point. Inertia is estimated from the duty if not given.

Parameter Type Required Description
suction string yes Suction node id
discharge string yes Discharge node id
count number yes Number of duty pumps
duty_flow_lps number yes Flow per pump at duty, L/s
duty_head_m number yes Head at duty, m
shutoff_head_m number Shut-off head, m (default 1.3 × duty)
curve string Optional full curve "L/s:m, …" (overrides duty points)
speed_rpm number Rated speed (default 1480)
efficiency_pct number Efficiency at duty (default 80)
inertia_kgm2 number Pump + motor inertia per pump
check_valve boolean Discharge non-return valve (default true)

Add a link between two nodes: pump, turbine, lineValve, nrv, prv, psv, fcv, orifice (nrv = non-return valve; prv/psv/fcv = control valves).

Parameter Type Required Description
kind string (pump, turbine, lineValve, nrv, prv, psv, fcv, orifice) yes Link kind
from string yes From node id
to string yes To node id
diameter_mm number Valve diameter, mm

insert_on_pipe#

Split a pipe and insert a junction, a link (pump, valve…) or a protection device at a fraction of its length.

Parameter Type Required Description
pipe string yes Pipe id
kind string (junction, pump, turbine, lineValve, nrv, prv, psv, fcv, orifice, airVessel, airValve, standpipe, feedTank, anticipator, relief, blowoff, burstDisc) yes What to insert
fraction number yes Position along the pipe, 0–1

set_properties#

Change fields of one or more elements of the same type. Node fields: label, x, y, elevation, demand_lps, water_level_m, kind. Pipe: length_m, diameter_mm, roughness, wavespeed_mps, pressure_class_m, minor_loss_k, material, wall_mm, closed, check_valve. Pump: curve ("L/s:m, …"), efficiency_pct, speed_rpm, inertia_kgm2, check_valve, running. Valve: diameter_mm, k_open, opening, characteristic, set_point.

Parameter Type Required Description
type string (node, pipe, pump, valve) yes Element type
ids array of string yes Element ids
values object yes Field → value

add_device#

Put a protection device on a junction: vessel, airValve, standpipe, feedTank, anticipator, relief, blowoff, burstDisc. Optional values as in set_device.

Parameter Type Required Description
node string yes Junction id
device string (vessel, airValve, standpipe, feedTank, anticipator, relief, blowoff, burstDisc) yes Device
values object Device field → value (see set_device)

set_device#

Change a device on a junction. vessel: volume_m3, gas_volume_m3, connection_mm, k_in, k_out, polytropic_n, shape, bladder. airValve: type, inflow_mm, outflow_mm, small_mm. standpipe/feedTank: diameter_m, bottom_m, top_m, connection_mm, riser_diameter_m, port_area_m2, riser_top_m. relief: set_head_m, diameter_mm. anticipator: low_set_m, diameter_mm, open_s, hold_s, close_s. blowoff/burstDisc: diameter_mm, opens_at_s, burst_head_m.

Parameter Type Required Description
node string yes Junction id
device string (vessel, airValve, standpipe, feedTank, anticipator, relief, blowoff, burstDisc) yes Device
values object yes Field → value

remove_device#

Remove a protection device from a junction.

Parameter Type Required Description
node string yes Junction id
device string (vessel, airValve, standpipe, feedTank, anticipator, relief, blowoff, burstDisc) yes Device

delete_elements#

Delete elements. Deleting a node also deletes the pipes, pumps and valves connected to it.

Parameter Type Required Description
refs array of object yes Items: type, id

rename_element#

Rename an element; every reference to it follows.

Parameter Type Required Description
type string (node, pipe, pump, valve) yes Type
id string yes Current id
new_id string yes New id

set_operations#

Replace the run's operations (what happens during the surge run). Kinds: pump_trip, pump_stop_ramp, pump_start, valve_close, valve_open, turbine_rejection, turbine_acceptance. Each element follows the first operation that lists it. Valve operations: duration_s = stroke time, final_opening 0–1, exponent 1 linear / 2 slow end, or curve [[t_s, stroke], …].

Parameter Type Required Description
operations array of object yes Items: kind, targets, start_s, duration_s, final_opening, exponent, curve

set_run_settings#

Change run settings: duration_s, friction (DW or HW), min_pressure_m, max_pressure_m, unsteady_friction, liquid (Water 0 °C, Water 5 °C, Water 10 °C, Water 15 °C, Water 20 °C…), site_elevation_m.

Parameter Type Required Description
duration_s number Simulation time, s
friction string (DW, HW) Friction method
min_pressure_m number Lowest allowed pressure, m
max_pressure_m number Highest allowed pressure, m
unsteady_friction boolean Unsteady friction
liquid string Liquid name
site_elevation_m number Site elevation above sea level, m
engine string (wave, rigid) Surge engine: wave (all events, default) or rigid (rigid columns: slow events, surge tank mass oscillation)

set_eps#

Extended-period (daily operation) settings: duration_h, step_min (hydraulic step), pattern_step_min, default_pattern (for junctions without one), quality (none, age, trace, chemical), trace_node, chemical, bulk_per_day (negative = decay, chlorine typically -0.5), wall_m_per_day (negative).

Parameter Type Required Description
duration_h number Duration, h
step_min number Hydraulic step, min
pattern_step_min number Pattern step, min
default_pattern string Default junction pattern id
quality string (none, age, trace, chemical) Water quality
trace_node string Trace source node
chemical string Chemical name
bulk_per_day number Bulk coefficient 1/day
wall_m_per_day number Wall coefficient m/day

set_patterns#

Create or replace time patterns (multipliers per pattern step, repeating), e.g. a 24-value daily demand pattern. Optionally assign a pattern to junctions (or a fixed-level source head).

Parameter Type Required Description
patterns array of object Items: id, factors
assign array of object Assignments

set_storage#

Make a fixed-level source a storage tank whose level changes in the extended-period run (levels in m above the tank bottom = node elevation), or remove the storage (remove: true).

Parameter Type Required Description
node string yes Fixed-level source id
init_level_m number Initial level
min_level_m number Minimum level
max_level_m number Maximum level (overflow)
diameter_m number Tank diameter
initial_quality number Initial quality
remove boolean Remove the storage

set_controls#

Replace the simple controls of the extended-period run. Each: link (pump, pipe or valve id), status open|closed (or setting), and one trigger: at_h (hours after start), clock_h (time of day, daily), or node + op (above|below) + value (tank level m above its bottom, or junction pressure m).

Parameter Type Required Description
controls array of object yes Items: link, status, setting, at_h, clock_h, node, op, value

set_rules#

Replace the rule-based controls of the extended-period run, written in EPANET rule syntax with SI values (levels, heads, pressures m; flows L/s; times h:mm). Example: "RULE 1 IF TANK T1 LEVEL BELOW 2 AND SYSTEM CLOCKTIME >= 22:00 THEN PUMP PU1 STATUS IS OPEN PRIORITY 1".

Parameter Type Required Description
text string yes Rules text

run_eps (read only)#

Run the extended-period simulation (daily operation: tank levels, pump cycling, pressures through the day, water quality). Returns a summary: tank level ranges, pump hours and energy, lowest and highest pressures with times, quality ranges, events.

optimise_protection#

Least-cost surge protection by a genetic algorithm: chooses sizes (or none) for candidate air vessels and air valves — and optionally the pressure class or diameter of the pipes — so the pressure limits are met, judging every design with a full surge run. Without candidates it uses vessels at pump discharges and air valves at high points. Applies the best design. Takes from seconds to a few minutes.

Parameter Type Required Description
candidates array of object Items: node, kind, options
pipes string (none, class, diameter) Also choose pipe pressure classes (class) or diameters (diameter)

skeletonise#

Simplify the model: merge pipes in series through plain junctions (same diameter and material; the junction stays as a profile point) and optionally trim small dead ends. keep = node ids that must stay.

Parameter Type Required Description
keep array of string
trim_below_mm number Trim dead ends below this diameter (0 = off)

health_check (read only)#

Check the model for errors and implausible inputs before running.

query_elements (read only)#

Find elements by data and results, e.g. "pipes where diameter_mm < 200 and material = PVC", "nodes where max_pressure_m > 120 or min_pressure_m < 0". Highlights them on the drawing and returns the ids.

Parameter Type Required Description
query string yes Query text

create_case#

Keep the current model as a case and continue in a new named copy (e.g. "Power failure, both pumps", "Valve V1 closes in 10 s"). Then change that copy (operations, devices). Cases are compared side by side in the Cases tab. With inherit, the new case is a child that keeps only its own changes, so later corrections to the current case flow into it (use it for variants of one design).

Parameter Type Required Description
name string yes Name of the new case
notes string What the case represents
inherit boolean Child case that inherits from the current one

apply_health_fixes#

Apply the suggested fix of every health-check finding that has one (or only those whose title contains match). One undo step.

Parameter Type Required Description
match string Only findings whose title contains this text

run_analysis (read only)#

Run the steady state and the surge simulation with the current model and operations; returns the results summary.

get_results (read only)#

Results of the last run: "summary", "nodes" (pressures at every node), "pipes" (flows and pressure envelopes), "forces" (largest unbalanced axial force per pipe for anchors and thrust blocks, kN), or a list of ids.

Parameter Type Required Description
what string (summary, nodes, pipes, forces) yes What
ids array of string Limit to these ids

size_air_vessel (read only)#

Find the smallest air vessel at a junction that keeps every point above the minimum pressure and within class (several engine runs). Does not change the model: apply the result with add_device.

Parameter Type Required Description
node string yes Junction id (usually the pump discharge)

suggest_air_valves (read only)#

Find high points that need air valves and the smallest standard inflow size for each (engine runs). Does not change the model.

select_elements (read only)#

Highlight elements on the drawing for the user (to show where something is).

Parameter Type Required Description
refs array of object yes Items: type, id