README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- TWSA
- GRACE
- Self-Supervised Assimilation
- Hydrology
frameworks: PyTorch
---

<p align="center"><strong><span style="font-size: 30px;">GRACE-SEDA</span></strong></p>

# Model Introduction

GRACE-SEDA is a self-supervised data-assimilation model for global high-resolution total-water-storage anomalies.

Paper: Global high-resolution total water storage anomalies from self-supervised data assimilation using deep learning algorithms  
https://doi.org/10.1038/s44221-024-00194-w

# Model Description

The model was proposed by teams including ETH Zurich. It was trained with JPL GRACE, WGHM, GLDAS hydrological variables, and coordinates. A residual encoder-decoder and dual self-supervised constraints support global 0.5-degree TWSA reconstruction, uncertainty estimation, and water-budget analysis.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| TWSA downscaling | Generate high-resolution water-storage anomalies. |
| Self-supervised assimilation | Balance GRACE aggregates and WGHM structure. |
| Uncertainty | Use a five-model deep ensemble. |
| ModelScope/OneCode execution | Validate data, training, inference, hydrology metrics, and visualization. |
| Multi-GPU training | Start multi-process training through `torchrun`. |

# Usage Instructions

```bash
hf download OneScience-Group/GRACE-SEDA --local-dir ./GRACE-SEDA
cd GRACE-SEDA
```

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can be used for connectivity validation with the default small-sample configuration.
- DCU users should install DTK 25.04.2 or a compatible OneScience-recommended version first.

**DCU Environment**

```bash
# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

**GPU Environment**

```bash
# Activate Conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

```bash
python scripts/fake_data.py
python scripts/train.py
torchrun --standalone --nproc_per_node=2 scripts/train.py
python scripts/inference.py
python scripts/result.py
```
Training optimizes GRACE aggregate and WGHM structural terms. Inference restores five models and evaluation reports finite correlation, aggregate error, and uncertainty.
## Trained Weights
No weights are bundled under `weight/`. The authors provide core code, trained models, and weights at https://gitlab.ethz.ch/spacegeodesy_public/grace_seda.
# Citation and License
This repository is an independent engineering reproduction of the public GRACE-SEDA specifications.

The original paper is licensed under CC BY 4.0; official code, model weights, and related data retain their respective terms.