Reallocation rules

This is the authoritative description of how SWAG-DSS moves water between sub-watersheds.

Unit of reallocation

Reallocation operates on sub-watersheds (one small hydrologically-conditioned drainage polygon each). Each sub-watershed has a stable band_id (the sub-watershed polygon identifier), a parent WRUA, and a mean elevation. CSVs and JSON refer to the sub-watershed as the "band" throughout the schema, for example combined_bands.csv, sat_bands.csv, and api_map_bands_all, and that field name means "sub-watershed" everywhere it appears.

Rules (in priority order)

1. Stay within the same WRUA. Water never crosses a WRUA boundary, even if a neighbouring WRUA has surplus.
2. Local reallocation only on slope < 3%. If the donor watershed's mean slope exceeds 3% (percent grade, not degrees), no local reallocation is attempted; deficit stays accounted for at source.
3. Flow downhill to adjacent watersheds. Candidate receivers must be topologically adjacent (share a polygon edge with the donor) AND lie at a lower mean elevation. Uphill transfer is disallowed.
4. Lowest-friction path. Among the eligible adjacent watersheds, pick the one with the lowest cumulative friction along the connecting flow path. Friction is the per-pixel cost surface used by the upstream model (landcover, slope, land use, etc.).
5. Tie-break by greatest mean elevation drop. When two or more candidates are tied on friction, prefer the receiver with the largest difference in mean elevation versus the donor (steeper drop wins).

What this affects

• reallocation.csv: long-format monthly reallocation rows, one per donor-receiver-month tuple.
• combined_bands.csv and sat_bands.csv: per-watershed monthly metrics computed after applying the rules above.
• simulation_combined.csv, simulation_sat.csv: 48-month series consumed by the dashboard's scenario charts.
• API: GET /api/map/bands and /api/map/bands/<wrua> return the resulting per-watershed deficit and surplus stats.