Download SEAS5 seasonal forecast from Copernicus

docs/INDEX.md

@@ -6,6 +6,8 @@ For an overview of the needed atmospheric forcing variables for eCLM see [Overvi
 
 For the default creation of atmospheric forcing based on ERA5 data see [eCLM atmospheric forcing based on ERA5](era5forcing).
 
+For the default creation of atmospheric forcing based on SEAS5 data see [eCLM atmospheric forcing based on SEAS5](seas5forcing).
+
 For a Python script that validates eCLM atmospheric forcing files
 specified in `datm_in` namelist and stream files see [Checking
 Atmospheric Forcing](checkingforcing).

docs/_toc.yml

@@ -10,6 +10,8 @@ parts:
     title: Overview atmospheric forcing
   - file: users_guide/era5-forcing
     title: ERA5 atmospheric forcing
+  - file: users_guide/seas5-forcing
+    title: SEAS5 atmospheric forcing
   - file: users_guide/icon-forcing
     title: ICON output atmospheric forcing
   - file: users_guide/other-forcing

docs/users_guide/era5-forcing.md

@@ -45,6 +45,7 @@ Source the provided environment file
 source jsc.2024_Intel.sh
 ```
 
+(era5forcing-download)=
 ### Download of ERA5 data
 
 `download_ERA5_input.py` contains a prepared retrieval for the `cdsapi` python module.

docs/users_guide/seas5-forcing.md

@@ -0,0 +1,121 @@
+(seas5forcing)=
+# eCLM atmospheric forcing based on SEAS5
+
+Start by sourcing the provided environment file
+
+```
+source jsc.2024_Intel.sh
+```
+
+Provide a Python virtual environment including all necessary modules,
+in particular `cdsapi` for downloading. It is important to load or
+activate the pyvenv after sourcing the environment file, since the
+environment file loads Python modules itself.
+
+First usage - creation of pyvenv:
+```
+	python -m venv python_cdsapi
+	source python_cdsapi/bin/activate
+	pip install cdsapi
+```
+
+Existing pyvenv - activating the pyvenv:
+```
+	source python_cdsapi/bin/activate
+```
+
+## Creation of forcing data from SEAS5
+
+Creation of SEAS5 forcing files is adapted from the creation of ERA5
+forcing files.
+
+The folder `mkforcing/` contains the scripts that assist the SEAS5
+retrieval.
+
+```
+	cd mkforcing
+```
+
+### Download of SEAS5 data
+
+`download_ERA5_input.py` contains a prepared retrieval for the cdsapi python module.
+
+More about cdsapi can be found in [Download of ERA5
+data](era5forcing-download).
+
+Usage: Three separate commands have to be executed, one for constant
+variables (orography), one for daily variables (e.g. total
+precipitation) and one for 6-hourly variables (e.g. temperature).
+
+For each type of output, a dedicated download directory is created.
+
+A main adaption from ERA5 download is the specification of a
+customized CDSAPI request using `--request`.
+
+```bash
+	python download_ERA5_input.py --year <year> --month <month> --dirout cdsapidwn_SEAS5_const --request ../custom_request_SEAS5_const.py
+	python download_ERA5_input.py --year <year> --month <month> --dirout cdsapidwn_SEAS5_24h   --request ../custom_request_SEAS5_24h.py
+	python download_ERA5_input.py --year <year> --month <month> --dirout cdsapidwn_SEAS5_06h   --request ../custom_request_SEAS5_06h.py	
+```
+
+**Note:** The wrapper script: `./download_ERA5_input_wrapper.sh` is
+currently NOT SUPPORTED for SEAS5 download.
+
+
+### Preparation of SEAS5 data: all variable to 06h
+
+Next, we want to have all variables available in 6-hourly interval
+
+- from constant: `z` has to be ported (same values as before)
+- from daily: `strd`, `ssrd` (thermal, solar, each accumulated) and
+  `tp` (total precipitation), these values would have to be
+  distributed. For `tp` the value would be divided by four and
+  assigned to the four corresponding 6-hour intervals. For the
+  radiations, it would be zero in the first/last interval ("night")
+  and half the value in the middle two intervals, then converted
+  to flux (W/m²) by dividing by the time interval.
+
+The script outputs radiation directly as flux variables (`flds`,
+`fsds`) in W/m².
+
+```bash
+	python seas5_daily_to_6hourly.py --const cdsapidwn_SEAS5_const/download_era5_2026_01.nc --daily cdsapidwn_SEAS5_24h/download_era5_2026_01.nc --hourly cdsapidwn_SEAS5_06h/download_era5_2026_01.nc --output cdsapidwn_SEAS5/download_era5_2026_01.nc --frequency 3 --include-hour-zero
+```
+
+### Preparation of SEAS5 data: correct input variables
+
+Steps for preparing SEAS5 data as eCLM input data
+
+1. Orography to elevation (adds a variable `elevation` to the netCDF
+   file)
+
+```bash
+	python orography_to_elevation.py cdsapidwn_SEAS5/download_era5_2026_01.nc
+```
+
+2. Mean sea level pressure to surface pressure
+
+```bash
+	python mslp_to_sp.py cdsapidwn_SEAS5/download_era5_2026_01.nc --elevation-var elevation
+```
+
+3. Humidity computed from dewpoint temperature and surface pressure
+
+```
+	python dewpoint_to_specific_humidity.py cdsapidwn_SEAS5/download_era5_2026_01.nc
+```
+
+4. Temperature and Specific Humidity converted from 2m to 10m
+
+```
+	python 2m_to_10m_conversion.py cdsapidwn_SEAS5/download_era5_2026_01.nc
+```
+
+### Preparation of SEAS5 data: Remapping, Data merging, CLM3.5
+
+
+Check inputs and replace according to your case.
+
+```
+	sh prepare_SEAS5_input.sh lwgtdis=true lgriddes=true wgtcaf=../wgtdis_era5caf_to_DE-RuS-$(date +%y%m%d).nc griddesfile=../griddes_DE-RuS_$(date +%y%m%d).txt  iyear=2026 imonth=01 author="Johannes KELLER" email="jo.keller@fz-juelich.de" tmpdir=tmpdir pathdata=../cdsapidwn_SEAS5
+```

mkforcing/custom_request_SEAS5_06h.py

@@ -0,0 +1,38 @@
+## Download for SEAS5 forecast variables
+# https://cds.climate.copernicus.eu/datasets/seasonal-original-single-levels?tab=download
+
+# 6-HOURLY VARIABLES
+
+# Forecast for 7 months
+
+# import cdsapi
+
+dataset = "seasonal-original-single-levels"
+request = {
+    "originating_centre": "ecmwf",
+    "system": "51",
+    "variable": [
+        # # constant
+        # "orography",  # used to convert mslp to sp
+        # # 24-hourly
+        # "surface_thermal_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        # "surface_solar_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        # "total_precipitation",
+        # 6-hourly
+        "mean_sea_level_pressure",  # convert to surface pressure, use elevation (hypsometric formula), surface geopotential height (orography)
+        "10m_u_component_of_wind",
+        "10m_v_component_of_wind",
+        "2m_temperature",
+        "2m_dewpoint_temperature",
+    ],
+    "year": ["2025"],
+    "month": ["09"],
+    "day": ["01"],
+    "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
+    "data_format": "netcdf",
+    "area": [50.870906+0.5, 6.4421445-0.5, 50.870906-0.5, 6.4421445+0.5]      # Selhausen
+    # "area": [74, -42, 20, 69] # Europe
+}
+
+# client = cdsapi.Client()
+# client.retrieve(dataset, request).download()

mkforcing/custom_request_SEAS5_24h.py

@@ -0,0 +1,38 @@
+## Download for SEAS5 forecast variables
+# https://cds.climate.copernicus.eu/datasets/seasonal-original-single-levels?tab=download
+
+# 24-HOURLY / DAILY VARIABLES
+
+# Forecast for 7 months
+
+# import cdsapi
+
+dataset = "seasonal-original-single-levels"
+request = {
+    "originating_centre": "ecmwf",
+    "system": "51",
+    "variable": [
+        # # constant
+        # "orography",  # used to convert mslp to sp
+        # 24-hourly
+        "surface_thermal_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        "surface_solar_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        "total_precipitation",
+        # # 6-hourly
+        # "mean_sea_level_pressure",  # convert to surface pressure, use elevation (hypsometric formula), surface geopotential height (orography)
+        # "10m_u_component_of_wind",
+        # "10m_v_component_of_wind",
+        # "2m_temperature",
+        # "2m_dewpoint_temperature",
+    ],
+    "year": ["2025"],
+    "month": ["09"],
+    "day": ["01"],
+    "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
+    "data_format": "netcdf",
+    "area": [50.870906+0.5, 6.4421445-0.5, 50.870906-0.5, 6.4421445+0.5]      # Selhausen
+    # "area": [74, -42, 20, 69] # Europe
+}
+
+# client = cdsapi.Client()
+# client.retrieve(dataset, request).download()

mkforcing/custom_request_SEAS5_const.py

@@ -0,0 +1,38 @@
+## Download for SEAS5 forecast variables
+# https://cds.climate.copernicus.eu/datasets/seasonal-original-single-levels?tab=download
+
+# CONSTANT VARIABLES
+
+# Forecast for 7 months
+
+# import cdsapi
+
+dataset = "seasonal-original-single-levels"
+request = {
+    "originating_centre": "ecmwf",
+    "system": "51",
+    "variable": [
+        # constant
+        "orography",  # used to convert mslp to sp
+        # # 24-hourly
+        # "surface_thermal_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        # "surface_solar_radiation_downwards",  # Unit conversion from accumulated value [J/m2] to mean rate [W/m2]
+        # "total_precipitation",
+        # # 6-hourly
+        # "mean_sea_level_pressure",  # convert to surface pressure, use elevation (hypsometric formula), surface geopotential height (orography)
+        # "10m_u_component_of_wind",
+        # "10m_v_component_of_wind",
+        # "2m_temperature",
+        # "2m_dewpoint_temperature",
+    ],
+    "year": ["2025"],
+    "month": ["09"],
+    "day": ["01"],
+    "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
+    "data_format": "netcdf",
+    "area": [50.870906+0.5, 6.4421445-0.5, 50.870906-0.5, 6.4421445+0.5]      # Selhausen
+    # "area": [74, -42, 20, 69] # Europe
+}
+
+# client = cdsapi.Client()
+# client.retrieve(dataset, request).download()

mkforcing/download_ERA5_input.py

@@ -139,7 +139,11 @@ def generate_datarequest(year, monthstr, days,
         # Adapt year, month and day to input values
         request["year"] = [str(year)]
         request["month"] = [monthstr]
-        request["day"] = days
+        if dataset == "seasonal-original-single-levels":
+            # First day of month specified for SEAS5
+            request["day"] = ["01"]
+        else:
+            request["day"] = days
 
     # Temporary filename w/o extension if not provided
     auto_detect_extension = target is None
@@ -159,7 +163,7 @@ def generate_datarequest(year, monthstr, days,
         extension = detect_file_type(target)
 
         # Rename to final target with correct extension
-        final_target = f'{target}{extension}'
+        final_target = f'download_era5_{year}_{monthstr}{extension}'
         os.rename(target, final_target)
         target = final_target
 
@@ -230,6 +234,8 @@ def generate_datarequest(year, monthstr, days,
     custom_request = None
     custom_dataset = args.dataset
     if args.request:
+        if not os.path.isfile(args.request):
+            raise FileNotFoundError(f"Custom request file not found: {args.request}")
         import importlib.util
         spec = importlib.util.spec_from_file_location("custom_request_module", args.request)
         custom_module = importlib.util.module_from_spec(spec)