icon-uv

Calculate the UV Index from ICON weather forecasts and CAMS atmospheric composition. icon-uv provides hourly grid and point forecasts and daily JSON for towns and mountain regions, using a bundled radiation lookup table.

Point forecasts need only coordinates and elevation. They use nearby ICON cloud and snow conditions, with optional UV albedo and horizon overrides for a specific site. Hourly and daily products share the same location definitions.

Installation

Install the released package with Python 3.11 or newer:

pip install 'icon-uv[cams]'
icon-uv --help

To run the current API and bundled examples, install from the repository with uv:

git clone https://github.com/ofuhrer/icon-uv.git
cd icon-uv
uv sync --locked --extra cams

The cams extra adds the ADS download client. CAMS requires an ADS account and accepted dataset terms; follow the CAMS API setup. ICON downloads are public. Omit [cams] when installing for saved inputs only.

Try it without credentials

uv run --no-sync python examples/offline.py --output-dir work/offline

This creates synthetic ICON/CAMS inputs and writes hourly grid/point NetCDF and daily JSON through the real radiation table. After installation it needs no network or credentials. The output illustrates the formats, not a weather forecast.

Calculate UV fields

Follow the forecast workflow to download ICON/CAMS inputs, compute a saved UV grid and export location products. The guide explains cycle selection, daylight coverage and ensemble options.

Hourly and daily locations

Define a point with coordinates and elevation, or a regional elevation band. The same catalog drives hourly point NetCDF and daily JSON; optional albedo and terrain horizons describe a specific site. See the location API for the Python API, JSON catalog and command-line examples.

Daily products reconstruct a rolling 30-minute peak from saved cloud and atmospheric state. They include ensemble summaries, support details and freshness checks. The offline example runs the complete saved-input workflow with synthetic data.

Documentation and examples

• Daily products: peak definition, ensemble uncertainty, missing data and JSON schemas.
• Output reference: NetCDF variables, provenance and quality flags.
• Interactive map: 30 towns and six mountain regions, with a dated CTRL snapshot and export scripts.
• Calculation method and validation: physics, evidence and limits.
• Examples, development and releasing.

Scope and limitations

The cloud fit uses ICON's downward shortwave flux without orographic shading (ASOD_S). Ambient forecasts do not apply a local terrain horizon. A town marker is an elevation-adjusted reference point; regional elevation bands provide context for surrounding mountains and cable-car trips. One marker cannot represent every slope, snow condition or cloud layer in a resort.

Snow-derived UV albedo is an experimental approximation. Cloud state is hourly; subhourly products follow solar geometry and do not resolve rapid cloud changes. Point elevation adjustments retain the source cloud column. Fixed atmospheric profiles, plane-parallel radiation and approximate optional horizon screening also limit accuracy; see the method and validation guides before interpreting results.

Sources and license

• MeteoSwiss ICON OGD
• CAMS atmospheric composition forecasts, produced by ECMWF for Copernicus
• libRadtran, used to generate the radiation table
• swisstopo elevation profiles, used for the supplied Davos horizon

Licensed under BSD 3-Clause. Input datasets and dependencies retain their own licenses and attribution requirements.