README.md

---
license: apache-2.0
language:
- en
tags:
- OneScience
- Earth Science
- Coupled Climate
- Ocean Emulator
- Atmosphere Emulator
- Long-Term Climate
frameworks: PyTorch
---

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

# Model Introduction

SamudrACE combines three-dimensional atmosphere and ocean emulators in a fast coupled climate model. SST, sea ice, and surface fluxes are exchanged in physical state space for stable long-term simulation.

Paper: SamudrACE: Fast and Accurate Coupled Climate Modeling With 3D Ocean and Atmosphere Emulators  
https://arxiv.org/abs/2509.12490

# Model Description

The model was proposed by teams from Ai2, New York University, Princeton University, NOAA/GFDL, Columbia University, and collaborators. It was trained with a 200-year GFDL CM4 pre-industrial control simulation. ACE2-style atmosphere and SamudraI-style ocean components exchange physical states for coupled climate simulation and drift diagnosis.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Coupled simulation | Drive one ocean step with 20 atmosphere steps. |
| Climate drift diagnosis | Assess atmosphere, heat, and salinity proxies. |
| Global climate emulation | Preserve a logical one-degree multilevel state. |
| ModelScope/OneCode execution | Validate structured data, training, inference, climate metrics, and visualization. |
| Multi-GPU training | Start multi-process training through `torchrun`. |

# Usage Instructions

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

### 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 --nproc_per_node=2 --nnodes=1 --master_addr="localhost" --master_port=29500 scripts/train.py
python scripts/inference.py
python scripts/result.py
```

Synthetic tiles retain all 126 fields enumerated by the paper and the 20-to-1 coupling ratio. Training performs coupled backpropagation through 20 atmosphere steps and one ocean step, and both single-process and two-process DDP runs have been verified. Inference restores the checkpoint and preserves 46 atmosphere channels, 80 ocean channels, original tile coordinates, and the incomplete-global marker. Training results are saved to `result/checkpoints/samudrace.pt`; inference and drift diagnostics are saved under `result/output/` and `result/evaluation/`.

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

The original paper, official code, weights, and GFDL CM4 data remain subject to their respective licenses and terms.