Skip to content

Rework KWSE flooring: per-discharge tailwater on an absolute grid#6

Open
ar-siddiqui wants to merge 2 commits into
mainfrom
fix/kwse-floor
Open

Rework KWSE flooring: per-discharge tailwater on an absolute grid#6
ar-siddiqui wants to merge 2 commits into
mainfrom
fix/kwse-floor

Conversation

@ar-siddiqui

@ar-siddiqui ar-siddiqui commented Jul 21, 2026

Copy link
Copy Markdown
Member

AI is used for most of the changes in this PR and following description.

Also see relevant PRs:
NGWPC/ripple1d-pipeline#17
https://github.com/NGWPC/twod-fim-knowledge-base/pull/112

2D SDR DR-032 and DR-033 have figures and concept for new approach.


Until now the known-water-surface-elevation (KWSE) run took a single scalar
min_elevation and swept one shared ladder of downstream water-surface
elevations for the whole reach, keeping only the rungs whose depth exceeded a
given discharge's own normal-depth result. That had two consequences we no
longer want. Because the floor was tied to a discharge's own normal depth
rather than to the water surface the downstream reach actually presents, the
lowest rung frequently sat above the real tailwater and left the bottom of the
library uncovered, while the highest discharges collapsed toward the ceiling
and produced one- or two-rung "curves" with nothing to interpolate between.
And because the single starting elevation was snapped to the nearest half foot
and then stepped by the increment, each reach inherited whatever half-foot
phase its data happened to fall on, so a library built with a one-foot
increment could still land on a half-foot grid.

This change reconditions the floor on the downstream reach and puts the whole
library on a predictable grid. run_known_wse now accepts a min_elevation_curve,
a list of [discharge, wse] pairs taken from the downstream reach's water
surface, in place of the scalar min_elevation, and a new stepwise_floor_lookup
resolves each discharge to the water surface of the greatest tabulated
discharge at or below it, clamping below the lowest tabulated discharge and
holding at the highest. The replacement create_flow_wse_envelopes sweeps every
discharge from its own floor up to the shared ceiling, so the floor now
reflects the actual tailwater the reach will see rather than the reach's own
normal depth.

The grid itself is now absolute. Rungs are multiples of the stage increment
anchored at zero, so a one-foot increment yields whole feet, a half-foot
increment yields half feet, and a two-foot increment yields even feet,
independent of where any particular tailwater falls. Both the shared ceiling
and each discharge's floor are rounded to the nearest grid line, which keeps
every discharge on one common lattice and accepts at most half an increment of
tolerance at the edges rather than fabricating downstream elevations the reach
can never physically reach; where a discharge's floor rounds onto the ceiling,
that single rung is the honest answer. To keep the grid on clean one-decimal
values the stage increment is restricted to one of {0.5, 1, 2, 5, 10} and is
validated both at the run_known_wse entry point and inside the envelope
builder. The function's return value now reports the water-surface elevations
that were actually run instead of the pre-filtered ladder.

The supporting changes move with the new signature: the API tests, the
rounding-error test, and the Postman collection now send min_elevation_curve;
the FAQ documents how the per-discharge floor is derived; and a new
tests/test_flow_wse_envelopes.py covers the floor lookup, the absolute-grid
placement, the nearest-line rounding, the single-rung floor-meets-ceiling case,
and the increment restriction. The package version is bumped to 0.11.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant