SurfaceForcing

SurfaceForcing#

class roms_tools.SurfaceForcing(*, grid: Grid, start_time: datetime | None = None, end_time: datetime | None = None, source: dict[str, str | Path | list[str | Path] | bool], type: str = 'physics', correct_radiation: bool = True, wind_dropoff: bool = False, restoring_forces: list[str] | None = None, coarse_grid_mode: str = 'auto', 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, regrid_method: str = 'auto', prefill: str | None = None, prefill_kwargs: dict | None = None, extrap_method: str | None = None, extrap_kwargs: dict | None = None)#

Represents surface 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.
source (RawDataSource) –
Dictionary specifying the source of the surface forcing data. Keys include:
- ”name” (str): Name of the data source. Currently supported: “ERA5”
- ”path” (optional; Union[str, Path, List[Union[str, Path]]]): Path(s) to the raw data file(s). Accepted formats:
  - A single string (supports wildcards),
  - A single Path object,
  - A list of strings or Path objects.
  If omitted or set to the ARCO URL, the data will be streamed from the cloud.
- ”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.
- ”restoring”: for restoring forces.
correct_radiation (bool) – Whether to correct shortwave and longwave radiation. Default is True.
wind_dropoff (bool, optional) – Whether to apply a coastal wind speed reduction to mimic nearshore wind drop-off. This applies an exponential decay to wind magnitude near the coast, based on a 12.5 km e-folding scale, with up to 40% reduction at the coastline. Default is False.
restoring_forces (list[str], optional) – Specifies which variables to apply restoring forces to. Sea surface salinity, DIC and alkalinity are supported: `['sss', 'sDIC', 'sALK']`.
coarse_grid_mode (str, optional) –
Specifies whether to interpolate onto grid coarsened by a factor of two. Options are:
- ”auto” (default): Automatically decide based on the comparison of source and target spatial resolutions.
- ”always”: Always interpolate onto the coarse grid.
- ”never”: Never use the coarse grid; interpolate onto the fine grid instead.
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.

Examples

>>> surface_forcing = SurfaceForcing(
...     grid=grid,
...     start_time=datetime(2000, 1, 1),
...     end_time=datetime(2000, 1, 2),
...     source={"name": "ERA5", "path": "era5_data.nc"},
...     type="physics",
...     correct_radiation=True,
... )

Methods

`SurfaceForcing.from_yaml`(filepath[, use_dask])	Create an instance of the SurfaceForcing class from a YAML file.
`SurfaceForcing.plot`(var_name[, time, save_path])	Plot the specified surface forcing field for a given time slice.
`SurfaceForcing.save`(filepath[, group, format])	Save the surface forcing fields to one or more NetCDF files.
`SurfaceForcing.to_yaml`(filepath)	Export the parameters of the class to a YAML file, including the version of roms-tools.

Attributes

`SurfaceForcing.bypass_validation`	Whether to skip validation checks in the processed data.
`SurfaceForcing.chunks`	Dask chunk sizes for lat/lon surface-forcing sources; default None.
`SurfaceForcing.coarse_grid_mode`	Specifies whether to interpolate onto grid coarsened by a factor of two.
`SurfaceForcing.correct_radiation`	Whether to correct shortwave and longwave radiation.
`SurfaceForcing.end_time`	The end time of the desired surface forcing data.
`SurfaceForcing.extrap_kwargs`	Method-specific keyword arguments for `extrap_method`.
`SurfaceForcing.extrap_method`	xESMF destination extrapolation on the default no-prefill path; defaults to `"inverse_dist"`.
`SurfaceForcing.initial_slice_bounds`	Optional initial bounding slice when loading source data (Dask); see dataset classes.
`SurfaceForcing.model_reference_date`	Reference date for the model.
`SurfaceForcing.prefill`	Source-side fill applied before regridding.
`SurfaceForcing.prefill_kwargs`	Method-specific keyword arguments for `prefill` (e.g. `num_src_pnts` / `dist_exponent` for `"inverse_dist"`).
`SurfaceForcing.regrid_method`	`"auto"` (xESMF if installed, else scipy), `"xesmf"`, or `"scipy"`.
`SurfaceForcing.restoring_forces`	The variables to create the restoring forces for.
`SurfaceForcing.start_time`	The start time of the desired surface forcing data.
`SurfaceForcing.type`	Specifies the type of forcing data ("physics", "bgc", "restoring").
`SurfaceForcing.use_dask`	Whether to use dask for processing.
`SurfaceForcing.wind_dropoff`	Whether to apply a coastal wind speed reduction to mimic nearshore wind drop- off.
`SurfaceForcing.grid`	Object representing the grid information.
`SurfaceForcing.source`	Dictionary specifying the source of the surface forcing data.
`SurfaceForcing.ds`	An xarray Dataset containing post-processed variables ready for input into ROMS.
`SurfaceForcing.use_coarse_grid`	Whether data is interpolated onto grid coarsened by factor 2.

SurfaceForcing

Contents

SurfaceForcing#