# Petrel Flow Accumulation — Layers — release notes Rolling version history for the Petrel Flow Accumulation **Layer** — DEM-derived drainage structure at ~278 m (9 arcsec) globally: distance-to-drainage and the topographic wetness index (TWI). Newest release first. --- ## v0.3 · 2026-09 - **The v0.1 drainage under-count is fixed, not just documented.** v0.1 derived flow per 10° tile, so any catchment crossing a tile boundary was truncated. Measured at reference gauges with published upstream areas, v0.1 captured **2.5–19.3%** of true drainage. v0.3 captures: | gauge | v0.1 | v0.3 | published upstream area | |---|---|---|---| | Amazon @ Óbidos | 5.6% | **99.8%** | 4,680,000 km² | | Congo @ Kinshasa | 19.3% | **97.3%** | 3,475,000 km² | | Mississippi @ Vicksburg | 8.9% | **99.4%** | 2,964,000 km² | | Nile @ Aswan | 2.5% | **96.6%** | 2,900,000 km² | | Ganges @ Hardinge Bridge | 3.0% | **100.3%** | 950,000 km² | | Danube @ Ceatal Izmail | 14.2% | **98.2%** | 807,000 km² | | Volga @ Volgograd | — | **100.4%** | 1,360,000 km² | | Amu Darya @ Kerki | — | **94.3%** | 309,000 km² | | Ural @ Atyrau | — | **90.0%** | 231,000 km² | - **Drainage is measured in area, not cells, across latitude.** A grid cell is a different area at every latitude, and an earlier build re-counted drainage at the receiving tile's cell size wherever a river crossed a north–south tile seam: the Mississippi read 108.6% (it flows south, into larger cells) and the Nile 90.0% (north, into smaller ones). v0.3 carries drainage in area units across every seam. - **Large reservoirs route through, not around.** Flat water gives a DEM no gradient, and the Volga was severed inside the Kuybyshev Reservoir where its confluence with the Kama sits on a tile seam (an earlier build read 15.5% at Volgograd). The eight Volga/Kama reservoirs (Rybinsk, Cheboksary, Kama, Votkinsk, Nizhnekamsk, Kuybyshev, Saratov, Volgograd; HydroLAKES polygons, CC BY 4.0) are now treated as nodes: everything entering a reservoir leaves at its dam and follows the mapped river (Natural Earth centerlines, public domain) to the next. Other lakes keep DEM routing. Reading the rasters over one of those reservoirs: the water surface is **channel**, so distance-to-drainage is 0 there, and its contributing area is the drainage passing through it. Rybinsk carries 155,766 km² against an independently published watershed of 150,074 km². - **TWI is corrected on major rivers.** `TWI = ln(a / tan β)` is a logarithm of accumulation, so v0.1's truncation read straight through. Recomputed from the corrected network, TWI rises **+2.70 units** on the Amazon mainstem (drainage > 1M km²) and is unchanged on hillslopes — the v0.1 note predicted 1.7–3.7 units low on major basins, and that is what it was. - **Channel threshold is now an area, not a cell count.** v0.1 used 1000 accumulated cells, which is 77 km² at the equator but 39 km² at 60°N, so the definition of "a river" drifted with latitude. v0.3 uses a fixed **1 km²** everywhere, giving a denser and latitude-consistent stream network; median distance-to-drainage over the Amazon tile drops from 3,345 m to 393 m. - **Bare-earth terrain and a true land mask.** Built on GEDTM30 bare earth (buildings and canopy do not dam a river), and the flow network is now masked to the canonical GSHHG-f shoreline. v0.1 routed the ocean as if it were flat terrain, which inflated coastal cells. - **Closed basins terminate.** Water reaching the Caspian, the Aral, Lake Chad, Lake Eyre, the Tarim or a Saharan sebkha now ends there, as it does in nature, instead of being pushed onward. Sinks are derived from the DEM by depression-fill depth, not a hard-coded list. - **Known limitations.** - **The Ural is under-counted** (~90% at Atyrau) and the Nile and Amu Darya sit at 94–97%: DEM routing through flat steppe and delta terrain still loses tributary area at a few points. Treated in a later release. - **Lakes other than the Volga/Kama cascade keep DEM routing.** Inside a large flat lake the flow direction is arbitrary; drainage entering a lake is conserved, but where it leaves may differ from the true outlet. A global lake-node treatment was built and measured; it fixed the Volga and broke four other basins at floodplain lakes, so it is not shipped. - **Zoomed-out views no longer show values over open ocean.** Distance to drainage is capped at 50 km, which encodes one step below the NoData code, so building reduced-resolution overviews by blending mixed land/ocean cells could land exactly on the cap. Scattered ocean pixels appeared in zoomed-out maps, including in v0.1 and v0.2. The band now builds its overviews without blending. - **Small islands saturate the distance cap.** An island too small to carry a 1 km² channel has no channel at all, so every cell on it reads the 50 km ceiling. That is 1,683 cells worldwide (118 km², 0.00007% of scored land) — the Coral Sea cays, the Bahamas, the north-west Hawaiian atolls, the Marianas. Read it as "no modelled channel here", not as a distance. - **TWI saturates on the largest rivers.** It is a logarithm of contributing area capped at 35, so a correction to drainage of tens of percent moves it by a fraction of a unit and not at all where it is already at the cap. - Distance-to-drainage and TWI are per-cell terrain indices, not flood extents; see the layer template for intended use. ## v0.1 · 2026-07 > **Live since 2026-07-28.** (A previous version of this file still read "not > yet live" months after publication, and its heading carried no month, so the > generated site changelog silently skipped the entry — the date parser needs > `## vX.Y · YYYY-MM`.) - **Initial release.** Flow accumulation and its drainage sub-layers derived entirely from the **Copernicus GLO-30 DEM** (pysheds fill → flow-direction → accumulation), so the product is Petrel-owned and carries no third-party redistribution obligations. Ships two sub-layers at **~278 m (9 arcsec)** globally: **distance-to-drainage** (metres to the nearest channel, ≥1000 accumulated cells) and the **topographic wetness index** (TWI). Raw accumulation is held as an internal intermediate for this vintage. - **A commercially-clean replacement for HydroSHEDS/HydroRIVERS.** Built as a drop-in drainage layer whose single permissive input lets it be both given back to the community (CC-BY-NC-4.0) and embedded cleanly inside Petrel's paid hazard models — the copyleft-flavoured HydroSHEDS licence never touches them. - **Native-honest resolution.** Ships at the true 9 arcsec derivation grid (`_278m`), not an interpolated 90 m; the filenames carry the real resolution. - **v0.1 caveat — QUANTIFIED 2026-09-09, and TWI is affected.** Derivation is halo-tiled (~110 km overlap), so accumulation is under-counted wherever a catchment crosses tiles. ⚠ **RE-MEASURED 2026-09-11 — the figures below replace an earlier set (Amazon 7.8%, Mississippi 10.4%, Congo 17.5%, Nile 22.7%, Danube 30.1%) that was measured with the wrong instrument and UNDERSTATED the shortfall.** Those took each 10-degree tile's maximum cell as the basin value; a tile maximum is whatever river is largest in that box, and on a network that had no land mask it was frequently seawater draining into a coastal cell rather than a river at all. Re-measured at reference gauges with published upstream areas, the capture is: | gauge | captured | published upstream area | |---|---|---| | Amazon @ Óbidos | **5.6%** | 4,680,000 km² | | Congo @ Kinshasa | 19.3% | 3,475,000 km² | | Mississippi @ Vicksburg | 8.9% | 2,964,000 km² | | Nile @ Aswan | **2.5%** | 2,900,000 km² | | Ganges @ Hardinge Bridge | 3.0% | 950,000 km² | | Danube @ Ceatal Izmail | 14.2% | 807,000 km² | The cause is also broader than halo truncation alone: the v0.1 conditioning left major rivers terminating on unresolved pits *mid-tile*, which under-counts exactly like a tile-edge cut. ⚠ **An earlier version of this entry said "channel geometry, distance-to-drainage and TWI are correct". That was wrong about TWI.** `TWI = ln(a / tan β)` is a direct logarithm of the under-counted quantity, so the corrected fractions above imply TWI reads **1.7–3.7 units low** on those major basins (ln of the captured fraction; the earlier entry said 1.2–2.6, derived from the superseded figures) — a wetness class on a 0–25 scale, not a rounding error. Widening the halo cannot fix it (the Amazon is ~3,000 km); a Barnes-style global two-pass accumulation is the v1 upgrade. **Unaffected:** local and small-catchment terrain, where the contributing area is contained within a tile, and the relative drainage structure within a tile. `distance_to_drainage` is thresholded from the same accumulation so it shares the dependency; its error has not been measured and is not claimed here. Antarctica is excluded by standard. - **Free, non-commercial Layer.** Distributed under CC-BY-NC-4.0; a derived input data product rather than a paid Hazard. Commercial use is licensed separately.