deepdiscover-hydro 1.0.0__tar.gz

deepdiscover_hydro-1.0.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0
+
+First public release of DeepDiscover for water-quantity modeling.
+
+- Conservative DiscoverUnits with Causal Relationship Constraints.
+- Multiple hydrological sources, losses, finite storage capacities and overflow.
+- Instantaneous, fixed, learned and state-dependent temporal routing.
+- Optional informational memory, snow accumulation and melt.
+- Streamflow, groundwater level and other observation operators.
+- Multivariable calibration, custom loss functions and numerical diagnostics.
+- CAMELS-US and synthetic examples, documentation and tests.

deepdiscover_hydro-1.0.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "Please cite the Multiple-DU methodological manuscript when using DeepDiscover."
+title: "DeepDiscover"
+version: 1.0.0
+type: software
+license: BSD-3-Clause
+repository-code: "https://github.com/avadombi/DeepDiscover"
+authors:
+  - family-names: Adombi
+    given-names: Adoubi Vincent De Paul
+preferred-citation:
+  type: unpublished
+  title: "Can discharge identify internal hydrological processes? Neural equifinality in the Multiple-DU extension of DeepDiscover"
+  authors:
+    - family-names: Adombi
+      given-names: Adoubi Vincent De Paul
+  year: 2026
+  status: submitted
+  notes: "Manuscript submitted."
+references:
+  - type: article
+    title: "DeepDiscover: towards autonomous discovery of bucket-type conceptual models – a proof of concept applied to hydrology"
+    authors:
+      - family-names: Adombi
+        given-names: Adoubi Vincent De Paul
+    journal: Journal of Hydrology
+    year: 2026
+    volume: "671"
+    doi: 10.1016/j.jhydrol.2026.135249

deepdiscover_hydro-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Vincent Adombi
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

deepdiscover_hydro-1.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE
+include CHANGELOG.md
+include CITATION.cff
+include mkdocs.yml
+include check.py
+include run_examples.py
+include verify_camels.py
+recursive-include docs *.md
+recursive-include examples *.ipynb
+recursive-include tests *.py
+prune data
+prune results
+prune .venv
+prune .pytest_cache
+global-exclude __pycache__ *.py[cod] *.log

deepdiscover_hydro-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+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.

deepdiscover_hydro-1.0.0/README.md

@@ -0,0 +1,164 @@
+# 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.

deepdiscover_hydro-1.0.0/check.py

@@ -0,0 +1,51 @@
+"""Short installation check for a new DeepDiscover environment.
+
+Run from the repository root:
+    python check.py
+    python -m pytest -q
+"""
+from pathlib import Path
+import numpy as np
+import tensorflow as tf
+import keras
+from deepdiscover import (
+    CRCNet, DiscoverUnit, MultiDUModel, DeepDiscover,
+    PrescribedSink, HydroDataset,
+)
+
+
+def main():
+    print('TensorFlow', tf.__version__, 'Keras', keras.__version__)
+    t = np.arange(45, dtype=np.float32)
+    rain = 2.0 + np.sin(t / 5)
+    pet = np.ones_like(rain)
+    drivers = np.stack([rain, pet], axis=-1)[None]
+    water = rain[None, :, None]
+    du = DiscoverUnit(
+        process_nets=[CRCNet([1, -1, 1], [5, 5, 100])],
+        context_indices=[(0, 1)],
+        exchanges=[PrescribedSink(driver_index=1, scale=0.1)],
+    )
+    model = DeepDiscover(MultiDUModel([du], [['outlet']]))
+    out = model.simulate(water, drivers)
+    error = float(tf.reduce_max(tf.abs(out['mass_residual'])).numpy())
+    print('Shapes:', {k: tuple(out[k].shape) for k in
+                       ('outlet', 'storage', 'process_fluxes', 'sink_total', 'mass_residual')})
+    print('Maximum mass residual:', error)
+    assert error < 1e-4
+    with tf.GradientTape() as tape:
+        y = model.simulate(water, drivers)['outlet']
+        objective = tf.reduce_mean(tf.square(y))
+    grad = tape.gradient(objective, model._variables())
+    assert any(g is not None for g in grad)
+    assert all(np.isfinite(g.numpy()).all() for g in grad if g is not None)
+    dataset = HydroDataset(rain, np.stack([rain, pet], axis=-1), {'streamflow': rain})
+    train = dataset.make_windows(warmup=5, score_length=10, stride=5)
+    model.fit(train, epochs=1, batch_size=2, verbose=0)
+    score = model.evaluate(train)
+    print('Training score:', score['loss'])
+    print('Installation check passed')
+
+
+if __name__ == '__main__':
+    main()

deepdiscover_hydro-1.0.0/docs/boundaries.md

@@ -0,0 +1,48 @@
+# Physical water sources and losses
+
+DeepDiscover distinguishes **boundary exchanges** from **training loss functions**. A boundary exchange changes the physical water balance and must be accounted for in the simulated system.
+
+## Sources
+
+`water` supplies the external conserved inputs directly to DUs. Additional sources can be specified in a DU's `exchanges` list:
+
+- `PrescribedSource(driver_index, scale=1)` adds a non-negative amount from a driver column.
+- `FunctionalSource(my_layer)` adds a non-negative amount computed by a differentiable Keras layer.
+- A custom `keras.layers.Layer` declaring `kind = "source"` can implement the same `call(drivers)` contract.
+
+Applications include precipitation, prescribed recharge, irrigation, lateral inflow and water transferred into the modeled domain. A physical source cannot be silently included in both `water` and `exchanges`, as that would count the same water twice.
+
+## Losses
+
+- `PrescribedSink(driver_index, scale=1)` requests an externally specified amount, such as pumping or managed extraction.
+- `DemandLimitedSink(efficiency_net, demand_index, context_indices)` requests a loss bounded by demand and an efficiency between zero and one.
+- `FunctionalSink(my_layer)` uses a custom layer returning a non-negative requested amount.
+- A custom `keras.layers.Layer` with `kind = "sink"` implements `call(drivers, storage, available)`.
+
+Loss requests from the same DU are combined. If demand exceeds water availability, each request is reduced by the same fraction. Simultaneous evaporation and groundwater pumping are therefore admissible and conserve water.
+
+## Example
+
+```python
+from deepdiscover import (
+    CRCNet, DiscoverUnit, PrescribedSource, PrescribedSink,
+    DemandLimitedSink,
+)
+
+et_efficiency = CRCNet(gamma=[1, 1], x_ref=[10, 100], output="sigmoid")
+du = DiscoverUnit(
+    process_nets=[CRCNet([1, 1], [10, 100])],
+    context_indices=[(0,)],
+    exchanges=[
+        PrescribedSource(driver_index=2),            # lateral inflow
+        DemandLimitedSink(et_efficiency, demand_index=1, context_indices=[0]),
+        PrescribedSink(driver_index=3),              # pumping
+    ],
+)
+```
+
+Here the driver columns represent precipitation information, PET, lateral inflow and pumping request. The user must decide which entries are conserved in `water`, and which are introduced as boundary sources. This choice determines the physical system boundary.
+
+## Requirements for custom exchanges
+
+Sources and sinks return one non-negative `(B,1)` tensor in quantity-per-step units. Non-finite or negative values raise errors. Custom sinks return **requested losses**; the DU applies the available-water constraint. These exchanges may carry trainable Keras parameters. If they introduce water from a separate physical reservoir outside the graph, that reservoir is not included in the system storage balance.

deepdiscover_hydro-1.0.0/docs/camels.md

@@ -0,0 +1,68 @@
+# CAMELS-US data
+
+The CAMELS-US example uses the forcing and observed streamflow files for basin `01013500`. Download the original data from the CAMELS-US provider. The files are not part of this repository.
+
+Arrange the files as follows:
+
+```text
+data/
+    camels/
+        01013500/
+            01013500_lump_cida_forcing_leap.txt
+            01013500_streamflow_qc.txt
+```
+
+```python
+from deepdiscover import load_camels_dataset
+
+data = load_camels_dataset(
+    ".", "01013500", n_du=2,
+    start="1980-10-01", end="2010-09-30",
+)
+print(data.water.shape, data.drivers.shape)
+```
+
+The data reader computes mean temperature, Hamon potential evapotranspiration and catchment-equivalent streamflow depth. Predictor order is precipitation, potential evapotranspiration and temperature. External precipitation enters DU 0 by default.
+
+A value of `-999` or quality flag `M` in the CAMELS streamflow file indicates a missing observation. These values are excluded from calibration through the observation mask. Other negative discharge values cause an error. Missing precipitation or meteorological drivers must be handled explicitly before simulation.
+
+The published case-study chronology uses 365 warm-up days from 1980-10-01, training from 1981-10-01 to 2000-09-30, validation from 2000-10-01 to 2005-09-30 and testing from 2005-10-01 to 2010-09-30. The notebook selects these dates explicitly.
+
+Review the original CAMELS-US data documentation and quality flags before using alternative basins or periods. Cite the original data sources in scientific publications.
+
+## Running the notebook
+
+For a short execution check:
+
+```bash
+python run_examples.py --only 04_camels_us
+```
+
+To measure training speed on the complete set of 19 windows:
+
+```bash
+python run_examples.py --only 04_camels_us --camels-mode benchmark
+```
+
+For full calibration:
+
+```bash
+python run_examples.py --only 04_camels_us --camels-mode full
+```
+
+The physical model in this example has two DUs and three release processes: one direct outlet pathway, one transfer to the second DU, and one downstream outlet pathway. The snow module separates precipitation into rain and snowmelt. These quantities and PET form the process drivers, in that order. The temperature series is used by the snow module.
+
+Training data have shapes `water=(19,730,2)`, `drivers=(19,730,3)` and `streamflow=(19,730,1)`. Each window contains 365 unscored warm-up days and 365 scored days. The 19 complete scored blocks cover 6,935 of the 6,940 available training days; the final five days are not included in these nonoverlapping blocks. Full calibration fits all 19 windows together in one gradient update per epoch, validates every five epochs, and uses an upper limit of 400 epochs with early stopping. The notebook uses a learning rate of 0.01. The benchmark mode uses the same windows but only three epochs to report execution times.
+
+The check and benchmark modes verify execution and measure timing. Their calibration scores should not be used in scientific analysis. The independent test period is evaluated only in full mode, after checkpoint selection on validation data. Do not use test results for model selection. For comparisons between models, report the random seeds, model parameters, calibration periods and evaluation conventions.
+
+
+## Verifying a saved checkpoint
+
+After a full notebook run, the selected weights and validation history are saved. To check their consistency without fitting again, run:
+
+```bash
+python verify_camels.py
+```
+
+This procedure reconstructs the notebook architecture, loads the saved parameters, evaluates the validation period, and checks the water balance. The recorded validation objective and selected epoch must agree with the saved model. It does not evaluate the independent test period. The checkpoint format requires the same model configuration and a compatible DeepDiscover version.