roms_tools.InitialConditionsSource.merge

roms_tools.InitialConditionsSource.merge#

classmethod InitialConditionsSource.merge(physics: InitialConditionsSource, bgc: InitialConditionsSource | Sequence[InitialConditionsSource], filepath: str | Path | None = None, format: Literal['NETCDF4', 'NETCDF3_CLASSIC', 'NETCDF3_64BIT_OFFSET', 'NETCDF3_64BIT_DATA'] = 'NETCDF4', serialize_dask: bool | None = None) → Dataset | list[Path]#

Merge a physics object with one or more bgc-only objects into a single ROMS-ready initial-conditions dataset. Fully dask-lazy.

Note: ROMS’s inifile namelist parameter is a single scalar path, unlike boundary/surface forcing’s file list. Initial condition has to be assembled into ONE dataset before writing, rather than written out as separate files.

Parameters:

  • physics (InitialConditionsSource) – The type="physics" object that was passed as physics_forcing= to every object in bgc. Its global attrs/coords are authoritative in the merge.

  • bgc (InitialConditionsSource or sequence of InitialConditionsSource) – One or more bgc-only objects, each built with physics_forcing=physics. Only contribute their own (non-overlapping, by convention of use_vars) BGC variables.

  • filepath (str or Path, optional) – If given, the merged dataset is saved via save_datasets() and the saved path(s) are returned instead of the dataset itself.

  • format ({"NETCDF4", "NETCDF3_CLASSIC", "NETCDF3_64BIT_OFFSET", "NETCDF3_64BIT_DATA"}, optional) – NetCDF file format, passed through to save_datasets when filepath is given. Defaults to "NETCDF4".

  • serialize_dask (bool, optional) – See roms_tools.utils.save_datasets(); only relevant when filepath is given. Defaults to None, which resolves to False (the ordinary concurrent write). Pass True to force the serialized, one-task-at-a-time write – a manual low-memory / troubleshooting tool.

Returns:

xr.Dataset or list[Path] – The merged dataset (when filepath is omitted), or the saved file path(s) (when filepath is given).

Raises:

ValueError – If bgc is empty, or any object in it was not built with physics_forcing=physics.

Examples

>>> ic_physics = InitialConditionsSource(
...     grid=grid, ini_time=t, source={"name": "GLORYS", "path": "..."}
... )
>>> ic_esper = InitialConditionsSource(
...     grid=grid,
...     ini_time=t,
...     type="bgc",
...     physics_forcing=ic_physics,
...     source={"name": "ESPER", "path": "..."},
... )
>>> ic_unified = InitialConditionsSource(
...     grid=grid,
...     ini_time=t,
...     type="bgc",
...     physics_forcing=ic_physics,
...     source={"name": "UNIFIED", "path": "...", "climatology": True},
...     use_vars=["Fe", "CHL"],
... )
>>> BGCMarbl().process_bgc_fields([ic_esper, ic_unified])
>>> merged = InitialConditionsSource.merge(ic_physics, [ic_esper, ic_unified])