Skip to content

Keep advection on next to inactive cells, add advection_bank_correction - #448

Open
maartenvanormondt wants to merge 5 commits into
mainfrom
bates-4-advection
Open

maartenvanormondt wants to merge 5 commits into
mainfrom
bates-4-advection

Conversation

@maartenvanormondt

@maartenvanormondt maartenvanormondt commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Description

Two changes to the advection term in compute_fluxes. The first changes results for some models; the second is an option that is off by default.

1. Advection is no longer switched off next to inactive cells (changes results)

set_advection_mask switches advection off at every uv point that has a neighbouring uv point with kcuv /= 1. That is meant for open boundaries and wave makers. It also catches uv points next to an inactive cell, because a missing neighbour points to the dummy index npuv + ncuv + 1, where kcuv = 0. The edge of the active domain is a closed wall, not an open boundary, so there is no reason to switch advection off there.

With this PR a missing neighbour no longer switches advection off. Next to open boundary points and wave maker points nothing changes.

Two cases in which advection is still switched off next to an inactive cell (pointed out in the review, not changed here): at a refinement transition, a combined uv point whose second fine face is missing (the fine cell is inactive) gets kcuv = 0 at a regular index, not the dummy index, so its neighbours are still masked. The same holds next to a Neumann cell that is reset to inactive because it has no valid neighbour.

Which models are affected: models with advection = 1 and advection_mask = 1 (both default) on a quadtree grid or a regular grid with more than one row, at uv points next to inactive cells. There the advection term is now included. There is no keyword to get the old behaviour back. Regular one-row models are not affected: for those the mask was never applied.

2. New option advection_bank_correction (default off)

A dry uv point has u = 0. In the upw1 scheme the velocity differences with the four neighbouring uv points then treat every step of a bank that follows the grid as a real 90 degree corner, which slows down the flow along the bank. With advection_bank_correction = 1 each of those differences is weighted with

wt = min(1, max(hu_k / hu, |q_k| / |q|))

the larger of the depth ratio and the flux ratio between neighbour k and the uv point. Only the terms with du/dx and du/dy are weighted. Only for advection_scheme = upw1.

Also: the comment on advlim in sfincs_input.f90 and sfincs_momentum.f90 now says that a value like 9999.9 is so high that the cap has no effect (the default stays 1.0), the map file gets the attribute advection_bank_correction, and docs/parameters.rst has an entry for it.

Test. Release build on Windows, one thread, against main (f2845d9):

Case default against main advection_bank_correction = 1 against 0
urban_drainage_charleston (no advection) bit-identical identical, as expected
Thacker1D (advection on, regular grid of one row) bit-identical 0.49 m largest difference in water level; rms 0.02 m

Neither case exercises change 1: the first has no advection, the second is a one-row model. The effect of change 1 has not been isolated in a test yet.

Checklist

Compilation

  • Compiles and runs successfully on Windows
  • Compiles and runs successfully on Linux (CPU)
  • Compiles and runs successfully on Linux (GPU)

Testing (for additions to the code)

If this PR modifies model functionality:

  • Testbed has been run, and significant performance change has been adressed

If this PR adds model functionality:

  • A conceptual test has been added to the testbed.
  • A real-world test case has been added to the testbed.

Documentation

  • Relevant documentation has been updated to reflect the changes.
  • Examples, tutorials, or user guides have been updated where necessary. n/a

HydroMT-SFINCS

Self Review

  • I have reviewed my own changes.
  • Fortran changes follow the coding style.

Additional Notes

  • The full test bed has to be run on this branch before merging, because change 1 alters results. A test bed run of the source branch (122 cases, this change together with a new wiggle suppression and without the cap on advection) had no failed runs: 42 identical, 61 below 1 %, 13 at 1 to 5 %, 6 above 5 %. The 6 are levee cases and are attributed to the removed cap, which is not part of this PR. How much of the rest comes from change 1 is not known.
  • Bank correction: the evidence so far is from idealised meander and oblique channel tests outside the test bed. No test bed case runs with it. In an earlier version of the code (a different momentum routine) it cost 11 to 17 % of the time in momentum; the cost has not been measured here.
  • The keyword advection_mask has no entry in parameters.rst; this PR does not add one.
  • Not built or run on Linux or on GPU.
  • This is one of four independent PRs taken from the branch bates-wiggle-advection: Swap flux and velocity arrays instead of copying them #445 (array swap), Add cbrt keyword for a fast cube root in the friction term, remove the h73 table #446 (cbrt), Add wet-area wiggle suppression as an option (wiggle_detect) #447 (wiggle suppression) and Keep advection on next to inactive cells, add advection_bank_correction #448 (advection). Each is based on main and they can be merged in any order. They add lines at the same places (the OpenMP private list in sfincs_momentum.f90, the logical flags in sfincs_data.f90, keyword lines in sfincs_input.f90, attributes in sfincs_ncoutput.F90, entries in parameters.rst), so the ones merged later will have small conflicts where both sides are to be kept.

🤖 Generated with Claude Code

Add an optional depth- and flux-weighted correction for upwind advection near shallow banks. Keep advection enabled at inactive-cell edges while preserving masking near boundaries and wave makers.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A moderate active finding remains because the documented advlim = 9999.9 sentinel still allows the advection value to be clamped, so the limiter-disable behavior is not implemented as promised.

1 open issue
What changed in this PR

This PR updates SFINCS advection handling near inactive-cell boundaries and adds an optional bank-correction method for the upw1 scheme.

Changes:

  • Preserves advection next to inactive cells while retaining masking near open boundaries and wave makers.
  • Adds the advection_bank_correction option with input parsing, NetCDF metadata, and documentation.
  • Updates advection-related comments and parameter descriptions.
File Description
source/​src/​sfincs_ncoutput.F90 Adds advection_bank_correction to the map-file NetCDF metadata.
source/​src/​sfincs_momentum.f90 Implements bank-correction weighting for upw1 advection terms and updates the advlim documentation.
source/​src/​sfincs_input.f90 Reads the new advection option and updates the advlim comment.
source/​src/​sfincs_domain.f90 Refines advection-mask handling to exclude dummy missing-neighbor indices.
source/​src/​sfincs_data.f90 Declares the new advection configuration flag.
docs/​parameters.rst Documents the advection_bank_correction parameter.

Review effort: Lite

Comment thread source/src/sfincs_momentum.f90 Resolved
Explain that 9999.9 is a high threshold, not a special value that disables the limiter.
@maartenvanormondt
maartenvanormondt marked this pull request as ready for review November 16, 2026 13:40

@Leynse Leynse left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, and thanks for stating clearly that change 1 alters results. I checked the reasoning: inactive quadtree cells are removed from np, so their faces point to the dummy index with kcuv = 0, and next to open boundaries and wave makers the mask still applies. The bank correction is safe against division by zero (a dry or dummy partner gives wt = 0 before any division), all partner indices stay within the arrays, and no GPU data needs to change.

Blocking

  1. Change 1 changes results by default, and is not tested yet. Neither of the two test cases runs this code path, and the testbed has not been run on this branch. Since there is no keyword to get the old behaviour back, I'd like to see the full testbed (CPU and GPU) with the differences explained before merging. A regular multi-row or quadtree case with advection = 1 next to inactive cells would show the effect of change 1 on its own.
  2. No Linux CPU or GPU build. The new code is inside the OpenACC momentum kernel, so nvfortran and the GPU path have not been exercised.

Non-blocking

  1. Change 1 is partial at refinement transitions (sfincs_domain.f90:2243-2244, 2275-2282). A combined uv point whose second fine face is missing (the fine cell is inactive) gets cuv_index_uv2 = dummy, so kcuv = 0 at an index <= npuv + ncuv, and it still switches advection off. The same holds for Neumann cells that are reset to kcs = 0 (sfincs_boundaries.f90:759). Is that intended? If so, the description ("a missing neighbour no longer switches advection off") could mention it.
  2. advection_mask comment (sfincs_input.f90:210) still says "mask advection near dry cells". After this PR it only applies next to open boundaries and wave makers.
  3. No warning with advection_scheme = original. advection_bank_correction is only used in the upw1 branch; a write_log warning when it is set with another scheme would help.
  4. Style. sfincs_input.f90:211 is one column out of alignment with the lines around it, and the comment block at sfincs_momentum.f90:502-510 wraps unevenly (line 502 is about 170 characters).
  5. Testing of the new option. No testbed case for advection_bank_correction yet.

Questions

  • Next to a closed wall, the tangential neighbour (u_ndm/u_num) falls back to the point itself (zero gradient) when the neighbouring cell is missing, but to the dummy (u = 0) when the cell exists without that face. Is that asymmetry acceptable? With the bank correction on, a dummy partner gets wt = 0, i.e. free slip.
  • Was the bank correction checked with subgrid, where hu is a grid-average depth and the ratio hu_k / hu mixes partly wet faces?

Suggestion

  • The advlim entry in docs/parameters.rst could use the same "a high value like 9999.9 switches the limiter off" wording as the new code comment.

@maartenvanormondt

Copy link
Copy Markdown
Contributor Author

Thanks Tim, thorough review. Answers below; the code changes are in the next commit on this branch.

Non-blocking points

  1. Refinement transitions and reset Neumann cells. Not intended, but left as it is: the mask only skips the dummy index, so a combined uv point with a missing fine face (kcuv = 0 at a regular index) and a Neumann cell reset to kcs = 0 still switch advection off around them. The PR description now says so.
  2. advection_mask comment. Fixed: "switch off advection at uv points next to open boundary and wave maker points".
  3. Warning. Added: advection_bank_correction with a scheme other than upw1 now gives a warning that it is not used.
  4. Style. Fixed: alignment of the keyword line and the wrapping of the comment block in sfincs_momentum.f90.
  5. Test case for the bank correction. Agreed, still open.

Suggestion. Done: the advlim entry in docs/parameters.rst now says that a high value like 9999.9 switches the limiter off (and the missing closing bracket is there).

These changes are comments, documentation and one warning. Checked with a release build on Windows, one thread: urban_drainage_charleston and Thacker1D are bit-identical to the previous commit (abb89e6), with the default settings and with advection_bank_correction = 1.

Your questions

  • Asymmetry next to a closed wall. Your reading of the code is right: a missing tangential neighbour falls back to the point itself (zero gradient, sfincs_domain.f90:1339-1340), an existing cell without that face gives the dummy with u = 0. This PR does not create the asymmetry, but it does expose it. On main the mask switched advection off at exactly these points, so the dummy value was never used there. With the bank correction off, one type of wall is now free slip and the other acts as no slip. With the bank correction on, the dummy partner gets wt = 0 and both are free slip. I think that is acceptable for now, and it is one of the reasons for the bank correction. Making the fallback the same in both cases would be a separate change.
  • Bank correction with subgrid. The tests behind the option (oblique channel, meander) were subgrid models, so it has been run with subgrid. What has not been looked at separately is the point you raise: the ratio hu_k / hu between faces that are both partly wet, where hu is a grid-average depth. That is still open, and the option is off by default.

Blocking points

Both are fair. Could you run the test bed on this branch yourself, CPU and GPU, together with the Linux builds? You have the Linux and GPU set-up, and I do not have it here. What to expect: differences against main only in models with advection = 1 on a quadtree grid or a regular grid with more than one row, at uv points next to inactive cells; regular one-row cases should be identical. A regular multi-row or quadtree case with advection = 1 next to inactive cells, as you propose, would indeed show change 1 on its own. If differences turn up that need explaining, send them my way.

maartenvanormondt and others added 3 commits November 19, 2026 06:42
Warn when advection bank correction is enabled with a scheme other than upw1. Clarify the advection mask, limiter, and bank correction comments.
Split the advlim comment in compute_fluxes over two lines, and note in
parameters.rst that advection_bank_correction is available from SFINCS
v2.5.1 onwards.

Co-Authored-By: SFINCS <sfincs@deltares.nl>
Add a line to the known issues in developments.rst that advection is no
longer switched off next to inactive cells, so models with advection can
give slightly different results near the edge of the active domain. Wrap
the long comment in set_advection_mask.

Co-Authored-By: SFINCS <sfincs@deltares.nl>
@Leynse

Leynse commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Thanks Maarten, the fixes in 0519cd2 look good. One more question on the bank correction, not blocking:

A wet partner face with q_k = 0 gets wt = 0, not hu_k / hu (sfincs_momentum.f90, the weight block in the upw1 scheme). Because the partner depth is derived as hu_k = q_k / u_k, if (q_k <= 0.0) wt = 0.0 gives full free slip to a partner that is wet but has exactly zero flux, while the formula in the comment, min(1, max(hu_k / hu, |q_k| / |q|)), would give about hu_k / hu there. So the weight jumps: a deep partner at 1 mm/s gets wt ≈ hu_k / hu, the same partner at rest gets wt = 0.

Exactly zero flux on a wet face mainly happens at thin dams, closed faces and structures, where free slip is arguably what you want, and stagnant water hardly ever reaches exactly 0. So I see it as a matter of definition rather than a bug. Is this intended? If so, could the comment say that a partner with zero flux is treated as a wall (free slip)?

Leynse added a commit that referenced this pull request Nov 19, 2026
Merge the current heads of bates-1-array-swap (01fa3c9), bates-2-cbrt
(fa08d6a), bates-3-wiggle (44adf1f) and bates-4-advection (fdcb9d4):
h73table deprecation and NaN-safe fast cube root, wiggle docs and style,
advection comments and docs.

Co-Authored-By: SFINCS <sfincs@deltares.nl>

@Leynse Leynse left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay checked. Merge after running testbed

Leynse added a commit that referenced this pull request Nov 19, 2026
Merge the current heads of bugfix/snapwave-wave-force-dissipation
(5f349be), fix/boundary-corner-water-level (0073407) and
fix/neumann-boundary-robustness (ff5e5bf, includes
fix/neumann-neighbour-lookup), on top of #445-#448. In compute_fluxes,
keep the array swap of #445 instead of the q0/uv0 copy loop, and add
kcs to the present list for the Neumann water level at kcuv = 6 faces.

Co-Authored-By: SFINCS <sfincs@deltares.nl>
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.

3 participants