anemoi-env 2025.11.1

Provides a reproducible, versioned Python environment for Anemoi experiments.

Provides a reproducible, versioned Python environment for Anemoi experiments.

anemoi-env is a meta-package that defines a standardized set of dependencies for machine learning and data science workflows. It contains no source code—only dependency declarations that are automatically versioned and published monthly.

Installation

Stable Release (Locked Dependencies)

For reproducible environments, install a specific calendar-versioned release from PyPI:

$ pip install anemoi-env==2025.11.1

Or install the latest locked version from the main branch:

$ pip install git+https://github.com/MeteoSwiss/anemoi-env.git@main

Development (Flexible Dependencies)

For development with the latest Anemoi features from main branches (no lock file):

$ pip install git+https://github.com/MeteoSwiss/anemoi-env.git@dev

Warning: The dev branch uses bleeding-edge dependencies and may be unstable.

Feature Testing (Fixed Commit SHAs)

For testing specific features with reproducible Anemoi commits, create a feature branch from main (not dev):

$ git checkout main
$ git checkout -b feature-test/new-graphs

Then edit pyproject.toml to pin specific commits:

[tool.poetry.dependencies]
anemoi-datasets = { git = "https://github.com/ecmwf/anemoi-datasets", rev = "abc123def" }
anemoi-graphs = { git = "https://github.com/ecmwf/anemoi-core.git", subdirectory = "graphs", rev = "def456abc" }
# ... other packages with fixed revisions

Run poetry lock to generate a lock file for this specific combination, then install:

$ poetry lock
$ poetry install

This approach provides reproducibility while testing bleeding-edge features before they’re released to PyPI.

Advanced Installation

CUDA-Specific PyTorch Versions

By default, anemoi-env installs PyTorch with CPU support or CUDA support based on what’s available in the default PyPI index. To install a specific CUDA version (e.g., CUDA 12.1), use PyTorch’s extra index URL:

$ pip install anemoi-env==2025.11.1 --extra-index-url https://download.pytorch.org/whl/cu121
$ pip install anemoi-env==2025.11.1 --extra-index-url https://download.pytorch.org/whl/cpu

Installing Anemoi Package Extras

Some Anemoi packages provide optional features via extras (e.g., anemoi-graphs[tri] for trimesh support). To use these extras while respecting the tested dependency versions from anemoi-env:

$ pip install anemoi-env==2025.11.1
$ pip install "anemoi-graphs[tri]"

Why install in two steps?

• Installing anemoi-env first locks all core Anemoi packages to tested, compatible versions

• Installing the extra second (e.g., [tri]) adds optional dependencies (like trimesh) with version constraints that are compatible with the already-installed anemoi-graphs

• If you directly pip install trimesh without the extra, you might get an incompatible version that hasn’t been tested with Anemoi

Always check each Anemoi package’s documentation for available extras.

Branching Strategy

This repository uses a multi-branch strategy with different dependency sources:

• main: Contains poetry.lock and uses stable PyPI releases of all dependencies. Updated automatically on the 1st of every month via CI. Each update creates a calendar-versioned release (e.g., 2025.10.0) and publishes to PyPI. Use this for reproducible, production-ready environments.

• dev: Contains pyproject.toml with no lock file and uses bleeding-edge versions from Anemoi package main branches (via git dependencies). Used for development against the latest Anemoi features. Not published to PyPI.

• feature-test/: Custom feature branches with fixed commit SHAs for each Anemoi package. Includes poetry.lock for reproducible testing of specific feature combinations. Useful for validating new features before they reach PyPI. Not published.

Continuous Integration

The repository includes automated CI/CD workflows:

• CI Test (CI_test.yaml): Runs on every push and pull request. Tests installation and verifies that all Anemoi packages can be imported successfully.

• CI Publish (CI_publish.yaml): Runs on the 1st of every month at 3 AM UTC. Automatically:

  1. Updates poetry.lock with latest compatible versions

  2. Updates version to current date (YYYY.MM.patch)

  3. Updates Changelogs with the new release information

  4. Creates a git tag

  5. Publishes the new release to PyPI

This ensures monthly snapshots of the Anemoi ecosystem are automatically published when updates are available.

Versioning

Uses Calendar Versioning (CalVer): YYYY.MM.patch

Each monthly release represents a snapshot of the dependency tree at that point in time. The patch number increments for additional releases within the same month (e.g., 2025.10.0, 2025.10.1, 2025.11.0).

What’s Included

• Anemoi Packages:

  • anemoi-datasets

  • anemoi-graphs

  • anemoi-inference

  • anemoi-models

  • anemoi-registry

  • anemoi-training

  • anemoi-utils

Development Setup with Poetry

Note: This package is a meta-package with no source code. Development primarily involves updating dependencies in pyproject.toml.

Local Development

Clone and install in development mode:

$ git clone https://github.com/MeteoSwiss/anemoi-env.git
$ cd anemoi-env
$ git checkout dev
$ poetry install

Generate Documentation

$ poetry run sphinx-build doc doc/_build

Then open the index.html file generated in anemoi-env/doc/_build/.

Usage For Reproducible Research

Always specify the exact version in your project dependencies:

For stable PyPI releases:

In pyproject.toml:

[tool.poetry.dependencies]
anemoi-env = "2025.11.1"

Or in requirements.txt:

anemoi-env==2025.11.1

For testing specific feature combinations:

[tool.poetry.dependencies]
anemoi-env = { git = "https://github.com/MeteoSwiss/anemoi-env.git", rev = "feature-test/new-graphs" }

This ensures your research uses a specific, reproducible set of dependencies—either from PyPI (stable) or from a pinned feature branch (testing).