README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Data Assimilation
- Model Error Correction
frameworks: PyTorch
---

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

# Model Introduction

AtmosphericDA-DModel learns and corrects systematic errors in atmospheric numerical dynamical models by combining a knowledge-based model with the paper's D model error corrector to improve data-assimilation analyses and short- to medium-range forecasts.

Paper: Using machine learning to correct model error in data assimilation and forecast applications  
https://doi.org/10.1002/qj.4116

# Model Description

The method reproduced by AtmosphericDA-DModel was proposed by research teams from CEREA, École des Ponts ParisTech, EDF R&D, and the European Centre for Medium-Range Weather Forecasts. The paper trains the error-correction model with data-assimilation analysis trajectories generated from complete noise-free and sparse noisy observations of a two-layer, two-dimensional quasi-geostrophic channel model with perturbed-parameter error. The model is suitable for dynamical model-error learning, hybrid surrogate forecasting, and improvement of data-assimilation analyses.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Dynamical model-error studies | Study perturbed-parameter error in two-layer streamfunction channel dynamics. |
| Hybrid forecast validation | Combine the perturbed dynamics with Dense D-model analysis increments. |
| Data-assimilation experiments | Generate executable approximate analyses from complete sparse-observation windows; the interface can be replaced by full 4D-Var. |
| ModelScope/OneCode execution | Validate training, inference, evaluation, visualization, and checkpoint workflows in ModelScope or OneCode. |
| Multi-GPU training | Launch distributed data-parallel training with `torchrun`. |

# Usage Instructions

## 1.OneCode

Experience intelligent, one-click AI4S programming through the OneCode online environment:

[Try intelligent, one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Download and Installation

```bash
hf download OneScience-Group/AtmosphericDA-DModel --local-dir ./AtmosphericDA-DModel
cd AtmosphericDA-DModel
```

### 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 must install DTK first. DTK 25.04.2 or later, or the OneScience-recommended version matching the cluster, is recommended.

**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
```

### Training Data

This repository uses a small number of structured two-layer quasi-geostrophic streamfunction samples to validate the engineering workflow. Each sample retains the complete `2×20×40` state and 12 batches of 50 bilinear observations at random locations. The input is an analysis state, and the target is the model-error increment between the next analysis and the original-model forecast; only the sample count is reduced, not the state or observation-window dimensions. Synthetic data validate model-error learning, training, inference, and evaluation only and do not represent the paper data distribution or formal performance.

```bash
python scripts/fake_data.py
```

### Training

For single-device training, use:

```bash
python scripts/train.py
```

For multi-GPU training, use:

```bash
torchrun --nproc_per_node=8 --nnodes=1 --rdzv_id=1000 --rdzv_backend=c10d --max_restarts=0 --master_addr="localhost" --master_port=29500 scripts/train.py
```

Training validates the state, observation, and target formats and fits the model with Adam and MSE. The default configuration reduces the number of epochs for quick workflow validation, and results are saved to:

```text
result/checkpoints/d_model.pt
result/training/metrics.json
```

### Trained Weights

This repository does not include weights under `weight/`. The paper does not provide a confirmed official checkpoint, and the current engineering checkpoint is not claimed to be compatible with external weights.

### Inference

```bash
python scripts/inference.py
```

Inference results include the reference analysis states, original-model forecasts, error corrections, and hybrid-model forecasts. Complete numerical results are saved to `result/output/predictions.npz`.

### Evaluation and Visualization

```bash
python scripts/result.py
```

Evaluation reports streamfunction RMSE for the dynamics and hybrid next analyses, plus strict analysis-increment RMSE, while validating complete dimensions and finite values. Metrics and the figure are saved to `result/evaluation/metrics.json` and `result/evaluation/comparison.png`. Synthetic results validate the workflow only and do not represent paper performance.

# Official OneScience Information

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |

# Citation and License

This repository is an independent engineering reproduction of the public AtmosphericDA-DModel specifications.

Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.