README.md

---
license: cc-by-4.0
language:
- en
tags:
- OneScience
- Earth Science
- Multi-Source Earth Observation
- Geospatial Embeddings
frameworks: PyTorch
---

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

# Model Introduction

AlphaEarthFoundations is a multi-source spatiotemporal embedding field model for global Earth observation mapping. It jointly encodes sparse and asynchronous data, including optical imagery, radar, LiDAR, climate, elevation, land cover, and geographic text, into 64-dimensional unit-sphere embeddings that support classification, regression, and change detection with limited labels.

Paper: AlphaEarth Foundations: An embedding field model for accurate and efficient global mapping from sparse label data  
https://arxiv.org/abs/2507.22291

# Model Description

AlphaEarth Foundations was proposed by research teams at Google DeepMind and Google. The model was trained on more than three billion observations. It takes Sentinel-2, Sentinel-1, and Landsat-8/9 time-series imagery as input and uses data including PALSAR-2, ERA5-Land, GEDI, GRACE, Copernicus DEM, NLCD, and geographic text as learning targets. The model is suitable for multi-source Earth observation representation learning, thematic mapping with sparse labels, biophysical variable estimation, and time-series change detection.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Multi-source spatiotemporal representation | Fuse asynchronous time-series observations from Sentinel-2, Sentinel-1, and Landsat-8/9. |
| Mapping with sparse labels | Train kNN or linear predictors using 64-dimensional embeddings and a small number of point labels. |
| Biophysical variable estimation | Regress continuous variables such as land surface emissivity and evapotranspiration from embeddings. |
| Land surface change detection | Compare unit-sphere embeddings from different validity periods to perform supervised or unsupervised change detection. |
| Local engineering validation | Use a small amount of synthetic data that preserves the paper's actual dimensions to validate training, inference, quantization, evaluation, and visualization workflows. |
| 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/AlphaEarthFoundations --local-dir ./AlphaEarthFoundations
cd AlphaEarthFoundations
```

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can be used to verify connectivity with the default small-sample configuration; full training and global inference require large-scale acceleration resources.
- 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
# uv installation is supported
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
# uv installation is supported
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 synthetic samples to validate the engineering workflow. The training and test data are stored in `data/train.npz` and `data/test.npz`, respectively. The synthetic data preserves the paper's 1.28 km × 1.28 km extent, 10-meter grid, 65 Sentinel-2 frames, 17 Sentinel-1 frames, 21 Landsat frames, and the explicitly disclosed input-source and training-target channel specifications; only the number of samples and the default internal model width are reduced.

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

### Training

```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 configuration is intended for rapid workflow validation. Formal experiments should use the multi-temporal data, complete task labels, model configuration, and training schedule corresponding to the paper.

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

### Trained Weights

This repository does not include synthetic or trained weights. Training generates `result/checkpoints/alphaearthfoundations.pt`; Google and Google DeepMind have not released the paper's v2.0/v2.1 model weights or checkpoints.

### Inference

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

Inference loads the training checkpoint and generates float32 unit-sphere embeddings, the paper's `s8²` signed int8 quantized embeddings, and reconstruction results for nine target categories. The outputs are saved to:

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

### Evaluation and Visualization

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

The evaluation reports reconstruction MAE or classification error rates for each training source, the mean embedding norm, and `s8²` quantization error. It also follows the paper's lightweight transfer approach by running kNN with `k=1`, kNN with `k=3`, unregularized linear classification, and linear regression; reporting Balanced Accuracy and R²; and generating comparison plots of the A01, A16, and A09 embedding axes against the land-cover target. Results on synthetic data are intended only to validate the engineering workflow and do not represent the paper's complete performance on 15 real downstream datasets.

```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 engineering reproduction of the original AlphaEarth Foundations paper.

Use of the code and data in this repository remains subject to the licenses and terms of use of their respective projects.