Metadata-Version: 2.4
Name: swissweathergrid
Version: 0.0.2
Summary: SwissWeatherGrid - Hourly temperature and irradiance for any point in Switzerland, on a 1 km grid
Author-email: Joseph Loustau <joseph.loustau@epfl.ch>
Maintainer-email: IPESE-IT <it.ipese@epfl.ch>
License: Apache-2.0
Project-URL: Documentation, https://swissweathergrid.readthedocs.io/
Project-URL: Repository, https://gitlab.epfl.ch/ipese/urban-systems/swissweathergrid
Project-URL: Download, https://pypi.org/project/swissweathergrid
Keywords: weather data,kriging,climate scenarios,Switzerland,energy systems
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi
Requires-Dist: netCDF4
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Provides-Extra: postgres
Requires-Dist: psycopg2-binary<3.0.0; extra == "postgres"
Requires-Dist: sqlalchemy>=2.0.0; extra == "postgres"
Provides-Extra: plotting
Requires-Dist: matplotlib; extra == "plotting"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# SwissWeatherGrid

![Mean annual temperature on the 1 km grid](https://gitlab.epfl.ch/ipese/urban-systems/swissweathergrid/-/raw/main/docs/images/grid_mean_annual_temperature.svg)

SwissWeatherGrid gives hourly temperature and irradiance for any point in
Switzerland, now or under a climate scenario, on a 1 km grid. This package rebuilds the MeteoSwiss interpolation and runs it on station data ([Frey & Frei, 2025](https://doi.org/10.1002/joc.8796)). This interpolation method is then reused to create a grid for the climate change scenarios from CH2025 and WSL's downscaling ([Michel et al., 2021](https://doi.org/10.1002/joc.7032)).


It is developed by EPFL (Switzerland), within the *Industrial Process and Energy
Systems Engineering (IPESE)* group.

It is designed for softwares the need hourly resolution but where the sequence of days does not matter, such as REHO or Energyscope, that work with typical days.

The motivation for its build was the lack of precision from the former source, PVGIS; PVGIS takes its temperature from ERA5, a project where the grid resolution is at 30 km, which is not sufficient in the Alpine terrain where the temperature elevation gradient can change drastically within that distance.

## Documentation

<https://swissweathergrid.readthedocs.io/>

## Use

#### 1. Install

```bash
pip install swissweathergrid
```

To read grids from PostgreSQL, install the optional extra:

```bash
pip install "swissweathergrid[postgres]"
```

#### 2. Get the data for one point

```python
from swissweathergrid import get_cell_weather

df = get_cell_weather(46.52, 6.63, 2023)   # Lausanne, 8760 rows
```

Coordinates are WGS84 degrees; the point is snapped to the 1 km cell containing
it. You get an hourly frame for the whole calendar year — 8760 rows, 8784 in a
leap year:

| column | unit | source |
|---|---|---|
| `temperature` | °C | the KED grid |
| `beam`, `diffuse` | W/m² | PVGIS, for the plane you asked for |
| `global_horizontal` | W/m² | `beam + diffuse` |

Pass `irradiance=False` for temperature only, or `slope=` and `azimuth=` for a
tilted plane.

#### 3. Choose a scenario

```python
df = get_cell_weather(46.52, 6.63, 2023, scenario="rcp45_2045")
```

A scenario is named `{pathway}_{year}`. A pathway says how the world gets warmer, a year says when you are
looking. Neither alone fixes a climate.

| part | values | meaning |
|---|---|---|
| pathway | `rcp26`, `rcp45`, `rcp85` | CH2018 emission pathway, 12 / 25 / 31 model chains |
| year | 1990–2100 | resolved to the WSL decade containing it |

`"current"` is the observed year, unwarmed.

The `year` argument stays the **base year** — the observed year being warmed.
So `scenario="rcp45_2045", year=2023` means "2023's weather, moved to the
climate of the 2040s under RCP4.5". The change is measured between the decade
containing your base year and the decade containing the scenario year, taken
from the same model chains, so the historical record cancels and only the
climate signal survives.


#### 4. What a scenario series may be used for

Each delivered year is a **continuous 8760-hour series** with real day-to-day
persistence, because the scenario warms an observed year rather than
synthesising one. What it is not is a moment in a trajectory.

**No transient series.** WSL provides decade snapshots, not a continuous run
through the century. The authors: "only snapshots for the future are provided
with discontinuities between them." Two scenario years are two separate
stationary climates, not two points on a path.

**No climate signal in the sub-daily cycle.** The delta is applied to a
historical hourly record, so the diurnal *shape* is inherited from the past.
What the method gets right is leaving that shape undistorted; what it cannot
tell you is how the shape itself changes.

**Only the change is usable.** The signal is a difference taken *inside* WSL,
between two decades of the same model chain, which cancels the bias of the
underlying record. Absolute scenario values do not carry over; differences and
ratios do.

In practice:

| you want | do |
|---|---|
| typical days, duration curves, monthly or seasonal statistics | fine — these use the distribution |
| a design day, a heating or cooling degree-hour total | fine |
| "what does 14 July 2045 look like" | **no** — the day order carries no information |
| a 2030 → 2040 → 2050 trajectory | **no** — the decades are separate stationary climates |
| a change in the shape of the daily cycle | **no** — inherited from the historical record |


## Structure

| folder | what it does |
|---|---|
| `swissweathergrid/core/` | HTTP caching, LV95 coordinates, elevation, grid definition |
| `swissweathergrid/interpolation_method/` | rebuilds and validates the method of Frey & Frei (2025) |
| `swissweathergrid/grid_building/` | applies it to produce national grids per scenario and year |
| `swissweathergrid/cell_access/` | queries a grid for one location, and adds irradiance |


## References

- Frey, L. & Frei, C. (2025). Interpolation of Hourly Surface Air Temperature — Application of a Spatio-Temporal Statistical Model in Complex Terrain. *International Journal of Climatology*, 45(7). <https://doi.org/10.1002/joc.8796>
- Michel, A., Sharma, V., Lehning, M. & Huwald, H. (2021). Climate change scenarios at hourly time-step over Switzerland from an enhanced temporal downscaling approach. *International Journal of Climatology*, 41(6), 3503–3522. <https://doi.org/10.1002/joc.7032>


## Main contributors

* Joseph **Loustau**, IPESE, EPFL

## License

Apache License 2.0 — see [LICENSE](LICENSE).
