BoundaryForcing

Contents

BoundaryForcing#

class roms_tools.BoundaryForcing(*, grid: Grid, start_time: datetime | None = None, end_time: datetime | None = None, boundaries: dict[str, bool] | None = None, source: dict[str, str | Path | list[str | Path] | bool], type: str = 'physics', prefill: str | None = None, prefill_kwargs: dict | None = None, regrid_method: str | None = None, extrap_method: str | None = None, extrap_kwargs: dict | None = None, apply_2d_horizontal_fill: bool | None = None, model_reference_date: datetime = datetime.datetime(2000, 1, 1, 0, 0), use_dask: bool = False, chunks: dict[str, int] | None = None, initial_slice_bounds: dict[str, tuple[int | float, int | float]] | None = None, bypass_validation: bool = False, bgc_interpolation_method: str = 'depth', physics_forcing: BoundaryForcing | None = None)#

Represents boundary forcing input data for ROMS.

Parameters:

  • grid (Grid) – Object representing the grid information.

  • start_time (datetime, optional) – The start time of the desired surface forcing data. This time is used to filter the dataset to include only records on or after this time, with a single record at or before this time. If no time filtering is desired, set it to None. Default is None.

  • end_time (datetime, optional) – The end time of the desired surface forcing data. This time is used to filter the dataset to include only records on or before this time, with a single record at or after this time. If no time filtering is desired, set it to None. Default is None.

  • boundaries (dict[str, bool], optional) – Specifies which grid boundaries (‘south’, ‘east’, ‘north’, ‘west’) are active and to be processed. if not provided, valid (non-land) boundaries are enabled automatically.

  • source (RawDataSource) –

    Dictionary specifying the source of the boundary forcing data. Keys include:

    • ”name” (str): Name of the data source (e.g., “GLORYS”).

    • ”path” (Union[str, Path, List[Union[str, Path]]]): The path to the raw data file(s). This can be:

      • A single string (with or without wildcards).

      • A single Path object.

      • A list of strings or Path objects.

      If omitted, the data will be streamed via the Copernicus Marine Toolkit. Note: streaming is currently not recommended due to performance limitations.

    • ”climatology” (bool): Indicates if the data is climatology data. Defaults to False.

  • type (str) –

    Specifies the type of forcing data. Options are:

    • ”physics”: for physical atmospheric forcing.

    • ”bgc”: for biogeochemical forcing.

  • prefill (str or None, optional) –

    How to fill NaN (land/void) cells in the source before regridding. The default (None) applies no source prefill: with xESMF installed, masked bilinear interpolation plus destination extrapolation (extrap_method) produces NaN-free boundaries directly; without xESMF, the source is automatically pre-filled with a cheap nearest-neighbor fill before scipy interpolation. Set prefill to fill the whole-domain source first (the regrid is then plain bilinear and extrap_method is ignored). Options:

    • "2d_lateral_fill" – legacy AMG Poisson fill (smoothest, slow; no xESMF required). This is the modern spelling of the deprecated apply_2d_horizontal_fill=True.

    • "inverse_dist" – xESMF inverse-distance-weighted source fill (tunable via prefill_kwargs; requires xESMF).

    • "nearest_s2d" – xESMF nearest-source fill (requires xESMF).

    • "nearest_neighbor" – cheap distance-transform fill (no xESMF; also the automatic fallback when xESMF is unavailable). Use for cross-platform reproducibility or when xESMF is unavailable and the AMG fill is too slow; not recommended when xESMF is available.

    • "creep_fill" – xESMF truncated Laplace-style diffusion source fill (tunable via prefill_kwargs; requires xESMF). Not available in current released xESMF – requires a newer/unreleased xESMF + ESMF; provided for use once a supporting xESMF is installed.

    Defaults to None.

  • prefill_kwargs (dict, optional) – Method-specific options for prefill: num_src_pnts / dist_exponent for "inverse_dist"; num_levels for "creep_fill". Ignored by the other methods. Defaults to None.

  • regrid_method (str or None, optional) –

    Horizontal regrid engine, chosen independently of prefill:

    • None / "auto" (default) – use xESMF if it is installed (lazy, weight-reused, faster on large grids), otherwise scipy.

    • "xesmf" – force the xESMF regridder (raises if xESMF is absent).

    • "scipy" – force scipy interp. Byte-reproducible with pre-v4 outputs; when prefill is None a nearest-neighbor source pre-fill is applied automatically so scipy cannot propagate NaNs.

    Note that inverse_dist / nearest_s2d prefills still require xESMF for the fill step regardless of regrid_method. Defaults to None.

  • extrap_method (str or None, optional) – xESMF destination extrapolation used on the default path (prefill is None) to fill boundary points whose source neighbors are all land/out of range, guaranteeing NaN-free output. "inverse_dist" (the effective default) gives an inverse-distance-weighted average of the nearest source points (smoothly varying); "nearest_s2d" uses the single nearest source point. Ignored when prefill is set. Defaults to None (treated as "inverse_dist").

  • extrap_kwargs (dict, optional) – Method-specific options for extrap_method: num_src_pnts / dist_exponent for "inverse_dist". Defaults to None.

  • apply_2d_horizontal_fill (bool, optional) – Deprecated – use prefill instead. True maps to prefill="2d_lateral_fill" and False to prefill=None; setting it emits a DeprecationWarning. Cannot be combined with an explicit prefill. Defaults to None (unset).

  • model_reference_date (datetime, optional) – Reference date for the model. Default is January 1, 2000.

  • use_dask (bool, optional) – Indicates whether to use dask for processing. If True, data is processed with dask; if False, data is processed eagerly. Defaults to False.

  • chunks (dict[str, int], optional) – Dictionary specifying chunk sizes for dask dimensions, e.g., {"latitude": 100, "longitude": 100}. If provided, these chunks override the default chunking scheme when use_dask=True. Defaults to None (default chunking is used).

  • initial_slice_bounds (dict, optional) –

    Optional horizontal subset to apply when loading with dask. Only Geographic bounds are supported:

    {"latitude": (min_lat, max_lat), "longitude": (min_lon, max_lon)} in degrees. The bounds are applied to the dataset before reading the underlying datasets to reduce memory usage.

  • bypass_validation (bool, optional) – Indicates whether to skip validation checks in the processed data. When set to True, the validation process that ensures no NaN values exist at wet points in the processed dataset is bypassed. Defaults to False.

  • bgc_interpolation_method (str, optional) –

    Vertical interpolation method for BGC tracers (only used when type='bgc'). One of:

    • "depth" (default): linear interpolation in depth.

    • "density": linear interpolation in potential-density (isopycnal) space, preserving water-mass properties. Density is computed via TEOS-10 sigma-0 from the BGC source’s own T/S (source coordinate) and the physics T/S supplied by physics_forcing (target coordinate).

    • "density_mld": the mixed layer depth (MLD) is found in the source and target density fields; the source mixed layer is scaled so its MLD matches the target’s, and below the MLD the tracer is interpolated 1:1 in depth. This keeps the mixed layers aligned while preserving the absolute depth of sub-mixed-layer features, and avoids the surface degeneracy of pure density space.

    "density" and "density_mld" require physics_forcing and a BGC source carrying temperature/salinity; otherwise interpolation falls back to depth space. Interpolation uses xgcm.Grid.transform with the linear method inside the source range and edge-value extrapolation outside (mask_edges=False).

  • physics_forcing (BoundaryForcing, optional) – A physics BoundaryForcing object (type='physics') whose T/S fields supply the target density coordinate for BGC tracer interpolation. When None and a density method is requested, falls back to depth-based interpolation.

Examples

>>> boundary_forcing = BoundaryForcing(
...     grid=grid,
...     boundaries={"south": True, "east": True, "north": False, "west": True},
...     start_time=datetime(2022, 1, 1),
...     end_time=datetime(2022, 1, 2),
...     source={"name": "GLORYS", "path": "glorys_data.nc"},
...     type="physics",
... )

Methods

BoundaryForcing.from_yaml(filepath[, use_dask])

Create an instance of the BoundaryForcing class from a YAML file.

BoundaryForcing.plot(var_name[, time, ...])

Plot the boundary forcing field for a given time-slice.

BoundaryForcing.save(filepath[, group, format])

Save the boundary forcing fields to one or more NetCDF files.

BoundaryForcing.to_yaml(filepath)

Export the parameters of the class to a YAML file, including the version of roms-tools.

Attributes

BoundaryForcing.apply_2d_horizontal_fill

Deprecated alias for prefill (sentinel None = unset).

BoundaryForcing.bgc_interpolation_method

"depth", "density", or "density_mld".

BoundaryForcing.boundaries

Dictionary specifying which boundaries are forced (south, east, north, west).

BoundaryForcing.bypass_validation

Whether to skip validation checks in the processed data.

BoundaryForcing.chunks

Optional Dask chunk sizes for lat/lon boundary-forcing sources.

BoundaryForcing.end_time

The end time of the desired surface forcing data.

BoundaryForcing.extrap_kwargs

Method-specific options for extrap_method (e.g. num_src_pnts/dist_exponent).

BoundaryForcing.extrap_method

xESMF destination extrapolation for the default path (prefill is None).

BoundaryForcing.initial_slice_bounds

Optional initial bounding slice when loading source data (Dask); see dataset classes.

BoundaryForcing.model_reference_date

Reference date for the model.

BoundaryForcing.physics_forcing

Physics BoundaryForcing object supplying T/S for density-based BGC interpolation.

BoundaryForcing.prefill

Source-side fill applied before regridding (None = no prefill, the default NaN-aware masked-bilinear path).

BoundaryForcing.prefill_kwargs

Method-specific options for prefill (e.g. num_src_pnts/dist_exponent).

BoundaryForcing.regrid_method

Horizontal regrid engine, independent of prefill.

BoundaryForcing.start_time

The start time of the desired surface forcing data.

BoundaryForcing.type

Specifies the type of forcing data ("physics", "bgc").

BoundaryForcing.use_dask

Whether to use dask for processing.

BoundaryForcing.grid

Object representing the grid information.

BoundaryForcing.source

Dictionary specifying the source of the boundary forcing data.

BoundaryForcing.ds

An xarray Dataset containing post-processed variables ready for input into ROMS.

BoundaryForcing.adjust_depth_for_sea_surface_height

Whether to account for sea surface height when computing depth coordinates.

BoundaryForcing.ds_depth_coords

An xarray Dataset containing the depth coordinates.
Contents