MOBIDICpy

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 for more details.

Model overview

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++, 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 is available on PyPI and can be installed with pip:

# Install the base package
pip install mobidicpy

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

Alternatively, it can be installed from source:

# 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:

# 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 directory.

Documentation

The project's full documentation is available here.

Contributing

If you want to contribute to the development of MOBIDICpy, have a look at the contribution guidelines.

Credits

This package was created using the NLeSC/python-template.

License

Copyright (c) 2026 University of Florence (Italy), Department of Civil and Environmental Engineering (DICEA).

Licensed under the Apache License, Version 2.0.

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

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

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.

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.

Ercolani, G., Castelli, F. (2017), Variational assimilation of streamflow data in distributed flood forecasting, Water Resour. Res., 53, 158–183. DOI: 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

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.

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

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

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.