From caead4c4e3598700cdaf41c4ec399dd66c091ad6 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 12:01:08 +0200 Subject: [PATCH 1/6] Docs: update download instructions and iMOD QGIS install --- README.md | 16 ++++++++++++++-- docs/index.qmd | 27 ++++++++++++++++++--------- docs/qgis/index.qmd | 17 ++++++++++++----- 3 files changed, 44 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 75717d4c8..592aa495a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Ribasim +[![Julia Tests](https://github.com/Deltares/Ribasim/actions/workflows/core_tests.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/core_tests.yml) +[![Ribasim Python Tests](https://github.com/Deltares/Ribasim/actions/workflows/python_tests.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/python_tests.yml) +[![QGIS](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml) [![codecov](https://codecov.io/gh/Deltares/Ribasim/branch/main/graph/badge.svg)](https://codecov.io/gh/Deltares/Ribasim) **Documentation: https://deltares.github.io/Ribasim/** @@ -13,13 +16,22 @@ Ribasim is written in the [Julia programming language](https://julialang.org/) a on top of the [SciML: Open Source Software for Scientific Machine Learning](https://sciml.ai/) libraries, notably [ModelingToolkit.jl](https://mtk.sciml.ai/stable/). -The latest builds can be downloaded here: +# Download + +For most users the [latest release](https://github.com/Deltares/Ribasim/releases/latest) is recommended, it can be downloaded here: + +- Ribasim executable: [ribasim_cli.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_cli.zip). +- Python package: [ribasim-0.4.0-py3-none-any.whl](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim-0.4.0-py3-none-any.whl) +- QGIS plugin: [ribasim_qgis.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_qgis.zip). +- Generated testmodels: [generated_testmodels.zip](https://github.com/Deltares/Ribasim/releases/latest/download/generated_testmodels.zip) + +The nightly builds contain the latest developments and can be found below. It is important to either use the release or nightly for all components. - Ribasim executable: [ribasim_cli.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_cli.zip). - Python package: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl) - QGIS plugin: [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). -Currently only Windows builds for `ribasim_cli.zip` are available. +Currently only Windows builds for `ribasim_cli.zip` are available. See [Usage](core/usage.qmd) for more information. ![Timeseries of results](https://user-images.githubusercontent.com/4471859/179259333-070dfe18-8f43-4ac4-bb38-013b252e2e4b.png) diff --git a/docs/index.qmd b/docs/index.qmd index 091551451..d4656604e 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -11,14 +11,6 @@ Ribasim is written in the [Julia programming language](https://julialang.org/) a on top of the [SciML: Open Source Software for Scientific Machine Learning](https://sciml.ai/) libraries, notably [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/). -The latest builds can be downloaded here: - -- Ribasim executable: [ribasim_cli.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_cli.zip). -- Python package: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl) -- QGIS plugin: [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). - -Currently only Windows builds for `ribasim_cli.zip` are available. See [Usage](core/usage.qmd) for more information. - ::: {layout-ncol=2 layout-valign="bottom"} Deltares logo ::: -# Status {#sec-usage} +# Download {#sec-download} + +For most users the [latest release](https://github.com/Deltares/Ribasim/releases/latest) is recommended, it can be downloaded here: + +- Ribasim executable: [ribasim_cli.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_cli.zip). +- Python package: [ribasim-0.4.0-py3-none-any.whl](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim-0.4.0-py3-none-any.whl) +- QGIS plugin: [ribasim_qgis.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_qgis.zip). +- Generated testmodels: [generated_testmodels.zip](https://github.com/Deltares/Ribasim/releases/latest/download/generated_testmodels.zip) + +The nightly builds contain the latest developments and can be found below. It is important to either use the release or nightly for all components. + +- Ribasim executable: [ribasim_cli.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_cli.zip). +- Python package: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl) +- QGIS plugin: [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). + +Currently only Windows builds for `ribasim_cli.zip` are available. See [Usage](core/usage.qmd) for more information. + +# Status The initial focus is on being able to reproduce the Mozart regional surface water reservoir results. Each component is defined by diff --git a/docs/qgis/index.qmd b/docs/qgis/index.qmd index 07ac8bfe7..0e1f99c4c 100644 --- a/docs/qgis/index.qmd +++ b/docs/qgis/index.qmd @@ -6,11 +6,11 @@ title: "QGIS plugin" ## Start -### Download plugin +Install [QGIS](https://qgis.org/en/site/) version 3.28 or higher. -Download [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). +### Install Ribasim plugin -### Add Ribasim and iMOD plugins to QGIS version 3.28 or higher +Download `ribasim_qgis.zip`, see the [download section](../index.qmd#sec-download). Plugins menu > Manage and Install Plugins... @@ -20,7 +20,6 @@ Select "Install from ZIP": - Browse to the `ribasim_qgis.zip` file containing the plugin that was downloaded earlier - Click "Install Plugin" -- Repeat for the iMOD plugin, `imodqgis.zip` ![](https://user-images.githubusercontent.com/4471859/224939080-7fec5db2-4417-4f7b-8e45-034d4cf4fd75.png){fig-align="left"} @@ -28,6 +27,14 @@ Start the Ribasim plugin. ![](https://user-images.githubusercontent.com/4471859/224939101-228e068a-875b-4df2-98bb-6ee6a3830ddd.png){fig-align="left"} +### Add iMOD plugin + +In QGIS, navigate to "Plugins > Manage and Install Plugins > All". +In the search bar, type: "iMOD". Select the iMOD plugin, and click "Install". + +The Time Series widget from the iMOD plugin is used for visualizing Ribasim results, which is described in @sec-results. +Documentation on the Time Series widget can be found in the [iMOD documentation](https://deltares.github.io/iMOD-Documentation/qgis_user_manual.html#time-series-time-series). + ### Prepare your model Open example model `basic.gpkg` or create a new model. @@ -125,7 +132,7 @@ geopackage = "basic.gpkg" - In your model directory there is now an `output/` folder with `basin.arrow` and `flow.arrow` output files. -## Inspect results +## Inspect results {#sec-results} ### Associate output to iMOD time series window From 8b698a511f9d83ae4889dbbb4f6ab5e6cd51c38c Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 12:02:47 +0200 Subject: [PATCH 2/6] add required version --- docs/qgis/index.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/qgis/index.qmd b/docs/qgis/index.qmd index 0e1f99c4c..d6ef00765 100644 --- a/docs/qgis/index.qmd +++ b/docs/qgis/index.qmd @@ -32,6 +32,8 @@ Start the Ribasim plugin. In QGIS, navigate to "Plugins > Manage and Install Plugins > All". In the search bar, type: "iMOD". Select the iMOD plugin, and click "Install". +At least version 0.4.0 of the iMOD plugin is required. + The Time Series widget from the iMOD plugin is used for visualizing Ribasim results, which is described in @sec-results. Documentation on the Time Series widget can be found in the [iMOD documentation](https://deltares.github.io/iMOD-Documentation/qgis_user_manual.html#time-series-time-series). From d34eaef7bd441a47dd85646d29476b2861644348 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 12:14:08 +0200 Subject: [PATCH 3/6] refer to download location --- docs/core/usage.qmd | 3 +-- docs/python/index.qmd | 10 +++++++++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/core/usage.qmd b/docs/core/usage.qmd index 9865146c5..e91b7e9fe 100644 --- a/docs/core/usage.qmd +++ b/docs/core/usage.qmd @@ -9,8 +9,7 @@ archive, that must be downloaded and unpacked. It can be placed anywhere, howeve important that the contents of the zip file are kept together in a directory. The Ribasim CLI executable is in the `bin` directory. -The latest build can be downloaded here: [ribasim_cli.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_cli.zip). -Currently only Windows builds are available. +To download `ribasim_cli.zip`, see the [download section](../index.qmd#sec-download). To check whether the installation was performed successfully, run `ribasim` with no arguments in the command line. diff --git a/docs/python/index.qmd b/docs/python/index.qmd index dd0f38db0..06559fb70 100644 --- a/docs/python/index.qmd +++ b/docs/python/index.qmd @@ -13,6 +13,14 @@ One can also use Ribasim Python to build entire models from base data, such that setup is fully reproducible. The package is [registered in PyPI](https://pypi.org/project/ribasim/) and can therefore -be installed with `pip install ribasim`. The most recent (nightly) version can be downloaded here: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl). It can be installed with `pip install ribasim-0.4.0-py3-none-any.whl`. +be installed with [pip](https://docs.python.org/3/installing/index.html): +``` +pip install ribasim +``` +For wheel (`.whl`) downloads, including nightly builds, see the [download section](../index.qmd#sec-download). +After downloading wheels can be installed by referring to the correct path: +``` +pip install path/to/ribasim-*.whl +``` For documentation please see the [examples](examples.ipynb) and [API reference](reference/). From bf48f65ee63ba748d6ae6a9308120a9861549002 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 12:17:55 +0200 Subject: [PATCH 4/6] clarify badge name --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 592aa495a..49e8e7b75 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Julia Tests](https://github.com/Deltares/Ribasim/actions/workflows/core_tests.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/core_tests.yml) [![Ribasim Python Tests](https://github.com/Deltares/Ribasim/actions/workflows/python_tests.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/python_tests.yml) -[![QGIS](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml) +[![QGIS Tests](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml/badge.svg)](https://github.com/Deltares/Ribasim/actions/workflows/qgis.yml) [![codecov](https://codecov.io/gh/Deltares/Ribasim/branch/main/graph/badge.svg)](https://codecov.io/gh/Deltares/Ribasim) **Documentation: https://deltares.github.io/Ribasim/** From 28b30dc439eae4c29bfdbd3fb17ff9b28a81a869 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 12:19:28 +0200 Subject: [PATCH 5/6] rename QGIS job --- .github/workflows/qgis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/qgis.yml b/.github/workflows/qgis.yml index 788a7e059..e2dc1f0ab 100644 --- a/.github/workflows/qgis.yml +++ b/.github/workflows/qgis.yml @@ -1,4 +1,4 @@ -name: QGIS +name: QGIS Tests on: push: From efb3c944edb6d7b19d7ff86418c839adc1500f35 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Fri, 13 Oct 2023 13:05:29 +0200 Subject: [PATCH 6/6] avoid quarto syntax in README --- README.md | 2 +- docs/index.qmd | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 49e8e7b75..56975cb3e 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The nightly builds contain the latest developments and can be found below. It is - Python package: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl) - QGIS plugin: [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). -Currently only Windows builds for `ribasim_cli.zip` are available. See [Usage](core/usage.qmd) for more information. +Currently only Windows builds for `ribasim_cli.zip` are available. ![Timeseries of results](https://user-images.githubusercontent.com/4471859/179259333-070dfe18-8f43-4ac4-bb38-013b252e2e4b.png) diff --git a/docs/index.qmd b/docs/index.qmd index d4656604e..e6c2546b0 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -40,7 +40,9 @@ The nightly builds contain the latest developments and can be found below. It is - Python package: [ribasim-0.4.0-py3-none-any.whl](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim-0.4.0-py3-none-any.whl) - QGIS plugin: [ribasim_qgis.zip](https://ribasim.s3.eu-west-3.amazonaws.com/teamcity/Ribasim_Ribasim/BuildRibasimCliWindows/latest/ribasim_qgis.zip). -Currently only Windows builds for `ribasim_cli.zip` are available. See [Usage](core/usage.qmd) for more information. +Currently only Windows builds for `ribasim_cli.zip` are available. + +See [Usage](core/usage.qmd) for more information. # Status