Skip to content

Add cbrt keyword for a fast cube root in the friction term, remove the h73 table - #446

Open
maartenvanormondt wants to merge 3 commits into
mainfrom
bates-2-cbrt
Open

maartenvanormondt wants to merge 3 commits into
mainfrom
bates-2-cbrt

Conversation

@maartenvanormondt

@maartenvanormondt maartenvanormondt commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Description

The Manning friction term in compute_fluxes needs hu**(7/3). This PR adds a fast approximation of the cube root as an option, and removes the look-up table that was the earlier attempt to speed this up. With the default setting the results do not change.

New keyword cbrt:

Value What it does
exact (default) hu**(1/3) with the power function, as before
fast an integer seed from the bit pattern of hu, refined by one Newton iteration; accurate to about 0.1 %, no power function

The cube root hu13 gives hu**(7/3) = hu * hu * hu13. With cbrt = fast it also gives hu**(5/3) = hu * hu13 * hu13 in the flux estimate at points that just became wet. With cbrt = exact that estimate keeps the expression hu ** (5.0 / 3.0) of main, so that the output stays identical; a comment marks it for replacement later. An unknown value of cbrt gives a warning and falls back to exact.

Removed: the keyword h73table, the table x73, fill_h73_tables and the function power7over3. An input file that still sets h73table runs as before: the keyword is ignored without a message.

Also: the map file gets the attribute cbrt_fast, and docs/parameters.rst has an entry for cbrt in place of h73table.

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

Case default (cbrt = exact) against main cbrt = fast against exact, largest difference in water level
urban_drainage_charleston bit-identical 0.23 m at a single cell, 249 of 387025 values above 1 mm
Thacker1D bit-identical 0.015 m, 650 of 314494 values above 1 mm

The differences with cbrt = fast are not the 0.1 % of the approximation itself. They are of the size this model gives for any change in the last digit: wetting and drying moves a jump in water level by one time step. In urban_drainage_charleston, main against main with alpha changed in the last digit gives 0.17 m at single cells.

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. n/a
  • A real-world test case has been added to the testbed. n/a

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

  • Run time: on urban_drainage_charleston the time in momentum showed no measurable difference between fast and exact. A gain has not been demonstrated yet on this branch; it needs timing on a larger model before fast becomes the default.
  • The default stays exact here on purpose. A later PR will change the defaults of this and the related PRs in one go, with a full test bed comparison.
  • Not built or run on Linux or on GPU. The full test bed has not been run on this branch; only the two cases above. transfer between real*4 and integer*4 is used inside the OpenACC region and has not been compiled with an OpenACC compiler.
  • docs/developments.rst still mentions h73table in the release notes of the version that introduced it; that line is history and is left as it is.
  • 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

Remove the h^(7/3) lookup table and calculate the friction term from a cube root instead. Add `cbrt=exact` (default) and `cbrt=fast` approximation, and record the selected mode in NetCDF output.

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

The module header still contains stale documentation for the removed fill_h73_tables() routine, so the change requires cleanup before approval.

1 open issue
What changed in this PR

Adds an optional cbrt input keyword for selecting an approximate cube-root calculation in the Manning friction term while preserving the existing exact behavior by default. The obsolete h73table lookup-table implementation and related support are removed.

Changes:

  • Adds cbrt = exact|fast parsing, validation, fallback handling, documentation, and map metadata.
  • Uses a bit-based cube-root seed with one Newton iteration for the fast option.
  • Removes the h73table state, lookup table, initialization routine, power helper, and OpenACC references.
File Description
source/​src/​sfincs_openacc.f90 Removes obsolete x73 lookup-table references from OpenACC data management.
source/​src/​sfincs_ncoutput.F90 Adds the cbrt_fast setting to map output metadata.
source/​src/​sfincs_momentum.f90 Implements exact and fast cube-root paths and updates the Manning friction calculation.
source/​src/​sfincs_input.f90 Parses and validates the new cbrt keyword and removes the active h73table input.
source/​src/​sfincs_domain.f90 Removes initialization of the obsolete lookup table.
source/​src/​sfincs_data.f90 Adds the cbrt_fast state and removes obsolete lookup-table data and routines.
docs/​parameters.rst Documents the cbrt parameter and removes the obsolete h73table entry.

Review effort: Lite

Comment thread source/src/sfincs_data.f90 Resolved
@maartenvanormondt
maartenvanormondt marked this pull request as ready for review November 16, 2026 13:36
@Leynse

Leynse commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Thanks, good to see the table go. I checked that nothing in source/ still refers to x73, h73table, fill_h73_tables or power7over3, that x73 is removed from the enter/exit data lists and the present clause, and that the default path is the same arithmetic as main (consistent with your bit-identical results).

Accuracy, checked with a float32 script over hu = 1e-12 to 1e5: the fast cube root is at most 0.128 % off (mean +0.035 %), the same over all decades, and always slightly too high (one Newton step on a convex function lands above the root), so cbrt = fast gives slightly too little friction. The removed table truncated its index and was up to 2.2 % too low, so fast is a clear improvement over what it replaces.

Blocking

  1. transfer() inside the OpenACC kernel (sfincs_momentum.f90:656 and :658). This has not been compiled with nvfortran or gfortran yet (the Linux boxes are unticked). It is a compile-time question, so the exact default does not protect against it: if nvfortran rejects transfer in device code, the GPU build breaks for everyone. Could you do a Linux CPU and GPU build before merging?

Non-blocking

  1. h73table is ignored without a message. A model that ran with h73table = 1 now gives different results (up to about 2 % in hu73). Could you read it into a local logical and write a warning to the log when it is set, e.g. that it was removed and cbrt = fast is the closest replacement? (Review checklist: removed keywords give a deprecation warning.)
  2. Accuracy wording. "About 0.1 %" in the code comment (sfincs_momentum.f90:654), the keyword comment in sfincs_input.f90 and docs/parameters.rst could say "at most 0.13 %, slightly overestimates hu**(1/3)".
  3. Style leftovers where code was removed:
    • sfincs_domain.f90:139-140: two ! lines before end subroutine; one is enough.
    • sfincs_data.f90 around contains (lines 892-896): empty and whitespace-only lines; a single ! after contains and the usual !/! separator before initialize_parameters.
  4. Testing. Two cases on Windows, one thread. The testbed (CPU and GPU) still needs to run.

Suggestions

  • In the fast branch, transfer(max(hu, tiny(hu)), i_cbrt) costs nothing and removes the NaN/-inf for -0.0, negative and subnormal hu, while the exact path stays bit-identical. (Neither path is protected against hu < 0 today, so this is not a regression.)
  • sfincs_ncoutput.F90: writing the attribute as cbrt = 'exact' | 'fast' instead of cbrt_fast matches the keyword and leaves room for more options.
  • If the aim is speed, a GPU timing would be useful: there powf is cheap, so the gain may be small.
  • docs/developments.rst still describes h73table. Fine as history, but the next release notes could say it was removed in favour of cbrt.

Question

  • Before fast becomes the default in a follow-up: is the systematic overestimate (+0.035 % on average) acceptable, or would a second Newton step be worth its cost?

@Leynse

Leynse commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Follow-up on blocking point 1 (transfer() inside the OpenACC kernel): this compiles with nvfortran.

I built a combined branch of #445, #446, #447, #448 and #449 on top of main with the GPU Docker build (NVHPC 25.5, -acc -gpu=ccall). It compiled and linked without errors. -Minfo=accel shows the main loop of compute_fluxes generated as GPU code, with i_cbrt among the loop scalars, so transfer is accepted in device code. The only warnings in sfincs_momentum.f90 are two type-conversion warnings on line 442 (the slopelim line), which is unchanged from main.

This only covers compilation: the GPU results with cbrt = fast have not been run or compared yet. The non-blocking points from the review still stand.

- Read h73table again into a local logical in sfincs_input and write a
  warning when it is set: the look-up table has been removed, the
  keyword is ignored, and cbrt = fast is the replacement.
- Restore the h73table entry in docs/parameters.rst, marked as
  deprecated after SFINCS v2.5.0 and replaced by cbrt.
- Guard the fast cube-root seed with max(hu, tiny(hu)), so that a
  negative hu (including -0.0) cannot give a NaN seed. The default
  cbrt = exact path is unchanged and stays bit-identical to main.
- Accuracy wording for cbrt = fast in code comments and docs: at most
  0.13 % off, always slightly overestimates hu**(1/3).
- Style: single ! before end subroutine in sfincs_domain, standard !
  lines around contains in sfincs_data.

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