diff --git a/.github/workflows/runTestSinglePython.yml b/.github/workflows/runTestSinglePython.yml index 95255ced0..fc4a7fdf0 100644 --- a/.github/workflows/runTestSinglePython.yml +++ b/.github/workflows/runTestSinglePython.yml @@ -6,8 +6,12 @@ name: Test single python version on: push: branches: [ master ] + paths-ignore: + - 'docs/**' pull_request: branches: [ master ] + paths-ignore: + - 'docs/**' workflow_dispatch: jobs: diff --git a/docs/advancedUsage.rst b/docs/advancedUsage.rst new file mode 100644 index 000000000..56b44aa63 --- /dev/null +++ b/docs/advancedUsage.rst @@ -0,0 +1,71 @@ +Advanced Usage (Script) +======================= + +After the installation, the next sections describe on how to get started. The sections configuration and logging +describe the general methods we use, this is helpful to understand how you can change model parameters and similar. + +.. include:: developinstall.rst + +-------------------------- + +.. include:: gettingstarted.rst + +--------------------------- + +.. include:: configuration.rst + +------------------------- + +.. include:: logging.rst + +------------------------- + +Example runscripts +------------------ + +In :py:mod:`runScripts` we provide ready-to-use scripts for different applications of the modules provided within +AvaFrame. + + +Derive input data +^^^^^^^^^^^^^^^^^^^ +- :py:mod:`runScripts.runComputeDist` + +Create a new project +^^^^^^^^^^^^^^^^^^^^^^ +- :py:mod:`runScripts.runInitializeProject` + + +Generate idealized/generic topography data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- :py:mod:`runScripts.runGenerateTopo` +- :py:mod:`runScripts.runGenProjTopoRelease` + + +Postprocessing +^^^^^^^^^^^^^^^ + +- :py:mod:`runScripts.runAna3AIMEC` +- :py:mod:`runScripts.runAna3AIMECCompMods` +- :py:mod:`runScripts.runAna3AIMECIndi` +- :py:mod:`runScripts.runStatsExample` +- :py:mod:`runScripts.runProbAna` + + +Visualisation +^^^^^^^^^^^^^^^ +- :py:mod:`runScripts.runQuickPlotSimple` +- :py:mod:`runScripts.runQuickPlotOne` +- :py:mod:`runScripts.runPlotTopo` +- :py:mod:`runScripts.runExportToCsv` + + +Testing +^^^^^^^^ +- :py:mod:`runScripts.runDamBreak` +- :py:mod:`runScripts.runSimilaritySol` +- :py:mod:`runScripts.runTestFP` +- :py:mod:`runScripts.runStandardTestsCom1DFAOrig` +- :py:mod:`runScripts.runComparisonModules` +- :py:mod:`runScripts.runFetchBench` +- :py:mod:`runScripts.runWriteDesDict` diff --git a/docs/com1DFAAlgorithm.rst b/docs/com1DFAAlgorithm.rst index 32574ea53..f2c95a91e 100644 --- a/docs/com1DFAAlgorithm.rst +++ b/docs/com1DFAAlgorithm.rst @@ -1,5 +1,5 @@ -Dense Flow Avalanche algorithm and workflow -============================================ +com1DFA Algorithm and workflow +============================== Algorithm graph ---------------- @@ -293,7 +293,7 @@ The mesh values are updated with the particles properties using This is used to compute flow thickness, flow velocity and pressure fields from the particle properties. Update particles flow thickness -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The mesh flow thickness is finally used to update the particle flow thickness value using :ref:`mesh to particle interpolation ` methods. diff --git a/docs/connector.rst b/docs/connector.rst new file mode 100644 index 000000000..a9296ebe8 --- /dev/null +++ b/docs/connector.rst @@ -0,0 +1,50 @@ +AvaFrameConnector (GUI) +======================= + +The AvaFrameConnector allows QGis users to access certain base workflows directly from QGis. The connector +only provides the interface to functions within the AvaFrame python package, and is developed separately, see the +`QGisAF github repository `_. +It makes use of the QGis processing plugin, which is included in all current QGis releases. + +Here is a quick overview of the processing scripts the AvaFrameConnector provides: + +Operational +----------- + +.. glossary:: + :sorted: + + Dense Flow Standard + Runs dense flow avalanche module com1DFA. For more specific info about the inputs (shapefile attributes etc), see + :ref:`moduleCom1DFA:Input`. You can select multiple shapefiles for release areas, each will be calculated as one scenario. + Each shapefile can contain multiple polygons. If you provide entrainment/resistance areas, each scenario will be calculated + once without them (i.e null simulation) and once with them. + + Full Operational Run + Runs com1DFA and additionally com2AB if profile and splitpoint are set. + Additional info see description of runCom1DFA. + + +Experimental +------------ + +These either require deeper knowledge about the AvaFrame python package, i.e. configuration files etc., or are not yet +fully tested and might produce unwanted results. + +.. glossary:: + :sorted: + + AvaFrameLayerRename + Renames com1DFA result layers by adding the values of the given variable (from the configuration file) + +Admin +----- + +.. glossary:: + :sorted: + + GetVersion + Displays the current version of the AvaFrame python package (NOT the AvaFrameConnector) + + UpdateAvaFrame + Updates the AvaFrame python package diff --git a/docs/develop.rst b/docs/develop.rst index 3fc25a6fc..446589ff9 100644 --- a/docs/develop.rst +++ b/docs/develop.rst @@ -1,5 +1,9 @@ -Notes to Developers -=================== +Development +=========== + + +Notes to developers +------------------- Here you can find notes on design principles and how to contribute to AvaFrame. @@ -32,7 +36,7 @@ AF-STYLE-4: No dead code reading the source code. Old code is available in the source history if it is needed. - +-------------------------- Our suggested git workflow -------------------------- @@ -88,6 +92,9 @@ repository/origin will be handled by the pull request):: git branch -d myAwesomeFeature +-------------------------- + + Build the documentation ------------------------ @@ -127,6 +134,7 @@ and you should see something like:: ==========================1 passed in 0.02s ========================= +--------------------------- How to add a benchmark test ---------------------------- @@ -163,52 +171,3 @@ You can check out the markdown-style report of the comparison at: ``tests/reports/standardTestsReportPy.md``. -Examples ---------- - -In :py:mod:`runScripts` we provide ready-to-use scripts for different applications of the modules provided within -AvaFrame. - - -Derive input data -~~~~~~~~~~~~~~~~~~~ -- :py:mod:`runScripts.runComputeDist` - -Create a new project -~~~~~~~~~~~~~~~~~~~~~~ -- :py:mod:`runScripts.runInitializeProject` - - -Generate idealized/generic topography data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :py:mod:`runScripts.runGenerateTopo` -- :py:mod:`runScripts.runGenProjTopoRelease` - - -Postprocessing -~~~~~~~~~~~~~~~ - -- :py:mod:`runScripts.runAna3AIMEC` -- :py:mod:`runScripts.runAna3AIMECCompMods` -- :py:mod:`runScripts.runAna3AIMECIndi` -- :py:mod:`runScripts.runStatsExample` -- :py:mod:`runScripts.runProbAna` - - -Visualisation -~~~~~~~~~~~~~~~ -- :py:mod:`runScripts.runQuickPlotSimple` -- :py:mod:`runScripts.runQuickPlotOne` -- :py:mod:`runScripts.runPlotTopo` -- :py:mod:`runScripts.runExportToCsv` - - -Testing -~~~~~~~~ -- :py:mod:`runScripts.runDamBreak` -- :py:mod:`runScripts.runSimilaritySol` -- :py:mod:`runScripts.runTestFP` -- :py:mod:`runScripts.runStandardTestsCom1DFAOrig` -- :py:mod:`runScripts.runComparisonModules` -- :py:mod:`runScripts.runFetchBench` -- :py:mod:`runScripts.runWriteDesDict` diff --git a/docs/developinstall.rst b/docs/developinstall.rst index 5ab33c204..b7b92863d 100644 --- a/docs/developinstall.rst +++ b/docs/developinstall.rst @@ -1,9 +1,9 @@ -Development Installation ------------------------- +Advanced (Script) Installation +------------------------------ This is a quick guide on how to install AvaFrame and the required dependencies on your machine. AvaFrame is developed on **Linux -machines** (Ubuntu/Manjaro/Arch) with recent Python versions 3.8/3.9. +machines** (Ubuntu/Manjaro/Arch) with recent Python versions > 3.8. These instructions assume you are familiar with working in a terminal. This guide is currently described for *Linux* only, but expert users should be able to adapt it to *Windows*. @@ -24,7 +24,7 @@ Setup AvaFrame Create a new `conda environment `_ -for AvaFrame, activate it and install pip in this environment:: +for AvaFrame, activate it and install pip, numpy and cython in this environment:: conda create --name avaframe_env conda activate avaframe_env @@ -55,7 +55,7 @@ current (local) version will be used. Test it by starting ``python`` and do an ``import avaframe``. If no error comes up, you are good to go. -Head over to :ref:`gettingstarted:Getting Started` for the next steps. +Head over to :ref:`gettingstarted:First run` for the next steps. Update AvaFrame ^^^^^^^^^^^^^^^ diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index 5b2731fd8..cf2c13ac6 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -1,14 +1,12 @@ -Basic usage -=========== +.. Basic usage +.. ----------- -.. Note:: +.. .. Note:: - These instructions target the development installation. If you are using the standard / operational installation we - provide a recording from the first public `AvaFrame workshop `_ . You will find a demo - starting at around the 17:25min mark. + .. These instructions target the development installation. If you are using the standard / operational installation we + .. provide a recording from the first public `AvaFrame workshop `_ . You will find a demo + .. starting at around the 17:25min mark. -After the installation, the next sections describe on how to get started. The sections configuration and logging -describe the general methods we use, this is helpful to understand how you can change model parameters and similar. First run --------- @@ -53,7 +51,7 @@ Workflow example The following example should make it easier for you to find your way in AvaFrame and setup your own AvaFrame workflow after you did the full setup. There is also a directory with examples for different workflows, see more here: -:ref:`develop:Examples`. +:ref:`advancedUsage:Example runScripts`. Make sure you change to your ``AvaFrame`` directory by:: @@ -105,9 +103,5 @@ template. We suggest you copy it and adjust it to your liking. There are annotations in the code that should help you to understand the structure. -A lot more examples can be found in the ``runScripts`` directory (see also :ref:`develop:Examples`). +A lot more examples can be found in the ``runScripts`` directory (see also :ref:`advancedUsage:Example runscripts`). - -.. include:: configuration.rst - -.. include:: logging.rst diff --git a/docs/index.rst b/docs/index.rst index 3d29d4f5d..f6271a229 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,10 +15,8 @@ General * :doc:`introduction` * :doc:`installation` - * :doc:`operational` - * :doc:`operationalGerman` - * :doc:`developinstall` - * :doc:`gettingstarted` + * :doc:`connector` + * :doc:`advancedUsage` * :doc:`testing` * :doc:`Visualisation` * :doc:`FAQ` @@ -27,16 +25,14 @@ General * :doc:`develop` .. toctree:: - :maxdepth: 3 + :maxdepth: 4 :hidden: :caption: General introduction.rst installation.rst - operational.rst - operationalGerman.rst - developinstall.rst - gettingstarted.rst + connector.rst + advancedUsage.rst testing.rst Visualisation.rst FAQ.rst diff --git a/docs/installation.rst b/docs/installation.rst index 4766d8ac9..3493cbf04 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,9 +4,10 @@ Installation .. Note:: There are two ways to install and use AvaFrame: - Standard + Operational (GUI) If you want the operational workflow, running *com1DFA* (dense flow avalanche) and *com2AB* (alpha beta) - with standard settings from within *QGis*, head over to the :ref:`operational:Standard / Operational Installation` section. + with standard settings from within *QGis*, head over to the :ref:`installation:Operational Installation` + (:ref:`Deutsche Version`) section. Use this if you want to: - use the standard, well tested and calibrated setup for hazard mapping or similar @@ -15,8 +16,8 @@ Installation - use the latest release - Development - If you want to contribute and develop AvaFrame, head over to :ref:`developinstall:Development Installation`. + Advanced (Script) + If you want to contribute and develop AvaFrame, head over to :ref:`advancedUsage:Advanced (Script) Installation`. Use this if you want to: - work on the code itself @@ -34,4 +35,94 @@ Installation - just want to adjust parameters in the configurations - want to use the latest release +Operational Installation +------------------------ +This is the quick start for the operational AvaFrame setup with QGis as +frontend. + +Requirements +^^^^^^^^^^^^ + +The prerequisites are: + +* QGis: install from here: `QGis installation `_ (we recommend + using the latest version) + +Setup AvaFrameConnector and run +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Open QGis from your start menu and go to Plugins -> Manage and Install Plugins + +#. Search for `AvaFrameConnector` and install it + +#. Wait for it to finish and restart QGis + +#. Access the QGis - Avaframe connector via Toolbox -> AvaFrame -> Operational -> FullOperationalRun + +#. Add the described data and run. Results will be loaded after a while + (depending on the size of your DEM) + +This tries to install the AvaFrame core package as well (since AvaFrameConnector version 1.2). If it fails, head +over to the :ref:`operational:Manual Installation` instructions. + +For more information about the functions in the AvaFrameConnector, see :ref:`connector:AvaFrameConnector (GUI)` + + +Update Avaframe to a new release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Restart/Open QGis from your start menu and go to Plugins -> Manage and Install Plugins + +#. Search for `AvaFrameConnector` and check whether it also needs updating + +#. Access the QGis - Avaframe connector via Toolbox -> AvaFrame + +#. Go to the *Admin* section, choose and run *Update* + + +-------------------------- + + +Operationelle Installation (Deutsch) +------------------------------- + +Dies ist der Schnellstart für die Verwendung von AvaFrame mit QGis als Frontend. + +Vorraussetzungen +^^^^^^^^^^^^^^^^ + +Die Vorraussetzungen sind: + +* QGis: `QGis installation `_ (Wir empfehlen die aktuellste Version zu + verwenden) + +Setup AvaFrameConnector +^^^^^^^^^^^^^^^^^^^^^^^ + +#. Öffnen Sie QGis über Ihr Startmenü und gehen Sie zu Erweiterungen -> Erweiterungen verwalten und installieren + +#. Nach `AvaFrameConnector` suchen und installieren + +#. Warten Sie, bis der Vorgang abgeschlossen ist und starten Sie QGis neu + +#. Rufen Sie den QGis - AvaframeConnector über Verarbeitungswerkzeuge -> AvaFrame -> Operational -> FullOperationalRun auf + +#. Fügen Sie die beschriebenen Daten hinzu und starten Sie den Connector. Die Ergebnisse werden nach einer Weile geladen + (abhängig von der Größe Ihres DEM) + +Hiermit wird versucht das AvaFrame-Kernpaket zu installieren (seit AvaFrameConnector Version 1.2). Wenn dies fehlschlägt, gehen Sie +zu: :ref:`operationalGerman:Manuelle Installation`. + +Für eine Kurzzusammenfassung der Funktionen des AvaFrameConnector, siehe :ref:`connector:AvaFrameConnector (GUI)`. + +Update Avaframe auf eine neue Version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Starten Sie QGis neu/öffnen Sie es über Ihr Startmenü und gehen Sie zu Plugins -> Plugins verwalten und installieren + +#. Suchen Sie nach AvaFrameConnector und prüfen Sie, ob es aktualisiert werden muss + +#. Rufen Sie den QGis - AvaframeConnector über Verarbeitungswerkzeuge -> AvaFrame auf + +#. Dann -> Admin -> Update aufrufen diff --git a/docs/operational.rst b/docs/operational.rst index 9d5efe3ee..cdb646d51 100644 --- a/docs/operational.rst +++ b/docs/operational.rst @@ -1,8 +1,8 @@ -Standard / Operational Installation -=================================== +Manual Installation +=================== -This is the quick start for the operational AvaFrame setup with QGis as -frontend. Currently described for **Windows** only (Linux user can use any terminal to go through the same steps below) +This is the quick start for the manual operational AvaFrame setup with QGis as +frontend. Currently described for **Windows** only (Linux users can use any terminal to go through the same steps below) Requirements ^^^^^^^^^^^^ diff --git a/docs/operationalGerman.rst b/docs/operationalGerman.rst index 587bbb545..1af08c8a6 100644 --- a/docs/operationalGerman.rst +++ b/docs/operationalGerman.rst @@ -1,5 +1,5 @@ -Operationelle Installation (Deutsch) -==================================== +Manuelle Installation +===================== Dies ist der Schnellstart für die Inbetriebnahme von AvaFrame mit QGis als Frontend. Derzeit nur für Windows beschrieben (Linux-Benutzer können ein beliebiges Terminal verwenden, um die gleichen Schritte durchzugehen) @@ -90,10 +90,10 @@ Update Avaframe .. Note:: - Wenn Sie auf einen Fehler wie diesen stoßen (unterste/letzte Zeile der Fehlermeldung; die Zahlen können abweichen): + Wenn Sie auf einen Fehler wie diesen stoßen (unterste/letzte Zeile der Fehlermeldung; die Zahlen können abweichen):: - ValueError: numpy.ndarray size changed, may indicate binary - incompatibility. Expected 88 from C header, got 80 from PyObject + ValueError: numpy.ndarray size changed, may indicate binary + incompatibility. Expected 88 from C header, got 80 from PyObject Führen Sie das Folgende in der OSGeo4W-Shell aus (der py3_env-Befehl wird bei neueren Versionen von QGis nicht benötigt, überspringen Sie ihn):: diff --git a/docs/releaseNotes.rst b/docs/releaseNotes.rst index 7bfe1fb7a..66ed5e226 100644 --- a/docs/releaseNotes.rst +++ b/docs/releaseNotes.rst @@ -1,6 +1,47 @@ Release Notes ============= + +1.3 (12. Okt 2022) +------------------ + +Main change is the change of logic for secondary release areas. This was done to be able +to expose this functions in the AvaFrameConnecter. So it is now possible to include secondary +release areas in dense flow simulations done via QGis. + +ENHANCEMENTS + +- Change logic for secondary release areas: + - Check for release and secondary release shapefiles + - If only release available -> just run release + - If both release and secondary release are available -> run with secondary release + UNLESS secRelArea = False + - ALL scenarios in release get the secondary release areas! +- Add rotational energy line test: helps to checks eg. for numerical grid independence +- Update ini file procedure for the energy line test and the rotation test +- Additional statistical plots +- New three panel plot of tt-diagram (plus animation) +- Add variation option for thickness settings and probrun based on normal distribution derived from ci and mean +- Add filtering option to aimec +- Add scenario name to configuration to be used for plotting example #757 +- Add surface parallel coordinate computation to Aimec +- Improve operational installation instructions +- Add german version of operational installation + +FIX +- Contour legend bug with matplotlib 3.5.2 +- Update installation instructions; fixes #764 +- Bugs in deriving variation +- Remeshing issue that lead to standard test differences (originated in commit 419c11f) +- No calls to matplotlib for plotting purposes in com1DFA +- Removes multiple printouts of config during run in, e.g. com1DFA +- CompareConfig always honours the toPrint flag + +Contributors: + +Code: core team + + 1.2 (07. July 2022) ------------------- @@ -88,7 +129,7 @@ Code: core team 1.0.1 (20. April 2022) -------------------- +---------------------- FIX