DRNX — instrukcja techniczna

Dokument dla projektanta sprawdzającego oraz dla zespołu utrzymującego kod. Opisuje, co aplikacja liczy, jak to liczy i jak wynik zweryfikować.

1. Architektura w jednym akapicie

Aplikacja jest pojedynczym plikiem index.html bez zależności zewnętrznych i bez CDN. Kod dzieli się na warstwy: teren, hydrologia, hydraulika, silnik doboru, silnik rysunkowy, writer PDF, eksporty, testy. Wszystkie obliczenia w jednostkach SI; konwersja wyłącznie przy wyświetlaniu. Żaden współczynnik normowy nie jest zaszyty w kodzie — wszystkie pochodzą z obiektu profilu, którego odpowiednik w formie edytowalnej leży w profiles/.

2. Symbole

3. Hydraulika przewodów zamkniętych

3.1 Prandtl–Colebrook

Prędkość wyznaczana jawnie, bez iteracji:

$$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)$$

gdzie D_h = 4R_h. Dla przewodu pełnego D_h = D.

Zakres: przepływ turbulentny. Dla Re < 4000 wynik jest orientacyjny.

Źródło: [DO WERYFIKACJI: DWA-A 110].

Implementacja: velocityPC(Dh, I, kb).

3.2 Geometria napełnienia

$$\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}$$

Implementacja: circGeom(D, h).

3.3 Odwrócenie Q \to h

Bisekcja na h \in (0;\,0{,}938D], 80 iteracji, tolerancja 10^{-6} m.

Dlaczego górna granica 0,938 D. Maksimum przepustowości przekroju kołowego występuje przy h/D \approx 0{,}938. Powyżej tej wartości funkcja Q(h) przestaje być monotoniczna i rozwiązanie nie jest jednoznaczne. Ograniczenie zakresu gwarantuje zbieżność. Przekroczenie sygnalizuje przepływ pod ciśnieniem — funkcja fillForQ zwraca wtedy null, a silnik doboru przechodzi do większej średnicy.

3.4 Kryteria kontrolne

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

Fr > 1 oznacza przepływ rwący i możliwość odskoku hydraulicznego w studni.

4. Kanały otwarte

Przekrój trapezowy:

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

Głębokość normalna z równania Manninga, rozwiązywana bisekcją. Głębokość krytyczna z warunku Fr = 1, również bisekcją. Wolna burta: \max(0{,}20;\ 0{,}25h).

Implementacja: trapezoid, openChannel.

5. Hydrologia

5.1 Wzór Błaszczyka (profil PL)

$$q = \frac{6{,}631\;\sqrt[3]{H^2C^2}}{t^{0{,}667}} \qquad [\mathrm{dm^3/(s\cdot ha)}]$$

Zakres: t = 5\ldots180 min. Źródło: [DO WERYFIKACJI: Błaszczyk 1954].

5.2 Krzywe IDF (profil DE)

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

Parametry z pliku profilu. Źródło: [DO WERYFIKACJI: KOSTRA-DWD — wartości przybliżone].

5.3 Metoda racjonalna

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

Warunek stosowalności: czas trwania deszczu równy czasowi koncentracji zlewni.

5.4 Deszcz krytyczny

Przeszukiwany zbiór t \in \{5,10,15,20,30,45,60,90,120,180\} min. Wybierany czas dający największy przepływ, nie największe natężenie. Wynik raportowany w panelu bocznym.

5.5 Hietogramy

Niezmiennik weryfikowany testem: każdy hietogram zachowuje sumę opadu z błędem poniżej 1 %. Zmierzony błąd wynosi 0,0000 %.

5.6 Delimitacja D8

• Wypełnianie zagłębień — priority flood (Wang & Liu) na kopcu binarnym; inicjalizacja z brzegu rastra, epsilon 10^{-4} m.
• Kierunki spływu — D8 na ośmiu sąsiadach, odległość skośna mnożona przez \sqrt2.
• Akumulacja — porządek malejących rzędnych wypełnionych.
• Przypisanie do węzłów — sieć rasteryzowana jako korytarz odbiorczy o szerokości trzech komórek; każda komórka wędruje w dół stoku aż napotka korytarz, z memoizacją ścieżki.

Limit 16 mln komórek. Na terenie demonstracyjnym: 196–300 ms.

6. Algorytm doboru

Kolejność: od wylotu w górę sieci, zgodnie z porządkiem topologicznym.

dla każdego odcinka i:
    I ← max(spadek terenu, I_min)
    dopóki I ≤ I_max:
        dla każdej średnicy D z katalogu rosnąco:
            jeśli D < D_poprzednie:        pomiń
            jeśli I < 1/DN oraz I < I_min: pomiń
            h ← fillForQ(D, Q_i, I, k_b)
            jeśli brak rozwiązania:        pomiń        (przepływ pod ciśnieniem)
            jeśli h/D > (h/D)_max:         pomiń
            jeśli v > v_max:               pomiń
            jeśli v < v_min oraz τ < τ_min: pomiń
            K ← c_rura(D)·L + c_wykop·V + c_studnia
            zapamiętaj wariant o najmniejszym K
        jeśli znaleziono wariant: zakończ
        I ← I + 0,0005

Funkcja celu:

$$K_i = c_{rura}(D)\,L + c_{wykop}\,V + c_{studnia}, \qquad V = L\,(c_{min}+D+0{,}15)\,(D+0{,}8)$$

Ograniczenia twarde

Rzędne dna

Pierwszy odcinek: z_{dna} = z_{terenu} - c_{min} - D.

Kolejne, łączenie po sklepieniu:

$$z_{dna,i} = \min\!\left(z_{dna,i-1}^{\,dół},\; z_{dna,i-1}^{\,dół} + D_{i-1} - D_i\right) - \Delta_{studnia}$$

Jeżeli tak wyznaczona rzędna daje przykrycie większe niż wymagane, zostaje podniesiona do poziomu wynikającego z przykrycia minimalnego — algorytm nie zakopuje kanału głębiej, niż to konieczne.

7. Fala kinematyczna

Równanie ciągłości rozwiązywane schematem jawnym upwind, z relacją kinematyczną Q = Q(A) wyznaczaną z Prandtla-Colebrooka:

$$A_i^{\,n+1} = A_i^{\,n} + \frac{\Delta t}{\Delta x}\left(q_{góra} + q_{boczny} - Q_i^{\,n}\right)$$

• Krok czasowy 5 s, czas symulacji 1 h (720 kroków).
• Dopływ boczny rozłożony wzdłuż odcinków proporcjonalnie do ordynaty hietogramu.
• Przekroczenie pojemności przekroju (0,98 D) daje objętość zalania w węźle poniżej.
• Bilans ciągłości: \varepsilon = |V_{we} - V_{wy} - \Delta V_{ret} - V_{zal}| / V_{we} \cdot 100\%, wymagane < 1\%.
• Warunek Couranta: Cr = v\Delta t/\Delta x \le 1, monitorowany i raportowany.

Zmierzone dla sieci demonstracyjnej: \varepsilon = 0{,}0000\%, Cr_{max} = 0{,}462, czas 34 ms.

8. Silnik rysunkowy i wierność skali

8.1 Zasada nadrzędna

Rysunek jest autorowany w milimetrach arkusza. Lista prymitywów (l linia, r prostokąt, p polilinia, f wypełnienie, t tekst) trafia do dwóch konsumentów:

• podgląd SVG — viewBox w milimetrach, atrybut width przeskalowany przez współczynnik podglądu;
• writer PDF — te same współrzędne przemnożone przez 72/25{,}4 = 2{,}834645669.

Ekran nie ma wpływu na PDF. Rasteryzacja jest zakazana — nie używa się html2canvas, dom-to-image ani canvas.toDataURL.

8.2 Transformacja

$$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}$$

Przewyższenie S_H/S_V jest wypisywane w tabelce rysunkowej.

8.3 Weryfikacja

Na każdym rysunku umieszczany jest znacznik kontrolny o znanej odległości terenowej (100 m na profilu, szerokość wykopu na przekroju). Test odbiorczy mierzy jego długość w gotowej geometrii i porównuje z wartością teoretyczną. Tolerancja ±0,1 %; zmierzony błąd wynosi 0,000000 %.

Dodatkowo test sprawdza MediaBox w strumieniu PDF (A3 = 1190,551 × 841,890 pt) oraz brak obiektów /Subtype /Image.

8.4 Writer PDF

Własny writer generuje PDF 1.7 z pięcioma obiektami: katalog, drzewo stron, strona, strumień treści, font. Font Helvetica z kodowaniem WinAnsi; znaki diakrytyczne są transliterowane tablicą MAP. Tabela xref budowana z rzeczywistych przesunięć bajtowych.

9. Model danych i format .drnx

Plik .drnx jest dokumentem JSON zawierającym:

schemaVersion, engineVersion, name
crsHorizontal, crsVertical
designProfileId, designProfileHash
route[], nodes[], conduits[]
terrainMeta        (bez tablicy rastra)
results            (wiersze + raport zgodności)
manifest.inputHash (SHA-256 całego dokumentu)

Migracje: przy odczycie porównywana jest schemaVersion. Wersja starsza uruchamia sekwencję migracji; wersja nowsza w zakresie major powoduje odmowę otwarcia z komunikatem o wymaganej aktualizacji.

Audytowalność: designProfileHash i inputHash pozwalają odtworzyć, która wersja reguł i jakie dane wejściowe dały zapisany wynik.

10. Testy odbiorcze

22 testy uruchamiane w przeglądarce przyciskiem w panelu 6.

Weryfikacja zewnętrzna

Eksport .inp umożliwia przeliczenie tej samej sieci w EPA SWMM. Zalecana procedura sprawdzającego: porównać Q i h w wylocie; rozbieżność powyżej 2 % wymaga wyjaśnienia.

11. Budżety wydajnościowe

12. Struktura kodu

Konwencja: komentarze w kodzie po angielsku, interfejs dwujęzyczny, nazwy zmiennych jednoznaczne inżyniersko.