[com4FlowPy] faster backTracking, previewMode and minor improvs

.gitignore

@@ -41,3 +41,10 @@ avaframe/com1DFA/*.so
 /pixi.lock
 
 /.pixi/
+
+# auxilliary geodata .xml files (created by GIS software packages)
+*.aux.xml
+
+# Byte-compiled / optimized / DLL files
+# see https://github.com/github/gitignore/blob/main/Python.gitignore
+*.py[cod]

avaframe/com4FlowPy/com4FlowPy.py

@@ -64,6 +64,9 @@ def com4FlowPyMain(cfgPath, cfgSetup):
     # modelParameters["infra"]  = cfgSetup["infra"]
     # modelParameters["forest"] = cfgSetup["forest"]
 
+    # Flag for preview mode
+    modelParameters["previewMode"] = cfgSetup.getboolean("previewMode")
+
     # Flags for use of dynamic input parameters
     modelParameters["varUmaxBool"] = cfgSetup.getboolean("variableUmaxLim")
     modelParameters["varAlphaBool"] = cfgSetup.getboolean("variableAlpha")
@@ -249,6 +252,9 @@ def startLogging(modelParameters, forestParams, modelPaths, MPOptions):
         log.info("calculation with Infrastructure")
         log.info(f"{'INFRA LAYER:' : <14}{'%s'%modelPaths['infraPath'] : <5}")
         log.info("------------------------")
+    if modelParameters["previewMode"]:
+        log.info("!!! previewMode is ON !!!! - mind when interpreting results!!!")
+        log.info("------------------------")
     if modelParameters["fluxDistOldVersionBool"]:
         log.info("Calculation using old (BUGGY!!) version of flux distribution!")
         log.info("------------------------")

avaframe/com4FlowPy/com4FlowPyCfg.ini

@@ -34,6 +34,18 @@ max_z = 8848
 
 infra = False
 
+#++++++++++++ preview Mode
+# if previewMode = True, not every release cell is processend independently
+# if a releaseCell is already "hit"/"affected" by a prior calculated path
+# then the processing of this release cell is skipped
+# can be used for a faster preview of model results (e.g. for checking of input parameters) or
+# to save calculation time (e.g. when calculating with infrastructure)
+# NOTE: results will deviate from "normal" model run and all outputLayers relying on the
+# summed/combined output of different paths will not provide sensible values!!!
+
+previewMode = False
+
+
 #++++++++++++ Use a dynamic u_max Limit
 # Requires an additional tif-file containing the uMax  (in m/s)
 # or zDeltaMax (m) Limits

avaframe/data/avaFlowPy/Inputs/REL/rel.cpg

@@ -0,0 +1 @@
+UTF-8

avaframe/data/avaFlowPy/Inputs/REL/rel.prj

@@ -0,0 +1 @@
+PROJCS["MGI_Austria_Lambert",GEOGCS["GCS_MGI",DATUM["D_MGI",SPHEROID["Bessel_1841",6377397.155,299.1528128]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]],PROJECTION["Lambert_Conformal_Conic"],PARAMETER["False_Easting",400000.0],PARAMETER["False_Northing",400000.0],PARAMETER["Central_Meridian",13.3333333333333],PARAMETER["Standard_Parallel_1",49.0],PARAMETER["Standard_Parallel_2",46.0],PARAMETER["Latitude_Of_Origin",47.5],UNIT["Meter",1.0]]

avaframe/tests/test_com4FlowPy.py

@@ -1,19 +1,13 @@
 """
-    Pytest for module com1DFA
+    Pytest for module com4FlowPy
 """
 
-import configparser
-import copy
-import logging
-import pathlib
-import pickle
-import shutil
-
 #  Load modules
 import numpy as np
 import pytest
 
 from avaframe.com4FlowPy import flowClass
+import avaframe.com4FlowPy.flowCore as flowCore
 
 def test_add_os():
     cell = flowClass.Cell(1,1,
@@ -23,3 +17,160 @@ def test_add_os():
                           startcell=True)
     cell.add_os(0.2)
     assert cell.flux == 1.2
+
+def test_reverseTopology():
+    '''
+    testing flowCore.reverseTopology() for different
+    examples of dir graphs
+    '''
+
+    testGraph = {0: [1,2,3],
+                      1: [2,4],
+                      2: [4,5],
+                      3: [2],
+                      4: [],
+                      5: [6],
+                      6: []}
+
+    testGraphReverse = {0: [],
+                        1: [0],
+                        2: [0,1,3],
+                        3: [0],
+                        4: [2,1],
+                        5: [2],
+                        6: [5]}
+
+    reverseGraphCalc = flowCore.reverseTopology(testGraph)
+
+    for key, item in reverseGraphCalc.items():
+        assert key in testGraphReverse.keys()
+        setTestChildren = set(item)
+        setCalcChildren = set(testGraphReverse[key])
+        assert setTestChildren == setCalcChildren
+
+    testGraph = {0:[1,2,3],
+                 1:[4],
+                 2:[5,6],
+                 3:[7,8],
+                 4:[9],
+                 5:[9,10],
+                 6:[10],
+                 7:[11],
+                 8:[],
+                 9:[],
+                 10:[12],
+                 11:[],
+                 12:[]}
+
+    testGraphReverse = {0:[],
+                        1:[0],
+                        2:[0],
+                        3:[0],
+                        4:[1],
+                        5:[2],
+                        6:[2],
+                        7:[3],
+                        8:[3],
+                        9:[4,5],
+                        10:[5,6],
+                        11:[7],
+                        12:[10]}
+
+    reverseGraphCalc = flowCore.reverseTopology(testGraph)
+
+    for key, item in reverseGraphCalc.items():
+        assert key in testGraphReverse.keys()
+        setTestChildren = set(item)
+        setCalcChildren = set(testGraphReverse[key])
+        assert setTestChildren == setCalcChildren
+
+
+def test_backTracking():
+    '''
+    testing flowCore.backTracking() for different
+    examples of dir graphs - basic graphs are the same as
+    in test_reverseTopology() with added 'infra' values
+    as valueDicts
+    '''
+
+    testGraph = {0: [1,2,3],
+                 1: [2,4],
+                 2: [4,5],
+                 3: [2],
+                 4: [],
+                 5: [6],
+                 6: []}
+
+    testValsIn = {0: 0,
+                  1: 0,
+                  2: 0,
+                  3: 0,
+                  4: 3,
+                  5: 0,
+                  6: 2}
+
+    testValsBT = {0: 3,
+                  1: 3,
+                  2: 3,
+                  3: 3,
+                  4: 3,
+                  5: 2,
+                  6: 2}
+
+    calcValsBT = flowCore.backTracking(testGraph, testValsIn)
+
+    for key,item in calcValsBT.items():
+        assert calcValsBT[key] == testValsBT[key]
+
+    testGraph = {0:[1,2,3],
+                 1:[4],
+                 2:[5,6],
+                 3:[7,8],
+                 4:[9],
+                 5:[9,10],
+                 6:[10],
+                 7:[11],
+                 8:[],
+                 9:[],
+                 10:[12],
+                 11:[],
+                 12:[]}
+
+    testValsIn = {0:0,
+                  1:0,
+                  2:0,
+                  3:0,
+                  4:0,
+                  5:0,
+                  6:0,
+                  7:0,
+                  8:0,
+                  9:1,
+                  10:0,
+                  11:3,
+                  12:2}
+
+    testValsBT = {0:3,
+                  1:1,
+                  2:2,
+                  3:3,
+                  4:1,
+                  5:2,
+                  6:2,
+                  7:3,
+                  8:0,
+                  9:1,
+                  10:2,
+                  11:3,
+                  12:2}
+
+    calcValsBT = flowCore.backTracking(testGraph, testValsIn)
+
+    for key,item in calcValsBT.items():
+        assert calcValsBT[key] == testValsBT[key]
+
+
+if __name__=='__main__':
+    test_add_os()
+    test_reverseTopology()
+    test_backTracking()

docs/moduleCom4FlowPy.rst

@@ -81,11 +81,21 @@ ii) additional modules (forest, infrastructure)
 - ``forest``: if set to ``True`` the runout calculation is performed with the *forest module* (a forest layer has to be provided)
 - ``infra``: if set to ``True`` the calculation is performend with the *backcalculation module* (an infrastructure layer has to be provided)
 
-iii) forest module parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+if ``infra`` is set to ``True`` the infrastructure layer has to be provided either in ``avalancheDir/INPUTS/INFRA`` (if ``useCustomPaths=False``) or at the defined
+``infraPath`` (if ``useCustomPaths=True``). The layer has to be of the same resolution and extent as the other input layers; infrastructure cells have to be coded with values > 0, while 
+values <= 0 will be interpreted as non-infrastructure. If infrastructure cells should contain an ordinal ranking (e.g. infrastructure importance), then higher values indicate higher
+infrastructure priority.
 
 .. Note::
-  Forest modules and parameters are currently updated/developed; we will update the description of parameters accordingly
+  - ``previewMode``: if this option is set to ``True`` not all release cells will be processed separately. Instead, release cells that are already contained in a previously modeled process path will not be modeled again.
+  Using this option can be useful for preliminary parameter studys since it saves computational time.
+  The previewMode will allow a rough approximation of results for output layers like ``zdelta``, ``travelLength``, or ``backCalculation`` with faster model run times.
+  However, model results relying on separate processing of all release cells (``cellCounts``, ``fpTravelAngle``, ``zDeltaSum``, ``slTravelAngle``, ``routFluxSum``, ``depFluxSum``) will
+  deviate strongly from ''full'' runs (``previewMode=False``) and should be interpreted with caution or simply removed from the output file list in ``(local_)com4FlowPyCfg.ini``.
+
+
+iii) forest module parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - ``forestModule``: if ``forest=True`` different forest modules ``[ForestFriction, ForestDetrainment, ForestFrictionLayer]`` can be selected.
 
@@ -234,6 +244,10 @@ If ``forestInteraction = True`` this layer will be written automatically (no nee
 
 - ``forestInteraction``: minimum number of forested raster cells a path runs through
 
+If ``infra = True`` this layer will be written automatically (no need to separately define in ``outputFiles``):
+
+- ``backcalculation``: Parts of modeled process paths upslope of infrastructure cells that are ''hit'' by (a) modeled process(es).
+
  .. Model Parameterisation
  .. ------------------------
  ..