Welcome to the Phydrus Docs!¶

This package provides a Python implementation of the HYDRUS-1D unsaturated zone model developed by Šimůnek, J., M. Th. van Genuchten, and M. Šejna. More information on the HYDRUS-1D model is available here. This software is licenced under the GNU GENERAL PUBLIC LICENSE found here. The Phydrus code is developed by R.A. Collenteur, G. Brunetti and M. Vremec. With Phydrus, a HYDRUS-1D model can be created, calibrated and visualized through Python scripts, making it easy to adjust the model and providing a 100% reproducible workflow of your modeling process.

Getting started with Phydrus¶

In this section you can find guidance on how to get started with Phydrus. Before being able to run a Phydrus model from Python Console you need to 1) install the Phydrus package, and 2) obtain a compiled version of the Hydrus-1D Fortran code. After you have succesfully completed these two steps, you can start creating your first Phydrus model. The final section will help to get you started by explaining the modeling approach applied in Phydrus.

Installing and Updating Phydrus¶

Installing Python¶

To install Phydrus, a working version of Python 3.7 or higher has to be installed. We recommend using the Anaconda Distribution of Python. This Python distribution includes most of the python package dependencies and the Jupyter Lab software to run the notebooks. Moreover, it includes the Graphical User Interface (GUI) Spyder to start scripting in Python. However, you are free to install any Python distribution you want.

Installing the Phydrus package¶

The latest stable version of the Phydrus package is available from the Pypi package index.

>>> pip install phydrus

To install in developer mode, clone the GitHub repository and use the following syntax:

>>> pip install -e .

Updating the Phydrus package¶

If you have already installed Phydrus, it is possible to update Phydrus easily. To update, open a Windows command screen or a Mac terminal and type:

>>> pip install phydrus --upgrade

Dependencies¶

Phydrus depends on a number of Python packages, which are all automatically installed when using the pip install manager. The following packages are necessary for the installation of Phydrus:

matplotlib >= 3.1
pandas >= 1.1
numpy >= 1.16

Compiling the Fortran Source Code¶

After installing the Phydrus package, you need to obtain an executable for the Hydrus-1D model. There after two options to obtain this executable: 1) download a pre-compiled version, or 2) compiled the fortan code locally. Below both approaches are described. Compiling the Fortran source code can be a bit more challenging depending on your environment. Please carefully read the instructions below and read through the dedicated GitHub Discussions category on this topic before opening a new Discussion.

Compiling the source code¶

The recommended option is to compile the adapted Hydrus-1D Fortran77 files for your own environment and computer. The following steps should be taken:

1. Download the Phydrus-optimized fortran code from this dedicated repository.

2. Open a Windown command line or Linux / MacOS Terminal and move into the source folder (e.g., cd path/to/directory).

3. and use the following syntax in your terminal or windows command line to compile the source code:

>>> make

4. This should create a Windows or Unix Executable that can be used to run the HYDRUS-1D simulation. In the Python code, you have to reference to the location of the executable, so you can store it anywhere you want.

Troubleshooting¶

Depending on your operation system (e.g., Windows/MacOS/Linux) you may need to install additional tools to compile:

The compile the source code for MacOS/Linux, Gfortran needs to be installed. Instructions can be found here: https://gcc.gnu.org/wiki/GFortranBinaries.
Please let us know when you find other requirements to add to this list!

Using pre-compiled executables¶

It is in principle possible to use pre-compiled versions of Hydrus-1D. Note that the Phydrus software has been developed based on the the Hydrus-1D 4.08 Fortran Code and other versions may not be suppported.

If you have the Graphical User Interface for Hydrus-1D for Windows installed (which can be obtained from https://www.pc-progress.com/ ), you may directly point to that exectuable. You can also download the pre-compiled versions from the source code repository. However, it can not be guaranteed that these executables work for your personal computing environment.

Modeling Approach in Phydrus¶

Examples¶

Developers Section¶

API-docs¶

This section contains the Documentation of the Application Programming Interface (API) of Phydrus. The information in this section is automatically created from the documentation strings in original Python code. In the left-hand menu you will find the different categories of the API documentation.

`model.Model`	Basic Phydrus model container.
`read`	The read module contains methods that can be used to read in- and output files.
`profile`	The profile module contains utility functions to help create the profile DataFrame.
`plot.Plots`	Class that contains all the methods to plot a Phydrus Model.
`utils`	The utils module contains utility funtions for Phydrus.