diff --git a/debrisframe/c1Tif/__init__.py b/debrisframe/c1TIF/__init__.py similarity index 100% rename from debrisframe/c1Tif/__init__.py rename to debrisframe/c1TIF/__init__.py diff --git a/debrisframe/c1Tif/c1Tif.py b/debrisframe/c1TIF/c1TIF.py similarity index 94% rename from debrisframe/c1Tif/c1Tif.py rename to debrisframe/c1TIF/c1TIF.py index 91c5112..4bdb4f8 100644 --- a/debrisframe/c1Tif/c1Tif.py +++ b/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 diff --git a/debrisframe/c1Tif/c1TifCfg.ini b/debrisframe/c1TIF/c1TIFCfg.ini similarity index 98% rename from debrisframe/c1Tif/c1TifCfg.ini rename to debrisframe/c1TIF/c1TIFCfg.ini index 9a98e04..829fd31 100644 --- a/debrisframe/c1Tif/c1TifCfg.ini +++ b/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] diff --git a/debrisframe/runC1Tif.py b/debrisframe/runC1TIF.py similarity index 91% rename from debrisframe/runC1Tif.py rename to debrisframe/runC1TIF.py index c3926ae..93bd998 100644 --- a/debrisframe/runC1Tif.py +++ b/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)) diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/sildeRelease.csv b/debrisframe/tests/data/testC1TIF/Inputs/REL/sildeRelease.csv similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/sildeRelease.csv rename to debrisframe/tests/data/testC1TIF/Inputs/REL/sildeRelease.csv diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.cpg b/debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.cpg similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.cpg rename to debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.cpg diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.dbf b/debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.dbf similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.dbf rename to debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.dbf diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.prj b/debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.prj similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.prj rename to debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.prj diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.shp b/debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.shp similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.shp rename to debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.shp diff --git a/debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.shx b/debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.shx similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/REL/slideRelease.shx rename to debrisframe/tests/data/testC1TIF/Inputs/REL/slideRelease.shx diff --git a/debrisframe/tests/data/testC1Tif/Inputs/slideTopo.asc b/debrisframe/tests/data/testC1TIF/Inputs/slideTopo.asc similarity index 100% rename from debrisframe/tests/data/testC1Tif/Inputs/slideTopo.asc rename to debrisframe/tests/data/testC1TIF/Inputs/slideTopo.asc diff --git a/debrisframe/tests/test_c1Tif.py b/debrisframe/tests/test_c1TIF.py similarity index 59% rename from debrisframe/tests/test_c1Tif.py rename to debrisframe/tests/test_c1TIF.py index f852593..246eb5a 100644 --- a/debrisframe/tests/test_c1Tif.py +++ b/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,13 +31,13 @@ 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"]: @@ -45,6 +45,6 @@ def test_runC1Tif(tmp_path): 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" diff --git a/docs/source/conf.py b/docs/source/conf.py index cb87c73..3a5e885 100644 --- a/docs/source/conf.py +++ b/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" diff --git a/docs/source/index.rst b/docs/source/index.rst index 654266d..a28f681 100644 --- a/docs/source/index.rst +++ b/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 ================== diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 979b46b..4974f91 100644 --- a/docs/source/installation.rst +++ b/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 diff --git a/docs/source/moduleC1TIF.rst b/docs/source/moduleC1TIF.rst new file mode 100644 index 0000000..ff5b2d9 --- /dev/null +++ b/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 `_ 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 `_. + + +.. 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 `_. +Regarding the release- and entrainment thickness settings we refer to the +`respective AvaFrame section `_. +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 `_. + + +Erosion, Deposition, adaptive topography +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When `entrainment `_, +`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 `_). +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 `_. + + +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 `_.