Metadata-Version: 2.4
Name: geoarches
Version: 0.2.1
Summary: Machine learning package for training, running, and evaluating ML models on geospatial data (specifically climate and weather data)
Author: ARCHES lab @ INRIA
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/INRIA/geoarches
Project-URL: Documentation, https://geoarches.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/INRIA/geoarches
Project-URL: Issues, https://github.com/INRIA/geoarches/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <=3.14.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<3.0.0,>=2.13.0
Requires-Dist: torchvision<1.0.0,>=0.25.0
Requires-Dist: xarray<2026.0.0,>=2025.1.1
Requires-Dist: submitit<2.0.0,>=1.5.2
Requires-Dist: diffusers<1.0.0,>=0.38.0
Requires-Dist: netcdf4<2.0.0,>=1.7.2
Requires-Dist: wandb<0.29.0,>=0.28.0
Requires-Dist: tqdm<5.0.0,>=4.67.1
Requires-Dist: matplotlib<4.0.0,>=3.10.0
Requires-Dist: hydra-core==1.3.2
Requires-Dist: axial-attention<0.7.0,>=0.6.1
Requires-Dist: lightning<3.0.0,>=2.5.0.post0
Requires-Dist: zarr<3.0.0,>=2.0.0
Requires-Dist: einops<0.9.0,>=0.8.0
Requires-Dist: tensordict<0.14.0,>=0.13.0
Requires-Dist: scipy<2.0.0,>=1.15.1
Requires-Dist: pyshtools<5.0.0,>=4.13.1
Requires-Dist: fasteners<0.20,>=0.19
Requires-Dist: timm<2.0.0,>=1.0.13
Requires-Dist: dask<2025.0.0,>=2024.12.1
Requires-Dist: seaborn<0.14.0,>=0.13.2
Requires-Dist: gcsfs<2026.0.0,>=2025.5.1
Requires-Dist: huggingface-hub<2.0.0,>=0.34.0
Dynamic: license-file

<h1 align="center">
  <a href="http://www.geoarches.readthedocs.io">
    <img src="https://raw.githubusercontent.com/INRIA/geoarches/main/docs/assets/logo.png" alt="geoarches logo" width="120" height="120">
  </a>
  <br/>
  geoarches
</h1>

<p align="center"><strong>Machine learning framework for geospatial data, mainly climate and weather.</strong></p>

<p align="center">
  <a href="https://geoarches.readthedocs.io/">Documentation</a>
</p>

## What is geoarches?

**geoarches** is a machine learning library for training, running and evaluating models on weather and climate data, developed by Guillaume Couairon and Renu Singh in the ARCHES team at INRIA (Paris, France).

geoarches's building blocks can easily be integrated into any research ML pipelines.
It can also be used to run the [ArchesWeather and ArchesWeatherGen](https://arxiv.org/abs/2412.12971) weather models.

geoarches builds on PyTorch, PyTorch Lightning and Hydra. Once installed, you can use its modules inside your own project, or use the main training and evaluating workflows.
To develop your own models or modify existing ones, the intended usage is to work in your own working directory and create your own configurations files and Lightning modules. See the [User Guide](https://geoarches.readthedocs.io/en/latest/user_guide/custom_models/) for the full details.

## Code Overview

geoarches is meant to jumpstart your ML pipeline with building blocks for data handling, model training, and evaluation. This is an effort to share engineering tools and research knowledge across projects.

### Data

- `download/`: Parallelized dataset download scripts with support for chunking to speed up read access.
- `dataloaders/`: PyTorch datasets for loading and preprocessing NetCDF files into ML-ready tensors.

### Model training

- `backbones/`: Network architectures that plug into Lightning modules.
- `lightning_modules/`: Training and inference wrappers that are agnostic to the backbone but specific to the ML task — handle losses, optimizers, and metrics.

### Evaluation

- `metrics/`: Tested suite of efficient, memory-friendly metrics.
- `evaluation/`: End-to-end scripts to benchmark model predictions and generate plots.

### Pipeline

- `main_hydra.py`: Entry point for training or inference using Hydra configurations.
- `docs/archesweather/`: Quickstart code for training and inference.

## Installation

Install the latest release from PyPI:

```sh
pip install geoarches
```

To contribute or work from the latest source, clone the repository and install the package
with either [Poetry](https://python-poetry.org/docs/) (>=2.2) or
[uv](https://docs.astral.sh/uv/):

```sh
git clone git@github.com:INRIA/geoarches.git
cd geoarches

# With Poetry
poetry install

# Or with uv
uv sync
```

> [!NOTE]
> Both tools install `geoarches` in editable mode. This allows you to make changes to the package locally, meaning any local changes will automatically be reflected to the code in your environment.

For full installation instructions, see the [documentation](https://geoarches.readthedocs.io/en/latest/getting_started/installation/).

## Contributing

The project welcomes contributions and suggestions. If you want to contribute, please read the [Contributing Guide](https://geoarches.readthedocs.io/en/latest/contributing/contribute/).

## External Resources

Many thanks to the authors of WeatherLearn for adapting the Pangu-Weather pseudocode to PyTorch. The code for our model is mostly based on their codebase.

- [WeatherBench](https://sites.research.google/weatherbench/)
- [WeatherLearn](https://github.com/lizhuoq/WeatherLearn/tree/master)

## License

geoarches is available under the
[BSD 3-Clause License](https://github.com/INRIA/geoarches/blob/main/LICENSE).
