Skip to content

𝛿MG

A generic framework for building differentiable models. 𝛿MG enables seamless coupling of neural networks with differentiable process-based equations, leveraging PyTorch's auto-differentiation for efficient, large-scale optimization on GPU. The spiritual successor to HydroDL, 𝛿MG generalizes differentiable modeling for cross-domain application while also imposing basic standardizations for research-to-operations pipelines.

Key Features

  • 🀝 Hybrid Modeling: Combine neural networks with process-based equations for enhanced interpretability and generalizability. Instead of manual model parameter calibration, for instance, use neural networks to directly learn robust and interpretable parameters (Tsai et al., 2021).
  • πŸ” PyTorch Integration: Scale with PyTorch for efficient training and compatibility with modern ML tools and numerical solvers.
  • 🧩 Modular Plugin Architecture: Swap in domain-specific components and configurations with ease.
  • ⚑ Benchmarking: All in one place. 𝛿MG + hydroDL2 will enable rapid deployment and replication of key published MHPI results.
  • 🌊 NextGen-ready: Designed for CSDMS BMI compliance to support differentiable hydrological models in NOAA-OWP's NextGen National Water Modeling Framework. (See the NextGen-ready 𝛿HBV2.0 for an example with a 𝛿MG-supported BMI).


𝛿MG is designed to scale with modern deep learning tools (e.g., foundation models) while maintaining physical interpretability. Our peer-reviewed and published benchmarks show that well-tuned differentiable models can match deep networks in performanceβ€”while better extrapolating to extreme or data-scarce conditions and predicting physically meaningful variables.

Differentiable modeling introduces more modeling choices than traditional deep learning due to its physical constraints. This includes learning parameters, missing process representations, corrections, or other enhancements for physical models.

Note: While differentiable models are powerful and have many desirable characteristics, they come with a larger decision space than purely data-driven neural networks since physical processes are involved, and can thus feel "trickier" to work with. Hence, we recommend beginning with our example notebooks and then systematically making changes, one at a time. Pay attention to multifaceted outputs, diverse causal analyses, and predictions of untrained variables permitted by differentiable models, rather than purely trying to outperform other models' metrics.


This work is mantained by MHPI and advised by Dr. Chaopeng Shen. If you find it useful, please cite (dedicated citations are coming):

Shen, C., et al. (2023). Differentiable modelling to unify machine learning and physical models for geosciences. Nature Reviews Earth & Environment, 4(8), 552–567. <https://doi.org/10.1038/s43017-023-00450-9>.


Installation

To install 𝛿MG, clone the repo and install in developer mode with Astral UV:

git clone git@github.com:mhpi/generic_deltamodel.git
uv pip install -e ./generic_deltamodel

Pip and Conda are also supported, though UV is recommended. See setup for further details.


Quick Start

See how to run.

Example -- Differentiable Parameter Learning: Use an LSTM to learn parameters for the HBV hydrological model.

from hydroDL2.models.hbv.hbv import HBV

from dMG.core.data.loaders import HydroLoader
from dMG.core.utils import load_nn_model, print_config, set_randomseed
from dMG.models.delta_models import DplModel
from example import load_config, take_data_sample

CONFIG_PATH = '../example/conf/config_dhbv_1_0.yaml'


# Model configuration
config = load_config(CONFIG_PATH)

# Initialize physical model and NN.
phy_model = HBV(config['delta_model']['phy_model'])
nn = load_nn_model(phy_model, config['delta_model'])

# Create differentiable model dHBV: a torch.nn.Module that describes how 
# the NN is linked to the physical model HBV.
dpl_model = DplModel(phy_model=phy_model, nn_model=nn)

# Load dataset of NN and HBV inputs.
dataset = HydroLoader(config).dataset
dataset_sample = take_data_sample(config, dataset, days=730, basins=100)

output = dpl_model(dataset_sample)

This exposes a key characteristic of the differentiable model DplModel: composition of a physical model, phy_model, and a neural network, nn. Internally, DplModel looks like

# NN forward
parameters = self.nn_model(dataset_sample['xc_nn_norm'])        

# Physics model forward
predictions = self.phy_model(
    dataset_sample,
    parameters,
)

Check out examples to see model training/testing/simulation in detail. We recommend starting here, which is a continuation of the above. A Colab Notebook for this Ξ΄HBV example is also available.


Use Cases

1. Lumped Hydrology

Lumped differentiable rainfall-runoff models 𝛿HBV 1.0 and improved 𝛿HBV 1.1p.

2. Unseen Extreme Events Test with 𝛿HBV 1.1p

In the unseen extreme events spatial test, we used water years with a 5-year or lower return period peak flow from 1990/10/01 to 2014/09/30 for training, and held out the water years with greater than a 5-year return period peak flow for testing. The spatial test was conducted using a 5-fold cross-validation approach for basins in the CAMELS dataset. This application has been benchmarked against LSTM and demonstrates better extrapolation abilities. Find more details and results in Song, Sawadekar, et al. (2024).

3. National-scale Water Modeling

A national-scale water modeling study on approximately 180,000 river reaches (with a median length of 7 km) across CONUS using the high-resolution, multiscale, differentiable water model 𝛿HBV 2.0. This model is also operating at global-scales and has been used to generate high-quality, seamless simulations for the entire CONUS. Find more details and results in Song, Bindas, et al. (2025).

4. Global-scale Photosynthesis Modeling

Currently in development. Find more details and results in Aboelyazeed et al. (2024).


Ecosystem Integration

  • HydroDL 2.0 (hydroDL2): Home to MHPI's suite of process-based hydrology models and differentiable model augmentations.
  • Differentiable Ecosystem Modeling (diffEcosys (dev version only)): A physics-informed machine learning system for ecosystem modeling, demonstrated using the photosynthesis process representation within the Functionally Assembled Terrestrial Ecosystem Simulator (FATES) model. This model is coupled to NNs that learn parameters from observations of photosynthesis rates.
  • Other Development: Many additions are currently in the progress: (i) numerical PDE solvers on PyTorch, torchode, torchdiffeq; (ii) adjoint sensitivity; (iii) extremely efficient and highly accurate surrogate models for process-based equations; (iv) data assimilation methods; (v) downscaled and bias-corrected climate data; (vi) mysteriously powerful neural networks, and more ...


𝛿MG Architecture

  • Data Loaders: Bulk data preprocessors customized per dataset.
  • Data Samplers: Dataset samplers for minibatching during model training and inference.
  • Trainers: Orchestrates high-level model training, testing, and simulation.
  • ModelHandler: Manages multimodeling, multi-GPU computation, and other high level operations. Acts as an drop-in model interface for CSDMS BMI or other R2O wrappers.
  • Delta Models: Differentiable models; describes how NNs and physical models are coupled (e.g., DplModel for parameter learning).


Repo

```text
.
β”œβ”€β”€ src/dMG/
β”‚   β”œβ”€β”€ __main__.py                 # Runs 𝛿MG; models, experiments
β”‚   β”œβ”€β”€ core/                       
β”‚   β”‚   β”œβ”€β”€ calc/                   # Calculation utilities
β”‚   β”‚   β”œβ”€β”€ data/                   # Data loaders and samplers
β”‚   β”‚   β”œβ”€β”€ post/                   # Post-processing utilities; plotting
β”‚   β”‚   └── utils/                  # Helper functions
β”‚   β”œβ”€β”€ models/                     
β”‚   β”‚   β”œβ”€β”€ criterion               # Loss functions  
β”‚   β”‚   β”œβ”€β”€ delta_models            # Differentiable model modalities
β”‚   β”‚   β”œβ”€β”€ multimodels             # Multimodeling processors
β”‚   β”‚   β”œβ”€β”€ neural_networks/        # Neural network architectures
β”‚   β”‚   β”œβ”€β”€ phy_models/             # Physical Models
β”‚   β”‚   └── model_handler.py        # High-level model manager
β”‚   └── trainers/                   # Model training routines
β”œβ”€β”€ conf/
β”‚   β”œβ”€β”€ hydra/                      # Hydra settings
β”‚   β”œβ”€β”€ observations/               # Observation configuration files
β”‚   β”œβ”€β”€ config.py                   # Configuration validator
β”‚   └── default.yaml                # Default master configuration file
β”œβ”€β”€ docs/                           
β”œβ”€β”€ envs/                           # Python ENV configurations
└── example/                        # Tutorials
```


Contributing

We welcome contributions! Please submit changes via a fork and pull requests. For more details, refer to docs/CONTRIBUTING.md.

Please submit an issue to report any questions, concerns, bugs, etc.