Documentation

Getting Started

SimuPipe is a steady-state hydraulic simulator for pipe networks. You build a network in the visual editor, configure fluid properties and boundary conditions, then run the solver to get pressures, flow rates, velocities, and more across every pipe and node.

Create a project

1. Sign in and go to the Dashboard.
2. Click New Project. You can start from a blank canvas or choose a template (Simple Loop, Compressed Air, Cooling Water).
3. The editor opens automatically.

Build your first network

1. Drag a Source (or a Tank) onto the canvas — both can act as inlet boundaries. On a Source, set pressure or flow rate; on a Tank, set level / pressure. Configure in the property panel on the right.
2. Configure the fluid on the inlet boundary — choose a preset (water, air, etc.) or enter custom properties. Fluid settings live on the Source (or Tank for liquid systems) and apply to the entire network.
3. Add more components: pumps, valves, elbows, tees, reducers, orifice plates, control valves, or custom components. Each component needs to be configured — click it to open the property panel and set its parameters. Defaults will work for fittings in Auto K-factor mode, but valves, control valves, pumps, and custom components need real values (Kv, setpoint, pump curve, K-factor) for the simulation to mean anything. See the Components section for typical values per component type.
4. Connect components by dragging from one node's handle to another. A pipe is created automatically. Click a pipe to set its length, diameter, material, and roughness.
5. Add a Sink (or another Tank) at the discharge end. Set its pressure or flow rate to define the outlet boundary.

Run a simulation

1. Click the Run button in the toolbar.
2. Results appear as colour-coded overlays on pipes. Use the overlay dropdown to switch between velocity, pressure, Reynolds number, flow rate, and Mach number.
3. Toggle the Node results button to show or hide result badges on nodes.
4. Open the Reports page (sidebar) for tabular results, which can be exported as PDF, CSV, or Excel.

Worked example: water filtration network

A complete walkthrough from blank canvas to converged simulation. Models a feed pump pushing water through a cartridge filter and a flow-control valve into two parallel process lines. Use this as a template the first time you build something real.

1. New Project → blank canvas. The editor opens with an empty canvas, the component catalog on the left, and the property panel on the right. Two top-left toolbar buttons toggle each side: Palette shows or hides the component catalog, Properties shows or hides the property panel. Collapse either to maximise canvas space on smaller screens.
2. Drag a Source onto the canvas. In the property panel, set Mode to Pressure and pressure to 300 kPa(g). In the Fluid section, pick the Water (IAPWS-IF97) preset. Elevation 0.
3. Drag a Pump. Click Pump, set Pump mode to Curve, and enter three points from your datasheet — e.g. (0 m³/h, 35 m), (50 m³/h, 30 m), (100 m³/h, 18 m). Click "View Curve" to confirm the fit looks right.
4. Drag a Custom Component. Set Icon to Filter (circle with a mesh cross), label it "Cartridge Filter", set Loss mode to Cv/Kv, and enter the rated Kv from the manufacturer datasheet (e.g. Kv = 120 (Kv metric)).
5. Drag a Control Valve. Set Control type to FCV (Flow Control) and Flow setpoint to 60 m³/h. The Diameter field auto-populates from the connected pipe.
   
   For a generic control valve, the defaults work — leave xT = 0.7 and FL = 0.9. But if you have a manufacturer datasheet for a specific valve, enter the real values for better accuracy:
   • Rated Kv (or Cv) — the valve's capacity at 100% open. The solver still computes the live Kv from the flow setpoint, but this caps the maximum throttle. Pick the valve's nominal Kv from its datasheet. Use the unit dropdown to switch between Kv (metric) and Cv (US).
   • x_T — critical pressure-ratio factor for gas choking. Datasheet value, typically 0.5–0.8 depending on body style. Globe valves: ~0.65–0.75. Ball: ~0.20–0.40 (low!). Butterfly: ~0.30–0.55.
   • F_L — liquid pressure recovery factor for cavitation prediction. Globe: 0.80–0.90. Ball: 0.55–0.70. Butterfly: 0.55–0.70.
   • Mode — switch from Standard to Position-Dependent if your datasheet gives x_T and F_L as functions of valve opening. Enter values at four positions (25 / 50 / 75 / 100%) and the solver interpolates during the run. Recommended for equal-percentage and quick-opening trims where the coefficients vary significantly with opening.
   See Valve Sizing for the IEC 60534 equations these parameters feed.
6. Drag a Tee to split flow downstream of the FCV. Keep K-factor mode on Auto.
7. Drag two Sinks — one for each branch. Set both to Mode = Pressure, Pressure = 101.325 kPa(a) (or equivalently 0 kPa(g)) — these represent the branches discharging to atmospheric conditions (an open tank, a vent to air, the room). The sink is what gives the flow somewhere to go; without a sink (or a Tank used as an outlet) the network has no outlet boundary and the solver can't develop any flow.
8. Connect the chain. Drag from Source's outlet handle to the Pump's inlet — a pipe appears. Continue: Pump → Cartridge Filter → FCV → Tee's inlet, then Tee's run → Sink 1, Tee's branch → Sink 2. At this point the canvas only shows the topology — flow direction, velocities, and pipe colouring only appear after a successful simulation run.
9. Configure each pipe — material, schedule, size, then length. Click a pipe to open its property panel and work top-down:
   1. Material — pick from the dropdown (stainless steel, carbon steel, PVC, copper, etc.). This sets the default roughness for the surface finish.
   2. Schedule — pick the pressure schedule (e.g. Sch 10S, Sch 40, Sch 80) for steel, or the SDR / pressure class for plastic. This determines wall thickness for a given nominal size.
   3. Nominal size — pick from the dropdown (e.g. DN 100 / 4").
   4. Internal diameter, wall thickness, and surface roughness auto-populate from the material + schedule + size combination. Override any of them with manufacturer data if you have it.
   5. Length — the developed length of pipe between the two connected fittings.
10. Tip — pipe property inheritance. When you create a new pipe, its properties pre-fill with the values you last used (material, schedule, size, roughness, length). This makes building runs of similar pipe quick: configure pipe 1 fully, then for pipes 2, 3, 4 you only need to adjust whatever changes (typically just the length). Use the unit dropdown next to any numeric input to switch between metric and imperial if your data source disagrees with the displayed unit.
11. Sanity check before simulating. Look for amber ! indicators. None should remain. Verify the minimum requirements callout: Source ✓, Sink ×2 ✓, connected path ✓, fluid set ✓, non-zero diameters ✓, Custom Component Kv set ✓.
12. Click Run. The toolbar shows Auto solver — for water (a liquid) it routes to the Incompressible solver automatically. The solve completes in a few seconds. Node result badges (pressure and flow at each component) appear on the canvas right away. Pipes stay neutral until you pick an overlay metric — see the next step.
13. Read the results. Open the overlay dropdown in the toolbar (defaults to No Overlay) and pick a metric: Velocity to spot any pipes outside the 1–3 m/s comfort range, Pressure for the pressure profile along the chain, or Reynolds, Flow rate, Mach. Pipes recolour live; switching overlays doesn't re-run the solve. Node badges showing pressure and flow are already on — toggle them off with the Node results button if the canvas feels busy.
14. Open Reports. Tabular results for every node and edge. Export as PDF, CSV, or XLSX for the design file.

Once this works, the patterns repeat at scale. Replace Source with a tank, fan out with more tees, add elbows where the geometry bends. Read Components for the full catalog and Troubleshooting if anything fails to converge.

Canvas controls

• Snap / Grid — toggle snap-to-grid and grid visibility in the toolbar; aligns nodes to a 15px grid.
• Rotate — select a node and press R to rotate it (0/90/180/270 degrees).
• Undo / Redo — Ctrl+Z / Ctrl+Shift+Z (up to 50 steps).
• Save — Ctrl+S or the Save button. Projects also auto-save before each simulation run.

Components

SimuPipe provides 12 component types. Drag them from the catalog in the left sidebar onto the canvas, then configure properties in the right panel.

K-factor modes

Fittings (elbow, reducer, tee, valve) have a K-factor mode: Auto calculates K from Crane TP-410 correlations based on geometry. Manual lets you enter a fixed K value directly.

See Connections for handle rules and how pipe diameter and elevation are inherited from connected nodes.

Connections

A pipe is created by dragging from one node's handle to another. The rules below explain which handles accept connections and how pipe diameter and elevation values are kept in sync with the nodes at each end.

Handle rules

• Default: each handle accepts one pipe. Drag from a handle on one node to a handle on another to create a pipe.
• Source: single connection only — one outbound pipe.
• Sink: accepts multiple inbound pipes on the inlet handle.
• Tank: accepts multiple connections on both the inlet and outlet handles, so it can act as a junction.
• Tee: three named legs — inlet, run, and branch. Each accepts one pipe. Solver loss correlations depend on which leg is the branch.
• Elbow / Reducer: two handles (in / out), one pipe each. Reducers connect two different pipe diameters; the upstream and downstream values are taken from the connected pipes.
• Invalid connections (e.g., a second pipe on a single-connection handle, or a self-loop) are blocked at drag time — the pipe will not form.

Diameter inheritance

• Pipes drive component sizes. Connecting a pipe to a fitting (elbow, valve, tee, reducer, flowmeter, orifice plate, custom component) sets the fitting's nominal diameter to the pipe's diameter.
• Edits propagate both ways. Changing a pipe diameter updates connected components; changing a component's nominal diameter updates the pipes attached to it.
• Reducers are the exception. A reducer holds two diameters (upstream / downstream) — the inlet pipe sets the upstream value, the outlet pipe sets the downstream value.
• Mismatch warnings. Elbows and reducers show an amber ! when a connected pipe's diameter disagrees with the fitting, so drift from auto-propagation is always surfaced.
• Source and Sink nodes don't carry a diameter — they're boundary conditions. Their connected pipe's diameter is independent.

Elevation inheritance

• Nodes hold the canonical elevation. A pipe's start and end elevations are presentation-layer mirrors of the connected nodes — a pipe end and its node are the same physical point. Only the node elevation is read by the solvers.
• Edits propagate both ways. Changing a pipe end elevation updates the connected node, and vice versa.
• New pipes default to horizontal. A fresh target node inherits the source's elevation when first connected. If the target is already wired to other pipes, it keeps its own elevation and the new pipe matches it.
• Drift is surfaced, not hidden. If a pipe end's elevation differs from its connected node by more than 1e-6 m (typically from an imported file or stale data), the pipe shows an amber ! indicator. Any edit on either end re-syncs them.
• Geometric impossibility check. If a pipe's vertical rise (|end − start|) exceeds its length, it shows an amber ! — the pipe cannot physically fit between those two points.
• EPANET imports are auto-reconciled: EPANET stores elevations on junctions but not on pipes, so SimuPipe pulls each pipe end from its connected node at parse time. No drift warnings on a fresh import.

Units

SimuPipe stores all values in SI internally (metres, m³/s, Pa, °C, kg/m³, Pa·s) and converts at the UI boundary. Every numeric input has a unit dropdown next to it — click it to switch the unit you type and read in. The stored value never changes.

Default units

Diameter range

SimuPipe supports nominal diameters from DN 8 (8 mm) to DN 1200 (1.2 m). If a pipe or component diameter is outside this range, you almost certainly typed the wrong unit (e.g. 2.5 intending inches but the input was set to meters). Switch the unit dropdown to in, mm, or DN before typing if you're working from imperial or nominal-size data.

Volumetric vs standard vs mass flow

For gases, SimuPipe distinguishes three families of flow units. They differ by what's held constant: density (volumetric), reference conditions (standard), or matter itself (mass).

For liquids, density is approximately constant, so actual and standard volumetric flow are interchangeable in practice. For gases the difference can be 5–10× depending on pressure, so always check which unit you're typing in.

Pressure: gauge vs absolute

SimuPipe displays pressures as gauge by default (relative to atmospheric, 101.325 kPa). Switch to bar(a), kPa(a), or psi(a) to enter and read absolute values. Internally, all solver math uses absolute pressure.

Simulation

Solver modes

SimuPipe has three solvers. By default, the solver is selected automatically based on the fluid type:

• Incompressible (Q‑H) — for liquids (water, oil, glycol, etc.). Solves for volumetric flow rate Q and hydraulic head Hat each node.
• Isothermal Compressible (P‑ṁ) — for gases (air, nitrogen, refrigerants, etc.). Assumes constant temperature throughout the network. Solves for mass flow rate and absolute pressure at each node. Supports Peng-Robinson EOS for non-ideal gases (refrigerants, CO₂, ammonia, hydrocarbons).
• Adiabatic Compressible (P‑ṁ‑T) — for insulated gas pipes, high-velocity flow, and relief systems where temperature changes are significant. Solves for mass flow, pressure, and temperature at each node using stagnation enthalpy conservation (Fanno flow). Gas cools as it expands through friction — results include temperature at every node and pipe inlet/outlet.

You can override the auto-selection in the toolbar if needed. The isothermal solver is the default for compressible fluids. Select Adiabatic when modelling insulated pipelines, high pressure-drop systems, or when temperature distribution matters.

Friction models

Two friction models are available, selectable in the toolbar:

• Darcy-Weisbach (default) — uses absolute pipe roughness and the Colebrook-White equation for friction factor. Works for both liquids and gases.
• Hazen-Williams — uses a dimensionless C-factor per pipe material (e.g., PVC: 150, steel: 120). Only valid for incompressible liquids — selecting it with a compressible fluid will return an error. Commonly used in water distribution.

Both roughness and C-factor values are stored on each pipe, so switching models does not lose data.

Reading results

After a successful simulation, results are shown in two ways:

• Pipe overlays — colour-coded pipes with labels. Use the overlay dropdown to switch between velocity, pressure, Reynolds number, flow rate, and Mach number.
• Node badges — toggle the Tags button in the toolbar to show pressure and flow results on each node.
• Reports page — detailed tabular results for all nodes and pipes. Export as PDF, CSV, or Excel (XLSX).

Warnings and errors

Two layers of feedback help you catch problems early.

Pre-simulation validation (amber ! on canvas)

Runs continuously while you edit. Hover any node or pipe with an amber indicator to see the specific message. Triggers include:

• Disconnected node — no pipes attached
• Source or Sink missing flow/pressure configuration
• Pipe length = 0 or diameter = 0
• Manual valve with Kv = 0 (set Kv or switch to Auto K-factor)
• Custom Component with both K-factor = 0 and Kv = 0
• Reducer diameters don't match connected pipes
• Elbow or reducer with diameter mismatch vs the connected pipe
• Pipe elevation drift vs connected nodes (> 1e-6 m)
• Pipe vertical rise greater than its length (geometrically impossible)
• Closed valve (openPercent = 0) on the only path to a sink
• Source flow rate that exceeds the network's natural capacity

Solver warnings (toast after a successful run)

Appear when the simulation converges but reveals physical or operating-envelope concerns. Each toast links to the relevant Troubleshooting entry. Includes:

• Reynolds number outside the correlation's validated range (very low laminar / very high turbulent)
• Mach number above 0.3 — compressibility effects becoming significant
• Choked flow at a gas valve (x ≥ F_k × x_T)
• Cavitation at a liquid valve (vena-contracta below vapor pressure)
• BPV / PRV setpoint not enforced (regulator demoted to wide-open)
• FCV setpoint unachievable (Kv saturated)
• Pump operating beyond its rated H-Q curve range
• Source flow rate doesn't match sum of sink flows (continuity imbalance > 1%)

Hard errors (e.g., self-loops, fluid missing on Source) block save with a red banner so the model never reaches the solver in an unrunnable state.

Troubleshooting

Common symptoms and fixes. If your issue isn't here, click Report Issue in the sidebar (signed in) or footer (anywhere) and we'll take a look.

Import / Export

Import

• SimuPipe JSON — native format (.json or .simupipe.json). Import from the dashboard or editor menu.
• EPANET .inp — import EPANET input files. SimuPipe auto-detects US/SI units from the [OPTIONS] section and the headloss model (Darcy-Weisbach or Hazen-Williams). Mapping: reservoirs become sources, junctions become tanks, pumps and valves are inserted as nodes with connector pipes. Pump [CURVES] are parsed and fitted to quadratic H-Q curves.

Export

• PNG — snapshot of the canvas diagram from the editor.
• PDF — full simulation report from the Reports page, including the network diagram and all tabular results.
• CSV / Excel — tabular data (node results, pipe results) from the Reports page.
• JSON — export the network model as a SimuPipe JSON file for backup or sharing.

Valve Sizing

Valves and control valves in compressible flow use the IEC 60534-2-1 standard for gas valve sizing. This section explains the key parameters.

Kv and Cv

Kv (metric) and Cv (imperial) express the flow capacity of a valve. Kv is the flow of water in m3/h that produces a 1 bar pressure drop. Cv is the equivalent in US gallons/min with a 1 psi drop. The conversion is Cv = 1.156 x Kv. SimuPipe uses Kv internally and converts for display when imperial units are selected.

x_T — critical pressure ratio factor

x_T characterises when a valve reaches choked flow. It depends on the valve's internal geometry. Typical values range from 0.5 (globe valve) to 0.8 (ball valve). The default is 0.7. Lower x_T means the valve chokes at a smaller pressure drop.

Choking detection

Choked flow occurs when the pressure ratio x = ΔP/P₁ reaches the choke point x_choked = F_k × x_T (where F_k = ratio of specific heats factor). At this point, increasing the pressure drop no longer increases flow. SimuPipe detects choking automatically and caps the expansion factor Y at ⅓. The simulation warns you when a valve is choked.

Position-dependent curves

For more accurate modelling, you can define how x_T and F_L vary with valve opening position. Switch the valve curve mode to "Position Dependent" and enter data points for each position (e.g., 25%, 50%, 75%, 100% open). SimuPipe interpolates between points during simulation.

Compressibility factor Z

For non-ideal gases (refrigerants, CO₂, ammonia, hydrocarbons), SimuPipe computes Z from the Peng-Robinson equation of state rather than assumingZ = 1. This improves accuracy for high-pressure or near-saturation conditions. Near-ideal gases (air, N₂, O₂, H₂) use Z = 1 directly.

F_L — liquid pressure recovery factor

F_L describes how much pressure is recovered downstream of the valve vena-contracta. A lower F_L means less pressure recovery and earlier onset of cavitation. Typical values: globe valve 0.8–0.9, butterfly 0.55–0.70, ball 0.60–0.80. F_L can be set as a fixed value or vary with valve position using position-dependent curves.

Liquid cavitation detection

For liquid (incompressible) flow, SimuPipe checks whether the pressure at the valve vena-contracta drops below the fluid's vapor pressure, which causes cavitation — the formation and collapse of vapor bubbles that can damage the valve and piping. The check uses the IEC 60534 criterion:

Cavitation occurs when: ΔP > F_L² × (P₁ − F_F × P_v)

• F_L — liquid pressure recovery factor (set on the valve).
• P₁ — upstream absolute pressure at the valve.
• P_v — vapor pressure of the fluid at flowing temperature. Automatically populated from the fluid preset (e.g., water at 20 °C = 2.34 kPa). Editable on the source node.
• F_F — liquid critical pressure ratio factor, computed as F_F = 0.96 − 0.28 × √(P_v/P_c), where P_c is the fluid's critical pressure (also from the preset).

When cavitation is detected, a warning appears in the simulation results showing the actual pressure drop versus the choked limit. The simulation still converges — the warning guides you to modify your design (e.g., reduce pressure drop, use a different valve, or add a downstream restriction).

Cavitation checks apply to valves, control valves, and custom components operating in Cv/Kv mode. Components using K-factor mode also receive cavitation warnings when the pressure drop exceeds the threshold.

For quick Cv/Kv conversions and sizing calculations without building a full network, try the free Valve Cv/Kv Calculator.