ERA5_pl

{
  "kind": "grid",
  "source": {
    "url_template": "https://data.earthsci.dev/era5/era5_pl_{date:%Y}_{date:%m}.nc"
  },
  "temporal": {
    "start": "1940-01-01T00:00:00Z",
    "end": "2025-12-31T23:59:59Z",
    "file_period": "P1M",
    "frequency": "PT1H",
    "records_per_file": 744,
    "time_variable": "valid_time",
    "records_per_sample": 2
  },
  "reference": {
    "citation": "Hersbach, H. et al. (2020). The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society, 146(730), 1999–2049.",
    "url": "https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5",
    "doi": "10.1002/qj.3803"
  },
  "metadata": {
    "tags": [
      "era5",
      "ecmwf",
      "meteorology",
      "reanalysis",
      "global",
      "pressure-level",
      "hourly",
      "0.25deg"
    ],
    "earthscidata_source": "src/era5.jl::ERA5FileSet (pressure-level variables)",
    "native_resolution_deg": {
      "longitude": 0.25,
      "latitude": 0.25
    },
    "native_extent": {
      "longitude": [
        -180.0,
        180.0
      ],
      "latitude": [
        -90.0,
        90.0
      ],
      "pressure_level_hpa": [
        1.0,
        1000.0
      ]
    },
    "native_staggering": "All variables are cell-centered (longitude/latitude/pressure_level all 'center') — ERA5 is stored on a regular non-staggered grid. The model regrids the horizontal wind components u, v with B-spline interpolation and all centered scalars (including the vertical-velocity field w) conservatively (RFC §5.2); see era5.esm `regrid`.",
    "pressure_levels_hpa": [
      1000,
      975,
      950,
      925,
      900,
      875,
      850,
      825,
      800,
      775,
      750,
      700,
      650,
      600,
      550,
      500,
      450,
      400,
      350,
      300,
      250,
      225,
      200,
      175,
      150,
      125,
      100,
      70,
      50,
      30,
      20,
      10,
      7,
      5,
      3,
      2,
      1
    ],
    "netcdf_dimensions": [
      "longitude",
      "latitude",
      "pressure_level",
      "valid_time"
    ],
    "file_naming": "era5_pl_{YYYY}_{MM:02d}.nc (monthly, one file per calendar month, all 16 pressure-level variables plus pressure_level dimension)",
    "level_indexing_note": "This loader's pressure_level dimension uses hPa values (1–1000 hPa) matching the NetCDF 'pressure_level' dimension. The regridding model's lev parameter uses 1-based integer indexing (1=1000 hPa, 37=1 hPa) matching the upstream ERA5FileSet convention; the runtime converts lev → hPa using the pressure_levels_hpa table before querying this loader.",
    "access_note": "ERA5 data is available from the Copernicus Climate Data Store (CDS) at https://cds.climate.copernicus.eu/. The url_template above uses a placeholder earthsci.dev mirror; in production, set EARTHSCIDATADIR to a local cache directory populated via the CDS API or the EarthSciData.jl ERA5FileSet download utilities.",
    "cds": {
      "dataset": "reanalysis-era5-pressure-levels",
      "format": "netcdf",
      "pressure_levels": [
        1000
      ],
      "description": "Opt-in CDS request descriptor (gap G7). When the loader seam is routed through the EarthSciIO provider adapter (earthsci_ast.data_loaders.esio_provider.esio_provider_factory), this block makes the loader resolve to the real Copernicus CDS API instead of the placeholder earthsci.dev mirror: the adapter builds a per-month `cds://reanalysis-era5-pressure-levels?<request>` URL (earthsciio.era5.era5_cds_url) whose `area` is the simulation domain's WGS84 bounding box, whose `variable` list maps this loader's NetCDF short names (t, u, v, r, …) to the CDS long names, and whose `pressure_level` set is `pressure_levels` below (default: all 37 ERA5 levels). EarthSciIO's registered `cds` transport then submits/polls/downloads the NetCDF asset, authenticating with the PRIVATE-TOKEN from ~/.cdsapirc or $CDSAPI_KEY. The submit→poll→download handshake cannot be expressed as the default ESS opener/fetcher's single HTTP GET, which is why the CDS path lives in the esio adapter rather than the default provider.",
      "pressure_levels_note": "The `pressure_levels` key (a list of hPa integers) trims the CDS request to the levels actually needed; omit it to request the full 37-level set (a large download that exceeds the CDS per-request cost limit when combined with a full month × 24 h × 16 variables). It is set to [1000] here because the consuming wildfire model reduces ERA5 to the ground surface (camp_fire's ground_surface interface, lev=min = 1000 hPa), so only the near-surface level is needed; raise it to the full set for a model that uses the vertical column."
    },
    "temporal_note": "ERA5 monthly files are released with a ~2-month lag. The temporal.end above is approximate; update as new months are released. ERA5 Back Extension covers 1940–1978 with slightly reduced quality; the main ERA5 record begins January 1979.",
    "merged_from": "components/earthsci_data/era5_loader.esm",
    "merge_note": "Merged from the standalone pure-I/O file components/earthsci_data/era5_loader.esm, which is deleted by the same commit. The 0.x `X.esm` + `X_loader.esm` split existed only because a loader was a COMPONENT and a {\"ref\"} target had to contain exactly one component. At esm 1.0.0 a data source is NOT a component, not a coupling endpoint and not a scoped-name path root, and `data_sources` no longer counts toward a file's top-level system count — so one file may hold a model AND the data_sources that model consumes and still be mountable by {\"ref\"}. This registry entry is byte-identical to the one the deleted file declared (it was already mirrored here so this document would validate), and the deleted file's own top-level metadata — name, description, tags, created, authors, references — is preserved verbatim in `merged_file_metadata` so no provenance, citation or migration note is lost.",
    "merged_file_metadata": {
      "name": "ERA5_pl_loader",
      "description": "Pure-I/O data loader for ERA5 ECMWF Reanalysis 5th Generation pressure-level fields. Provides hourly pressure-level atmospheric variables (wind, temperature, humidity, geopotential, cloud, ozone, and derived fields) on the native 0.25°×0.25° global longitude/latitude grid, 1940–present, sourced from monthly NetCDF files.\n\nThis is the loader half of the era5 loader+regridding-model split (RFC pure-io-data-loaders §4.1/§7; bead esm-3nc.1). It is PURE I/O: it declares its source (url_template), the file variables it reads (with units), and its temporal cadence. It performs NO reprojection and NO regridding — those are per-variable concerns of the regridding model (components/earthsci_data/era5.esm), which references this file as a subsystem via {\"ref\": \"./era5_loader.esm\"}.\n\nBecause a `temporal` block is present, this loader seeds DISCRETE cadence for its variables (ess-v9a.5): the runtime refreshes the file buffers hourly. (A consumer that needs a single time slice as a static field — e.g. the wildlandfire.esm surface-met coupling — binds one resolved hour as a CONST provider.)\n\nMigration esm 0.7.0 -> 0.8.0 (this file): v0.8.0 is a clean break that REMOVED the DataLoader `grid`/`mesh` descriptor (esm-spec §8.4; esm-schema.json DataLoader is now additionalProperties:false over {kind, source, temporal, determinism, variables, reference, metadata} with no `grid` key). Accordingly the former GDD `grid` block (family/crs/dimensions/extents + the n_pressure_level parameter) has been REMOVED. Grid geometry is now ordinary data: the native 0.25°×0.25° lon/lat lattice and the 37 pressure levels are documented in metadata below and materialized downstream by `aggregate` FAQs / coupling expressions (esm-spec §8.6). Reprojection (longlat identity) and conservative/bspline regridding onto a consuming grid are performed at the coupling edge via the reprojection/ and regridding/ template libraries in earthscidiscretizations, NOT here.\n\nMigrated from EarthSciData.jl@830435a065f27e99f10bba91107ca1730322cc6b:src/era5.jl:385 (ERA5FileSet, pressure-level variables). Split out of the pre-migration components/earthsci_data/era5.esm (esm-te2e); grid block removed in the 0.7.0 -> 0.8.0 migration.",
      "tags": [
        "earthsci_data",
        "meteorology",
        "reanalysis",
        "era5",
        "ecmwf",
        "pressure_levels",
        "global",
        "data_loader",
        "pure-io",
        "longlat"
      ],
      "created": "2026-06-25T00:00:00Z",
      "authors": [
        "ECMWF",
        "EarthSciModels migration (esm-3nc.1)"
      ],
      "references": [
        {
          "citation": "Hersbach, H., Bell, B., Berrisford, P., Hirahara, S., Horanyi, A., Munoz-Sabater, J., Nicolas, J., Peubey, C., Radu, R., Schepers, D., Simmons, A., Soci, C., Abdalla, S., Abellan, X., Balsamo, G., Bechtold, P., Biavati, G., Bidlot, J., Bonavita, M., De Chiara, G., Dahlgren, P., Dee, D., Diamantakis, M., Dragani, R., Flemming, J., Forbes, R., Fuentes, M., Geer, A., Haimberger, L., Healy, S., Hogan, R. J., Holm, E., Janiskova, M., Keeley, S., Laloyaux, P., Lopez, P., Lupu, C., Radnoti, G., de Rosnay, P., Rozum, I., Vamborg, F., Villaume, S., and Thepaut, J.-N. (2020). The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society, 146(730), 1999–2049.",
          "url": "https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5",
          "doi": "10.1002/qj.3803"
        },
        {
          "citation": "Source: EarthSciData.jl@830435a065f27e99f10bba91107ca1730322cc6b:src/era5.jl:385 (ERA5 constructor). ERA5FileSet, ERA5_PRESSURE_LEVELS_HPA."
        }
      ]
    }
  }
}