Source code for energy_data_retrieval.sources.cds.era5

"""Explicit ERA5 single-level selections, divided into one request per month."""

from __future__ import annotations

import calendar
import math
import re
from collections.abc import Sequence
from datetime import date

from energy_data_retrieval.transport import JSONValue

from .client import CDSRequest


[docs] def era5_requests( start: date, end: date, *, variables: Sequence[str], area: tuple[float, float, float, float], monthly_means: bool = False, data_format: str = "grib", ) -> tuple[CDSRequest, ...]: """Build inclusive UTC date-label requests for ERA5 reanalysis (not ERA5-Land). ``area`` is [north, west, south, east] in degrees. Dateline crossing must be split explicitly. Hourly requests include all 24 source labels per selected day; no extra endpoint is added or radiation-interval alignment inferred. Monthly means require whole calendar months and request 00:00 by CDS convention. Plans are limited to 1,200 months and 64 variables, executed sequentially. """ if type(start) is not date or type(end) is not date or not date(1940, 1, 1) <= start <= end: raise ValueError("ERA5 dates must be calendar dates ordered from 1940-01-01") count = (end.year - start.year) * 12 + end.month - start.month + 1 if count > 1200: raise ValueError("Split ERA5 plans exceeding 1200 months") if isinstance(variables, str) or not 1 <= len(variables) <= 64: raise ValueError("Supply 1..64 explicit ERA5 variable names") if len(set(variables)) != len(variables) or any( not isinstance(v, str) or not re.fullmatch(r"[a-z0-9][a-z0-9_]{0,127}", v) for v in variables ): raise ValueError("ERA5 variable names must be unique CDS identifiers") if len(area) != 4 or any( isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) for v in area ): raise ValueError("area requires finite north, west, south, east coordinates") north, west, south, east = area if not (-90 <= south <= north <= 90 and -180 <= west <= east <= 180): raise ValueError("area must be ordered north/west/south/east without dateline crossing") if data_format not in {"grib", "netcdf"}: raise ValueError("data_format must be grib or netcdf") if not isinstance(monthly_means, bool): raise ValueError("monthly_means must be boolean") if monthly_means and (start.day != 1 or end.day != calendar.monthrange(end.year, end.month)[1]): raise ValueError("Monthly means require whole calendar months") requests = [] for offset in range(count): year, month0 = divmod(start.year * 12 + start.month - 1 + offset, 12) month = month0 + 1 first = start.day if offset == 0 else 1 last = end.day if offset == count - 1 else calendar.monthrange(year, month)[1] selection: dict[str, JSONValue] = { "product_type": ["monthly_averaged_reanalysis" if monthly_means else "reanalysis"], "variable": [*variables], "year": [str(year)], "month": [f"{month:02d}"], "time": ["00:00"] if monthly_means else [f"{hour:02d}:00" for hour in range(24)], "area": [float(v) for v in area], "data_format": data_format, "download_format": "unarchived", } if not monthly_means: selection["day"] = [f"{day:02d}" for day in range(first, last + 1)] dataset = "reanalysis-era5-single-levels" + ("-monthly-means" if monthly_means else "") requests.append(CDSRequest(dataset, selection)) return tuple(requests)