[c1]: rename to c1TIF; add documentation

debrisframe/c1Tif/c1Tif.py → debrisframe/c1TIF/c1TIF.py

@@ -12,10 +12,10 @@
 from avaframe.com1DFA import com1DFA
 
 # create local logger under avaframe namespace to use its logging configuration
-log = logging.getLogger("avaframe.debrisframe.c1Tif")
+log = logging.getLogger("avaframe.debrisframe.c1TIF")
 
 
-def c1TifMain(cfgMain, debrisCfg):
+def c1TIFMain(cfgMain, debrisCfg):
     """Run and adjust parameters to match debris flow settings for com1DFA run,
     result files, reports and plots are saved analog to a standard com1DFA model run
 

debrisframe/c1Tif/c1TifCfg.ini → debrisframe/c1TIF/c1TIFCfg.ini

@@ -1,5 +1,5 @@
 ### Config File - This file contains the main settings for the debris flow simulation run
-## Copy to  local_c1TifCfg.ini and set your parameters
+## Copy to  local_c1TIFCfg.ini and set your parameters
 
 
 [GENERAL]

debrisframe/runC1Tif.py → debrisframe/runC1TIF.py

@@ -15,10 +15,10 @@
 
 # import computation modules
 import debrisframe as debf
-from debrisframe.c1Tif import c1Tif
+from debrisframe.c1TIF import c1TIF
 
 
-def runC1Tif(debrisDir=""):
+def runC1TIF(debrisDir=""):
     """Run com1DFA with debris flow parameters with only an avalanche/ debris flow directory as input
 
     Parameters
@@ -35,7 +35,7 @@ def runC1Tif(debrisDir=""):
     startTime = time.time()
 
     # log file name; leave empty to use default runLog.log
-    logName = "runC1Tif"
+    logName = "runC1TIF"
 
     # Load debris flow directory from general configuration file
     # More information about the configuration can be found here
@@ -59,10 +59,10 @@ def runC1Tif(debrisDir=""):
     initProj.cleanSingleAvaDir(debrisDir, deleteOutput=False)
 
     # load debris flow config
-    DebrisCfg = cfgUtils.getModuleConfig(c1Tif)
+    DebrisCfg = cfgUtils.getModuleConfig(c1TIF)
 
     # perform com1DFA simulation with debris flow settings
-    _, plotDict, reportDictList, _ = c1Tif.c1TifMain(cfgMain, DebrisCfg)
+    _, plotDict, reportDictList, _ = c1TIF.c1TIFMain(cfgMain, DebrisCfg)
 
     # Get peakfiles to return to QGIS
     debrisDir = pathlib.Path(debrisDir)
@@ -88,4 +88,4 @@ def runC1Tif(debrisDir=""):
     )
     print(parser)
     args = parser.parse_args()
-    runC1Tif(str(args.debrisdir))
+    runC1TIF(str(args.debrisdir))

debrisframe/tests/test_c1Tif.py → debrisframe/tests/test_c1TIF.py

@@ -1,5 +1,5 @@
 """
-Pytest for module c1Tif
+Pytest for module c1TIF
 """
 
 #  Load modules
@@ -8,17 +8,17 @@
 import shutil
 import pytest
 
-from debrisframe.c1Tif import c1Tif
+from debrisframe.c1TIF import c1TIF
 
 from avaframe.in3Utils import cfgUtils
 
 
-def test_runC1Tif(tmp_path):
-    """Check that runCom1DFA produces the good outputs"""
+def test_runC1TIF(tmp_path):
+    """Check that runC1TIF produces the good outputs"""
 
     testDir = pathlib.Path(__file__).parents[0]
-    inputDir = testDir / "data" / "testC1Tif"
-    avaDir = pathlib.Path(tmp_path, "testC1Tif")
+    inputDir = testDir / "data" / "testC1TIF"
+    avaDir = pathlib.Path(tmp_path, "testC1TIF")
     shutil.copytree(inputDir, avaDir)
 
     cfgMain = configparser.ConfigParser()
@@ -31,20 +31,20 @@ def test_runC1Tif(tmp_path):
         "debugPlot": "False",
     }
     # modCfg, modInfo = cfgUtils.getModuleConfig(com1DFA, fileOverride=cfgFile, modInfo=True)
-    modCfg, modInfo = cfgUtils.getModuleConfig(c1Tif, modInfo=True)
+    modCfg, modInfo = cfgUtils.getModuleConfig(c1TIF, modInfo=True)
 
-    modCfg['com1DFA_com1DFA_override']['rho'] = '1000'
-    modCfg['com1DFA_com1DFA_override']['explicitFriction'] = '0'
-    modCfg['com1DFA_com1DFA_override']['frictModel'] = 'Voellmy'
+    modCfg["com1DFA_com1DFA_override"]["rho"] = "1000"
+    modCfg["com1DFA_com1DFA_override"]["explicitFriction"] = "0"
+    modCfg["com1DFA_com1DFA_override"]["frictModel"] = "Voellmy"
 
-    dem, plotDict, reportDictList, simDF = c1Tif.c1TifMain(cfgMain, modCfg)
+    dem, plotDict, reportDictList, simDF = c1TIF.c1TIFMain(cfgMain, modCfg)
 
     outDir = avaDir / "Outputs" / "com1DFA"
     for ext in ["pft", "pfv", "ppr"]:
         assert (outDir / "peakFiles" / ("%s_%s.asc" % (simDF["simName"].iloc[0], ext))).is_file()
 
     assert (outDir / "configurationFiles" / ("%s.ini" % (simDF["simName"].iloc[0]))).is_file()
     assert (outDir / "configurationFiles" / ("allConfigurations.csv")).is_file()
-    assert simDF['rho'].iloc[0] == 1000
-    assert simDF['explicitFriction'].iloc[0] == 0
-    assert simDF['frictModel'].iloc[0] == 'Voellmy'
+    assert simDF["rho"].iloc[0] == 1000
+    assert simDF["explicitFriction"].iloc[0] == 0
+    assert simDF["frictModel"].iloc[0] == "Voellmy"

docs/source/conf.py

@@ -17,6 +17,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autosectionlabel",
 ]
 
 intersphinx_mapping = {
@@ -27,6 +28,10 @@
 
 templates_path = ["_templates"]
 
+# make referencing unique if the same section heading exists doubly
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 4
+
 # -- Options for HTML output
 
 html_theme = "sphinx_rtd_theme"

docs/source/index.rst

@@ -29,6 +29,21 @@ General
    installation.rst
 
 
+Computational modules
+=====================
+
+.. only:: html
+
+    * :doc:`moduleC1TIF`
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+   :caption: Computational modules
+
+   moduleC1TIF.rst
+
+
 Indices and tables
 ==================
 

docs/source/installation.rst

@@ -30,7 +30,7 @@ change into your ``debrisframe`` directory (replace [YOURDIR] with your path fro
 
 
   cd [YOURDIR]/DebrisFrame/debrisframe
-  python runC1Tif.py
+  python runC1TIF.py
 
 
 

docs/source/moduleC1TIF.rst

@@ -0,0 +1,92 @@
+c1TIF: thickness integrated flow module
+=======================================
+
+:py:mod:`c1TIF` is a module for debris flow computations using thickness integration.
+c1TIF executes  `AvaFrame::com1DFA <https://docs.avaframe.org/en/latest/moduleCom1DFA.html>`_ with
+overwriting various parameters and adding debris-flow related features.
+Calculations are based on the thickness integrated governing equations and
+solved numerically using the smoothed particle hydrodynamics (sph) method. Please note
+the use of *thickness averaged/integrated* instead of *depth averaged/integrated* for clarity and consistency.
+
+Thickness integrated flow simulations can be performed for different release scenarios, with or without
+entrainment and/or resistance areas, and is controlled via a configuration file.
+The configuration can be modified in order to change any of the default settings and also allows
+to perform simulations for varying parameters all at once.
+
+.. Note::
+   We provide the documentation of the most important debris flow related features here,
+   for the entire documentation we refer to the
+   `AvaFrame documentation <https://docs.avaframe.org/en/latest/moduleCom1DFA.html>`_.
+
+
+.. Note::
+   The configuration parameters are still under development.
+
+Input
+---------
+
+c1TIF simulations 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>`_.
+Regarding the release- and entrainment thickness settings we refer to the
+`respective AvaFrame section <https://docs.avaframe.org/en/latest/moduleCom1DFA.html#release-entrainment-thickness-settings>`_.
+Note that option 3 (thickness set via time dependent release file) is the default setting in c1TIF.
+This option is used for hydrographs as input.
+
+
+Friction parameters
+^^^^^^^^^^^^^^^^^^^
+The available friction models are described
+`here <https://docs.avaframe.org/en/latest/theoryCom1DFA.html#friction-model>`_.
+
+
+Erosion, Deposition, adaptive topography
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When `entrainment <https://docs.avaframe.org/en/latest/theoryCom1DFA.html#entrainment>`_,
+`detrainment <https://docs.avaframe.org/en/latest/theoryCom1DFA.html#detrainment>`_
+or stopping (flow velocity is zero) occurs and the respective flags `adaptSfcEntrainment`,
+`adaptSfcDetrainment` and `adaptSfcStopped` are switched on, the surface is adapted accordingly
+(see the `AvaFrame adaptive topography documentation <https://docs.avaframe.org/en/latest/theoryCom1DFA.html#adaptive-surface>`_).
+Additionally, the deposition can be erodible if `entrainableDeposition` is switched on.
+
+
+Model configuration
+--------------------
+The model configuration is read from a configuration file: ``c1TIF/c1TIFCfg.ini``. In this file,
+all model parameters are listed and can be modified. These parameters overwrite the respective parameters
+of AvaFrame's `com1DFACfg.ini` configuration file. We recommend to create a local copy
+and keep the default configuration in ``c1TIF/c1TIFCfg.ini`` untouched.
+For this purpose, in ``DebrisFrame/debrisframe/`` run:
+
+  ::
+
+    cp c1TIF/c1TIFCfg.ini c1TIF/local_c1TIFCfg.ini
+
+and modify the parameter values in there.
+
+It is also possible to perform multiple simulations at once, with varying input parameters.
+
+
+Output
+---------
+The simulation results are saved to: *Outputs/com1DFA*.
+The description of the default and optional results are in the `AvaFrame documentation <https://docs.avaframe.org/en/latest/moduleCom1DFA.html#output>`_.
+
+
+To run
+--------
+
+* first go to ``DebrisFrame/debrisframe``
+* copy ``debrisframeCfg.ini`` to ``local_debrisframeCfg.ini`` and set your desired process directory name
+* create a process directory with required input files
+* copy ``c1TIF/c1TIFCfg.ini`` to ``c1TIF/local_c1TIFCfg.ini`` and if desired change configuration settings
+
+* run:
+  ::
+
+    pixi run python runC1TIF.py
+
+
+Theory
+--------
+The theory and numerics of the thickness integrated flow model can be found in the
+`AvaFrame documentation: com1DFA Theory <https://docs.avaframe.org/en/latest/theoryCom1DFA.html>`_.