InitialConditions

InitialConditions#

class roms_tools.InitialConditions(*, grid: Grid, ini_time: datetime, source: dict[str, str | Path | list[str | Path] | bool], bgc_source: dict[str, str | Path | list[str | Path] | bool] | None = None, model_reference_date: datetime = datetime.datetime(2000, 1, 1, 0, 0), allow_flex_time: bool = False, 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')#

Represents initial conditions for ROMS, including physical and biogeochemical data.

Parameters:

  • grid (Grid) – Object representing the grid information used for the model.

  • ini_time (datetime) – The date and time at which the initial conditions are set. If no exact match is found, the closest time entry to ini_time within the time range [ini_time, ini_time + 24 hours] is selected.

  • source (RawDataSource) –

    Dictionary specifying the source of the physical initial condition 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.

  • bgc_source (RawDataSource, optional) –

    Dictionary specifying the source of the biogeochemical (BGC) initial condition data. Keys include:

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

    • ”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 containing multiple files.

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

  • model_reference_date (datetime, optional) – The reference date for the model. Defaults to 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. Dimensions must match the underlying dataset, e.g. for ROMS restart files, the dimensions must be “eta_rho”, etc. 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. Not used for ROMS restart or other datasets sources.

  • allow_flex_time (bool, optional) –

    Controls how strictly ini_time is handled:

    • If False (default): requires an exact match to ini_time. Raises a ValueError if no match exists.

    • If True: allows a +24h search window after ini_time and selects the closest available time entry within that window. Raises a ValueError if none are found.

  • 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. One of:

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

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

    • "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" only apply when bgc_source is provided, the physics source is a lat/lon dataset (not a ROMS restart), and the BGC source carries temperature/salinity (e.g. the unified dataset’s temp_WOA/ salt_WOA); otherwise interpolation falls back to depth space and notes in the log. Interpolation uses xgcm.Grid.transform with the linear method inside the source range and edge-value extrapolation outside (mask_edges=False).

Examples

>>> initial_conditions = InitialConditions(
...     grid=grid,
...     ini_time=datetime(2022, 1, 1),
...     source={"name": "GLORYS", "path": "physics_data.nc"},
...     bgc_source={
...         "name": "CESM_REGRIDDED",
...         "path": "bgc_data.nc",
...         "climatology": False,
...     },
... )

>>> initial_conditions = InitialConditions(
...     grid=grid,
...     ini_time=datetime(2022, 1, 1),
...     source={"name": "ROMS", "grid": parent_grid, "path": "restart.nc"},
...     bgc_source={
...         "name": "ROMS",
...         "grid": parent_grid,
...         "path": "restart.nc",
...     },
... )

Methods

InitialConditions.from_yaml(filepath[, use_dask])

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

InitialConditions.plot(var_name[, s, eta, ...])

Plot the initial conditions field for a given eta-, xi-, or s_rho- slice.

InitialConditions.save(filepath[, format])

Save the initial conditions information to one NetCDF file.

InitialConditions.to_yaml(filepath)

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

Attributes

InitialConditions.allow_flex_time

Whether to handle ini_time flexibly.

InitialConditions.bgc_interpolation_method

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

InitialConditions.bgc_source

Dictionary specifying the source of the biogeochemical (BGC) initial condition data.

InitialConditions.bypass_validation

Whether to skip validation checks in the processed data.

InitialConditions.chunks

Optional Dask chunk sizes for lat/lon and ROMS-restart initial-condition sources.

InitialConditions.initial_slice_bounds

Optional initial bounding slice when loading lat/lon forcing data with Dask.

InitialConditions.model_reference_date

The reference date for the model.

InitialConditions.use_dask

Whether to use dask for processing.

InitialConditions.grid

Object representing the grid information.

InitialConditions.ini_time

The date and time at which the initial conditions are set.

InitialConditions.source

Dictionary specifying the source of the physical initial condition data.

InitialConditions.ds

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

InitialConditions.adjust_depth_for_sea_surface_height

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

InitialConditions.ds_depth_coords

An xarray Dataset containing the depth coordinates.