# ECMWF S2S reforecast inventory (Phase 0)

Grounded in **current** documentation checked 2026-09-23 (not from memory), plus
one live retrieval probe from the HPC node. Machine-readable companions:
`metadata/ecmwf_variable_inventory.csv`, `metadata/ecmwf_reforecast_inventory.csv`,
`metadata/ecmwf_minimal_retrieval_status.json`.

## Access status — BLOCKER for bulk retrieval

| Item | Finding | Evidence |
|---|---|---|
| Endpoint migration | S2S datasets **migrated to ECDS on 2026-05-27**; old `apps.ecmwf.int/datasets/data/s2s-*` pages are redirect notices | ECMWF dataset page |
| Configured client | `ecmwf-api-client 1.6.3`, `~/.ecmwfapirc` -> `https://api.ecmwf.int/v1` (legacy Web API) | node inspection |
| Live probe | Node reached the API and `who-am-i`, returned **`ecmwf.API error 1: Access token expired`** | `scripts/01_minimal_ecmwf_retrieval.py`, status JSON |
| cdsapi | `~/.cdsapirc` -> `https://cds.climate.copernicus.eu/api`, present but untested for S2S/ECDS | node inspection |
| GRIB reader | **`cfgrib` not installed**; eccodes 2.0.0 CLI (`grib_ls`), cdo 1.9.3, nco available | node inspection |

**Consequence:** the minimal retrieval could not complete this session. Network
and the client work; the credential is expired and the dataset now lives on ECDS.
This is a credential/access blocker (an authorized Phase 0 stop condition), not a
code problem. See gate decision items D1, D2.

## Confirmed archive structure (from documentation)

- Dataset `s2s`, `class=s2`, `origin=ecmf`, `model=glob`, `expver=prod`.
- Reforecasts (hindcasts): `stream=enfh`. Control forecast = `type=cf` (perturbed = `pf`).
- MARS `date` = **model version date** (real-time, produced twice weekly Mon/Thu);
  `hdate` = **hindcast date** (~20 past years per model version).
- Archive-native grid **1.5°** (ocean parameters **1.0°**), **GRIB2**, global regular lat-lon.
- Forecast length **34–65 days** (ECMWF ~46) — covers the required LT0–LT45.
- Catalogue years available: **2015–2026** (`apps.ecmwf.int/data-catalogues/s2s`).

The **1.5°** native grid matches the locked predictor definition (finer grids are
remapping, not added dynamical information).

## To confirm from live metadata before bulk retrieval (do NOT assume)

1. Valid `date`/`hdate` pairs whose hindcast years cover **2003–2022**, and the
   **actual number of initializations per year** (do not assume 104).
2. **Model-cycle/version consistency** across 2003–2022 — tabulate per
   initialization; if the span straddles cycles, document and propose alternatives.
3. Daily-max 2m-temperature aggregation window and its **UTC** definition (obs Tx
   is a local UTC+7 day maximum; LT0 may be a partial day).
4. Requested vs **actually retrieved** grid, level types, member type, valid dates
   — verified from the returned **GRIB header**.

## Candidate minimal retrieval (ready once credential/endpoint fixed)

See `scripts/01_minimal_ecmwf_retrieval.py`: one initialization, `type=cf`,
`levtype=sfc param=167.128` (2t), `grid=1.5/1.5`, `step=0/24`. Extend with one
pressure-level field (e.g. `t` @ 850) to verify `levtype=pl`. Verify dimensions,
grid, units, level type, member type and valid dates from the GRIB metadata
(`grib_ls`/`grib_dump`) before combining any samples.