Installation

Nous recommandons fortement d’installer xHydro dans un environnement Python Anaconda. De plus, en raison de la complexité de certaines librairies, le solveur de dépendances par défaut peut prendre beaucoup de temps pour résoudre l’environnement. Si mamba n’est pas déjà votre solveur par défaut, nous vous conseillons d’exécuter les commandes suivantes pour accélérer le processus :

conda install -n base conda-libmamba-solver
conda config --set solver libmamba

Si vous n’avez pas pip installé, ce guide d’installation Python peut vous aider à traverser le processus.

Note

Certaines librairies utilisées par xHydro ou ses dépendances peuvent ne pas fonctionner correctement si l’environnement approprié n’est pas activé. Pour éviter tout problème potentiel, il est fortement recommandé d’activer systématiquement votre environnement avant d’exécuter du code Python. Vous pouvez le faire avec la commande suivante :

conda activate name_of_your_environment

Cette recommandation s’applique également à certaines applications avec interface graphique, comme PyCharm, qui n’activent pas automatiquement l’environnement du projet. Dans ce cas, veillez à activer l’environnement avant de lancer l’application.

Sur Windows, cela peut être fait en exécutant la commande ci-dessus dans Anaconda Prompt, puis en lançant l’application depuis cette même fenêtre. Vous pouvez également lancer l’application via Anaconda Navigator, en veillant à ce que le bon environnement soit sélectionné au préalable.

Version stable (Anaconda)

Certaines dépendances de xHydro peuvent être difficiles à installer avec pip. C’est pourquoi nous recommandons fortement d’installer xHydro via Anaconda. Cela garantira que toutes les dépendances sont satisfaites et que le paquet fonctionnera correctement.

conda install -c conda-forge xhydro

Cela installera la dernière version stable de xHydro avec toutes ses dépendances, à deux exceptions près :

Si vous souhaitez utiliser le module extreme_value_analysis, qui repose sur le package Extremes.jl de Julia, vous devrez installer l’extra julia :

pip install xhydro[julia]

Si vous souhaitez utiliser le module frequency_analysis.regional, vous devrez installer vous-même la libaririe lmoments3. Celle-ci est disponible sur PyPI et conda-forge, mais elle est soumise à une licence restreinte. Notez que si vous avez installé xHydro via conda, vous devrez également installer lmoments3 via conda. Si vous avez installé xHydro en utilisant le fichier environment-dev.yml, lmoments3 aura été ajouté automatiquement.

conda install -c conda-forge lmoments3

Version stable (PyPI)

Bien que cela ne soit pas recommandé, vous pouvez également installer xHydro depuis PyPI en utilisant pip :

pip install xhydro

Certaines dépendances de xHydro peuvent ne pas être entièrement fonctionnelles lorsqu’elles sont installées via pip. Par exemple, des paquets comme xESMF peuvent nécessiter une configuration système supplémentaire pour fonctionner correctement.

Les considérations mentionnées ci-dessus concernant les modules extreme_value_analysis et frequency_analysis.regional s’appliquent également à l’installation via PyPI, avec quelques remarques supplémentaires :

• L’extra julia nécessite un compilateur C++ fonctionnel. Certains utilisateurs ont signalé des erreurs de segmentation lors de l’utilisation de la librairie juliacall avec xHydro installé depuis PyPI, ce que nous pensons être dû au fait que l’environnement Julia n’est pas lancé avec un compilateur C++ adéquat. Si vous rencontrez ce problème, nous vous recommandons d’utiliser plutôt la méthode d’installation via conda.

• L’extra raven dépend des librairies ravenpy et raven-hydro, qui peuvent être difficiles à installer dans des environnements pip standards en raison de dépendances complexes au niveau du système. Consultez la note ci-dessous pour plus de détails. À moins d’être familier avec l’installation de ces librairies, nous recommandons d’utiliser plutôt la méthode d’installation via conda.

Note

Nous n’avons pas encore effectué de tests approfondis pour l’installation de l’extra raven via pip, mais les commandes suivantes sont connues pour fonctionner sur certains systèmes Linux :

apt-get update && apt-get upgrade -y
apt-get install -y git gdal-bin python3-gdal libgdal-dev libnetcdf-dev build-essential
pip install xhydro[raven]

Cela installera ravenpy et raven-hydro depuis PyPI. Vous pouvez aussi remplacer la dernière ligne et installer uniquement ravenpy, à condition d’avoir votre propre exécutable Raven. Pour plus d’informations sur l’installation de ces paquets, consultez la documentation officielle de ravenpy et raven-hydro.

Avertissement

Sur Windows, l’installation de toutes les dépendances pour ravenpy peut nécessiter des privilèges administrateur, car certains paquets doivent être ajoutés au PATH du système. En cas de problème, envisagez d’utiliser plutôt la méthode d’installation via Anaconda.

Depuis les sources

xHydro est toujours en développement actif et les dernières fonctionnalités peuvent ne pas être encore disponibles sur PyPI ou conda-forge. Si vous voulez utiliser les dernières fonctionnalités, ou si vous souhaitez contribuer au développement de xHydro, vous pouvez l’installer depuis les sources.

Les sources de xHydro peuvent être téléchargées depuis le Github repo.

1. Téléchargez le code source depuis le Github repo en utilisant l’une des méthodes suivantes :

   • Clonez le dépôt public :

     git clone git@github.com:hydrologie/xhydro
     

   • Téléchargez l’archive tarball :

     curl -OJL https://github.com/hydrologie/xhydro/tarball/main
     

2. Une fois que vous avez une copie des sources, vous pouvez l’installer avec :

   conda env create -f environment-dev.yml
   conda activate xhydro-dev
   make development
   

   Si vous êtes sous Windows, remplacez la commande make development par celle-ci :

   python -m pip install --group dev
   python -m pip install --no-user --editable .
   prek install
   

   Bien que vous ne souhaitiez pas contribuer à xHydro, nous privilégions l’utilisation de environment-dev.yml plutôt que environment.yml car il inclut des librairies supplémentaires nécessaires pour exécuter tous les exemples fournis dans la documentation. Si, pour une raison quelconque, vous souhaitez installer la version PyPI de xHydro dans un environnement Anaconda existant (non recommandé si les exigences ne sont pas remplies), exécutez uniquement la dernière commande ci-dessus.

3. Lorsque de nouveaux changements sont apportés au Github repo, vous pouvez mettre à jour votre copie locale en utilisant les commandes suivantes depuis la racine du dépôt :

   git fetch
   git checkout main
   git pull origin main
   conda env update -n xhydro-dev -f environment-dev.yml
   conda activate xhydro-dev
   make development
   

   Ces commandes devraient fonctionner dans la plupart des cas, mais si de gros changements sont apportés au dépôt, vous devrez peut-être supprimer l’environnement et le recréer.