[ahuber-bfw]

PR Summary

⚠️ Important: PR might introduce potential backward-compatibility issues with com4FlowPy.checkInputParameterValues() for external callers, since the updated function now expects an additional input forestParams if modelParams['forestBool'] - if modelParams['forestBool'] == False then the legacy behaviour is unchanged.

---

This PR fixes issue #1344 and also applies a Bugfix previously applied in the python engine (PR #1342) to the numba engine (fixed typo in calculation of 3D distances).

Summary of Changes

orig PR

Commit	Subject
684ea5cb	fixes issue #1341 also for numba implementation
ef93b3af	added forest input parameter checks in com4FlowPy.py
c9c8a69d	deleted main entryPoints from com4 pytests and added tests for forest input parameter checks

PR review

Commit	Subject
40c91e9	linting issues
0b2e3932	addressing review comments FSO
b0628b0e	addressing review comments PS

Changed files:

• avaframe/com4FlowPy/com4FlowPy.py
• avaframe/com4FlowPy/flowCoreNumba.py
• avaframe/tests/test_com4FlowPy.py
• avaframe/tests/test_com4FlowPyNumba.py

1. Forest input parameter checks (com4FlowPy.py)

added new input data checks for forestModule related input parameters and data to com4FlowPy.checkInputParameterValues(), that is triggered when 'forestBool' is set.

added checks - grouped by forestModule:

• All modules
  • skipForestDist >= 0.
  • alphaMax is taken from the global alpha, or — when varAlphaBool is true — as the
    maximum of the variable-alpha raster inside the release-area mask.
  • forestModule must be in ['forestFriction', 'forestDetrainment', 'forestFrictionLayer']
• forestFriction / forestDetrainment
  • FSI raster values must lie in [0, 1] (cells with FSI <= 0 are masked out, matching the
    existing flowClass.py convention).
  • alphaMax + maxAddedFriction < 90 (total friction must not reach 90°).
  • velThForFriction >= 0.
  • minAddedFriction <= maxAddedFriction.
  • Detrainment extras: velThForDetrain >= 0, minDetrainment <= maxDetrainment, and both
    detrainment bounds within [0, 1].
• forestFrictionLayer
  • velThForFriction >= 0.
  • forestFrictionLayerType == "absolute": layer values within [0, 90].
  • forestFrictionLayerType == "relative": 0 <= alphaMax + max(layer) < 90.
  • Any other type raises ValueError.

All failures raise ValueError with a message naming the offending parameter and config key.
On success, a short summary is written to the log.

2. Numba engine bug fix (flowCoreNumba.py)

The 3D minimum-distance calculation in the numba engine flowCoreNumba.py - _bfs_single() used dy twice
(sqrt(dy² + dy² + dz²)), replicating an upstream Bug of flowClass.calcDistMin().
It now uses sqrt(dx² + dy² + dz²), mirroring the fix already on master in flowClass.py
(issue #1341). This affects the skipForestDist gate in the Numba engine.

3. Tests (test_com4FlowPy.py, test_com4FlowPyNumba.py)

• modified/extended test_com4FlowPy.py
  • New helpers makeForestParameters(), makeForestModelPaths() and
    _makeForestReadRaster() to build valid inputs and fake IOf.readRaster.
  • New tests for checkForestInputParameters() covering all three forest modules, both
    global and variable alpha, all valid branches, and the invalid cases (out-of-range FSI,
    friction/detrainment limits, unknown layer type, negative thresholds), using
    pytest.mark.parametrize.
  • Removed the if __name__ == "__main__": block that re-ran a hand-picked subset of tests. $\rightarrow$ this is not required when invoking tests through pytest
• test_com4FlowPyNumba.py
  • Removed the corresponding if __name__ == "__main__": block. $\rightarrow$ this is not required when invoking tests through pytest

4. Main Changes

• Invalid forest parameter and input data settings now abort with ValueError() instead of failing silently or producing unintended results.

---

PR Checklist

Please confirm before requesting review:

• I ran pytest locally without fails
• I added/updated tests where needed
• I updated documentation where needed

Confirm before the final merge/rebase into master

• Commits are sensibly squashed and rebased onto latest master
• Standardtest run without difference (with recompiled cython code)

[qltysh]

All good ✅

[fso42]

This adds backwards incompatible code (checkInputParameterValues now takes an extra argument). Please highlight this in the PR summary, as external calles must update this