Merge pull request #177 from DassHydro/doc-build-from-source

DOC: Add build from source documentation
DassHydro · May 2, 2024 · d99f879 · d99f879
2 parents 298bbc8 + a712a2f
commit d99f879
Show file tree

Hide file tree

Showing 15 changed files with 513 additions and 265 deletions.
diff --git a/Makefile b/Makefile
@@ -46,7 +46,7 @@ test-baseline:
 #% Format Python files with ruff and Fortran files with fprettify
 format:
 	ruff format
-	fprettify -e forward_db.f90 -e f90wrap -f .f90 --indent 4 -r smash
+	fprettify -e forward_db.f90 -e forward_openmp_db.f90 -e f90wrap -f .f90 --indent 4 -r smash
 
 #% Check Python files with ruff linters
 check:

diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
 <h1 align="center">
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="doc/source/_static/corporate_logo_dark.svg">
-  <img src="doc/source/_static/corporate_logo.svg" width="300", hspace=30>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/DassHydro/smash/main/doc/source/_static/corporate_logo_dark.svg">
+  <img src="https://raw.githubusercontent.com/DassHydro/smash/main/doc/source/_static/corporate_logo.svg" width="300", hspace=30>
 </picture>
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="doc/source/_static/logo_smash_dark.svg">
-  <img src="doc/source/_static/logo_smash.svg" width="300", hspace=30>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/DassHydro/smash/main/doc/source/_static/logo_smash_dark.svg">
+  <img src="https://raw.githubusercontent.com/DassHydro/smash/main/doc/source/_static/logo_smash.svg" width="300", hspace=30>
 </picture>
 </h1><br>
 
@@ -19,7 +19,8 @@
 
 **smash** offers a range of advanced optimization techniques, including Variational Data Assimilation (VDA), Bayesian estimation, and Artificial Neural Network (ANN) approaches, using an adjoint model generated with the **Tapenade** Automatic Differentiation Engine.
 
+- **Tapenade** website: https://team.inria.fr/ecuador/en/tapenade/
 - **Tapenade** article: https://doi.org/10.1145/2450153.2450158
 - **Tapenade** source code: https://gitlab.inria.fr/tapenade/tapenade.git
 
-Whether you are managing water resources or conducting research on hydrological models, **smash** can provide an easy-to-use yet powerful solution for your work. See [this documentation](https://smash.recover.inrae.fr/getting_started/index.html) for the installation instructions.
+Whether you are managing water resources or conducting research on hydrological models, **smash** can provide an easy-to-use yet powerful solution for your work. See [this documentation](https://smash.recover.inrae.fr/getting_started/index.html) for the installation instructions.
diff --git a/doc/gen_dataset.py → doc/generate_dataset.py b/doc/gen_dataset.py → doc/generate_dataset.py
diff --git a/doc/source/_static/logo_anaconda.png b/doc/source/_static/logo_anaconda.png
diff --git a/doc/source/_static/logo_docker.png b/doc/source/_static/logo_docker.png
diff --git a/doc/source/_static/logo_terminal.svg b/doc/source/_static/logo_terminal.svg
diff --git a/doc/source/contributor_guide/development_process_details.rst b/doc/source/contributor_guide/development_process_details.rst
diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst
@@ -8,109 +8,31 @@ Getting Started
 Installation
 ------------
 
-`smash` can be used on Linux and is compatible with most distributions. It has been tested for use on Ubuntu 20.04 and 22.04 LTS, and supports Python versions 3.8 to 3.11.
-The installation instructions are detailed for Ubuntu. Depending on your distribution, you will need to use the correct package manager and insert the appropriate packages.
+`smash` can be installed with pip on **Linux**, **Windows** or from source and supports Python versions **3.9** to **3.11**.
 
-First, clone the Git repository:
+.. note::
 
-.. code-block:: none
-
-    git clone https://github.com/DassHydro/smash.git
+    We strongly recommend using `smash` on **Linux**, particularly if you are using it on a large dataset, as 
+    Fortran parallel computation is not supported on **Windows**. 
 
-and navigate to the working directory:
+If you already have Python, you can install `smash` with:
 
 .. code-block:: none
 
-    cd smash
-
-Now you can proceed with building the code and installing dependencies. You have the options to use `Anaconda <https://www.anaconda.com/>`__ or your own environment.
-
-**********************
-Anaconda (recommended)
-**********************
-
-.. image:: ../_static/logo_anaconda.png
-    :width: 175
-    :align: center
-
-1. **Create environment**
-    In the ``smash`` directory, create a `conda <https://www.anaconda.com/>`__ environment named **smash**:
-
-    .. code-block:: none
-
-        conda env create -f environment.yml
-
-2. **Activate environment**
-    Activate the environment:
-
-    .. code-block:: none
-
-        conda activate smash
-
-3. **Build**
-    Use the `make <https://www.gnu.org/software/make/manual/make.html>`__ command inside the ``smash`` directory:
-
-    .. code-block:: none
-
-        (smash) make
-
-4. **Check your installation**
-    Once the compilation is complete, make sure that everything went well by tring to import the `smash` package inside a Python interface:
-
-    .. code-block:: none
-
-        (smash) python3
-
-    .. code-block:: python
-
-        import smash
-
-.. hint::
-
-    If you'd prefer that conda's base environment not be activated on startup, 
-    set the auto_activate_base parameter to false:
-
-    .. code-block::
-
-        conda config --set auto_activate_base false
-
-********************
-Your own environment
-********************
-
-.. image:: ../_static/logo_terminal.svg
-    :width: 75
-    :align: center
-
-1. **Install dependencies**
-    In the ``smash`` directory, install development tools and Python requirements:
-
-    .. code-block:: none
-
-        sudo apt-add-repository ppa:ubuntugis/ubuntugis-unstable
-        sudo apt-get update
-        sudo apt-get install build-essential make gcc gfortran gdal-bin libgdal-dev python3-pip
-        pip3 install wheel numpy
-        pip3 install gdal==$(gdal-config --version)
-        pip3 install -r requirements.txt
-
-2. **Build**
-    Use the `make <https://www.gnu.org/software/make/manual/make.html>`__ command inside the ``smash`` directory:
-
-    .. code-block:: none
-
-        make
+    pip install hydro-smash
 
-3. **Check your installation**
-    Once the compilation is complete, make sure that everything went well by tring to import the `smash` package inside a Python interface:
+------
+Import
+------
 
-    .. code-block:: none
+To access `smash` and its functions import it in your Python code like this:
 
-        python3
+.. code-block:: python
 
-    .. code-block:: python
+    import smash
 
-        import smash
+Because of a name conflict on `PyPI <https://pypi.org/>`__, the distribution name (i.e. the name used in pip
+install, ``hydro-smash``) is not the same as the package name (i.e. the name used to import, ``smash``).
 
 ---------
 Tutorials

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -8,7 +8,14 @@ smash documentation
 
 **Date**: |today| **Version**: |version|
 
-`smash` (**S**\patially distributed **M**\odelling and **AS**\similation for **H**\ydrology) is an open-source Python library that provides a variety of user-friendly routines for hydrological modeling. It includes features such as data preprocessing, high-dimensional optimization tools, sensitivity and signatures analysis, all interfaced with an efficient Fortran solver.
+`smash` is a computational software framework dedicated to **S**\patially distributed **M**\odelling and
+**AS**\similation for **H**\ydrology, enabling to tackle spatially distributed differentiable hydrological
+modeling, with learnable parameterization-regionalization. This platform enables to combine vertical and
+lateral flow operators, either physically based or hydrid  with neural networks, and perform high dimensional
+non linear optimization from multi-source data. It is designed to simulate discharge hydrographs and
+hydrological states at any spatial location within a basin and reproduce the hydrological response of
+contrasted catchments, both for operational forecasting of floods and low flows, by taking advantage of
+spatially distributed meteorological forcings, physiographic data and hydrometric observations.
 
 .. grid:: 2
 

diff --git a/doc/source/release/1.0.0-notes.rst b/doc/source/release/1.0.0-notes.rst
@@ -9,6 +9,10 @@ smash 1.0.0 Release Notes
 The smash 1.0.0 release brings major updates aimed at simplifying the user experience while continuing the 
 ongoing work to improve the handling, fix possible bugs, clarify the documentation. The highlights are:
 
+- ``PyPI installation``
+    `smash` is now available on `PyPI <https://pypi.org/>`__ with the following distribution name
+    ``hydro-smash``.
+
 - ``CPU parallel computation``
     CPU parallel computation in simulation and optimization. This has been made possible using the 
     `OpenMP <https://www.openmp.org/>`__ library, whose most of the directives are handled by Tapenade to
@@ -54,11 +58,18 @@ This release was made possible thanks to the contributions of:
 - Thomas de Fournas (`<https://github.com/ThomasdeFournas>`__)
 - Apolline El Baz (`<https://github.com/asjeb>`__)
 - Pierre-André Garambois (`<https://github.com/pag13>`__)
+- Maxime Jay-Allemand (`<https://github.com/maximejay>`__)
 
 ---------------
 Compatibilities
 ---------------
 
+- The `smash` package is now available on `PyPI <https://pypi.org/>`__ and can be installed as follows:
+
+  .. code-block:: none
+
+    pip install hydro-smash
+
 - The `gdal <https://gdal.org/api/python_bindings.html>`__ package has been replaced by
   `rasterio <https://rasterio.readthedocs.io/en/stable/>`__. This change has been made purely to improve
   the distribution of `smash`. Despite the better performance in terms of raster reading time, gdal does
@@ -755,4 +766,3 @@ Interception reservoir capacity calculation
 Missing values were not properly taken into account in the calculation of the interception reservoir. Missing
 values in Fortran for precipitation and potential evapotranspiration are stored as -99, resulting in
 erroneous values. This was fixed simply by not incorporating these values into the calculation.
-
diff --git a/doc/source/user_guide/classical_uses/lez_regionalization.rst b/doc/source/user_guide/classical_uses/lez_regionalization.rst
@@ -84,7 +84,7 @@ Open a Python interface:
     :suppress:
 
     import os
-    os.system("python3 gen_dataset.py -d Lez")
+    os.system("python3 generate_dataset.py -d Lez")
 
 Imports
 -------

diff --git a/doc/source/user_guide/quickstart/cance_first_simulation.rst b/doc/source/user_guide/quickstart/cance_first_simulation.rst
@@ -130,7 +130,7 @@ Open a Python interface:
     :suppress:
 
     import os
-    os.system("python3 gen_dataset.py -d Cance")
+    os.system("python3 generate_dataset.py -d Cance")
 
 Imports
 -------
@@ -144,6 +144,14 @@ We will first import everything we need in this tutorial: `smash` of course, the
     import pandas as pd
     import matplotlib.pyplot as plt
 
+.. hint::
+
+    The visualization library `matplotlib <https://matplotlib.org/>`__ is not installed by default but can be installed with pip as follows:
+
+    .. code-block:: none
+
+        pip install matplotlib
+
 Model creation
 --------------
 

diff --git a/doc/source/user_guide/quickstart/france_large_domain_simulation.rst b/doc/source/user_guide/quickstart/france_large_domain_simulation.rst
@@ -61,7 +61,7 @@ Open a Python interface:
     :suppress:
 
     import os
-    os.system("python3 gen_dataset.py -d France")
+    os.system("python3 generate_dataset.py -d France")
 
 Imports
 -------

diff --git a/doc/source/user_guide/quickstart/lez_split_sample_test.rst b/doc/source/user_guide/quickstart/lez_split_sample_test.rst
@@ -65,7 +65,7 @@ Open a Python interface:
     :suppress:
 
     import os
-    os.system("python3 gen_dataset.py -d Lez")
+    os.system("python3 generate_dataset.py -d Lez")
 
 Imports
 -------

diff --git a/pyproject.toml b/pyproject.toml
@@ -13,7 +13,7 @@ dynamic = ["version"]
 description = "An open source, Python library interfacing the Fortran Spatially distributed Modelling and ASsimilation for Hydrology platform."
 readme = "README.md"
 authors = [
-    {name = "INRAE RECOVER RHAX Team", email = "pierre.javelle@inrae.fr"},
+    {name = "INRAE RECOVER RHAX Team", email = "francois.colleoni@inrae.fr"},
 ]
 license = {text = "GPL-3.0"}
 requires-python = ">=3.9"