DRNX — technical manual

Written for the checking engineer and for the team maintaining the code. It describes what the application computes, how it computes it, and how to verify the result.

1. Architecture in one paragraph

The application is a single index.html file with no external dependencies and no CDN. The code is layered: terrain, hydrology, hydraulics, sizing engine, drawing engine, PDF writer, exports, tests. All computation uses SI units; conversion happens only at display time. No normative coefficient is hard-coded — every one comes from the profile object, whose editable counterpart lives in profiles/.

2. Symbols

3. Closed-conduit hydraulics

3.1 Prandtl–Colebrook

Velocity is obtained explicitly, without iteration:

$$v = -2\sqrt{2\,g\,D_h\,I}\;\log_{10}\!\left(\frac{2.51\,\nu}{D_h\sqrt{2\,g\,D_h\,I}} + \frac{k_b}{3.71\,D_h}\right)$$

where D_h = 4R_h. For a full pipe D_h = D.

Range: turbulent flow. Below Re = 4000 the result is indicative only.

Source: [TO BE VERIFIED: DWA-A 110].

Implementation: velocityPC(Dh, I, kb).

3.2 Partial-flow geometry

$$\theta = 2\arccos\!\left(1 - \frac{2h}{D}\right)$$

$$A = \frac{D^2}{8}(\theta - \sin\theta), \qquad U = \frac{D\theta}{2}, \qquad B = D\sin\frac{\theta}{2}$$

Implementation: circGeom(D, h).

3.3 Inverting Q \to h

Bisection over h \in (0,\,0.938D], 80 iterations, tolerance 10^{-6} m.

Why the 0.938 D ceiling. Maximum capacity of a circular section occurs near h/D \approx 0.938. Above that value Q(h) ceases to be monotonic and the solution is not unique. Bounding the search guarantees convergence. Exceeding capacity signals pressurised flow — fillForQ then returns null and the sizing engine moves to a larger diameter.

3.4 Control criteria

$$\tau = \rho\,g\,R_h\,I, \qquad Fr = \frac{v}{\sqrt{g\,A/B}}$$

Fr > 1 indicates supercritical flow and a possible hydraulic jump at the manhole.

4. Open channels

Trapezoidal section:

$$A = bh + mh^2, \qquad U = b + 2h\sqrt{1+m^2}, \qquad B = b + 2mh$$

Normal depth from the Manning equation, solved by bisection. Critical depth from Fr = 1, also by bisection. Freeboard: \max(0.20,\ 0.25h).

Implementation: trapezoid, openChannel.

5. Hydrology

5.1 Błaszczyk formula (PL profile)

$$q = \frac{6.631\;\sqrt[3]{H^2C^2}}{t^{0.667}} \qquad [\mathrm{dm^3/(s\cdot ha)}]$$

Range: t = 5\ldots180 min. Source: [TO BE VERIFIED: Błaszczyk 1954].

5.2 IDF curves (DE profile)

$$q = \frac{a\,C^{\,m}}{(t+b)^{\,c}}$$

Parameters come from the profile file. Source: [TO BE VERIFIED: KOSTRA-DWD — approximate values].

5.3 Rational method

$$Q = \psi\,q\,F$$

Valid when storm duration equals the catchment time of concentration.

5.4 Critical storm

The set t \in \{5,10,15,20,30,45,60,90,120,180\} min is searched. The duration producing the greatest flow is chosen — not the greatest intensity. The result is reported in the side panel.

5.5 Hyetographs

Invariant verified by test: every hyetograph preserves the rainfall depth within 1 %. The measured error is 0.0000 %.

5.6 D8 delineation

• Depression filling — priority flood (Wang & Liu) on a binary heap; initialised from the raster boundary, epsilon 10^{-4} m.
• Flow directions — D8 over eight neighbours, diagonal distance multiplied by \sqrt2.
• Accumulation — in order of descending filled elevation.
• Assignment to nodes — the network is rasterised as a receiving corridor three cells wide; each cell walks downslope until it meets the corridor, with path memoisation.

Limit: 16 million cells. On the demonstration terrain: 196–300 ms.

6. Sizing algorithm

Order: from the outfall upstream, following topological order.

for each reach i:
    I ← max(ground gradient, I_min)
    while I ≤ I_max:
        for each diameter D in ascending catalogue order:
            if D < D_previous:           skip
            if I < 1/DN and I < I_min:   skip
            h ← fillForQ(D, Q_i, I, k_b)
            if no solution:              skip        (pressurised)
            if h/D > (h/D)_max:          skip
            if v > v_max:                skip
            if v < v_min and τ < τ_min:  skip
            K ← c_pipe(D)·L + c_exc·V + c_manhole
            keep the option with the lowest K
        if an option was found: break
        I ← I + 0.0005

Objective function:

$$K_i = c_{pipe}(D)\,L + c_{exc}\,V + c_{manhole}, \qquad V = L\,(c_{min}+D+0.15)\,(D+0.8)$$

Hard constraints

Invert levels

First reach: z_{inv} = z_{ground} - c_{min} - D.

Subsequent reaches, crown matching:

$$z_{inv,i} = \min\!\left(z_{inv,i-1}^{\,down},\; z_{inv,i-1}^{\,down} + D_{i-1} - D_i\right) - \Delta_{manhole}$$

If the resulting level yields more cover than required, it is raised to the minimum-cover level — the algorithm never buries the sewer deeper than necessary.

7. Kinematic wave

The continuity equation is solved with an explicit upwind scheme, with the kinematic relation Q = Q(A) evaluated through Prandtl–Colebrook:

$$A_i^{\,n+1} = A_i^{\,n} + \frac{\Delta t}{\Delta x}\left(q_{up} + q_{lat} - Q_i^{\,n}\right)$$

• Time step 5 s, simulated duration 1 h (720 steps).
• Lateral inflow distributed along reaches in proportion to the hyetograph ordinate.
• Exceeding section capacity (0.98 D) produces flood volume at the downstream node.
• Continuity error: \varepsilon = |V_{in} - V_{out} - \Delta V_{stored} - V_{flood}| / V_{in} \cdot 100\%, required < 1\%.
• Courant condition: Cr = v\Delta t/\Delta x \le 1, monitored and reported.

Measured for the demonstration network: \varepsilon = 0.0000\%, Cr_{max} = 0.462, runtime 34 ms.

8. Drawing engine and scale fidelity

8.1 Governing principle

The drawing is authored in sheet millimetres. A primitive list (l line, r rectangle, p polyline, f fill, t text) feeds two consumers:

• SVG preview — viewBox in millimetres, width scaled by a preview factor;
• PDF writer — the same coordinates multiplied by 72/25.4 = 2.834645669.

The screen has no influence on the PDF. Rasterisation is prohibited — html2canvas, dom-to-image and canvas.toDataURL are never used.

8.2 Transformation

$$x_{mm} = x_0 + \frac{(X - X_{ref})\cdot 1000}{S_H}, \qquad y_{mm} = y_0 - \frac{(Z - Z_{ref})\cdot 1000}{S_V}$$

The exaggeration S_H/S_V is stated in the title block.

8.3 Verification

Every drawing carries a control marker of known ground distance (100 m on the profile, trench width on the cross section). The acceptance test measures its length in the finished geometry and compares it against the theoretical value. Tolerance ±0.1 %; the measured error is 0.000000 %.

The test additionally checks the MediaBox in the PDF stream (A3 = 1190.551 × 841.890 pt) and the absence of /Subtype /Image objects.

8.4 PDF writer

A bespoke writer emits PDF 1.7 with five objects: catalog, page tree, page, content stream, font. Helvetica with WinAnsi encoding; diacritics are transliterated through the MAP table. The xref table is built from actual byte offsets.

9. Data model and the .drnx format

A .drnx file is a JSON document containing:

schemaVersion, engineVersion, name
crsHorizontal, crsVertical
designProfileId, designProfileHash
route[], nodes[], conduits[]
terrainMeta        (without the raster array)
results            (rows + compliance report)
manifest.inputHash (SHA-256 of the whole document)

Migrations: on load, schemaVersion is compared. An older version triggers a migration sequence; a newer major version is refused with a message stating that the application must be updated.

Auditability: designProfileHash and inputHash make it possible to reconstruct which rule version and which inputs produced a stored result.

10. Acceptance tests

22 tests run in the browser from the button in panel 6.

External verification

The .inp export allows the same network to be re-run in EPA SWMM. Recommended checking procedure: compare Q and h at the outfall; a discrepancy above 2 % requires explanation.

11. Performance budgets

12. Code structure

Convention: code comments in English, bilingual interface, engineering-unambiguous variable names.