TidalForcing

Contents

TidalForcing#

class roms_tools.TidalForcing(*, grid: Grid, source: dict[str, str | Path | dict[str, str | Path]], ntides: int = 10, model_reference_date: datetime = datetime.datetime(2000, 1, 1, 0, 0), use_dask: bool = False, bypass_validation: bool = False, prefill: str | None = None, prefill_kwargs: dict | None = None, regrid_method: str | None = None, extrap_method: str | None = None, extrap_kwargs: dict | None = None)#

Represents tidal forcing for ROMS.

Parameters:

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

  • source (Dict[str, Union[str, Path, Dict[str, Union[str, Path]]]]) –

    Dictionary specifying the source of the tidal data. Keys include:

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

    • ”path” (Union[str, Path, Dict[str, Union[str, Path]]]):

      • If a string or Path is provided, it represents a single file.

      • If “name” is “TPXO”, “path” can also be a dictionary with the following keys:

        • ”grid” (Union[str, Path]): Path to the TPXO grid file.

        • ”h” (Union[str, Path]): Path to the TPXO h-file.

        • ”u” (Union[str, Path]): Path to the TPXO u-file.

  • ntides (int, optional) – Number of constituents to consider. Maximum number is 15. Default is 10.

  • model_reference_date (datetime, optional) – The reference date for the ROMS simulation. Default is datetime(2000, 1, 1).

  • 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.

  • 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.

  • prefill (str or None, optional) –

    How to fill masked land cells in the source tidal data before regridding. (TPXO stores zeros over land; the source mask, not NaNs, marks those cells invalid.) The default (None) applies no source prefill: with xESMF installed, masked bilinear interpolation plus destination extrapolation (extrap_method) produces NaN-free tidal fields 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). Together with regrid_method="scipy" this reproduces the pre-v4 tidal output.

    • "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).

    • "creep_fill" – xESMF truncated Laplace-style diffusion source fill (tunable via prefill_kwargs; requires xESMF). Not available in current released xESMF – 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 target points whose source neighbors are all masked land or 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.

Examples

Using a TPXO dataset with separate grid, h, and u files:

>>> tidal_forcing = TidalForcing(
...     grid=grid,
...     source={
...         "name": "TPXO",
...         "path": {"grid": "tpxo_grid.nc", "h": "tpxo_h.nc", "u": "tpxo_u.nc"},
...     },
... )

Using a single file as a source:

>>> tidal_forcing = TidalForcing(
...     grid=grid,
...     source={"name": "TPXO", "path": "tpxo_merged.nc"},
... )

Methods

TidalForcing.from_yaml(filepath[, use_dask])

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

TidalForcing.plot(var_name[, ntides, save_path])

Plot the specified tidal forcing variable for a given tidal constituent.

TidalForcing.save(filepath[, format])

Save the tidal forcing information to a NetCDF file.

TidalForcing.to_yaml(filepath)

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

Attributes

TidalForcing.bypass_validation

Whether to skip validation checks in the processed data.

TidalForcing.extrap_kwargs

Method-specific options for extrap_method.

TidalForcing.extrap_method

xESMF destination extrapolation used on the default no-prefill path (None is treated as "inverse_dist") to fill target points whose source neighbors are all masked.

TidalForcing.model_reference_date

The reference date for the ROMS simulation.

TidalForcing.ntides

Number of constituents to consider.

TidalForcing.prefill

Source-side fill applied before lateral regridding.

TidalForcing.prefill_kwargs

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

TidalForcing.regrid_method

None/"auto" uses xESMF when installed (else scipy), "xesmf" forces xESMF, "scipy" forces scipy.

TidalForcing.use_dask

Whether to use dask for processing.

TidalForcing.grid

Object representing the grid information.

TidalForcing.source

Dictionary specifying the source of the tidal data.

TidalForcing.ds

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