Search the component catalogue.

Returns id, alias, name, summary, ports, key parameters (with units and defaults), fidelity level and tags of every matching component. Call without a query to list everything, then describe_component with all the components you need in one call.

Describe component types: everything needed to use them.

Pass every component you need as a list in one call: the result is then {components: [...]} in that order (one id: one description). Each has ports; parameters and inputs with units, defaults and hard limits (table columns in row order); states and observables; modes (the first whose condition holds is reported); warning codes; scenario and contract ids; bindings. Plain numbers are in these units; pressures are gauge unless stated; quantity 'temperature_difference' converts by scale only. A state's steady is 'settle' (solve sets its equilibrium) or 'hold' (solve keeps it, e.g. a tank level). A warning's source is 'envelope' (its condition holds) or 'component' (raised by code; message says when).

Run a component's scenarios and contracts and report pass or fail.

Scenarios have expected results; contracts check monotonicity, bounds, conservation and warning conditions against the reference implementation.

Create a new empty system and return its system_id.

For building step by step; a new system is quicker as one load_system call.

Add a component instance to a system.

Returns the resolved parameters, inputs and states with units, the instance's port paths, and pre-flight issues about it (unconnected ports until you connect them).

Remove a component instance and every connection to it.

Set inputs, parameters or states by path (atomically: all or nothing).

Plain numbers are in the declared unit; strings may carry units. Returns the values now in effect, in declared units.

Connect two ports. Connecting several ports to one node forms a junction (tee).

Errors name the offending port and list the instance's valid ports. Returns the connections and the ports still unconnected (unconnected ports are capped).

Remove the direct connection between two ports.

Add a control that reads one result and writes one component input.

pi: solve finds the output holding the setpoint (control_saturated if unreachable); simulate runs it after each step's solve. hysteresis: on below on_below, off above off_above (short_cycling if too frequent). Returns every control.

Remove a control; its input keeps its last value.

Structural pre-flight with stable issue codes.

Codes: unknown_component, unknown_port, incompatible_ports, self_connection, unconnected_port (warning), no_pressure_reference, boundary_short_circuit, parameter_out_of_range, invalid_value; for controls unknown_variable, invalid_control, control_conflict. solve and simulate refuse to run while any error remains.

Every variable path with kind, unit, limits and description.

Kinds: parameter, input, state (settable), observable, port ('..p' in bar gauge, '.m_flow' in kg/s into the component, '.T' in degC) and control ('control..output' and '.measure'; component='control' lists them).

Solve the steady operating point.

Returns the selected values with units (6 significant digits; pressures carry their reference, port pressures are bar gauge), the mode of every instance, component warnings and non-fatal pre-flight issues. Fails with the list of errors when check_system reports any. Controls: PI actuators are set to hold their setpoints, hysteresis switches hold their state; controls reports each loop (output, measured, setpoint, error, saturated or state).

Goal seek: the value of one input or parameter that gives a target result.

Brent's method on vary between lower and upper until target equals value, e.g. the pump speed for 15 m3/h. If the target does not cross the value inside the bounds, the error reports it at both bounds and nothing changes. On success vary stays at the value found; the result is the operating point there, as from solve.

Simulate over time with a fixed step and timed events (set or linear ramp).

Samples at every multiple of step, at each event time and at the end. Returns downsampled series with min, max and final over the full run; each warning once (first time, last time, active at end); every mode change. Controls act after each sample's solve (taking effect over the next step); their series are always included and controls reports each loop at the end. Unless restore is true, the system keeps its final state.

The system document (design 6.3): components with explicit values, connections, changed states, controls and the optional simulation block. Pass it to load_system later.

Build a whole system in one call from a system document; returns its system_id.

The quickest way to create a system: every component (with parameters and inputs), connection and control in one document, then solve. get_system returns such a document. A wrong shape fails with every schema error and the expected shape of the offending part; unknown types, ports and invalid values are kept and listed in issues (the check_system report, no need to call it): fix every error, then solve.

Export a system as EPANET .inp text (units CMH, Darcy-Weisbach).

Faucets and heaters are unsupported. notes: what the export approximates.

Solve the system here and in EPANET (via WNTR) and compare: per-link flows (m3/h) and node pressures (bar gauge), differences and why they diverge.