OneScience-Group/AlphaEarthFoundations

<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

Usage Instructions

1.OneCode

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

Try intelligent, one-click AI4S programming

2.Download and Installation

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

# 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

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

python scripts/fake_data.py

Training

python scripts/train.py

For multi-GPU training, use:

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.

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

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:

result/output/predictions.npz

Evaluation and Visualization

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.

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

Official OneScience Information

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.