pyremo.preproc.remap

remap(ds, domain_info, vc, surflib, initial=False, static=False)[source]

Remap CF-compliant GCM/analysis data to a REMO target domain.

This performs the REMO preprocessing chain analogous to the legacy FORTRAN “intorg” tool: 1) horizontal interpolation of 3‑D and 2‑D fields to the rotated target grid, 2) first pressure correction using a PBL estimate, 3) vertical interpolation from input hybrid coefficients (akgm, bkgm)

to the requested vertical coordinate vc (ak, bk),

  1. second pressure correction with hydrostatic consistency,

  2. wind rotation and divergence correction,

  3. surface field remapping (SST, sea ice) and optional initial fields.

Parameters:

  • ds (xarray.Dataset) – CF-compliant dataset holding at least ta (air temperature), ua/va (winds), hus (specific humidity), ps (surface pressure), tos (SST), orog (orography), sftlf (land fraction). Optionally clw for cloud liquid water content. Must also contain hybrid coordinate coefficients akgm and bkgm (full levels) needed for vertical interpolation.

  • domain_info (dict) – Description of the target rotated domain with keys such as ll_lon, ll_lat, dlon, dlat, nlon, nlat, pollon, pollat. Optional metadata like CORDEX_domain or domain_id is preserved.

  • vc (pandas.DataFrame) – Vertical coordinate definition with columns ak and bk (half levels) and akh/bkh (mid levels); typically produced via pyremo tables.

  • surflib (xarray.Dataset) – Surface library on the target grid providing at least BLA (land/sea mask) and FIB (surface geopotential/orography divided by gravity). When initial or static is True, additional static fields (e.g. WSMX) are merged if available.

  • initial (bool, default: False) – If True, add dynamic/static fields required for model initial conditions (soil moisture/temperature, glacier mask, etc.). Implies static=True.

  • static (bool, default: False) – If True, merge static fields from surflib (e.g. land/sea mask, orography) into the returned dataset.

Returns:

xarray.Dataset – Forcing dataset on the target domain with rotated coordinates (rlon, rlat) and vertical dimension lev. Includes at least T, U, V, PS, humidity diagnostics (QD, QW, QDBL when available), TSW, TSI, optional SEAICE, and vertical coordinate coefficients (hyai, hybi, hyam, hybm). Global attributes and domain identifiers are propagated.

Raises:

  • KeyError – If required variables (e.g. ta, ua, va, hus, ps, tos, orog, sftlf) or hybrid coefficients (akgm, bkgm) are missing from ds.

  • ValueError – If domain_info is inconsistent or the vertical coordinate vc lacks the expected ak/bk columns.

Notes

After interpolation, a nearest-neighbour selection aligns the result to the exact target grid points from surflib to ensure coordinate identity. Time and calendar metadata are preserved when present.