[doc] Add new resistance setup to doc

benchmarks/avaKotResTest/avaKotResTest_desDict.json

@@ -0,0 +1,49 @@
+{
+  "TAGS": [
+    "res",
+    "resistance",
+    "standardTest",
+    "real"
+  ],
+  "DESCRIPTION": " this is Kot resistance test",
+  "TYPE": [
+    "2DPeak"
+  ],
+  "FILES": [
+    "relKot_5f7151e370_D_S_res_dfa_pft.asc",
+    "relKot_5f7151e370_D_S_res_dfa_pfv.asc",
+    "relKot_5f7151e370_D_S_res_dfa_ppr.asc"
+  ],
+  "TOPOTYPE": "real",
+  "AVANAME": "avaKot",
+  "AVADIR": "data/avaKot",
+  "simNameRef": "relKot_5f7151e370_D_S_res_dfa",
+  "NAME": "avaKotResTest",
+  "Test Info": {
+    "type": "text",
+    "Test Info": "This test runs the Kot resistance test."
+  },
+  "simType": "res",
+  "simName": {
+    "type": "simName",
+    "name": "relKot_5f7151e370_D_S_res_dfa"
+  },
+  "Simulation Parameters": {
+    "type": "list",
+    "Program version": "1.12+15.g5020492b.dirty",
+    "Parameter set": "Default",
+    "Release Area Scenario": "relKot",
+    "Entrainment": "No",
+    "Resistance": "Yes",
+    "Secondary release area": "No",
+    "Density [kgm-3]": "200",
+    "Friction model": "samosATSmall",
+    "Initial mass [kg]": "4328073.73",
+    "Final mass [kg]": "24949108.21",
+    "Entrained mass [kg]": "0.00",
+    "Entrained volume [m3]": "0.00",
+    "Stop criterion": "< 1.00 percent of PKE",
+    "Avalanche run time [s]": "103.70",
+    "Computation time [s]": "14.83"
+  }
+}

benchmarks/avaKotResTest/avaKot_AIMECCfg.ini

@@ -0,0 +1,11 @@
+### Config File - This file contains the main settings for the ana3AIMEC run
+## Set your parameters
+# This file is part of Avaframe.
+
+# Optional settings-------------------------------
+[AIMECSETUP]
+# define a runout area based on an angle of the thalweg profile (requires splitPoint in avaName/Inputs/POINTS as shpFile)
+defineRunoutArea = True
+# only used if defineRunoutArea=True - angle for the start of the run-out zone
+startOfRunoutAreaAngle = 25
+

benchmarks/avaKotResTest/avaKot_com1DFACfg.ini

@@ -0,0 +1,15 @@
+### Config File - This file contains the main settings for the simulation run
+## Copy to  local_com1DFACfg.ini and set you parameters
+# This file is part of Avaframe.
+
+
+[GENERAL]
+#++++++++++++++++ simulation type
+# list of simulations that shall be performed (null, ent, res, entres)
+simTypeList = res
+
+dam = False
+
+[INPUT]
+# specify a particular release area scenario, provide name of shapefile with or without extension .shp (optional)
+releaseScenario = relKot

docs/DFAnumerics.rst

@@ -642,18 +642,20 @@ reads:
 
 Added resistance force
 ~~~~~~~~~~~~~~~~~~~~~~~
-The resistance force on each particle reads (where :math:`h^{\text{eff}}_{k}`
-is a function of the average flow thickness :math:`\overline{h}_{k}`):
+The resistance force on each particle reads:
 
 .. math::
     F_{k,i}^{\text{res}}
-    = - \rho_0\,A_{k}\,h^{\text{eff}}_{k}\,C_{\text{res}}\,\|\overline{\mathbf{u}}_{k}\|^2\,\frac{\overline{u}_{k,i}}{|\overline{\mathbf{u}}_{k}\|}
+    = - \rho_0\,A_{k}\,C_{\text{resH}}\,\|\overline{\mathbf{u}}_{k}\|^2\,\frac{\overline{u}_{k,i}}{|\overline{\mathbf{u}}_{k}\|}
     :label: resistance force
 
 Both the bottom friction and resistance force are friction forces. The expression above represent the maximal
 friction force that can be added. This maximal force is added if the particles are flowing. If not, the friction force
 equals the driving forces. See :cite:`MaVi2003` for more information.
 
+In the default setup (``ResistanceModel =  default``), either detrainment or the extra resistance force is applied within the resistance area, depending on the thickness and speed of the flow.
+See :ref:`theoryCom1DFA:Resistance:` for more details.
+
 Entrainment force
 ~~~~~~~~~~~~~~~~~~~~~~~
 The term :math:`- \overline{u_i}\,\rho_0\,\frac{\mathrm{d}(A\,\overline{h})}{\mathrm{d}t}`

docs/com1DFAAlgorithm.rst

@@ -222,12 +222,14 @@ Go back to :ref:`com1DFAAlgorithm:Algorithm graph`
 
 Compute friction forces
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
 The friction force encompasses all forces that oppose the motion of the particles.
 One of those forces is the bottom shear force. The other is an optional resistance force.
 Both components are added to the :math:`F_{fric}` force term.
 
 Bottom shear force
-"""""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 This force accounts for the friction between the snow particles and the bottom surface.
 The expression of the bottom shear stress depends on the friction model chosen but can be written in the
 following general form, :math:`\tau^{(b)}_i = f(\sigma^{(b)},\overline{u},\overline{h},\rho_0,t,\mathbf{x})`.
@@ -238,9 +240,12 @@ gravity force and the curvature acceleration term as shown in :eq:`sigmab`. It i
 to deactivate the curvature acceleration component of the shear stress by setting the
 ``curvAcceleration`` coefficient to 0 in the configuration file.
 
+Go back to :ref:`com1DFAAlgorithm:Algorithm graph`
+
 
 Added resistance force
-"""""""""""""""""""""""
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 An additional friction force called resistance can be added. This force aims to model the added
 resistance due to the specificity of the terrain on which the avalanche evolves, for example
 due to forests. To add a resistance force, one must provide a resistance shapefile in the ``Inputs/RES``
@@ -298,15 +303,18 @@ Take detrainment into account
 Snow detrainment can be added to the simulation. One must provide a resistance shapefile
 in ``Inputs/RES`` and set the ``simType`` to ``res``, ``entres`` or ``available``
 (see :ref:`com1DFAAlgorithm:Initialize release, entrainment and resistance areas`) and set the flag ``detrainment = True``.
-If the flag ``detWithoutRes = True``, the resistance force (see :ref:`com1DFAAlgorithm:Compute friction forces`) is not computed. If ``detWithoutRes = False``, the detrainment effect and the resistance force are taken into account.
 
 In the areas defined by the resistance shapefile (for example in forests), mass of particles can be detrained causing a change of mass due to the detrainment.
 
 This is further detailed in :ref:`Detrainment <theoryCom1DFA:Detrainment:>`. The parameter
 used to compute these processes can be set in the configuration file.
 
 In the numerics, the mass is updated according to the detrainment model in
-:py:func:`com1DFA.DFAfunctionsCython.computeDetMass`. 
+:py:func:`com1DFA.DFAfunctionsCython.computeDetMass`.
+
+Detrainment is only applied when ``ResistanceModel =  default`` and ``detrainment = True``; depending on actual flow thickness and velocity,
+either detrainment or the additional resistance force is applied within the resistance area.
+See :ref:`theoryCom1DFA:Resistance:` for more details.
 
 
 Go back to :ref:`com1DFAAlgorithm:Algorithm graph`

docs/com1DFAAlgorithmGraph.dot

@@ -38,7 +38,7 @@ digraph "com1DFA algorithm graph" {
   computeGravityForce [label="Compute gravity driving force",
   href="../com1DFAAlgorithm.html#compute-driving-force" tooltip="Go to: Gravity force" target="_top"];
 
-  computeResForce [label="Compute additional resistance forces",
+  computeResForce [label="Compute additional resistance force",
   href="../com1DFAAlgorithm.html#added-resistance-force" tooltip="Go to: Additional resistance" target="_top"];
 
   updateMassEntr [label="Take entrainment into account, update mass and velocity",

docs/moduleCom1DFA.rst

@@ -78,6 +78,7 @@ at least two results are generated: the *null* variant and the variant with entr
 
   - marks the (multiple) areas where resistance is considered
   - resistance areas must not contain any "holes" or inner rings
+  - please consider the information about resistance below :ref:`moduleCom1DFA:Resistance setup`
 
 
 * one secondary release area (multi-) polygon shapefile (in Inputs/SECREL)
@@ -105,6 +106,7 @@ at least two results are generated: the *null* variant and the variant with entr
 
 Release-, entrainment thickness settings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. Note::
     Thickness is unambiguous: it is measured normal to the slope.
 
@@ -164,6 +166,19 @@ By default the friction parameter set *samosATAuto* is active. This uses the cal
 secondary release areas) to determine the parameters used for the samosAT friction model.
 See :ref:`samosatfrict` for the limits regarding release volumes.
 
+Resistance setup
+^^^^^^^^^^^^^^^^^^^
+
+.. Note::
+
+    In  versions earlier than 1.13, the default resistance setup included information about tree diameter, tree spacing,
+    etc. and was dependent on an effective thickness (a function of flow thickness). Please check out previous
+    documentation versions for details. This change leads to different results, so please assess whether the new
+    default setup is appropriate for your project. We provide a difference report at
+    `our homepage <https://avaframe.org/reports/>`_.
+
+By default, the resistance setup includes detrainment depending on the flow thickness (FT) and velocity (FV). Please 
+see :ref:`resistance` for more information.
 
 
 DEM input data

docs/theoryCom1DFA.rst

@@ -7,7 +7,7 @@ Governing Equations for the Dense Flow Avalanche
 The governing equations of the dense flow avalanche are derived from the
 incompressible mass and momentum balance on a Lagrange control volume (:cite:`Zw2000,ZwKlSa2003`).
 
-Mass balance:
+Mass balance
 ~~~~~~~~~~~~~~~
 
 .. math::
@@ -19,7 +19,7 @@ Mass balance:
 Where :math:`q^{\text{ent}}` represents the snow entrainment rate, 
 :math:`q^{\text{det}}` the snow detrainment rate (:math:`q^{\text{det}} < 0`).
 
-Momentum balance:
+Momentum balance
 ~~~~~~~~~~~~~~~~~~~
 
 .. math::
@@ -64,7 +64,7 @@ Using the mass balance equation :eq:`mass-balance1`, we get:
 
    \quad i=(1,2,3)
 
-Boundary conditions:
+Boundary conditions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The free surface is defined by :
@@ -97,7 +97,7 @@ The normals at the free surface (:math:`n_i^{(s)}`) and bottom surface (:math:`n
    \frac{\partial F_{s,b}}{\partial x_j}\right)^{-1/2}
 ..   :label: surface-normals
 
-Choice of the coordinate system:
+Choice of the coordinate system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The previous equations will be developed in the orthonormal coordinate
@@ -119,7 +119,7 @@ leads to:
    \mbox{for} \quad i=(1,2),\quad \mbox{and} \quad u^{(b)}_2 = u^{(b)}_3 = 0
 ..   :label: NCS-consequence
 
-Thickness averaged equations:
+Thickness averaged equations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In this NCS and considering a prism-like Control volume, the volume
 content :math:`V(t) = A_b(t)\overline{h}` is obtained by multiplication
@@ -139,7 +139,7 @@ the flow thickness,
 
         Small Lagrangian prism-like Control volume
 
-Entrainment:
+Entrainment
 """""""""""""
 
 The Snow entrainment processes are plowing at the front of the avalanche and erosion
@@ -191,7 +191,7 @@ defined by :math:`q^{\text{ent}}: =\rho^{\text{ent}} h^{\text{ent}}` which depen
 or erosion, is derived using the integral of :math:`\dot{q}^{\text{plo}}`, or respectively
 :math:`\dot{q}^{\text{ero}}`, over time.
 
-Detrainment:
+Detrainment
 """""""""""""
 
 The detrained snow :math:`M_{det}` at obstacles (e.g., trees) is computed by following the approach of (:cite:`FeBeTeBuChThBa2014`):
@@ -202,32 +202,40 @@ The detrained snow :math:`M_{det}` at obstacles (e.g., trees) is computed by fol
 
 The parameter :math:`K` (:math:`Pa`) depends on the structure of the obstacles and the properties of the snow.
 
+Currently, detrainment is only applicable when using the ``ResistanceModel =  default``. In this case,
+if flow thickness or flow velocity fall below minimum thresholds defined in the configuration file, detrainment is applied.
 
-Resistance:
+
+.. _resistance:
+
+Resistance
 """""""""""""
 
 The force :math:`F_i^{\text{res}}` due to obstacles is expressed
-as a function of the characteristic
-coefficient :math:`c_{\text{res}}` that depends on the structure of the obstacles and the effective height :math:`h^{\text{eff}}`, defined as :math:`\min(\overline{h}, h_{res} )`:
+as a function of the characteristic coefficient :math:`c_{\text{resH}}`:
 
 .. math::
-   F_i^{\text{res}} = -c_{\text{res}}\,\rho_0\,A\,
-    h^{\text{eff}}\,\overline{u}^2\,
+   F_i^{\text{res}} = -c_{\text{res}H}\,\rho_0\,A\,
+    \overline{u}^2\,
     \frac{\overline{u}_i}{\|\overline{u}\|}
 
-Note: in previous versions, this formula included information about tree diameter, tree spacing, etc. Please check out previous documentation versions for details.
+.. Note::
 
-There is also the option to compute the resistance force :math:`F_i^{\text{res}}`  independent of the effective height :math:`h^{\text{eff}}`:
+    In  versions earlier than 1.13, this formula included information about tree diameter, tree spacing, etc. and
+    was dependent on an effective thickness (a function of flow thickness). Please check out previous documentation
+    versions for details.
 
-- .. math::
-   F_i^{\text{res}} = -c_{\text{resH}}\,\rho_0\,A\,
-    \overline{u}^2\,
-    \frac{\overline{u}_i}{\|\overline{u}\|}
-
-with characteristic coefficient :math:`c_{\text{resH}}`.
+In the default setup (``ResistanceModel =  default`` and ``detrainment = True``) either detrainment or increased
+friction (using :math:`F_i^{\text{res}}`) is applied, depending on the flow thickness (FT) and velocity (FV) at the
+current cell and time step:
+
+   * FV OR FT below min thresholds: apply only detrainment, no increased friction
+   * FV AND FT within min and max thresholds: no detrainment, only apply increased friction
+   * FV OR FT above max thresholds: no detrainment and no increased friction applied
 
+If ``detrainment = False``, the additional resistance force is accounted for in the entire resistance area.
 
-Surface integral forces:
+Surface integral forces
 """""""""""""""""""""""""
 
 The surface integral is split in three terms, an integral over

pyproject.toml

@@ -46,7 +46,8 @@ dependencies = [
     "rasterio",
     "contextily",
     "geopandas",
-    "fiona"
+    "fiona",
+    "salib"
 ]
 
 [tool.flake8]