[in2TopoHyd]: Module for computing hydraulic inital conditions by JuLa96 · Pull Request #90 · OpenNHM/DebrisFrame

JuLa96 · 2026-08-14T08:46:17Z

in2TopoHyd is an input module for deriving initial hydraulic conditions for the c1TIF computation module
for a debris-flow hydrograph at a prescribed release line. The module combines the topography of the release area with
a time-dependent discharge hydrograph (Topo-Hydrograph) to calculate the corresponding flow thickness and flow velocity at the release line.

The hydraulic conditions are derived from the terrain cross section along the release line.
A rating curve is calculated from the cross-sectional geometry, relating flow thickness to flow area.
For each discharge value of the input hydrograph, the module determines the corresponding mean flow velocity and flow thickness.
The flow thickness is then distributed over the wetted cells of the release cross section.

The resulting initial conditions contain the flow thickness as well as the velocity components in x, y and z direction for every wet cell and every hydrograph timestep.

closes #85

Compiled doc : https://docs.debrisframe.org/en/jl_addtopohydmodule/

initial conditions in time-dependent release mode Add documentation Add test case

qltysh · 2026-08-14T08:47:29Z

❌ 1 blocking issue (1 total)

Tool	Category	Rule	Count
ruff	Lint	Local variable `surfElevRC` is assigned to but never used	1	❌

qltysh · 2026-08-14T08:47:31Z

+    thicknessRC = ratingCurve["thickness"]
+    flowAreaRC = ratingCurve["flowArea"]
+    # fetch debris-flow surface elevation
+    surfElevRC = ratingCurve["surfElev"]


Local variable surfElevRC is assigned to but never used [ruff:F841]

Suggested change

surfElevRC = ratingCurve["surfElev"]

ratingCurve["surfElev"]

qltysh · 2026-08-14T08:48:28Z

Coverage Impact

This PR will not change total coverage.

🚦 See full report on Qlty Cloud »

🛟 Help

Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.
Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.
File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)
- Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

PaulaSp3 · 2026-08-17T06:03:33Z

+    # inputDir = avaDir / "Outputs" / "in2TopoHyd" / "peakFiles"
+    # peakFilesDF = fU.makeSimDF(inputDir, avaDir=avaDir)


Suggested change

# inputDir = avaDir / "Outputs" / "in2TopoHyd" / "peakFiles"

# peakFilesDF = fU.makeSimDF(inputDir, avaDir=avaDir)

PaulaSp3 · 2026-08-17T06:04:11Z

+
+    # Get csv-file with initial conditions
+    debrisDir = pathlib.Path(debrisDir)
+    inputDir = debrisDir / "Outputs" / "in2TopoHyd" / "peakFiles"


Suggested change

inputDir = debrisDir / "Outputs" / "in2TopoHyd" / "peakFiles"

outputDir = debrisDir / "Outputs" / "in2TopoHyd" / "peakFiles"

PaulaSp3 · 2026-08-17T06:17:42Z

Is this the same DEM as in debrisParabolaChanneled? Then, I suggest adding POINTS and REL into this debris data folder.

PaulaSp3 · 2026-08-17T06:36:36Z

+
+The :py:mod:`in2TopoHyd` module requires a
+
+* **digital elevation model as raster file**,
+
+* **a time-dependent discharge hydrograph**,
+
+* **a release line**,
+
+* **and levee points**.
+
+:py:mod:`in2TopoHyd` calculations are performed within a process directory, organized with the
+folder structure described in the `AvaFrame documentation <https://docs.avaframe.org/en/latest/moduleCom1DFA.html#input>`_.


I suggest defining the directory structure of the inputs directly here instead of referencing to avaframe, similar to https://docs.avaframe.org/en/latest/moduleCom1DFA.html#input

PaulaSp3 · 2026-08-17T06:38:07Z

+^^^^^^^^^^^^
+
+The release line is read from the ``Inputs/REL`` directory. It must contain **exactly two points**, representing the starting and ending point of the release line.
+If a ``releaseScenario`` is specified in ``local_c1TIFCfg.ini``, this file is used (**with** extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.


Suggested change

If a ``releaseScenario`` is specified in ``local_c1TIFCfg.ini``, this file is used (**with** extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.

If a ``releaseScenario`` is specified in ``(local_)c1TIFCfg.ini``, this file is used (**with** extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.

PaulaSp3 · 2026-08-17T07:23:19Z

+^^^^^^^^^^^^
+
+The release line is read from the ``Inputs/REL`` directory. It must contain **exactly two points**, representing the starting and ending point of the release line.
+If a ``releaseScenario`` is specified in ``local_c1TIFCfg.ini``, this file is used (**with** extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.


releaseScenario or timeDependentReleaseScenarios, I could not find releaseScenario in c1TIFCfg.ini

PaulaSp3 · 2026-08-17T07:26:01Z

+
+    # get file name of release line
+    # first, check if name is provided in the c1TIF-config file
+    fname = debrisCfg["com1DFA_com1DFA_override"]["releaseScenario"]


In debrisCfg["com1DFA_com1DFA_override"] there is no "releaseScenario".
python runIni.. raises an error!

PaulaSp3 · 2026-08-17T07:31:16Z

this file ends with "Levee", below in the documentation it says, the file needs to end with "levee" (lower case).
When running the example, I get this error:

File not found or there are more than one levee files in POINTS-folder!
Ensure that there is exactly one point-shapefile including the ending *levee.shp!

PaulaSp3 · 2026-08-17T07:34:49Z

+        raise ValueError(message)
+
+    # get file name of levee points
+    fname = debrisDir + "/Inputs/POINTS/*levee.shp"


I suggest providing the levee points in a folder "LEVEE", instead of considering the name within the file.

PaulaSp3 · 2026-08-17T08:37:18Z

I suggest moving the hydrograph csv file to a different folder (e.g., HYDR ??)
The csv file in the REL folder is the input file for c1TIF.

fso42 · 2026-08-17T08:23:49Z

+        # if the tickness at the very left and the very right cell is still > 0,
+        # there are remaining subareas on both sides that have to be considered
+        left, right = idx[0], idx[-1]
+        diffElevLeft = elevation[left - 1] - elevation[left]


This assumes that the channel is strictly interior, right? Is that validated before? Does that assumption always hold?
If the levee point is the first (or last) cell, eg.left -1 becomes -1 and then elevation would be wrapped...

fso42 · 2026-08-17T08:27:27Z

+        raise ValueError(message)
+
+    # get file name of levee points
+    fname = debrisDir + "/Inputs/POINTS/*levee.shp"


If file is wanted, I suggest pathlib.Path(debrisDir, "Inputs", "POINTS").glob("*levee.shp") as this works both with pathlib path and str (as mentioned in the docstring)

fso42 · 2026-08-17T08:29:24Z

@@ -0,0 +1,861 @@
+"""
+Get initial conditions for hydrograph


I think this module should be tested by pytests. If it is too much for this PR, open an issue and adress it in a latter PR...

fso42 · 2026-08-17T08:31:05Z

+
+    # calculate unit normal vectors on left- and right-handside
+    # of direction vector
+    n1 = np.array([-dy, dx]) / magnitude


Lines 244 to 249 are duplicates of 468 to 473. I suggest extracting a shared helper

fso42 · 2026-08-17T08:32:28Z

+    Returns
+    --------
+    thickness: 1D-array
+        flow thickness and velocity values as starting condition


flowVel is missing from the returns

fso42 · 2026-08-17T08:36:49Z

+            v = 2.1 * math.pow(q, 0.33) * math.pow(slope, 0.33)
+            flowVel.append(v)
+
+    #TODO: add addtional methods for calculating the flow velocity


typo additional

fso42 · 2026-08-17T08:37:07Z

+        the elevation of the cross-section cells,
+        the path along (distance) along the cross-section cells
+    ratingCurve: dict
+        dictionary containing the miminimum elevation of cross section (channel)


typo minimum

fso42 · 2026-08-17T08:37:42Z

+    # assign levee points to neares cross-section coordinates
+    crossSection = assignCrossSectionCoords(leveePoints, crossSection)
+
+    # export cross section cell centers as points for plausability check


typo plausibility

fso42 · 2026-08-17T08:37:59Z

+    # compute rating curve
+    ratingCurve = computeRatingCurve(crossSection, topoHydCfg)
+
+    # plot cross section and rating curve for plausability check


typo plausi...

fso42 · 2026-08-17T08:46:30Z

+                                 crossSectionY + (csz - modulus))
+
+    # get indices of cross-section cells
+    col = np.int32(np.array((crossSectionX - xllcenter) / csz))


Why not use the same convention avaframe's own readLine uses (int(np.floor((x - xllcenter) / csz))) ?

col = np.int32(np.round((crossSectionX - xllcenter) / csz)) row = np.int32(np.round((crossSectionY - yllcenter) / csz))

As I think your combination shifts the cell if the center is not a (half-)multiple of cellsize.

assignRasterCoords snaps x to the nearest multiple of cellsize.
getCrossSectionCells converts to an index with np.int32(...), which truncates (chops off the decimal)
rather than rounds.

PaulaSp3 · 2026-08-17T09:37:08Z

+    # assign raster cell coord to starting and ending point of release line
+    xcoord = []
+    ycoord = []
+    for i in range(len(releaseLine["x"])):


simpler would be:

Suggested change

for i in range(len(releaseLine["x"])):

for x, y in zip(releaseLine["x"], releaseLine["y"]):

below you can just use x, y instead of releaseLine["x"][i], releaseLine["y"][i]

PaulaSp3 · 2026-08-17T09:41:25Z

+
+    return crossSection
+
+def assignRasterCoords(cellSize, releaseLine):


why don't you use avaframe.in3Utils.geoTrans.getCellsAlongLine() instead?

PaulaSp3 · 2026-08-17T09:42:56Z

+    crossSection: dict
+        dictionaray containing x,y-coordinates of cross-section cells,
+        the elevation of the cross-section cells,
+        the path along (distance) along the cross-section cells


typo (one along is enough)

PaulaSp3 · 2026-08-17T11:19:11Z

+    # horizontal distance between neighbouring cells
+    distance = crossSection["s"]
+    # get elevation steps
+    dElev = float(topoHydCfg["GENERAL"]["dElev"])


Suggested change

dElev = float(topoHydCfg["GENERAL"]["dElev"])

dElev = topoHydCfg["GENERAL"].getfloat("dElev")

PaulaSp3 · 2026-08-17T12:28:25Z

+        left, right = idx[0], idx[-1]
+        diffElevLeft = elevation[left - 1] - elevation[left]
+        dsLeft = distance[left] - distance[left - 1]
+        slopeLeft = diffElevLeft / dsLeft


would it make sense to compute the slope as:
(elevation[left+1]) - elevation[left-1]) / (distance[left + 1] - distance[left-1])

PaulaSp3 · 2026-08-17T13:16:36Z

+
+    return thickness, flowVel
+
+def getCrossSectionCells(dem, releaseLine):


Could you use avaframe.in3Utils.geoTrans.getCellsAlongLine() to simplify this function?

PaulaSp3 · 2026-08-17T13:17:17Z

+
+    Returns
+    --------
+    flowDir: 1D-array


Suggested change

flowDir: 1D-array

flwDir: 1D-array

PaulaSp3 · 2026-08-17T13:18:07Z

+    crossSection: dict  
+        dictionary containing x,y-coordinates of cross-section cells,
+        the elevation of the cross-section cells,
+        the path along (distance) along the cross-section cells


twice "along"?

PaulaSp3 · 2026-08-17T13:36:42Z

+    # combine to 3D-unit-normal vector
+    flwDir = np.append(flwDir, nz)
+    magnitude = np.sqrt(flwDir[0]**2 + flwDir[1]**2 + nz**2)
+    flwDir = flwDir / magnitude


Do you want to normalize flwDir here?
Then also use DFAtls.normalize ?

PaulaSp3 · 2026-08-17T13:37:11Z

+    flwDir = np.append(flwDir, nz)
+    magnitude = np.sqrt(flwDir[0]**2 + flwDir[1]**2 + nz**2)


Suggested change

flwDir = np.append(flwDir, nz)

magnitude = np.sqrt(flwDir[0]**2 + flwDir[1]**2 + nz**2)

flwDir = np.append(flwDir, nz)

magnitude = np.sqrt(flwDir[0]**2 + flwDir[1]**2 + flwDir[2]**2)

??

Add in2TopoHyd-module for computing the hydraulic

92420ee

initial conditions in time-dependent release mode Add documentation Add test case

JuLa96 added the enhancement New feature or request label Aug 14, 2026

JuLa96 self-assigned this Aug 14, 2026

JuLa96 requested review from PaulaSp3 and fso42 August 14, 2026 08:46

qltysh Bot reviewed Aug 14, 2026

View reviewed changes

PaulaSp3 requested changes Aug 17, 2026

View reviewed changes

PaulaSp3 reviewed Aug 17, 2026

View reviewed changes

fso42 requested changes Aug 17, 2026

View reviewed changes

PaulaSp3 requested changes Aug 17, 2026

View reviewed changes

Add sphinxcontrib-bibtex to documentation requirements

dab337a

		# inputDir = avaDir / "Outputs" / "in2TopoHyd" / "peakFiles"
		# peakFilesDF = fU.makeSimDF(inputDir, avaDir=avaDir)

	inputDir = debrisDir / "Outputs" / "in2TopoHyd" / "peakFiles"
	outputDir = debrisDir / "Outputs" / "in2TopoHyd" / "peakFiles"

	If a ``releaseScenario`` is specified in ``local_c1TIFCfg.ini``, this file is used (with extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.
	If a ``releaseScenario`` is specified in ``(local_)c1TIFCfg.ini``, this file is used (with extension .shp). Otherwise, the module searches the ``REL`` directory for a release file.

	for i in range(len(releaseLine["x"])):
	for x, y in zip(releaseLine["x"], releaseLine["y"]):


		return crossSection

		def assignRasterCoords(cellSize, releaseLine):

	dElev = float(topoHydCfg["GENERAL"]["dElev"])
	dElev = topoHydCfg["GENERAL"].getfloat("dElev")


		return thickness, flowVel

		def getCrossSectionCells(dem, releaseLine):

		flwDir = np.append(flwDir, nz)
		magnitude = np.sqrt(flwDir[0]2 + flwDir[1]2 + nz**2)

Uh oh!

Conversation

JuLa96 commented Aug 14, 2026 • edited by fso42 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qltysh Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qltysh Bot Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

qltysh Bot commented Aug 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

JuLa96 commented Aug 14, 2026 •

edited by fso42

Loading

qltysh Bot commented Aug 14, 2026 •

edited

Loading