Metadata-Version: 2.4
Name: mobidicpy
Version: 0.4.0
Summary: MOBIDICpy - Distributed and continuous hydrological balance model
Author-email: Matteo Masi <matteo.masi@unifi.it>, Fabio Castelli <fabio.castelli@unifi.it>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/mobidichydro/mobidicpy
Project-URL: Issues, https://github.com/mobidichydro/mobidicpy/issues
Keywords: Hydrology,Numerical modelling,Distributed hydrologic modelling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.16
Requires-Dist: matplotlib>=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rasterio>=1.4.0
Requires-Dist: geopandas>=1.1.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pyarrow>=21.0.0
Requires-Dist: xarray>=2023.1.0
Requires-Dist: netcdf4>=1.6.0
Requires-Dist: numba>=0.63.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: genbadge[coverage]>=1.1.3; extra == "dev"
Requires-Dist: ruff>=0.2.1; extra == "dev"
Requires-Dist: bump-my-version>=1.0; extra == "dev"
Provides-Extra: calibration
Requires-Dist: pyemu>=1.4.0; extra == "calibration"
Requires-Dist: HydroErr>=2.0.0; extra == "calibration"
Provides-Extra: doc
Requires-Dist: mkdocs>=1.6.0; extra == "doc"
Requires-Dist: mkdocs-material>=9.6.0; extra == "doc"
Requires-Dist: mkdocstrings[python]>=0.30.0; extra == "doc"
Requires-Dist: mkdocs-autorefs>=1.4.0; extra == "doc"
Requires-Dist: mdx-include>=1.4.1; extra == "doc"
Requires-Dist: mkdocs-markdownextradata-plugin>=0.2.5; extra == "doc"
Requires-Dist: mike>=2.0.0; extra == "doc"
Dynamic: license-file


[![GitHub](https://img.shields.io/badge/github-mobidicpy-blue?logo=github)](https://github.com/mobidichydro/mobidicpy)
[![License](https://img.shields.io/github/license/mobidichydro/mobidicpy)](https://github.com/mobidichydro/mobidicpy/blob/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/mobidicpy.svg?colorB=blue)](https://pypi.org/project/mobidicpy/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19597504.svg)](https://doi.org/10.5281/zenodo.19597504)
[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/12552/badge)](https://www.bestpractices.dev/projects/12552)
[![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu)
[![cffconvert](https://github.com/mobidichydro/mobidicpy/actions/workflows/cffconvert.yml/badge.svg)](https://github.com/mobidichydro/mobidicpy/actions/workflows/cffconvert.yml)
[![Linting](https://github.com/mobidichydro/mobidicpy/actions/workflows/lint.yml/badge.svg)](https://github.com/mobidichydro/mobidicpy/actions/workflows/lint.yml)
[![Python package](https://github.com/mobidichydro/mobidicpy/actions/workflows/build.yml/badge.svg)](https://github.com/mobidichydro/mobidicpy/actions/workflows/build.yml)
[![Coverage](https://raw.githubusercontent.com/mobidichydro/mobidicpy/main/badges/coverage.svg)](https://github.com/mobidichydro/mobidicpy/actions/workflows/coverage.yml)
[![Docs](https://github.com/mobidichydro/mobidicpy/actions/workflows/documentation-test.yml/badge.svg)](https://github.com/mobidichydro/mobidicpy/actions/workflows/documentation-test.yml)

# `MOBIDICpy`

<p align="left">
  <img src="https://raw.githubusercontent.com/mobidichydro/mobidicpy/main/docs/assets/logo_mobidic_color_white_bg.svg" alt="MOBIDICpy Logo" width="160">
</p>

MOBIDIC (MOdello di Bilancio Idrologico DIstribuito e Continuo – distributed and continuous hydrological balance model) is a physically-based distributed hydrological model that simulates water and energy balances of the hydrological cycle at the catchment scale, and compute runoff generation and propagation through the river network.

MOBIDICpy is a Python implementation of the MOBIDIC model, originally developed in MATLAB by Castelli et al. See [References](https://github.com/mobidichydro/MOBIDICpy#references) for more details.

## Model overview

<p align="left">
  <img src="https://raw.githubusercontent.com/mobidichydro/mobidicpy/main/docs/assets/mobidic_processes.png" alt="MOBIDICpy hydrological processes" width="500">
</p>

The diagram above shows the main components of the hydrological cycle as simulated by MOBIDICpy. The model discretizes the basin horizontally using a regular mesh grid and resolves vertical processes across four layers: vegetation, surface storage, soil, and aquifer.

Precipitation partitioning, evapotranspiration, and soil moisture dynamics are represented through a five-reservoir scheme comprising plant interception, surface storage, and two soil reservoirs. Following a dual-pore approach (Castillo et al., 2015), the soil is described by two nonlinear reservoirs: a gravitational reservoir, representing the larger pores from which water drains under gravity, and a capillary reservoir, representing the smaller pores that retain water through capillary forces. The model also includes an aquifer reservoir to represent groundwater storage and baseflow contributions to the river network.

The simulated processes include interception, evapotranspiration, infiltration, Horton and Dunne runoff, exchange between the two soil reservoirs (absorption and capillary rise), percolation, hypodermic (subsurface) flow, groundwater baseflow, and propagation through the river network via channel (and reservoir) routing.

Model parameters can be calibrated against observed data through the USGS [PEST++](https://github.com/usgs/pestpp), a suite of tools for parameter estimation and uncertainty analysis. MOBIDICpy provides an interface to PEST++ with current support for Gauss-Levenberg-Marquardt (GLM) optimization, iterative ensemble smoother (IES), sensitivity analysis (SEN), and parameter sweep (SWP) tools.



## Installation

The package can be installed locally via pip:

```bash
# Clone the repository
git clone https://github.com/mobidichydro/mobidicpy.git
cd mobidicpy

# Create a virtual environment (optional)
python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

# Install the base package
pip install .

# For calibration and sensitivity analysis (PEST++)
pip install .[calibration] && get-pestpp :pyemu

# For development with all dependencies
pip install --no-cache-dir --editable .[dev]
```

The documentation can be built locally using [MkDocs](https://www.mkdocs.org/):

```bash
# Install documentation dependencies
pip install .[doc]

# Serve the documentation locally (http://127.0.0.1:8000)
python -m mkdocs serve
```

## Examples

Examples are available in the [`examples`](https://github.com/mobidichydro/MOBIDICpy/blob/main/examples) directory. 

## Documentation

The project's full documentation is available [here](https://mobidichydro.github.io/MOBIDICpy/).

## Contributing

If you want to contribute to the development of MOBIDICpy,
have a look at the [contribution guidelines](https://github.com/mobidichydro/MOBIDICpy/blob/main/CONTRIBUTING.md).

## Credits

This package was created using the [NLeSC/python-template](https://github.com/NLeSC/python-template).

## License

Copyright (c) 2026 University of Florence (Italy), Department of Civil and Environmental Engineering ([DICEA](https://www.dicea.unifi.it/)).

Licensed under the [Apache License, Version 2.0](https://github.com/mobidichydro/MOBIDICpy/blob/main/LICENSE).


## References

Campo, L., Caparrini, F., Castelli, F. (2006). Use of multi-platform, multi-temporal remote-sensing data for calibration of a 
distributed hydrological model: an application in the Arno basin, Italy. Hydrol. Process., 20: 2693-2712. 
DOI: [10.1002/hyp.6061](https://doi.org/10.1002/hyp.6061)

Castelli, F. (1996). A simplified stochastic model for infiltration into a heterogeneous soil forced by random precipitation. Advances in water resources, 19(3), 133-144. DOI: [10.1016/0309-1708(95)00041-0](https://doi.org/10.1016/0309-1708(95)00041-0)

Castelli, F., Menduni, G., and Mazzanti, B. (2009). A distributed package for sustainable water
management: A case study in the Arno basin. Role of Hydrology in Water Resources Management,
327, 52–61.

Castillo, A., Castelli, F., Entekhabi, D. (2015). Gravitational and capillary soil moisture dynamics for distributed
hydrologic models, Hydrol. Earth Syst. Sci., 19, 1857–1869, DOI: [10.5194/hess-19-1857-2015](https://doi.org/10.5194/hess-19-1857-2015).

Castelli, F., Ercolani, G. (2016). Improvement of operational flood forecasting through the assimilation of satellite observations and 
multiple river flow data, Proc. IAHS, 373, 167–173. DOI: [10.5194/piahs-373-167-2016](https://doi.org/10.5194/piahs-373-167-2016).

Ercolani, G., Castelli, F. (2017), Variational assimilation of streamflow data in distributed flood forecasting, Water Resour. Res., 53, 158–183. 
DOI: [10.1002/2016WR019208](https://doi.org/10.1002/2016WR019208).

Ercolani, G., Chiaradia, E. A., Gandolfi, C., Castelli, F., Masseroni, D. (2018). Evaluating performances of green roofs for stormwater runoff mitigation in a high flood risk urban catchment. Journal of Hydrology, 566, 830-845. DOI: [10.1016/j.jhydrol.2018.09.050](https://doi.org/10.1016/j.jhydrol.2018.09.050)

Masi, M., Masseroni, D., Castelli, F. (2025). Coupled hydrologic, hydraulic, and surface water quality models for pollution management in urban–rural areas. 
Journal of Hydrology, 657, 133172. DOI: [10.1016/j.jhydrol.2025.133172](https://doi.org/10.1016/j.jhydrol.2025.133172).

Masi, M., Moghaddam, M. B., Castelli, F., & Arrighi, C. (2026). Modelling nutrient loads in data-scarce large catchments using spatially regularized ensemble calibration. Science of The Total Environment, 1038, 181900. DOI: [10.1016/j.scitotenv.2026.181900](https://doi.org/10.1016/j.scitotenv.2026.181900)

Yang, J., Castelli, F., Chen, Y. (2014). Multiobjective sensitivity analysis and optimization of
distributed hydrologic model MOBIDIC. Hydrology and Earth System Sciences, 18(10), 4101–4112.
DOI: [10.5194/HESS-18-4101-2014](https://doi.org/10.5194/HESS-18-4101-2014)

Yang, J., Entekhabi, D., Castelli, F., Chua, L. (2014). Hydrologic response of a tropical watershed to urbanization. 
Journal of Hydrology, 517, 538-546. DOI: [10.1016/j.jhydrol.2014.05.053](https://doi.org/10.1016/j.jhydrol.2014.05.053).
