How FloodTwin Works

FloodTwin is a two-dimensional hydrodynamic flood model of Hoboken, New Jersey and Manhattan's West Side that runs on the graphics card in a web browser. This page documents every data set, processing step, equation and assumption behind the numbers it shows, and how well it reproduces Hurricane Sandy.

Model version 1.0Documented October 2026EntanglixVertical datum NAVD88, horizontal NAD83 / UTM zone 18N

4 mdefault grid; 2 m and 8 m selectable

940,992cells at 4 m over 15.1 km²

13,152buildings with lidar heights

0.17 mmean absolute error at 10 Sandy high-water marks

Overview

The model answers three questions for any flood event on this piece of waterfront: where does the water go (depth, speed and arrival time on a 4 m grid, every fraction of a second of simulated time), how dangerous is it (a hazard-to-people rating), and what does it cost (damage ratio and expected loss for each of the 8,901 buildings with National Structure Inventory records, and for any portfolio of properties loaded into it).

Flood water is computed with the local inertial form of the shallow-water equations, the formulation used in operational inundation models such as LISFLOOD-FP, solved explicitly on a regular grid. The terrain is the USGS 3DEP one-metre lidar surface; buildings are solid obstacles taken from OpenStreetMap footprints with heights measured from lidar point clouds. The sea boundary is the Hudson River, driven by an observed or synthetic water level; rain falls on every land cell. Damage comes from FloodVuln Global, a distributional depth-damage model fitted to 1.86 million National Flood Insurance Program claims.

Everything runs client-side: the browser downloads about 13 MB of prepared data, builds the model grid, and steps the solver in WebGL 2 fragment shaders while it renders the scene. No result on screen is precomputed except the reference validation runs reported below, which were produced by exactly the same code.

Domain and Grid

The domain is a rectangle 4,056 m east to west and 3,712 m south to north in NAD83 / UTM zone 18N (EPSG:26918), from x = 580,472 to 584,528 m and y = 4,509,496 to 4,513,208 m. It covers Hoboken, the southern part of Weehawken and Lincoln Harbor, the edge of Jersey City Heights, 1.3 km of the Hudson River, and Manhattan from the West Village to Hell's Kitchen, including Chelsea, Hudson Yards and the Javits Center. Elevations are metres above NAVD88.

Cell size	Columns × rows	Cells	Typical use
8 m	507 × 464	235,248	Fast screening, integrated graphics
4 m	1,014 × 928	940,992	Default; resolves streets and most alleys
2 m	2,028 × 1,856	3,763,968	Detail: narrow gaps between buildings; about eight times the cost of 4 m

All grids are aggregated from the same 2 m source layers, so a change of resolution changes only the discretisation, not the inputs.

Data Sources

Data	Used for	Detail
USGS 3DEP bare-earth DEM, 1 m	Terrain	Lidar-derived, hydro-flattened; downloaded through the 3DEP ImageServer and mosaicked to the domain
USGS 3DEP lidar point clouds	Building heights, tree canopy	New Jersey 2014 and New York City 2017 collections, 108 million points within the domain, read from the Entwine Point Tile service
USDA NAIP orthoimagery, 0.5 m	Ground imagery, vegetation index, roof colour	Four-band (red, green, blue, near-infrared)
OpenStreetMap	Building footprints and parts, streets	13,152 footprints and 1,034 building parts; © OpenStreetMap contributors, ODbL
USACE National Structure Inventory	Occupancy, values, first-floor height, storeys, foundation, residents	22,463 structure points; 22,334 matched to 8,901 footprints
NOAA CO-OPS 8518750, The Battery	Hurricane Sandy boundary	Six-minute observed and predicted water level, NAVD88, 28 to 31 October 2012
USGS Short-Term Network	Validation	Surveyed high-water marks for Hurricane Sandy (event 24); 10 fall inside the domain
NOAA Atlas 14, Volume 10	Design rainfall	Partial-duration depths for 5 minutes to 60 days, 1 to 1,000 years, at 40.745° N, 74.030° W
FEMA National Flood Hazard Layer	Effective flood zones overlay	54 zone polygons; base flood elevations of 9 and 10 ft NAVD88 in Hoboken
FloodVuln Global	Damage ratios	Zero-and-one inflated beta model of damage against depth above the first floor, with New Jersey and New York calibration

Terrain and Land Cover

River and Boundary Water

The 3DEP surface is hydro-flattened: open water is replaced by a flat surface near −0.5 m. The river is the largest connected region below −0.45 m, plus flat pockets within 40 m of it (larger than 300 m², median between −0.8 and −0.3 m, standard deviation under 0.15 m) that piers separate from the main channel. When the model grid is built, marinas, slips and coves below +0.5 m that connect to the river through cells below +0.5 m are added; every bulkhead and pier deck in the domain is higher than that. These cells form the boundary water: their level is prescribed, not computed.

Resampling

The 1 m surface is block-averaged to 2 m for distribution (encoded as zigzag row differences at 1 cm precision, 2.2 MB compressed), and the model grid averages 2 m blocks to the chosen cell size. A cell is boundary water when more than half of its 2 m sub-cells are river.

Land Cover and Roughness

Vegetation is NAIP near-infrared NDVI above 0.22 outside buildings and water. Each cell's Manning coefficient is the mean over its sub-cells of the class value, and the user can change the paved and green values.

Class	Default Manning n (s/m^1/3)	Losses
Streets, sidewalks and other paved ground	0.016	Drainage capacity
Grass and lawns	0.035	Drainage plus infiltration
Tree canopy	0.060	Drainage plus infiltration
Bare ground and gravel	0.030	Drainage capacity
River	0.030	None (prescribed level)
Porous buildings (option)	0.150	None

Ambient occlusion for display is computed from the lidar surface with buildings, by horizon scanning in 16 directions at 2 m; it affects shading only.

Buildings and Exposure

Footprints and Heights

Footprints and building parts come from OpenStreetMap. Roof height is the 90th percentile of the lidar normalised surface (first returns minus bare earth) inside the footprint; 13,042 buildings take their height this way, 44 use a newer OSM height tag, and the rest fall back to levels or NSI storeys. A footprint becomes a solid obstacle on the grid where buildings cover more than half of a cell. The default treats buildings as watertight blocks that divert flow; the porous option lets water through at high roughness instead.

Ground Level at Each Building

Water depth at a building is measured against the ground at its doors: the median elevation of the open cells on a ring around the footprint (up to eight cells, spread by angle, within four cells of the walls). The footprint statistic in the data, the 10th percentile of the bare-earth surface inside the footprint, is not used for depth because it catches areaways and the low corner of sloping lots, and for structures over water (the Hoboken Terminal train shed, sheds on piers, the USS Intrepid) it is the river surface.

Exposure Attributes

NSI structure points are assigned to the footprint that contains them. Where several fall in one footprint, values, units and residents are summed and the occupancy, foundation, first-floor height, storeys and year come from the most valuable point. 8,901 buildings carry attributes, with $34.5 billion of structure value and 176,034 night-time residents. The remainder are mostly garages, sheds, parts of larger complexes and structures without an NSI record; they are drawn and act as obstacles but carry no loss.

Archetypes

Each NSI occupancy and foundation type maps to a FloodVuln archetype. Where FloodVuln has no curve for the occupancy, the closest available curve is used and the mapping is flagged as a proxy.

NSI occupancy	Foundation or storeys	FloodVuln archetype	Mapping
RES1, single family	Two or more storeys, basement	Single-family, 2 storey, basement	Direct
RES1	Two or more storeys, other	Single-family, 2 storey, slab	Direct
RES1	One storey: slab, crawlspace, pier or pile	Matching 1 storey curve, elevated with enclosure for pier and pile	Direct
RES2, manufactured	Any	Manufactured home	Direct
RES3A and RES3B, two to four units	Any	Small multifamily, 2 storey	Direct for RES3A, proxy for RES3B
RES3C to RES3F, larger multifamily	Any	Small multifamily, 2 storey	Proxy
COM1 retail, COM8 entertainment	Any	Commercial, 1 storey	Direct
Other commercial, industrial, institutional	Any	Commercial, 1 storey	Proxy

Trees and Vehicles

13,209 trees are lidar canopy peaks above 3.5 m in vegetated areas, each with its measured height, a crown radius from the canopy extent in eight directions, and its colour from the aerial image. 26,202 parked vehicles are placed along OSM streets at kerbside spacing to give a sense of scale and motor exposure; their positions are modelled, not observed.

Hydraulic Model

Water depth h and unit discharge q = (q_x, q_y) evolve by conservation of mass and a momentum balance in which the advection term is neglected, the local inertial approximation of Bates et al. (2010). It is accurate for slow, gradually varied urban flood flow and much cheaper and more robust than the full shallow-water equations.

\frac{\partial h}{\partial t} + \frac{\partial q_{x}}{\partial x} + \frac{\partial q_{y}}{\partial y} = R - L

\frac{\partial q_{x}}{\partial t} + g h \frac{\partial η}{\partial x} + \frac{g n^{2} | q | q_{x}}{h^{7 / 3}} = 0

η = z + h is the water surface (m NAVD88), z the bed, g = 9.81 m/s², n Manning's coefficient, R rainfall and L losses to drainage and infiltration (m/s). The y-momentum equation is the same with x and y exchanged.

Numerical Scheme

Depths live at cell centres and discharges on cell faces (a staggered grid): q_x on each east face and q_y on each north face. Each time step updates every face discharge, then every depth.

Momentum

The face discharge uses the θ-weighted form of de Almeida et al. (2012), which damps the checkerboard oscillation of the original scheme in shallow, slow flow, with friction treated semi-implicitly:

q_{i + \frac{1}{2}}^{n + 1} = \frac{θ q_{i + \frac{1}{2}}^{n} + \frac{1 - θ}{2} (q_{i - \frac{1}{2}}^{n} + q_{i + \frac{3}{2}}^{n}) - g h_{f} Δ t \frac{η_{i + 1} - η_{i}}{Δ x}}{1 + g Δ t {n_{f}}^{2} | q^{n} | / h_{f}^{7 / 3}}

θ = 0.8 by default (θ = 1 recovers Bates et al. 2010). |q| uses the face-normal discharge and the average of the four neighbouring cross-face discharges. The flow depth at the face is h_f = max(η_i, η_i+1) − max(z_i, z_i+1) and n_f is the mean of the two cells.

Continuity

h_{i, j}^{n + 1} = h_{i, j}^{n} + \frac{Δ t}{Δ x} (q_{i - \frac{1}{2}, j}^{n + 1} - q_{i + \frac{1}{2}, j}^{n + 1} + q_{i, j - \frac{1}{2}}^{n + 1} - q_{i, j + \frac{1}{2}}^{n + 1}) + Δ t (R - L)

Losses are capped at the water available in the cell, so depth never goes negative.

Stability and Limiters

Time step. Δt = α Δx / max(|u| + √(g h)), α = 0.7 by default, at most 2 s. The maximum is taken over all land cells, and land next to boundary water counts with the depth the boundary stage would give it, so a rising tide never outruns the step. The bound comes from a GPU reduction refreshed every frame and is padded by 15%.
Froude limit. |q| ≤ Fr_max h_f √(g h_f) with Fr_max = 1, which prevents unphysical supercritical jets on steep cells.
Positivity. A face may not drain more than a quarter of the donor cell's water in one step, |q| Δt ≤ h_donor Δx / 4, so four outflowing faces cannot empty a cell below zero.
Wetting and drying. Faces with flow depth under 1 mm carry no flow. Faces into building cells and between two boundary cells carry no flow.

GPU Implementation

The state is stored in 32-bit float textures, one texel per cell: depth, east-face discharge, north-face discharge and the time the cell was last wet. The bed is a second texture holding elevation, Manning n, cell type and loss rate. One time step is two full-screen fragment shader passes, momentum then continuity, so every cell is updated in parallel. The order of operations follows a reference Python implementation line by line, and the two are compared after every change (see Verification).

Reductions. The stable time step, the deepest water, the flooded area and the water volume come from a 4 × 4 reduction pyramid read back asynchronously, so the CPU never waits on the GPU during a run.
Running statistics. Every 10 simulated seconds a pass updates peak depth, first arrival of 10 cm, peak speed and peak hazard rating per cell.
Building sampling. A pass gathers, for every building and high-water mark, the water on the ring of cells around it. The result is read back about twice a second and turned into damage on the CPU.
Snapshots. The state and statistics are copied to half-precision textures every 30 to 60 simulated minutes, within a 160 MB budget, so the timeline can jump back without re-running from the start.
Display field. A last pass writes the water surface, extended one cell into dry ground so it meets the terrain cleanly, with depth and velocity, to a half-float texture that the water, tracers and analysis layers read with hardware filtering.

Boundary Conditions and Scenarios

Hurricane Sandy Replay

The boundary water level is the six-minute observed record at The Battery (NOAA 8518750) on NAVD88, from 17:00 EDT on 29 October to 02:00 EDT on 30 October 2012 (nine hours). The record peaked at 3.44 m at 21:24 EDT. The Battery is 2 to 4 km south of the domain, and the four USGS high-water marks within 100 m of the waterfront (three on the Hoboken bulkhead, one on the Manhattan side) sit about 0.22 m below its peak. By default the record is lowered by 0.216 m, the mean difference between those four marks and the simulated peak with the raw record. The correction can be switched off; results with and without it are both reported below.

Synthetic Coastal Surge

The boundary is the astronomical tide plus a Gaussian surge pulse:

η (t) = A \cos (2 π (t - t_{HW}) / T_{2}) + S e^{- {((t - t_{p}) / σ)}^{2}} + SLR

A = 0.72 m and T₂ = 12.42 h (the principal lunar tide at The Battery, about mean sea level at 0 m NAVD88), σ is a quarter of the storm duration, t_p is five hours into the run, and S is chosen so the combined peak equals the requested level. The surge peak can fall on high, mid or low tide.

Rainfall

Rain is spatially uniform with a constant intensity over a chosen window (a block hyetograph). The design-storm helper takes depths from NOAA Atlas 14 at Hoboken: for example 73 mm in one hour at 1 in 100 years, and 91 mm in six hours at 1 in 10 years. The scenario note reports the return period of any depth and duration by log-log interpolation in the Atlas 14 table. Drainage capacity is removed from every wet land cell, and infiltration from the green fraction of each cell. Rain on building cells is not routed. Rainfall-only scenarios start near low tide so the river stays in its banks.

Presets

Preset	Boundary	Rain	Drainage, infiltration (mm/h)
Hurricane Sandy	Battery record, −0.216 m	None	10, 10
1-in-100-Year Coastal Flood	Peak 3.05 m (FEMA base flood elevation, 10 ft) on high tide, 12 h storm	None	10, 10
Coastal Flood With Sea Level Rise	As above plus 0.6 m	None	10, 10
1-in-100-Year Cloudburst	Tide only	73 mm/h for 1 h	25, 12
Ida-Like Downpour	Tide only	80 mm/h for 1 h	25, 12
Compound Surge and Rain	Peak 2.3 m on high tide	15.2 mm/h for 6 h	15, 10

Every parameter of every preset can be edited, and defences can be added: a continuous wall along the Hoboken bulkhead at a chosen crest, barriers drawn on the map, and pumps that remove water at a set rate. Barriers raise the cells along their line to the crest elevation, with the line made four-connected so water cannot slip through diagonally.

Hazard Outputs

Depth and water surface at every cell, every step.
Speed: cell-centre velocity from the average of the two face discharges in each direction, divided by depth (cells deeper than 5 cm).
Hazard to people after the UK Environment Agency and Defra method FD2320: HR = d (v + 0.5) + DF, with debris factor DF = 0.5 where depth exceeds 0.25 m. Classes: low (below 0.75, caution), moderate (to 1.25, danger for some), significant (to 2.0, danger for most) and extreme (danger for all).
Arrival time: the first time each cell holds 10 cm of water.
Flooded land: the area of land cells deeper than 10 cm. Boundary water is excluded.

Damage and Losses

Water at Each Building

For each building the sampling pass reads the ring of open cells around its footprint. The water surface at the building is the mean, over the ring cells that have been wet, of each cell's peak water surface. The mean rather than the maximum keeps sloping ground from passing for depth when rain wets every cell. Depth at the building is that surface minus the ground level defined above.

Entry

FloodVuln curves describe damage given that water has entered a building. A building counts as reached, and takes damage, once 15 cm of water stands against it; thinner sheet flow from rain is treated as not entering.

Damage Ratio

Depth above the first floor is the water surface minus (ground level + NSI first-floor height). FloodVuln Global gives the distribution of the damage ratio at that depth for the building's archetype, with New Jersey or New York calibration: its mean, and its 10th, 50th and 90th percentiles. Because the model is fitted to claims that include basement and below-first-floor damage, the ratio can be positive when water is below the first floor.

Taller Buildings

The curves were fitted mostly to houses and small multifamily buildings, where the flooded floors are a large share of the value. For taller buildings damage is applied to the two lowest storeys only: the share of value exposed is min(1, 2 / storeys), with storeys from the NSI or, failing that, the lidar height divided by 3.1 m.

Loss = \overline{D} (d_{FF}) \times (V_{structure} + V_{contents}) \times \min (1, 2 / storeys)

D̄ is the mean damage ratio at depth above the first floor d_FF; V are the NSI modelled replacement values for structure and contents.

Uncertainty Range

The range shown under the expected loss sums the 10th and 90th percentile damage of every building. It assumes building damage is fully correlated within the event, so it is a deliberately wide band, not a portfolio confidence interval.

People and Vehicles

Residents affected are the NSI night-time population of buildings with water above the first floor. Vehicles are counted where the modelled peak depth exceeds 30 cm (water at the floor and engine intake on most cars) and 60 cm (where cars float, and the usual threshold for a write-off); in the scene, cars lift off once the local depth passes 0.55 m.

Portfolio Scoring

A portfolio is a CSV of properties with id, latitude, longitude and value, and optionally loan balance, type and first-floor height. Each property is matched to the nearest open cell within four cells and scored with the same damage model: depth, damage ratio with its percentiles, expected loss, and for loans the loan-to-value ratio after damage, loan / (value − loss). The summary counts loans that the event pushes over 80% and over 100% loan to value. The demo book is 600 small residential properties drawn from the NSI, valued at their per-unit structure value, with synthetic loans between 55% and 90% of value.

Validation: Hurricane Sandy

After Sandy the USGS surveyed the elevations of mud lines, debris lines and seed lines that the peak water left on buildings and structures. Ten such high-water marks fall inside the domain: eight in Hoboken and two on the Manhattan bulkhead. The four within 100 m of the waterfront, three in Hoboken and one in Manhattan, set the boundary correction; the other six are held out. Simulated values are the peak water surface on the cells around each mark from a full nine-hour run at 4 m.

Mark	Location	Quality	Use	Observed	Raw boundary	Corrected	Error

Set	Marks	Bias	Mean absolute error	RMSE

Observed against simulated peak water surface (m NAVD88) with the corrected boundary. Blue: waterfront calibration marks. Orange: held-out marks. The line is one to one.

Reading the Results

The simulated water surface across Hoboken at the peak is nearly flat, within 5 cm of the boundary level, which is expected when the city fills slowly behind a breached waterfront. The surveyed marks scatter around that level by about ±0.5 m. Some of the scatter is mark quality: 6335 is a fair-quality stain line on the Manhattan bulkhead, probably raised by waves, and 6080 and 6081, less than 300 m apart, differ by 0.8 m. With 6335 set aside, the five inland held-out marks have a bias of +0.02 m and a median absolute error of 0.13 m. The raw Battery record overpredicts every waterfront mark, by 0.18 to 0.27 m, which is the reason for the correction.

Over the event 2.8 km² of land floods deeper than 10 cm in the corrected run (2.9 km² with the raw record). Much of it stays flooded after the tide falls: 1.6 km² is still under water at the end of the run, and low-lying west Hoboken took days to drain after the storm.

Verification

The equations are solved twice: on the GPU in the browser and by a reference Python implementation. The reference is tested against analytic and limiting cases, and the GPU code is compared with it after every change.

Test	Result

Performance

Measured on an NVIDIA GeForce RTX 4090 in Microsoft Edge (Direct3D 11 through ANGLE), solver only, Sandy boundary on the rising limb:

Cell size	Steps per second	Mean time step	Simulated time per real second
8 m	about 30,000	0.40 s	about 12,000 ×
4 m	about 20,000	0.20 s	about 4,000 ×
2 m	about 3,300	0.10 s	about 340 ×

The nine-hour Sandy replay takes about 137,000 steps at 4 m. In the app the solver shares each frame with rendering: the number of steps per frame adapts to keep the display near 40 to 60 frames per second, and the clock shows the speed reached. Integrated graphics are typically ten to twenty times slower, and the 8 m grid and the Fast render setting are there for them.

Limitations

Drainage is lumped. There is no sewer network: drainage removes water at a fixed rate from every wet land cell, so surcharging sewers, backflow through outfalls and the combined sewer system are not represented.
Still-water boundary. The river level is prescribed from a gauge record or a synthetic curve. Waves, wave run-up and overtopping, and wind set-up across the river are not modelled, and the river itself carries no computed current.
One gauge. The Sandy boundary comes from The Battery with a single uniform correction. The real water level along the waterfront varied in space and time in ways one offset cannot capture.
Terrain date. The lidar is from 2014 (New Jersey) and 2017 (New York), after Sandy. Construction pits and rail cuts in the 2017 survey appear as deep depressions, and post-Sandy waterfront changes are in the terrain the Sandy replay uses.
Buildings are blocks. Water does not enter buildings in the solver; doors, basements, garages and subway entrances do not store or convey water. Underground infrastructure (PATH, subway, tunnels) is not modelled.
Exposure is modelled. NSI values are modelled replacement costs, not market values or insured limits; first-floor heights are partly imputed in the NSI; contents values follow NSI ratios.
Damage curves are residential. FloodVuln is fitted to NFIP claims, which are mostly residential. Commercial, industrial and large multifamily buildings use proxy curves, and the two-storey rule for taller buildings is an assumption.
No time dimension in damage. Damage depends on peak depth only, not on duration, velocity or contamination. Business interruption, displacement costs and infrastructure losses are not included.
Vehicles are placed, not observed. Parked car positions follow kerbside spacing along OSM streets and convey order of magnitude only.
Single events. Each run is one scenario. There is no stochastic event set, so annual expected loss and return-period losses are not computed here.

Exports and Formats

Building results (CSV): one row per building with location, class, height, ground level, NSI attributes, archetype, peak water surface, depths, damage ratio percentiles, value share and expected loss.
Peak depth grid (ESRI ASCII grid with a .prj file): peak depth so far on land in NAD83 / UTM zone 18N at the model resolution; buildings and boundary water are NODATA.
Time series (CSV): boundary level, rainfall, flooded land, water volume, buildings reached and expected loss every five simulated minutes.
Portfolio results (CSV) and an image of the current view (PNG).
Share links encode the scenario, model settings, defences, display and camera, so a recipient opens the same run.

References and Licences

Bates, P.D., Horritt, M.S. and Fewtrell, T.J. (2010). A simple inertial formulation of the shallow water equations for efficient two-dimensional flood inundation modelling. Journal of Hydrology 387, 33–45.
de Almeida, G.A.M., Bates, P., Freer, J.E. and Souvignet, M. (2012). Improving the stability of a simple formulation of the shallow water equations for 2-D flood modeling. Water Resources Research 48, W05528.
HR Wallingford, Flood Hazard Research Centre and Risk and Policy Analysts (2006). Flood Risks to People, Phase 2. Defra / Environment Agency R&D Technical Report FD2320/TR2.
Perica, S. et al. (2015). NOAA Atlas 14, Volume 10: Precipitation-Frequency Atlas of the United States, Northeastern States. NOAA National Weather Service.
McCallum, B.E. et al. (2013). Monitoring storm tide and flooding from Hurricane Sandy along the Atlantic coast of the United States, October 2012. USGS Open-File Report 2013–1043.
Gornitz, V. et al. (2019). New York City Panel on Climate Change 2019 Report, Chapter 3: Sea Level Rise. Annals of the New York Academy of Sciences 1439, 71–94.
U.S. Army Corps of Engineers. National Structure Inventory (NSI) Technical Documentation. Hydrologic Engineering Center.

US federal data (USGS, NOAA, USDA, FEMA, USACE) are in the public domain. Building footprints and streets © OpenStreetMap contributors, available under the Open Database Licence. Rendering uses three.js (MIT licence). Type is Geist and Geist Mono (SIL Open Font Licence).