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

AlphaEarthFoundations

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