The LankaFlood AI guide

This guide teaches the mathematics behind the project and records what has been done. Every section says whether it is measured (run on real data) or planned (the design for a later stage). No world model has been trained yet.

What has been done

Stage	Status	What exists
1. Foundation	Done	Repository, tests, static site, deployment, portfolio link
2. Historical GIS data	Done	UNESCO and Copernicus layers on one aligned 11 m grid, an interactive map, 17 alignment tests
3 to 8	Planned	Simulator, weather data, training, browser inference, evaluation, landslides

The rest of this guide follows the path of the data: from map grid, to flood scores, to water physics, to the learned model.

1. Turning a map into a grid (measured)

A raster is a table of numbers. An affine transform says where each table cell sits on Earth. For column $c$ and row $r$ :

λ = λ_{0} + c Δ λ, φ = φ_{0} - r Δ φ

Here $λ$ is longitude, $φ$ is latitude, and $(λ_{0}, φ_{0})$ is the top-left corner. Latitude has a minus sign because rows count downwards while latitude increases upwards.

The UNESCO raster has $Δ λ = Δ φ = 0.000 1^{\circ}$ . Our crop starts at a whole-number column and row, so every pixel is the source's own pixel, and nothing is resampled. A test confirms the crop matches the source exactly.

How big is one pixel?

An arc of angle $θ$ radians on a sphere of radius $R$ has length $Rθ$ :

0.000 1^{\circ} \times \frac{π}{180} \times 6, 378, 137 m \approx 11.13 m

East-west distances shrink towards the poles by $cos φ$ , so the area of a cell depends on its row:

A (φ) \approx R^{2} Δ λ Δ φ cos φ

The pipeline uses the more accurate WGS 84 ellipsoid, which gives about $122.2 m^{2}$ per cell at $7^{\circ}$ N. Flooded area is the sum over wet cells:

Area = r, c \sum w_{r, c} A (φ_{r}), w_{r, c} \in {0, 1}

Check against the source: rasterising the Copernicus polygons this way gave 3,376.2 ha against the published 3,377.0 ha, a difference of 0.02%. That is the evidence that the grid and area maths are right.

Why a flat image lines up on a web map

Web maps use Web Mercator, where north-south position is:

y (φ) = R ln tan (\frac{π}{4} + \frac{φ}{2})

Our pixels are evenly spaced in latitude, but $y (φ)$ is curved. MapLibre pins an image by its corners and stretches it in a straight line, so there is an error. The maximum error of a straight line across a curve over an interval of height $h$ is:

E \leq \frac{h ^{2}}{8} max ∣ f^{''} ∣, y^{''} (φ) = R sec φ tan φ

Our crop is $h = 0.1 3^{\circ} = 0.00227$ radians tall, near $φ = 7^{\circ}$ :

E \approx \frac{( 0.00227 ) ^{2}}{8} \times 6, 378, 137 \times 0.124 \approx 0.5 m

The numerical check gives 0.504 m, about one twentieth of a pixel. So keeping the data in its original EPSG:4326 and overlaying it is safe at this size. Because $E$ grows with $h^{2}$ , a crop 10 times taller would be 100 times worse, about 50 m, and this shortcut would stop working. There's a test for that as well.

2. Scoring one flood map against another (measured)

For any two wet-or-dry maps, every cell falls into one of four boxes:

	Reference wet	Reference dry
Predicted wet	Hit, $H$	False alarm, $F$
Predicted dry	Miss, $M$	Correct dry, $C$

Plain accuracy is a trap. Most cells are dry, so a model that always says "dry" scores very well while being useless. The critical success index ignores correct dry cells:

CSI = \frac{H}{H + M + F}

It's the same formula as intersection over union (IoU). It runs from 0 (no overlap) to 1 (perfect). Two companions show the type of error:

POD = \frac{H}{H + M}, FAR = \frac{F}{H + F}

The probability of detection (POD) falls when you miss water, and the false alarm ratio (FAR) rises when you invent it.

The seen mask

You can't score a model where nobody could see the ground. Define a mask $S$ , where $S_{r, c} = 1$ only if both images analysed that cell, and count $H$ , $M$ and $F$ only there. This matters a lot here:

Measure	30 Nov	3 Dec
Observed flood, all of it	3,377.0 ha	688.3 ha
Not analysed	636.2 ha	7,122.3 ha
Observed flood, where both dates saw the ground	1,969.6 ha	685.4 ha

The naive fall is 80%. The fair fall is 65%. The source doesn't say why ground wasn't analysed, and the two images come from different sensors, so even 65% is not a clean measure.

The score to beat

The simplest possible forecast is that nothing changes, so the 30 November map also serves as the prediction for 3 December. Its measured score on the seen mask is:

CSI_{no change} = 0.27

This is the project's first real research number. A world model that can't beat 0.27 has learned nothing useful about this transition.

Checking alignment

If two sources were misregistered, sliding one over the other would raise the overlap. So for each shift $(d_{x}, d_{y})$ up to 12 pixels each way we compute:

(d_{x}^{*}, d_{y}^{*}) = ar g d_{x}, d_{y} max IoU (a, shift (b, d_{x}, d_{y}))

The best shift between UNESCO and Copernicus is $(0, 0)$ on both dates. There is no systematic offset. Their IoU is only 0.53 and 0.24, which isn't a contradiction, since they cover different times and methods. Alignment and agreement are different questions.

3. How water moves (planned, stage 3)

Water depth changes for two reasons: it flows between cells, or it's added and removed. This is conservation of mass:

\frac{\partial h}{\partial t} + \frac{\partial q _{x}}{\partial x} + \frac{\partial q _{y}}{\partial y} = R - I

Here $h$ is depth (m), $q$ is flow per unit width (m²/s), $R$ is rainfall and $I$ is infiltration (m/s).

On a grid, this becomes bookkeeping. Each cell's depth changes by what flows through its four faces:

h_{i}^{t + Δ t} = h_{i}^{t} + \frac{Δ t}{Δ x} (q_{in} - q_{out}) + Δ t (R - I)

Flow itself is driven by the slope of the water surface $S$ and held back by friction. One standard simplification, the local inertial scheme of Bates and colleagues, is:

q^{t + Δ t} = \frac{q ^{t} - g h Δ t S}{1 + g Δ t n ^{2} ∣ q ^{t} ∣ / h ^{7/3}}

$n$ is Manning's roughness: rough forest slows water more than smooth pavement.

Why physics is slow, and a tiny model might help

A wave moves at about $g h$ . If the time step is too long, water jumps over whole cells and the solution blows up. The stability limit is:

Δ t \leq α \frac{Δ x}{g h}

For 30 m cells, 4 m depth and $α = 0.7$ :

Δ t \leq 0.7 \times \frac{30}{9.81 \times 4} \approx 3.4 s

Covering the 73.45 hours between our two Kelani maps would take about 79,000 steps. A world model can learn a rule that jumps, say, an hour per step, which would be about 73 steps. That's the reason for learning this at all.

4. The world model (planned, stage 5)

A world model learns the rule for what happens next:

\overset{s}{^}_{t + 1} = s_{t} + f_{θ} (s_{t}, z, a_{t})

Symbol	Meaning
$s_{t}$	Water depth on the grid at time $t$
$z$	Terrain, obstacles and drainage
$a_{t}$	Weather inputs, if this version uses them
$f_{θ}$	A small neural network with weights $θ$

It predicts the change in water. Most cells change little per step, so "no change" becomes its natural starting point. Depth can't be negative, so the output is clipped: $\hat{h} = max (0, \hat{h})$ .

Training

The weights are chosen to minimise prediction error across simulated floods:

L (θ) = \frac{1}{N} i = 1 \sum N w_{i} (\hat{h}_{i} - h_{i})^{2} + λ (i \sum \hat{h}_{i} - i \sum h_{i} - net inflow)^{2}

The first term is weighted error, where wet cells get a larger $w_{i}$ so the model can't win by predicting dry land. The second penalises creating or destroying water, with $λ$ setting its strength.

Rollout: why errors compound

To look further ahead, each prediction becomes the next input. Suppose each step adds a fresh error of size $ε$ , and the network amplifies existing errors by up to $1 + L$ . Then:

e_{t + 1} \leq (1 + L) e_{t} + ε ⟹ e_{n} \leq ε \frac{( 1 + L ) ^{n} - 1}{L}

With $ε = 0.01$ m and $L = 0.05$ , these are illustrative values rather than measurements:

Steps	Worst-case error
1	0.01 m
5	0.06 m
10	0.13 m
20	0.33 m

This is a bound and not a forecast of behaviour, but it explains why a model that looks excellent at one step can fail at 20. Rollout error is therefore the main metric, and it's what H1 measures.

What does "tiny" mean?

A convolution layer with kernel size $k$ , $c_{in}$ input channels and $c_{out}$ output channels has this many weights:

P = (k^{2} c_{in} + 1) c_{out}

At 4 bytes per weight, 200,000 weights take about 0.8 MB, which is a reasonable download. For scale, the closest published flood model we found has about 2.7 million weights and ran on a GPU. H1 asks how much accuracy you lose as $P$ falls.

5. With and without weather (planned, stages 4 and 5)

You asked to predict both with and without weather. In research this is an ablation study: remove one input, keep everything else the same, and measure what you lose.

Version	Inputs	Question
M0	Water and terrain	How far do terrain and the current flood get us?
M1	M0 + rainfall and inflow	What does knowing incoming water add?
M2	M1 + cloud	Does cloud add anything once rain is known?

What each input physically means

Rain adds volume directly:

V = R A 100 mm over 16, 071 ha = 0.1 \times 160, 710, 000 \approx 16 million m^{3}

Cloud doesn't add water. Clouds are only a clue that rain may be coming, and physics never needs them once rain is known. So the honest expectation is that M2 may barely beat M1 for water depth. That would still be a useful result. Cloud could matter more for forecasting, when future rain isn't known yet.

Cloud also matters in a second way. It can hide the ground from optical satellites like the ones used here:

P (cell is observed) = P (no cloud) \times P (inside image)

So cloud may explain some of the missing ground on 3 December, although the source doesn't state the reason. Stage 4 can test that against real cloud data.

The crop's limit: most water reaching the lower Kelani falls as rain further upstream. Rain inside our crop isn't enough, so the upstream inflow has to be either supplied or estimated.

How to compare fairly

Each version gets the same architecture budget, training data and random seeds. The gain from weather is a difference in scores on the same test floods:

Δ_{rain} = CSI_{M 1} - CSI_{M 0}

Averages can mislead, so the comparison is paired per flood. Repeatedly resampling those test floods gives a confidence interval (a bootstrap). If the interval includes zero, we can't claim a gain. A skill score then measures improvement over the no-change baseline, on a scale where 1 is perfect and 0 is no better:

SS = \frac{CSI _{model} - CSI _{no change}}{1 - CSI _{no change}}

On the real Kelani transition, a model scoring 0.50 would have $SS = (0.50 - 0.27) /0.73 = 0.32$ . That number is an example only. And with only one real transition there is no interval at all, so real-event results stay a case study.

The trap: hindcast versus forecast

Using rain measured after the event is a hindcast. In a real forecast, future rain is itself uncertain:

Hindcast: a_{t} = a_{t}^{observed} Forecast: a_{t} = a_{t}^{observed} + forecast error

A model tested on observed rain will look better than it would in real use. Every result in this project must say which one it is, and inputs at time $t$ may only use data available by time $t$ .

6. Knowing when it's guessing (planned, H2)

Train $K$ copies of a model from different random starts. Where they disagree, they're probably guessing:

\overset{ˉ}{h} = \frac{1}{K} k = 1 \sum K \hat{h}^{(k)}, u = \frac{1}{K} k = 1 \sum K (\hat{h}^{(k)} - \overset{ˉ}{h})^{2}

This works in published flood models, but downloading $K$ copies costs $K$ times the size. H2 compares cheaper signals, judging each by whether a high warning really predicts a failed rollout on scenarios the model never saw.

7. Getting ready for landslides (data acquired, model planned for stage 8)

Landslides are not floods with different labels. The mathematics differs:

	Flood	Landslide
Physics	Water moving continuously	A slope failing suddenly
Output	Depth per cell, over time	Probability of failure per cell
Key input	Water state, inflow	Slope, soil, saturation
Rollout	Natural	Rarely meaningful after failure
Class balance	Common in floodplains	Extremely rare

The physics: factor of safety

A simple model treats the slope as an infinite tilted layer of soil:

FS = \frac{c ^{'} + ( γ z cos ^{2} β - u ) tan φ ^{'}}{γ z sin β cos β}

Here $β$ is slope angle, $z$ is soil depth, $γ$ is soil unit weight, $c^{'}$ is cohesion, $φ^{'}$ is friction angle (not latitude here), and $u$ is water pressure. $FS < 1$ means the slope is predicted to fail. Rain raises $u$ , which reduces the numerator. That's the physical link between weather and landslides.

Soil properties are rarely known at this scale, so a data-driven approach is common. A classic form is a rainfall threshold, where failures become likely when intensity $I$ over duration $D$ exceeds:

I = α D^{- β_{D}}

A learned version estimates a probability from terrain and weather features $x$ :

P (failure ∣ x) = \frac{1}{1 + e ^{- (w^{⊤} x + b)}}

Why plain accuracy fails even worse here

UNESCO maps about 2,163 ha of landslides nationally, against about 414,789 ha of flood. Landslide cells are so rare that "never" would be nearly always right. The right tools are precision and recall:

Precision = \frac{H}{H + F}, Recall = \frac{H}{H + M}

What readiness means today

Data: the UNESCO landslide raster is downloaded, checksummed and measured.
Structure: the region config and map manifest list hazards separately, so adding one doesn't change flood code.
Design: terrain and weather inputs are shared, and each hazard gets its own output and loss:

L_{total} = L_{flood} + μ L_{landslide}

Two limits to remember: the landslide layer starts at $80.2 6^{\circ}$ E, east of our flood crop, so landslide work needs its own area. Its metadata is also inconsistent (the file is named for Sentinel-2, but the attribute says Sentinel-1), and it's unvalidated. So it's a starting label set, not ground truth.

8. What the data can and can't support

Layer	Use it for	Don't use it for
Copernicus observed	Main score for H3	Anywhere not analysed
Copernicus extrapolated	Comparison, with care	Ground truth: it comes from a terrain model, like ours will
Copernicus depth	Rough depth classes for the start state	A measured depth target
UNESCO composite	Where water appeared in the window	A time step: it has no per-area dates

The circularity risk: Copernicus extrapolates with FABDEM terrain. If our model used the same terrain and were scored against that extrapolated layer, a high score could just mean that two terrain-based methods agree. That's why H3 scores on observed water.

9. Check yourself

Why does a model that always predicts "dry" get high accuracy but a CSI of 0? Because it has no hits. CSI ignores correct dry cells, and $H = 0$ makes the score 0.
If the crop were twice as tall, how much would the overlay error grow? Four times, since it grows with $h^{2}$ .
Why compare only where both images saw the ground? Otherwise a cell that went unseen counts as "no flood", and it looks as though water receded.
If M1 beats M0 on simulated floods, have we shown rainfall helps on the real river? No. It shows that for the simulator. The real pair is one case study.
Why might cloud not help once rain is known? Cloud doesn't add water. It's a clue about rain, which is already known.