Getting Started

How to install HydroFlows

To install HydroFlows, you can use either pip, pixi or conda. The package is not yet available on PyPi or conda-forge, so you need to install it from the GitHub repository. Note that you need to have git installed on your system to clone the repository.

The library installs only the core submodules by default. To install all flood risk methods, you can install the package with the extra methods dependencies.

Using conda (or mamba)

We suggest using mamba as a faster alternative to conda, which is included in the miniforge Python distribution. To install HydroFlows using conda, you first need to clone the repository, then create a conda environment file from the pyproject.toml and install all dependencies, and finally install HydroFlows. Here we install the methods and extra dependencies to be able to use all flood risk methods. To develop we recommend using the or full profile which includes all optional dependencies.

git clone git@github.com:Deltares-research/HydroFlows.git
cd HydroFlows
python make_env.py methods,extra -n hydroflows
mamba env create -f environment.yml
conda activate hydroflows
pip install .

Using pip

Pip allows you to install HydroFlows directly from the GitHub repository. We suggest you install HydroFlows in a conda environment with graphiz (and git). Without a conda install of graphviz, the plotting methods will not work.

To install HydroFlows using pip in a new conda environment, run the following commands:

conda create -n hydroflows python=3.11 git graphviz -c conda-forge
conda activate hydroflows
pip install "hydroflows[methods,extra] @ git+https://github.com/Deltares-research/HydroFlows.git"

Using pixi

Pixi offers a project-centric approach for python environments and run commands. Using the pixi.lock file the environment is reproducible and can be shared with others.

First, install pixi using the instructions on the pixi website. Then, clone the repository and install HydroFlows using pixi (this will also create an editable installation of HydroFlows):

git clone git@github.com:Deltares-research/HydroFlows.git
cd HydroFlows
pixi install                # default (methods,extra) py3.11 installation from the lock file

Using pixi (for developers)

To install HydroFlows for development, you can use the full profile which includes all optional dependencies. This will install all dependencies and create an editable installation of HydroFlows.

git clone git@github.com:Deltares-research/HydroFlows.git
cd HydroFlows
pixi install -e full        # full dev py3.11 installation from the lock file

# optional commands (see "pixi run x" for more options)
pixi run -e full install-pre-commit # install pre-commit hooks
pixi run -e full tests              # run all tests
pixi run -e full html-docs          # build the documentation

To update the lock file and your environment after changes to the dependencies, run:

pixi update

How to use HydroFlows

HydroFlows is designed to create workflows using python scripts and parse these to a workflow engine like snakemake. The example below shows how two methods can be chained together in a workflow and parsed to Snakemake. More information on how to use HydroFlows including several examples can be found in the online user documentation.

from hydroflows import Workflow
from hydroflows.methods import sfincs

# create a workflow
wf = Workflow(root="./my_workflow_root", name="my_workflow")

# initialize a method and add it to the workflow
sfincs_build = sfincs.SfincsBuild(
   region="data/region.shp",
   sfincs_root="models/sfincs",
   config="config/hydromt_sfincs.yml",
   catalog_path="data/data_catalog.yml",
)
wf.create_rule(sfincs_build, rule_id="sfincs_build")

# initialize a second method and add it to the workflow
sfincs_run = sfincs.SfincsRun(
   sfincs_inp=sfincs_build.output.sfincs_inp,
   run_method="exe",
   sfincs_exe="bin/sfincs/sfincs.exe"
)
wf.create_rule(sfincs_run, rule_id="sfincs_run")

# parse the workflow to Snakemake, this will save a ./my_workflow_root/Snakefile
wf.to_snakemake()