Installation#

Requirements#

Python ≥ 3.11

Install from PyPI#

pip

pip install healpix-convert

uv

uv add healpix-convert

healpix-convert is not available on conda-forge yet.

Dataset converters#

The ERA5, CAMS and ClimateDT converters need extra packages to download and read their input data. Install them with the matching extra:

pip install "healpix-convert[era5]"       # cdsapi, cfgrib
pip install "healpix-convert[cams]"       # requests
pip install "healpix-convert[climatedt]"  # cfgrib, polytope-client, destinelab

PyTorch#

healpix-convert depends on PyTorch, which the resampling methods of healpix-resample run on. On x86-64 Linux, pip installs the CUDA build of PyTorch: with its NVIDIA libraries, that is about 3 GB to download. For a CPU-only environment, install PyTorch from its CPU index first:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install healpix-convert

The PyTorch installation guide lists the other builds.

Development install#

Clone the repository:

git clone https://github.com/GRID4EARTH/healpix-convert
cd healpix-convert

If you have pixi installed, create the complete development environment with:

pixi install -e dev

Otherwise, install the package in editable mode in an isolated environment of your choice:

python -m pip install -e .

Note

pixi.toml declares the linux-64 and win-64 platforms with CUDA 12. On a Linux or Windows machine without an NVIDIA driver, pixi then refuses to install the environments (“Unsatisfied requirements: __cuda >= 12.0”). Set CONDA_OVERRIDE_CUDA=12.0 to work around it, like the CI does:

CONDA_OVERRIDE_CUDA=12.0 pixi install -e dev

Run the tests#

pixi run -e dev tests

Build the documentation#

pixi run -e docs build-docs

The HTML pages are written in docs/_build/html. Use pixi run -e docs autobuild-docs for a live preview that rebuilds on every change.

Verify the installation#

import healpix_convert

print(healpix_convert.__version__)