README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Climate Parameterization
- Subgrid Processes
frameworks: PyTorch
---

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

# Model Introduction

NNCAM predicts physical tendencies and fluxes produced by cloud, convection, and radiation subgrid processes from atmospheric-column states for data-driven climate-model parameterization research.

Paper: Deep learning to represent subgrid processes in climate models  
https://gmd.copernicus.org/articles/11/3999/2018/

# Model Description

The method was proposed by research teams from Ludwig Maximilian University of Munich, the University of California Irvine, and Columbia University. The paper trains on approximately 140 million atmospheric-column samples from one year of SPCAM aquaplanet simulation. The model predicts 65 heating, moistening, radiative-flux, and precipitation outputs from a 94-dimensional atmospheric-column state.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Subgrid-process parameterization | Predict physical tendencies and fluxes from temperature, humidity, wind, and surface forcing. |
| Atmospheric-column diagnostics | Validate heating, moistening, radiation, and precipitation relationships over 30 levels. |
| Local engineering validation | Validate training, inference, conservation diagnostics, and visualization with structured synthetic samples. |
| ModelScope/OneCode execution | Validate structured data, training, inference, parameterization metrics, and visualization in ModelScope or OneCode environments. |
| Multi-GPU training | Validate distributed training and the checkpoint workflow through `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/NNCAM --local-dir ./NNCAM
cd NNCAM
```

### 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 in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current 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

The paper uses SPCAM aquaplanet simulations with a 30-minute timestep and 30 vertical levels. Inputs are `[B,94]` temperature, humidity, wind, and surface-forcing columns, and targets are `[B,65]` heating, moistening, four radiative fluxes, and precipitation. This repository uses a small structured synthetic dataset for engineering validation only and does not represent the real SPCAM distribution, training scale, or paper performance.

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

### Training

For single-GPU 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
```

The default reduces the paper's nine 256-node layers to four 32-node layers and shortens training without reducing the 94 inputs, 65 outputs, or 30-level vertical protocol. Formal experiments require real SPCAM data and the paper-scale model, with artifacts saved to:

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

### Trained Weights

The paper does not provide directly loadable official model weights, and this repository bundles no weights under `weight/`. The locally trained checkpoint is saved to `result/checkpoints/nncam.pt` and must not be represented as an official pretrained weight.

### Inference

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

Inference loads the training checkpoint and generates subgrid tendencies, radiative fluxes, and precipitation from complete atmospheric-column states. Complete numerical outputs are saved to:

```text
result/output/predictions.npz
```

### Evaluation and Visualization

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

Evaluation computes grouped RMSE and R² and generates grouped-error and precipitation-prediction comparisons. Synthetic-data results validate engineering only and do not represent paper performance; outputs are saved to:

```text
result/evaluation/metrics.json
result/evaluation/comparison.png
```

# 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 NNCAM specifications.

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