Adaptive Differentiable Ecohydrological Land Model
ADELM is a fully differentiable land surface model built in PyTorch and it represents the coupled water, energy, and carbon exchange of the land surface within a single automatic-differentiation graph.
The source of each parameter is itself a choice among:
- a prescribed value (fixed constant, plant-functional-type lookup, remote-sensing product, or pedotransfer function),
- a globally shared learned value, or
- a spatially varying learned value, expressed as a differentiable function of environmental attributes defined across the domain.
adelm/
├── model/
│ ├── environment/ # physical descriptors of the land–atmosphere environment
│ ├── processes/ # carbon, water, and energy process modules
│ ├── parameterization/ # PFT-based and neural-network parameterization
│ ├── runtime/ # model assembly, data loading, and execution
│ │ ├── configs/ # runtime configuration dataclasses
│ │ ├── builders/ # model assembly (system, process, parameter, states)
│ │ ├── loaders/ # data loading for site and grid inputs
│ │ ├── runners/ # execution entry points (site learning, simulation, grid)
│ │ └── workflows/ # cross-validation workflows (no-CV, spatial, temporal)
│ ├── utils/ # shared utility functions
│ └── variables/ # central variable registry and metadata
├── scripts/ # command-line entry points (site learning, simulation, grid)
├── examples/ # example configuration files
├── config.yaml # annotated configuration template
└── gpu_environment.yml # conda environment specification
ADELM is a Python package built on PyTorch. Create the provided conda environment, which installs the scientific stack and a CUDA-enabled PyTorch build:
conda env create -f gpu_environment.yml
conda activate adelm_gpuFor a CPU-only setup, install the CPU PyTorch wheels instead of the CUDA index given in gpu_environment.yml.
ADELM is driven by a single YAML configuration file. Copy and edit config.yaml (a fully annotated template), or start from one of the ready-made files in examples/. The three command-line entry points are:
# Learn parameter mappings from multi-site observations
python scripts/site_learning.py --config examples/example_spatial_learning_no_cv.yaml
# Forward simulation at site scale (prescribed or learned parameters)
python scripts/site_simulation.py --config examples/example_site_simulation_default_parameters.yaml
# Forward simulation over a spatial grid
python scripts/grid_simulation.py --config examples/example_grid_simulation_default_parameters.yamlThe cross-validation workflow for site learning (none / spatial / temporal) is selected automatically from the site_learning.cross_validation settings in the configuration.
Full documentation — installation, configuration reference, process notes, and example workflows — is available at: https://adelm.org/.
ADELM is developed at the Max Planck Institute for Biogeochemistry and the ELLIS Unit Jena.
Correspondence: Shijie Jiang.
Contributions are welcome — including bug reports, process-formulation discussions, and parameterization or diagnostics proposals. See CONTRIBUTING.md for guidelines on reporting issues and submitting changes.
ADELM is free and open-source software, licensed under the European Union Public Licence v1.2 (EUPL).
You are free to copy, modify, and redistribute the code, and to use it in both commercial and non-commercial contexts. If you redistribute a modified version — excluding changes made solely for interoperability — you must do so under the EUPL v1.2 or a compatible licence.
This software is provided in the hope that it will be useful, but without any warranty, including, without limitation, the implied warranties of merchantability or fitness for a particular purpose.
Copyright © 2026 Max Planck Institute for Biogeochemistry