From ef407bf91d564485f0689fe619e89a0b5e58a6b6 Mon Sep 17 00:00:00 2001 From: Felix Oesterle <6945681+fso42@users.noreply.github.com> Date: Thu, 16 Oct 2025 19:06:18 +0200 Subject: [PATCH 1/3] docs(com9MoTVoellmy): update and expand documentation - Replaced `autosummary_mock_imports` with correct `autodoc_mock_imports` in `conf.py`. - Added extensive details for input, output, and setup for running `com9MoTVoellmy`. - Updated API references and module index to include `com9MoTVoellmy`. - Improved formatting and feature documentation docs(com9MoTVoellmy): update installation instructions and requirements - Removed outdated instructions for downloading the AvaFrame connector docs(com9MoTVoellmy): update installation steps and parameters - Added new forest density (`nd`) and tree diameter (`bhd`) parameters with descriptions. --- docs/api.rst | 1 + docs/conf.py | 35 +------------- docs/index.rst | 2 +- docs/moduleCom9MoTVoellmy.rst | 87 +++++++++++++++++++++++++++-------- pyproject.toml | 1 + 5 files changed, 74 insertions(+), 52 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index b0af8b82c..616b2f40c 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -17,6 +17,7 @@ Computational Modules com5SnowSlide com6RockAvalanche com7Regional + com9MoTVoellmy Input/Transformation Modules ============================ diff --git a/docs/conf.py b/docs/conf.py index e9cef6d40..23e15240e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,39 +49,8 @@ # alternative: use base requirements.txt in readthedocs.yml files to install # missing modules on rtd -autosummary_mock_imports = [ - 'avaframe', - 'avaframe.com1DFA.damCom1DFA', - 'com1DFA.damCom1DFA', - 'com1DFA.DFAfunctionsCython', - 'com1DFA.DFAToolsCython', - 'out3Plot.plotUtils', - 'numpy', - 'shapefile', - 'scipy', - 'matplotlib', - 'glob', - 'subprocess', - 'shutil', - 'math', - 'pandas', - 'copy', - 'os', - 'logging', - 'time', - 'mpl_toolkits', - 'seaborn', - 'shapely', - 'configUpdater', - 'configupdater', - 'geopandas', - 'tabulate', - 'deepdiff', - 'deepmerge', - 'cmcrameri', - 'pyshp', - 'make_axes_locatable', -] +# Note: autosummary_mock_imports is not a valid Sphinx option, use autodoc_mock_imports instead +autodoc_mock_imports = [] autosummary_generate = True napoleon_google_docstring = True diff --git a/docs/index.rst b/docs/index.rst index 1a8df07a0..54e2e15ce 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,7 +54,7 @@ Computational modules * :doc:`moduleCom6RockAvalanche` * :doc:`moduleCom7Regional` * :doc:`moduleCom8MoTPSA` - * :doc:`moduleCom8MoTVoellmy` + * :doc:`moduleCom9MoTVoellmy` .. toctree:: :maxdepth: 3 diff --git a/docs/moduleCom9MoTVoellmy.rst b/docs/moduleCom9MoTVoellmy.rst index 7a141c3e4..d5574b724 100644 --- a/docs/moduleCom9MoTVoellmy.rst +++ b/docs/moduleCom9MoTVoellmy.rst @@ -1,5 +1,5 @@ com9MoTVoellmy: NGI MoT-Voellmy -========================== +=============================== .. Note:: This module (as well as this documentation) is currently under development and highly experimental! The parameter settings are completely untested and unchecked. Do not expect sensible results with the included @@ -8,16 +8,78 @@ com9MoTVoellmy: NGI MoT-Voellmy :py:mod:`com9MoTVoellmy` allows to run the MoT-Voellmy code by Norwegian-Geotechnical-Institute (`MoT-Voellmy github repository `_). +More information and background can be found there as +well `MoT-Voellmy Documentation `_ + +**This documentation covers issues related directly to running MoT-Voellmy with the help of AvaFrame** + +There are 2 ways of running, please choose below. + +MoT Voellmy via QGis +-------------------- + +Installation on Windows: +^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Open the OSGeo4WShell that matches your QGis installation +#. Run:: + + pip install avaframe==2.0a3 + +#. Start QGis and go to `Plugins` -> `Manage and install plugins` +#. Choose `All`, search for `AvaFrame` and install/update +#. You find the `AvaFrame` toolset in the `Processing Toolbox` +#. Go to `NGI_experimental` and start `MoTVoellmy (com9)` + + Input ------ -TODO +^^^^^ + +For additional info, see also `NGI Dokumentation `_. + +Required is + +* digital elevation model as raster file with `ESRI grid format `_. + +ONE of the following: + +* release area scenario as (multi-) polygon shapefile + + - the release area polygon must not contain any "holes" or inner rings + - the release area name should not contain an underscore. + - recommended attributes are *name*, *thickness* (see :ref:`moduleCom1DFA:Release-, entrainment thickness settings`) + - ALL features within one shapefile are released at the same time (and interact), this is what we refer to as *scenario* + - if you want to simulate different scenarios with the same features, you have to copy them to separate shapefiles + +* release area scenario as raster file + + - same specifications as the DEM (extend, cellsize) + +And the following optional raster files, in the same specification as the DEM (extend, cellsize): + +* mu / Dry friction coefficient. If this is given, k needs to be set as well. +* k / Turbulent friction coefficient. If this is given, mu needs to be set as well. +* b0 / Erodible snow depth. If this is given, tau_c needs to be set as well. +* tau_c / Snow shear strength. If this is given, b0 needs to be set as well +* nd / Forest density. If this is given, bhd needs to be set as well +* bhd / Tree diamenter. If this is given, nd needs to be set as well + +The `Destination Folder` should be empty! + + Outputs --------- -TODO +^^^^^^^ + +After you ran the simulation, the peak fields will be loaded in QGis and the `Destinaton Folder` will contain, results, +plots, and configuration files. + + +MoT Voellmy via the script variant +---------------------------------- To run -------- +^^^^^ * go to ``AvaFrame/avaframe/com9MoTVoellmy`` * copy ``com9MoTVoellmy/com9MoTVoellmyCfg.ini`` to ``com9MoTVoellmy/local_com9MoTVoellmyCfg.ini`` and edit (if not, default values are used) @@ -25,16 +87,5 @@ To run * enter the path to the desired dataset in ``local_avaframeCfg.ini`` * run:: - python3 runCom8MoTPSA.py - - -Theory ------- - -TODO - - -Configuration parameters ---------------------------------- + python3 runCom9MoTVoellmy.py -TODO \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index cdff1d1b3..c9cdb5141 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -94,6 +94,7 @@ gdal = "*" libgdal = "*" geos = "*" proj = "*" +python = "<3.14" # Feature dev [tool.pixi.feature.dev.pypi-dependencies] From feb6738e0ba98e4b4d0b1763923bb4e4e42512ef Mon Sep 17 00:00:00 2001 From: Felix Oesterle <6945681+fso42@users.noreply.github.com> Date: Tue, 21 Oct 2025 15:26:12 +0200 Subject: [PATCH 2/3] chore(config): comment out deprecated dependencies in `pyproject.toml` - Marked `gdal`, `geos`, `proj`, and `python <3.14` dependencies as comments. - Prepares for removal of deprecated entries in the future. --- pyproject.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index c9cdb5141..ecdf0afd2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,11 +90,11 @@ setuptools = "*" setuptools-scm = "*" cibuildwheel = "*" # FSO: remove as soon as possible -gdal = "*" +#gdal = "*" libgdal = "*" -geos = "*" -proj = "*" -python = "<3.14" +#geos = "*" +#proj = "*" +#python = "<3.14" # Feature dev [tool.pixi.feature.dev.pypi-dependencies] From 33986d1e8bee2a30774f114184cd971595c95576 Mon Sep 17 00:00:00 2001 From: Felix Oesterle <6945681+fso42@users.noreply.github.com> Date: Tue, 21 Oct 2025 16:15:38 +0200 Subject: [PATCH 3/3] docs(com9MoTVoellmy): fix typos in documentation docs(config): readd doc `conf.py` mock modules --- docs/conf.py | 88 ++++++++++++++++++++++++----------- docs/moduleCom9MoTVoellmy.rst | 14 +++--- 2 files changed, 67 insertions(+), 35 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 23e15240e..630f55ab7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,17 +13,18 @@ import os import sys import sphinx_rtd_theme + # import avaframe # sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath('../avaframe')) -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath("../avaframe")) +sys.path.insert(0, os.path.abspath("..")) # sys.path.insert(0, os.path.abspath('../avaframe')) # -- Project information ----------------------------------------------------- -project = 'AvaFrame' -copyright = '2021, AvaFrame developers' -author = 'AvaFrame developers' +project = "AvaFrame" +copyright = "2021, AvaFrame developers" +author = "AvaFrame developers" # -- General configuration --------------------------------------------------- @@ -32,25 +33,56 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.napoleon', - 'sphinx.ext.autosummary', - 'sphinx.ext.viewcode', - 'sphinx_rtd_theme', - 'sphinx.ext.autosectionlabel', - 'sphinx.ext.extlinks', - 'sphinxcontrib.bibtex', - 'sphinx.ext.graphviz', + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosummary", + "sphinx.ext.viewcode", + "sphinx_rtd_theme", + "sphinx.ext.autosectionlabel", + "sphinx.ext.extlinks", + "sphinxcontrib.bibtex", + "sphinx.ext.graphviz", ] # -- GraphViz configuration ---------------------------------- -graphviz_output_format = 'svg' +graphviz_output_format = "svg" -bibtex_bibfiles = ['references_all.bib'] +bibtex_bibfiles = ["references_all.bib"] # alternative: use base requirements.txt in readthedocs.yml files to install # missing modules on rtd -# Note: autosummary_mock_imports is not a valid Sphinx option, use autodoc_mock_imports instead -autodoc_mock_imports = [] +autodoc_mock_imports = [ + "avaframe", + "avaframe.com1DFA.damCom1DFA", + "com1DFA.damCom1DFA", + "com1DFA.DFAfunctionsCython", + "com1DFA.DFAToolsCython", + "out3Plot.plotUtils", + "numpy", + "shapefile", + "scipy", + "matplotlib", + "glob", + "subprocess", + "shutil", + "math", + "pandas", + "copy", + "os", + "logging", + "time", + "mpl_toolkits", + "seaborn", + "shapely", + "configUpdater", + "configupdater", + "geopandas", + "tabulate", + "deepdiff", + "deepmerge", + "cmcrameri", + "pyshp", + "make_axes_locatable", +] autosummary_generate = True napoleon_google_docstring = True @@ -65,15 +97,15 @@ autosectionlabel_maxdepth = 4 # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'run*', '*run*', 'run'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "run*", "*run*", "run"] # Set the master document name for readthedocs builds -master_doc = 'index' +master_doc = "index" # -- Options for HTML output ------------------------------------------------- @@ -86,27 +118,27 @@ # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'logo_only': True, - 'style_nav_header_background': '#343131', + "logo_only": True, + "style_nav_header_background": "#343131", # 'display_version': False, } # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_static/logo.png' +html_logo = "_static/logo.png" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = '_static/favicon.png' +html_favicon = "_static/favicon.png" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # -- Options for LaTeX output --------------------------------------------- -latex_logo = '_static/logo.png' +latex_logo = "_static/logo.png" # -- Options for referencing ------------------------------------------- numfig = True @@ -115,4 +147,4 @@ def setup(app): - app.add_css_file('css/custom.css') + app.add_css_file("css/custom.css") diff --git a/docs/moduleCom9MoTVoellmy.rst b/docs/moduleCom9MoTVoellmy.rst index d5574b724..3b46eeceb 100644 --- a/docs/moduleCom9MoTVoellmy.rst +++ b/docs/moduleCom9MoTVoellmy.rst @@ -35,7 +35,7 @@ Installation on Windows: Input ^^^^^ -For additional info, see also `NGI Dokumentation `_. +For additional info, see also `NGI Documentation `_. Required is @@ -53,16 +53,16 @@ ONE of the following: * release area scenario as raster file - - same specifications as the DEM (extend, cellsize) + - same specifications as the DEM (extent, cellsize) -And the following optional raster files, in the same specification as the DEM (extend, cellsize): +And the following optional raster files, in the same specification as the DEM (extent, cellsize): * mu / Dry friction coefficient. If this is given, k needs to be set as well. * k / Turbulent friction coefficient. If this is given, mu needs to be set as well. * b0 / Erodible snow depth. If this is given, tau_c needs to be set as well. -* tau_c / Snow shear strength. If this is given, b0 needs to be set as well -* nd / Forest density. If this is given, bhd needs to be set as well -* bhd / Tree diamenter. If this is given, nd needs to be set as well +* tau_c / Snow shear strength. If this is given, b0 needs to be set as well. +* nd / Forest density. If this is given, bhd needs to be set as well. +* bhd / Tree diameter. If this is given, nd needs to be set as well. The `Destination Folder` should be empty! @@ -71,7 +71,7 @@ The `Destination Folder` should be empty! Outputs ^^^^^^^ -After you ran the simulation, the peak fields will be loaded in QGis and the `Destinaton Folder` will contain, results, +After you ran the simulation, the peak fields will be loaded in QGis and the `Destination Folder` will contain, results, plots, and configuration files.