Metadata-Version: 2.4
Name: deepdiscover-hydro
Version: 1.0.0
Summary: Conservative differentiable hydrological modeling with DiscoverUnits
Author: Vincent Adombi
License-Expression: BSD-3-Clause
Project-URL: Repository, https://github.com/avadombi/DeepDiscover
Project-URL: Issues, https://github.com/avadombi/DeepDiscover/issues
Keywords: hydrology,groundwater,scientific machine learning,conservation
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: tensorflow<2.22,>=2.16
Requires-Dist: keras>=3.0
Provides-Extra: examples
Requires-Dist: pandas>=2.0; extra == "examples"
Requires-Dist: matplotlib>=3.7; extra == "examples"
Requires-Dist: nbformat>=5.9; extra == "examples"
Requires-Dist: nbclient>=0.9; extra == "examples"
Requires-Dist: ipykernel>=6.0; extra == "examples"
Requires-Dist: jupyterlab>=4.0; extra == "examples"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: build>=1.0; extra == "test"
Requires-Dist: pandas>=2.0; extra == "test"
Dynamic: license-file

# DeepDiscover

DeepDiscover is a Python library for differentiable hydrological modeling with explicit water conservation. A model contains one or more DiscoverUnits (DUs), each with a water store and constitutive relationships that determine water releases. Each release process has one declared destination. Temporal routing is specified separately.

The same hydrological system can be calibrated against streamflow, groundwater levels, soil moisture and other measured variables using observation operators. Multiple observation types can be used together.

## Installation

Python 3.11 or 3.12 is recommended. DeepDiscover uses TensorFlow and Keras.

Install from this repository:

```bash
python -m pip install .
```

Install the optional dependencies for the notebooks and documentation:

```bash
python -m pip install ".[examples,docs]"
```

Once published on [PyPI](https://pypi.org/), install the distribution with `python -m pip install deepdiscover-hydro`.

## Example

```python
import numpy as np
from deepdiscover import CRCNet, DeepDiscover, DiscoverUnit, MultiDUModel

n_days = 365
precipitation = np.maximum(2 + np.sin(np.arange(n_days) / 9), 0).astype("float32")
pet = np.ones(n_days, dtype="float32")

water = precipitation[:, None]
drivers = np.column_stack([precipitation, pet])

release = CRCNet(gamma=[1, -1, 1], x_ref=[5, 3, 100])
unit = DiscoverUnit(process_nets=[release], context_indices=[(0, 1)])
physical_model = MultiDUModel([unit], destinations=[["outlet"]])
model = DeepDiscover(physical_model, observations={"streamflow": "outlet"})

prediction = model.predict(water[None], drivers[None])["streamflow"]
print(prediction.shape)  # (1, 365, 1)
```

To calibrate the model, provide observed discharge as an array and create training windows:

```python
from deepdiscover import HydroDataset

data = HydroDataset(water, drivers, {"streamflow": observed_discharge})
train = data.make_windows(warmup=30, score_length=60, stride=30)
model.fit(train, epochs=30, batch_size=4, loss="mse")
```

Here `observed_discharge` is a measured series containing one value per day.

## Main features

| Component | Options |
| --- | --- |
| DiscoverUnits | Multiple storages, processes and fixed or learned storage capacities |
| Constitutive relationships | Causal Relationship Constraints (CRC), custom Keras layers |
| Sources | Prescribed water inputs, lateral inflow, managed recharge, custom source layers |
| Losses | Evapotranspiration, pumping, prescribed extraction, custom sink layers |
| Routes | Instantaneous, prescribed, learned and state-dependent temporal routing |
| Additional states | Optional information memory and storage deficit |
| Snow | Differentiable degree-day snow model |
| Observations | Direct outputs, groundwater-head operators, soil-moisture operators, custom layers |
| Training | Time windows, warm-up, observation masks, multivariable and custom losses |
| Diagnostics | States, fluxes, routing storage, numerical water balance and model scores |
| Model comparison | Multi-seed fitting and validation-based comparison of declared structures |

Water losses belong to the physical balance. Training losses measure the agreement between simulations and observations. Both can be configured independently.

## Model topologies

Each release process has one destination, and several processes may lead to the same destination. The library supports both a direct outlet pathway plus an internal DU transfer, and a cascade with two downstream outlet processes. See [model topologies](docs/topologies.md) for explicit configurations and [structural comparison](docs/structural_comparison.md) for validation-based comparisons.

## Examples

The `examples/` directory contains four notebooks:

- `01_streamflow.ipynb`: simulation and calibration of streamflow.
- `02_groundwater_level.ipynb`: joint calibration using streamflow and groundwater levels.
- `03_sources_losses_routing.ipynb`: custom physical boundaries and delayed routing.
- `04_camels_us.ipynb`: a CAMELS-US case study with snow and chronological data partitions.

To run the three self-contained notebooks:

```bash
python run_examples.py
```

To run the CAMELS-US example, obtain the original forcing and streamflow files and follow [the data instructions](docs/camels.md). Three execution modes are provided:

```bash
# Short check of loading, simulation, calibration and evaluation
python run_examples.py --only 04_camels_us

# Measure the cost of full-length training windows (three epochs)
python run_examples.py --only 04_camels_us --camels-mode benchmark

# Full chronological calibration with the original training-window settings
python run_examples.py --only 04_camels_us --camels-mode full
```

The short check uses a limited number of training windows and two epochs. Its scores should not be used as scientific results. The benchmark and full modes use 19 parallel windows with 365 warm-up and 365 scored days. Full mode uses up to 400 epochs and validates every five epochs. It saves the validation-selected model and its training history under `results/camels/01013500/two_du_serial_seed42/`. During notebook execution, progress is printed for each code cell and each optimization batch.

Output notebooks and execution reports are written to `results/notebooks/`, which is excluded from version control.

A saved CAMELS-US checkpoint can be verified independently, without repeating model fitting or consulting the test period:

```bash
python verify_camels.py
```

This command requires the CAMELS-US files and the `checkpoint/` and `history.json` created by the full example.

## Documentation

The `docs/` directory covers the [scientific equations](docs/scientific_formulation.md), [model configuration](docs/model_configuration.md), [topologies](docs/topologies.md), [data](docs/data.md), [routing](docs/routing.md), [observation operators](docs/observations.md), [custom components](docs/customization.md), [calibration](docs/training_and_evaluation.md) and [model comparison](docs/structural_comparison.md).

To build the documentation locally:

```bash
python -m pip install ".[docs]"
mkdocs build
```

## Tests

```bash
python -m pip install ".[test]"
python check.py
python -m pytest -q
```

The tests cover conservation, routing, gradients, observation operators, training, model saving, temporal windows and CAMELS data preparation.

## Reporting bugs

Report bugs and request features through [GitHub Issues](https://github.com/avadombi/DeepDiscover/issues). Include the Python, TensorFlow and Keras versions, the model configuration, a minimal example and the complete error message. Avoid sharing private datasets or credentials.

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## Scientific references and license

DeepDiscover is intended for water-quantity modeling. Its latent states and processes require scientific interpretation in the context of the available observations. See [limitations](docs/limitations.md).

The methodological article is identified in [CITATION.cff](CITATION.cff). Source code is distributed under the [BSD 3-Clause License](LICENSE). CAMELS-US data must be obtained separately from their original provider.

## Citation

The current Multiple-DU methodology is described in:

Adombi, A. V. D. P. (2026). *Can discharge identify internal hydrological processes? Neural equifinality in the Multiple-DU extension of DeepDiscover*. Manuscript submitted to *Journal of Hydrology*.

The original DeepDiscover formulation is published in:

Adombi, A. V. D. P. (2026). *DeepDiscover: towards autonomous discovery of bucket-type conceptual models – a proof of concept applied to hydrology*. *Journal of Hydrology*, 671, 135249. https://doi.org/10.1016/j.jhydrol.2026.135249

The submitted manuscript currently has no publication DOI. Citation information will be updated when it is published.
