From 959262e88afb7143761e09e9f54228be8f0e35fa Mon Sep 17 00:00:00 2001 From: Jingru Feng Date: Tue, 3 Sep 2024 11:59:34 +0200 Subject: [PATCH 1/3] merge download with other chapter --- docs/install.qmd | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/install.qmd b/docs/install.qmd index 93233692c..94c249482 100644 --- a/docs/install.qmd +++ b/docs/install.qmd @@ -2,7 +2,10 @@ title: "Installation" --- +In this document, we describe how to install the Ribasim software package. + # Components {#sec-components} + The figure below illustrates the relation between the various components of the Ribasim software package. ```{mermaid} @@ -52,23 +55,28 @@ One can also use Ribasim Python to build entire models from base data, such that # Download {#sec-download} -- Ribasim executable - Windows: [ribasim_windows.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_windows.zip) -- Ribasim executable - Linux: [ribasim_linux.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_linux.zip) -- 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 Ribasim Python package is [registered in PyPI](https://pypi.org/project/ribasim/) and [conda-forge](https://prefix.dev/channels/conda-forge/packages/ribasim) and can therefore be installed with [pip](https://docs.python.org/3/installing/index.html), [conda](https://docs.conda.io/) or [pixi](https://pixi.sh/): -``` -pip install ribasim -``` +There are three main components of the Ribasim software package. +They are the Ribasim core (written in Julia language), the Ribasim Python package and the Ribasim QGIS plugin. +The Ribasim core is the computation kernel of the Ribasim software package and is used to run simulations. +The Ribasim Python package is used to build Ribasim models programmatically with Python script. +The Ribasim QGIS plugin is used to construct or view a model in GUI. +Users can choose to use Ribasim Python or QGIS plugin or a combination of them to build a Ribasim model. +And then use the Ribasim core to run the simulation. -# Ribasim core +## Ribasim core Ribasim is typically used as a command-line interface (CLI). It is distributed as a `.zip` archive, that must be downloaded and unpacked. It can be placed anywhere, however it is important that the contents of the zip file are kept together in a directory. The Ribasim executable is in the main folder. +To download the Ribasim core, download the appropriate zip file for your operating system: + +- Ribasim executable - Windows: [ribasim_windows.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_windows.zip) +- Ribasim executable - Linux: [ribasim_linux.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_linux.zip) + +Note that we currently only support and provide binaries for Windows and Linux, for the x86_64 architecture. + To check whether the installation was performed successfully, open a terminal and go to the path where the executable is for example 'C:\Ribasim\ribasim_windows'. If you are using cmd.exe type `ribasim`, or for PowerShell `./ribasim`. @@ -83,7 +91,7 @@ Usage: ribasim For more information, try '--help'.' ``` -# Ribasim Python +## Ribasim Python The Ribasim Python package (named `ribasim`) aims to make it easy to build, update and analyze Ribasim models programmatically. @@ -95,23 +103,25 @@ Python instead. One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible. -The package is [registered in PyPI](https://pypi.org/project/ribasim/) and can therefore -be installed with [pip](https://docs.python.org/3/installing/index.html): +The Ribasim Python package is [registered in PyPI](https://pypi.org/project/ribasim/) and [conda-forge](https://prefix.dev/channels/conda-forge/packages/ribasim) and can therefore be installed with [pip](https://docs.python.org/3/installing/index.html), [conda](https://docs.conda.io/) or [pixi](https://pixi.sh/): ``` pip install ribasim ``` For documentation please see the [examples](/guide/examples.ipynb) and [API reference](/reference/reference). -# Ribasim QGIS plugin +## Ribasim QGIS plugin The Ribasim QGIS plugin requires [QGIS](https://qgis.org/en/site/) 3.34 or higher. +The Ribasim QGIS plugin is also distributed as a .zip archive and must be downloaded and installed in QGIS. -## Install Ribasim plugin +### Install Ribasim plugin -Download `ribasim_qgis.zip`, see the [download section](#sec-download). +Firstly, download `ribasim_qgis.zip`: + +- QGIS plugin: [ribasim_qgis.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_qgis.zip). -Plugins menu > Manage and Install Plugins... +In QGIS plugin, go to Plugins menu > Manage and Install Plugins... ![](https://user-images.githubusercontent.com/4471859/224939069-9aae77ea-898f-442f-83b5-f2671c114956.png){fig-align="left"} @@ -126,7 +136,7 @@ Open the Ribasim plugin panel. ![](https://user-images.githubusercontent.com/4471859/224939101-228e068a-875b-4df2-98bb-6ee6a3830ddd.png){fig-align="left"} -## Install iMOD plugin +### Install 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". From 6258cdd72b7d931b738809e6e032240094f7ead3 Mon Sep 17 00:00:00 2001 From: Martijn Visser Date: Thu, 5 Sep 2024 13:31:26 +0200 Subject: [PATCH 2/3] Update references --- docs/guide/delwaq.ipynb | 2 +- docs/guide/qgis.qmd | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/guide/delwaq.ipynb b/docs/guide/delwaq.ipynb index e81472512..1082aba42 100644 --- a/docs/guide/delwaq.ipynb +++ b/docs/guide/delwaq.ipynb @@ -15,7 +15,7 @@ "source": [ "In order to generate the Delwaq input files, we need a completed Ribasim simulation (typically one with a results folder) that ideally also includes some substances and initial concentrations. Let's take the basic test model for example, which already has set some initial concentrations.\n", "\n", - "All testmodels can be [downloaded from here](/install.qmd#sec-download)." + "All testmodels can be [downloaded from here](/install.qmd)." ] }, { diff --git a/docs/guide/qgis.qmd b/docs/guide/qgis.qmd index 94abdee02..41faf4929 100644 --- a/docs/guide/qgis.qmd +++ b/docs/guide/qgis.qmd @@ -4,8 +4,9 @@ title: "QGIS plugin" # Preparing a model +This guide assumes you have already installed the Ribasim core, test models and QGIS plugin as described in the [install page](/install.qmd). Open an existing model or create a new model. -As an example of an existing model, you can use the "basic" model from `generated_testmodels.zip`, see the [download section](/install.qmd#sec-download). +As an example of an existing model, you can use the "basic" model from `generated_testmodels.zip`. ![](https://user-images.githubusercontent.com/4471859/224939126-b38f0eed-2e89-4120-b541-5b8c31798c09.png){fig-align="left"} From f31540172172c71f47e750714d707c76244a86b1 Mon Sep 17 00:00:00 2001 From: Jingru Feng Date: Thu, 5 Sep 2024 16:00:23 +0200 Subject: [PATCH 3/3] address comments --- docs/install.qmd | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/install.qmd b/docs/install.qmd index 94c249482..650776765 100644 --- a/docs/install.qmd +++ b/docs/install.qmd @@ -2,11 +2,12 @@ title: "Installation" --- -In this document, we describe how to install the Ribasim software package. +In this document, we describe how to install the different components of Ribasim. +First the components and their relation are introduced, then installation instructions per component follow. # Components {#sec-components} -The figure below illustrates the relation between the various components of the Ribasim software package. +The figure below illustrates the relation between the various components of Ribasim. ```{mermaid} flowchart TB @@ -41,6 +42,9 @@ classDef system_ext fill:#D2D2D2 classDef boundary fill:transparent,stroke-dasharray:5 5 ``` +There are three main components of the Ribasim software package. +They are the Ribasim core (written in Julia language), the Ribasim Python package and the Ribasim QGIS plugin. + The kernel of Ribasim is written in the [Julia programming language](https://julialang.org/) and is built 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 [Ribasim Python package](/install.qmd) is available to build, update and analyze Ribasim models programmatically. @@ -53,17 +57,10 @@ Deltares also provides the iMOD QGIS plugin, which can be used to inspect the re For larger edits using Python is recommended. One can also use Ribasim Python to build entire models from base data, such that your model setup is fully reproducible. -# Download {#sec-download} - -There are three main components of the Ribasim software package. -They are the Ribasim core (written in Julia language), the Ribasim Python package and the Ribasim QGIS plugin. -The Ribasim core is the computation kernel of the Ribasim software package and is used to run simulations. -The Ribasim Python package is used to build Ribasim models programmatically with Python script. -The Ribasim QGIS plugin is used to construct or view a model in GUI. Users can choose to use Ribasim Python or QGIS plugin or a combination of them to build a Ribasim model. And then use the Ribasim core to run the simulation. -## Ribasim core +# Install Ribasim core Ribasim is typically used as a command-line interface (CLI). It is distributed as a `.zip` archive, that must be downloaded and unpacked. It can be placed anywhere, however it is @@ -77,7 +74,7 @@ To download the Ribasim core, download the appropriate zip file for your operati Note that we currently only support and provide binaries for Windows and Linux, for the x86_64 architecture. -To check whether the installation was performed successfully, open a terminal and go to the path where the executable is for example 'C:\Ribasim\ribasim_windows'. +To check whether the installation was performed successfully, open a terminal and go to the path where the executable is for example `C:\bin\ribasim\`. If you are using cmd.exe type `ribasim`, or for PowerShell `./ribasim`. This will give the following message: @@ -91,7 +88,7 @@ Usage: ribasim For more information, try '--help'.' ``` -## Ribasim Python +# Install Ribasim Python The Ribasim Python package (named `ribasim`) aims to make it easy to build, update and analyze Ribasim models programmatically. @@ -110,18 +107,18 @@ pip install ribasim For documentation please see the [examples](/guide/examples.ipynb) and [API reference](/reference/reference). -## Ribasim QGIS plugin +# Install Ribasim QGIS plugin The Ribasim QGIS plugin requires [QGIS](https://qgis.org/en/site/) 3.34 or higher. -The Ribasim QGIS plugin is also distributed as a .zip archive and must be downloaded and installed in QGIS. +The Ribasim QGIS plugin is only distributed as a .zip archive and must be downloaded and installed in QGIS. -### Install Ribasim plugin +## Install Ribasim plugin Firstly, download `ribasim_qgis.zip`: - QGIS plugin: [ribasim_qgis.zip](https://github.com/Deltares/Ribasim/releases/latest/download/ribasim_qgis.zip). -In QGIS plugin, go to Plugins menu > Manage and Install Plugins... +In QGIS, go to Plugins menu > Manage and Install Plugins... ![](https://user-images.githubusercontent.com/4471859/224939069-9aae77ea-898f-442f-83b5-f2671c114956.png){fig-align="left"} @@ -136,7 +133,7 @@ Open the Ribasim plugin panel. ![](https://user-images.githubusercontent.com/4471859/224939101-228e068a-875b-4df2-98bb-6ee6a3830ddd.png){fig-align="left"} -### Install iMOD plugin +## Install 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".