roms-tools 3.3.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

roms_tools/setup/utils.py

@@ -3,13 +3,13 @@ import logging
 import time
 import typing
 from collections.abc import Sequence
+from copy import deepcopy
 from dataclasses import asdict, fields, is_dataclass
-from datetime import datetime, timedelta
+from datetime import datetime
 from enum import StrEnum
 from pathlib import Path
 from typing import Any, Literal, TypeAlias
 
-import cftime
 import numba as nb
 import numpy as np
 import pandas as pd
@@ -18,7 +18,6 @@ import yaml
 from pydantic import BaseModel
 
 from roms_tools.constants import R_EARTH
-from roms_tools.utils import interpolate_from_rho_to_u, interpolate_from_rho_to_v
 
 if typing.TYPE_CHECKING:
     from roms_tools.setup.grid import Grid
@@ -128,32 +127,6 @@ def substitute_nans_by_fillvalue(field, fill_value=0.0) -> xr.DataArray:
     return field.fillna(fill_value)
 
 
-def one_dim_fill(da: xr.DataArray, dim: str, direction="forward") -> xr.DataArray:
-    """Fill NaN values in a DataArray along a specified dimension.
-
-    Parameters
-    ----------
-    da : xr.DataArray
-        The input DataArray with NaN values to be filled, which must include the specified dimension.
-    dim : str
-        The name of the dimension along which to fill NaN values (e.g., 'depth' or 'time').
-    direction : str, optional
-        The filling direction; either "forward" to propagate non-NaN values downward or "backward" to propagate them upward.
-        Defaults to "forward".
-
-    Returns
-    -------
-    xr.DataArray
-        A new DataArray with NaN values filled in the specified direction, leaving the original data unchanged.
-    """
-    if dim in da.dims:
-        if direction == "forward":
-            return da.ffill(dim=dim)
-        elif direction == "backward":
-            return da.bfill(dim=dim)
-    return da
-
-
 def assign_dates_to_climatology(ds: xr.Dataset, time_dim: str) -> xr.Dataset:
     """Assigns climatology dates to the dataset's time dimension.
 
@@ -182,240 +155,6 @@ def assign_dates_to_climatology(ds: xr.Dataset, time_dim: str) -> xr.Dataset:
     return ds
 
 
-def interpolate_cyclic_time(
-    data_array: xr.DataArray,
-    time_dim_name: str,
-    day_of_year: int | float | np.ndarray | xr.DataArray | Sequence[int | float],
-) -> xr.DataArray:
-    """Interpolates a DataArray cyclically across the start and end of the year.
-
-    This function extends the data cyclically by appending the last time step
-    (shifted back by one year) at the beginning and the first time step
-    (shifted forward by one year) at the end. It then performs linear interpolation
-    to match the specified `day_of_year` values.
-
-    Parameters
-    ----------
-    data_array : xr.DataArray
-        The input data array containing a time-like dimension.
-    time_dim_name : str
-        The name of the time dimension in the dataset.
-    day_of_year : Union[int, float, np.ndarray, xr.DataArray, Sequence[Union[int, float]]]
-        The target day(s) of the year for interpolation. This can be:
-        - A single integer or float representing the day of the year.
-        - A NumPy array or xarray DataArray containing multiple days.
-        - A list or tuple of integers or floats for multiple target days.
-
-    Returns
-    -------
-    xr.DataArray
-        The interpolated DataArray, ensuring cyclic continuity across year boundaries.
-
-    Notes
-    -----
-    - This function is useful for interpolating climatological data, where the time axis
-      represents a repeating annual cycle.
-    - The `day_of_year` values should be within the range [1, 365] or [1, 366] for leap years.
-    """
-    # Concatenate across the beginning and end of the year
-    time_concat = xr.concat(
-        [
-            data_array[time_dim_name][-1] - 365.25,  # Shift last time backward
-            data_array[time_dim_name],
-            data_array[time_dim_name][0] + 365.25,  # Shift first time forward
-        ],
-        dim=time_dim_name,
-    )
-
-    data_array_concat = xr.concat(
-        [
-            data_array.isel(
-                **{time_dim_name: -1}
-            ),  # Append last value at the beginning
-            data_array,
-            data_array.isel(**{time_dim_name: 0}),  # Append first value at the end
-        ],
-        dim=time_dim_name,
-    )
-    data_array_concat[time_dim_name] = time_concat
-
-    # Interpolate to specified times
-    data_array_interpolated = data_array_concat.interp(
-        **{time_dim_name: day_of_year}, method="linear"
-    )
-
-    return data_array_interpolated
-
-
-def interpolate_from_climatology(
-    field: xr.DataArray | xr.Dataset,
-    time_dim_name: str,
-    time: xr.DataArray | pd.DatetimeIndex,
-) -> xr.DataArray | xr.Dataset:
-    """Interpolates a climatological field to specified time points.
-
-    This function interpolates the input `field` based on `day_of_year` values
-    extracted from the provided `time` points. If `field` is an `xarray.Dataset`,
-    interpolation is applied to all its data variables individually.
-
-    Parameters
-    ----------
-    field : xarray.DataArray or xarray.Dataset
-        The input field to be interpolated.
-        - If `field` is an `xarray.DataArray`, it must have a time dimension identified by `time_dim_name`.
-        - If `field` is an `xarray.Dataset`, all variables within the dataset are interpolated along `time_dim_name`.
-        The time dimension is assumed to represent `day_of_year` for climatological purposes.
-    time_dim_name : str
-        The name of the time dimension in `field`. This dimension is used for interpolation.
-    time : xarray.DataArray or pandas.DatetimeIndex
-        The target time points for interpolation. These are internally converted to `day_of_year`
-        before performing interpolation.
-
-    Returns
-    -------
-    xarray.DataArray or xarray.Dataset
-        The interpolated field, maintaining the same type (`xarray.DataArray` or `xarray.Dataset`)
-        but aligned to the specified `time` values.
-
-    Notes
-    -----
-    - This function assumes that `field` represents a climatological dataset, where time is expressed as `day_of_year` (1-365).
-    - The `time` input is automatically converted to `day_of_year`, so manual conversion is not required before calling this function.
-    """
-
-    def interpolate_single_field(data_array: xr.DataArray) -> xr.DataArray:
-        if isinstance(time, xr.DataArray):
-            # Extract day of year from xarray.DataArray
-            day_of_year = time.dt.dayofyear
-        else:
-            if np.size(time) == 1:
-                # Convert single datetime64 object to pandas.Timestamp
-                date = pd.Timestamp(time)
-                day_of_year = (
-                    date.dayofyear
-                    + (date.hour / 24)
-                    + (date.minute / 1440)
-                    + (date.second / 86400)
-                )
-            else:
-                # Convert each datetime64 object in the array to pandas.Timestamp and compute fractional day of year
-                day_of_year = np.array(
-                    [
-                        pd.Timestamp(t).dayofyear
-                        + (pd.Timestamp(t).hour / 24)
-                        + (pd.Timestamp(t).minute / 1440)
-                        + (pd.Timestamp(t).second / 86400)
-                        for t in time
-                    ]
-                )
-
-        data_array_interpolated = interpolate_cyclic_time(
-            data_array, time_dim_name, day_of_year
-        )
-
-        if np.size(time) == 1:
-            data_array_interpolated = data_array_interpolated.expand_dims(
-                {time_dim_name: 1}
-            )
-        return data_array_interpolated
-
-    if isinstance(field, xr.DataArray):
-        return interpolate_single_field(field)
-    elif isinstance(field, xr.Dataset):
-        interpolated_data_vars = {
-            var: interpolate_single_field(data_array)
-            for var, data_array in field.data_vars.items()
-        }
-        return xr.Dataset(interpolated_data_vars, attrs=field.attrs)
-
-    else:
-        raise TypeError("Input 'field' must be an xarray.DataArray or xarray.Dataset.")
-
-
-def get_time_type(data_array: xr.DataArray) -> str:
-    """Determines the type of time values in the xarray DataArray.
-
-    Parameters
-    ----------
-    data_array : xr.DataArray
-        The xarray DataArray to be checked for time data types.
-
-    Returns
-    -------
-    str
-        A string indicating the type of the time data: 'cftime', 'datetime', or 'int'.
-
-    Raises
-    ------
-    TypeError
-        If the values in the DataArray are not of type numpy.ndarray or list.
-    """
-    # List of cftime datetime types
-    cftime_types = (
-        cftime.DatetimeNoLeap,
-        cftime.DatetimeJulian,
-        cftime.DatetimeGregorian,
-        cftime.Datetime360Day,
-        cftime.DatetimeProlepticGregorian,
-    )
-
-    # Check if any of the coordinate values are of cftime, datetime, or integer type
-    if isinstance(data_array.values, np.ndarray | list):
-        # Check if the data type is numpy datetime64, indicating standard datetime objects
-        if data_array.values.dtype == "datetime64[ns]":
-            return "datetime"
-
-        # Check if any values in the array are instances of cftime types
-        if any(isinstance(value, cftime_types) for value in data_array.values):
-            return "cftime"
-
-        # Check if all values are of integer type (e.g., for indices or time steps)
-        if np.issubdtype(data_array.values.dtype, np.integer):
-            return "int"
-
-        # If none of the above conditions are met, raise a ValueError
-        raise ValueError("Unsupported data type for time values in input dataset.")
-
-    # Handle unexpected types
-    raise TypeError("DataArray values must be of type numpy.ndarray or list.")
-
-
-def convert_cftime_to_datetime(data_array: np.ndarray) -> np.ndarray:
-    """Converts cftime datetime objects to numpy datetime64 objects in a numpy ndarray.
-
-    Parameters
-    ----------
-    data_array : np.ndarray
-        The numpy ndarray containing cftime datetime objects to be converted.
-
-    Returns
-    -------
-    np.ndarray
-        The ndarray with cftime datetimes converted to numpy datetime64 objects.
-
-    Notes
-    -----
-    This function is intended to be used with numpy ndarrays. If you need to convert
-    cftime datetime objects in an xarray.DataArray, please use the appropriate function
-    to handle xarray.DataArray conversions.
-    """
-    # List of cftime datetime types
-    cftime_types = (
-        cftime.DatetimeNoLeap,
-        cftime.DatetimeJulian,
-        cftime.DatetimeGregorian,
-    )
-
-    # Define a conversion function for cftime to numpy datetime64
-    def convert_datetime(dt):
-        if isinstance(dt, cftime_types):
-            # Convert to ISO format and then to nanosecond precision
-            return np.datetime64(dt.isoformat(), "ns")
-        return np.datetime64(dt, "ns")
-
-    return np.vectorize(convert_datetime)(data_array)
-
-
 def get_variable_metadata():
     """Retrieves metadata for commonly used variables in the dataset.
 
@@ -1227,46 +966,6 @@ def get_target_coords(
     return target_coords
 
 
-def rotate_velocities(
-    u: xr.DataArray, v: xr.DataArray, angle: xr.DataArray, interpolate: bool = True
-) -> tuple[xr.DataArray, xr.DataArray]:
-    """Rotate and optionally interpolate velocity components to align with grid
-    orientation.
-
-    Parameters
-    ----------
-    u : xarray.DataArray
-        Zonal (east-west) velocity component at u-points.
-    v : xarray.DataArray
-        Meridional (north-south) velocity component at v-points.
-    angle : xarray.DataArray
-        Grid angle values for rotation.
-    interpolate : bool, optional
-        If True, interpolates rotated velocities to grid points (default is True).
-
-    Returns
-    -------
-    tuple of xarray.DataArray
-        Rotated velocity components (u_rot, v_rot).
-
-    Notes
-    -----
-    - Rotation formulas:
-      - u_rot = u * cos(angle) + v * sin(angle)
-      - v_rot = v * cos(angle) - u * sin(angle)
-    """
-    # Rotate velocities to grid orientation
-    u_rot = u * np.cos(angle) + v * np.sin(angle)
-    v_rot = v * np.cos(angle) - u * np.sin(angle)
-
-    # Interpolate to u- and v-points
-    if interpolate:
-        u_rot = interpolate_from_rho_to_u(u_rot)
-        v_rot = interpolate_from_rho_to_v(v_rot)
-
-    return u_rot, v_rot
-
-
 def compute_barotropic_velocity(
     vel: xr.DataArray, interface_depth: xr.DataArray
 ) -> xr.DataArray:
@@ -1626,142 +1325,262 @@ def write_to_yaml(yaml_data, filepath: str | Path) -> None:
         )
 
 
+def serialize_paths(value: Any) -> Any:
+    """Recursively convert Path objects to strings."""
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, list):
+        return [serialize_paths(v) for v in value]
+    if isinstance(value, dict):
+        return {k: serialize_paths(v) for k, v in value.items()}
+    return value
+
+
+def normalize_paths(value: Any) -> Any:
+    """Recursively convert path-like strings back to Path objects.
+
+    Heuristic: strings containing '/' or ending with '.nc' are treated as paths.
+    """
+    if isinstance(value, str):
+        return Path(value) if "/" in value or value.endswith(".nc") else value
+    if isinstance(value, list):
+        return [normalize_paths(v) for v in value]
+    if isinstance(value, dict):
+        return {k: normalize_paths(v) for k, v in value.items()}
+    return value
+
+
+def serialize_datetime(value: datetime | list[datetime] | Any) -> Any:
+    """Convert datetime or list of datetimes to ISO 8601 strings."""
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, list) and all(isinstance(v, datetime) for v in value):
+        return [v.isoformat() for v in value]
+    return value
+
+
+def deserialize_datetime(
+    value: str | list[str] | datetime | Any,
+) -> datetime | list[datetime] | Any:
+    """Convert ISO 8601 string(s) to datetime object(s).
+
+    Returns:
+        datetime if input is string,
+        list of datetime if input is list of strings,
+        original value if parsing fails or input is already datetime.
+    """
+    if isinstance(value, list):
+        result: list[datetime | Any] = []
+        for v in value:
+            try:
+                result.append(datetime.fromisoformat(str(v)))
+            except ValueError:
+                result.append(v)
+        return result
+
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value)
+        except ValueError:
+            return value
+
+    return value
+
+
+def serialize_source_dict(src: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Serialize a source or BGC source dictionary for YAML or JSON output.
+
+    This function performs the following transformations:
+    - Converts any `Path` objects (including nested lists or dicts) to strings.
+    - Serializes any nested `Grid` objects using `serialize_grid`.
+    - Creates a deep copy of the input dictionary to avoid modifying the original.
+
+    Parameters
+    ----------
+    src : dict[str, Any] | None
+        The source or BGC source dictionary to serialize. Keys typically include:
+        - "path": path(s) to files
+        - "grid": a Grid object
+
+    Returns
+    -------
+    dict[str, Any] | None
+        A serialized dictionary suitable for saving to YAML or JSON, with:
+        - Paths converted to strings
+        - Nested Grid objects serialized
+        Returns `None` if input `src` is `None`.
+    """
+    if src is None:
+        return None
+
+    src = deepcopy(src)
+
+    # Serialize paths
+    if "path" in src:
+        src["path"] = serialize_paths(src["path"])
+
+    # Serialize nested grid
+    if "grid" in src and src["grid"] is not None:
+        src["grid"] = serialize_grid(src["grid"])
+
+    return src
+
+
+def deserialize_source_dict(src: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Deserialize a source / bgc_source dictionary.
+
+    Converts string paths back to Path objects.
+
+    Parameters
+    ----------
+    src : dict[str, Any] | None
+        Serialized source or bgc_source dictionary.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        Dictionary with paths converted to Path objects.
+    """
+    if src is None:
+        return None
+
+    src = deepcopy(src)
+
+    # Deserialize paths
+    if "path" in src:
+        src["path"] = normalize_paths(src["path"])
+
+    return src
+
+
+def serialize_grid(grid_obj: Any) -> dict[str, Any]:
+    """Serialize a Grid object to a dictionary, excluding non-serializable attributes."""
+    return pop_grid_data(asdict(grid_obj))
+
+
+def pop_grid_data(grid_data: dict[str, Any]) -> dict[str, Any]:
+    """Remove non-serializable or unnecessary keys from a Grid dictionary.
+
+    Removes 'ds', 'straddle', and 'verbose' keys if present.
+
+    Parameters
+    ----------
+    grid_data : dict
+        Dictionary representation of a Grid object.
+
+    Returns
+    -------
+    dict
+        Cleaned dictionary suitable for serialization.
+    """
+    for key in ("ds", "straddle", "verbose"):
+        grid_data.pop(key, None)
+    return grid_data
+
+
 def to_dict(forcing_object, exclude: list[str] | None = None) -> dict:
     """Serialize a forcing object (including its grid) into a dictionary.
 
-    This function serializes a dataclass object (forcing_object) and its associated
-    `grid` attribute into a dictionary. It omits fields like `grid` and `ds`
-    that are not serializable or meant to be excluded.
+    This function serializes a forcing object (dataclass or pydantic model),
+    including its associated grid(s), into a dictionary suitable for YAML output.
 
-    The function also converts datetime fields to ISO format strings for proper
-    serialization.
+    - Top-level grids (`grid`, `parent_grid`) are serialized consistently
+    - Nested grids inside `source` and `bgc_source` are also serialized
+    - Datetime objects are converted to ISO strings
+    - Path objects are converted to strings
 
     Parameters
     ----------
     forcing_object : object
-        The object that contains the forcing data, typically a dataclass with attributes
-        such as `grid`, `start_time`, `end_time`, etc.
+        A dataclass or pydantic model representing a forcing configuration.
     exclude : list[str], optional
-        List of keys to exclude from the serialized output. Defaults to empty list. The field "ds" is always excluded by default.
+        List of field names to exclude from serialization. The fields
+        "grid", "parent_grid", and "ds" are always excluded.
 
     Returns
     -------
     dict
+        Serialized representation of the forcing object.
     """
-    # Serialize Grid data
+    exclude_list = exclude or []
+    exclude_set: set[str] = {"grid", "parent_grid", "ds", *exclude_list}
+
+    # --- Serialize top-level grid(s) ---
+    yaml_data = {}
+
     if hasattr(forcing_object, "grid") and forcing_object.grid is not None:
-        grid_data = asdict(forcing_object.grid)
-        grid_yaml_data = {"Grid": pop_grid_data(grid_data)}
-    elif hasattr(forcing_object, "parent_grid"):
-        grid_data = asdict(forcing_object.parent_grid)
-        grid_yaml_data = {"ParentGrid": pop_grid_data(grid_data)}
-
-    # Ensure Paths are Strings
-    def ensure_paths_are_strings(obj, key):
-        attr = getattr(obj, key, None)
-        if attr is not None and "path" in attr:
-            paths = attr["path"]
-            if isinstance(paths, list):
-                attr["path"] = [str(p) if isinstance(p, Path) else p for p in paths]
-            elif isinstance(paths, Path):
-                attr["path"] = str(paths)
-            elif isinstance(paths, dict):
-                for key, path in paths.items():
-                    attr["path"][key] = str(path)
-
-    ensure_paths_are_strings(forcing_object, "source")
-    ensure_paths_are_strings(forcing_object, "bgc_source")
-
-    # Prepare Forcing Data
-    forcing_data = {}
+        yaml_data["Grid"] = serialize_grid(forcing_object.grid)
+
+    if (
+        hasattr(forcing_object, "parent_grid")
+        and forcing_object.parent_grid is not None
+    ):
+        yaml_data["ParentGrid"] = serialize_grid(forcing_object.parent_grid)
+
+    # --- Collect forcing fields ---
     if isinstance(forcing_object, BaseModel):
-        field_names = forcing_object.model_fields
+        field_names = forcing_object.model_fields.keys()
     elif is_dataclass(forcing_object):
-        field_names = [field.name for field in fields(forcing_object)]
+        field_names = [f.name for f in fields(forcing_object)]
     else:
-        raise TypeError("Forcing object is not a dataclass or pydantic model")
+        raise TypeError("Forcing object must be a dataclass or pydantic model")
 
-    if exclude is None:
-        exclude = []
-    exclude = ["grid", "parent_grid", "ds", *exclude]
-
-    filtered_field_names = [param for param in field_names if param not in exclude]
-
-    for field_name in filtered_field_names:
-        # Retrieve the value of each field using getattr
-        value = getattr(forcing_object, field_name)
+    forcing_data = {}
 
-        # If the field is a datetime object, convert it to ISO format
-        if isinstance(value, datetime):
-            value = value.isoformat()
-        # Convert list of datetimes to list of ISO strings
-        elif isinstance(value, list) and all(isinstance(v, datetime) for v in value):
-            value = [v.isoformat() for v in value]
+    for name in field_names:
+        if name in exclude_set:
+            continue
 
-        # Add the field and its value to the forcing_data dictionary
-        forcing_data[field_name] = value
+        value = getattr(forcing_object, name)
 
-    # Combine Grid and Forcing Data into a single dictionary for the final YAML content
-    yaml_data = {
-        **grid_yaml_data,  # Add the grid data to the final YAML structure
-        forcing_object.__class__.__name__: forcing_data,  # Include the serialized forcing object data
-    }
+        if name in {"source", "bgc_source"}:
+            forcing_data[name] = serialize_source_dict(value)
+            continue
 
-    return yaml_data
+        value = serialize_datetime(value)
+        value = serialize_paths(value)
 
+        forcing_data[name] = value
 
-def pop_grid_data(grid_data):
-    grid_data.pop("ds", None)  # Remove 'ds' attribute (non-serializable)
-    grid_data.pop("straddle", None)
-    grid_data.pop("verbose", None)
+    # --- Final YAML structure ---
+    yaml_data[forcing_object.__class__.__name__] = forcing_data
 
-    return grid_data
+    return yaml_data
 
 
 def from_yaml(forcing_object: type, filepath: str | Path) -> dict[str, Any]:
-    """Extract the configuration data for a given forcing object from a YAML file.
+    """Load configuration for a forcing object from a YAML file.
 
-    This function reads a YAML file, searches for the configuration data associated
-    with the class name of the forcing object, and returns the configuration data
-    as a dictionary. The dictionary contains the forcing parameters extracted from
-    the YAML file, with any date fields converted from ISO format.
+    Searches for a dictionary keyed by the class name of `forcing_object` and
+    returns it, converting:
+    - ISO-format date strings to `datetime` objects
+    - Path-like strings back to `Path` objects
+    - `source` and `bgc_source` nested dictionaries back to proper Grid objects
 
     Parameters
     ----------
-    filepath : Union[str, Path]
-        The path to the YAML file from which the parameters will be read.
-    forcing_object : Type
-        The class type (e.g., TidalForcing) whose configuration data is to be loaded
-        from the YAML file. The class name is used to locate the relevant data in
-        the YAML structure.
+    forcing_object : type
+        The class type whose configuration to load (e.g., `TidalForcing`).
+    filepath : str | Path
+        Path to the YAML file containing the configuration.
 
     Returns
     -------
-    dict
-        A dictionary containing the forcing parameters extracted from the YAML file.
-        This dictionary contains key-value pairs where the keys are the parameter
-        names, and the values are the corresponding values from the YAML file.
-        Any date fields are converted from ISO format if necessary.
+    dict[str, Any]
+        Dictionary of configuration parameters with dates, paths, and nested grids restored.
 
     Raises
     ------
     ValueError
-        If no configuration for the specified class name is found in the YAML file.
+        If no configuration for the specified class is found in the YAML file.
     """
-    # Ensure filepath is a Path object
     filepath = Path(filepath)
-
-    # Read the entire file content
-    with filepath.open("r") as file:
-        file_content = file.read()
-
-    # Split the content into YAML documents
-    documents = list(yaml.safe_load_all(file_content))
+    with filepath.open("r") as f:
+        documents = list(yaml.safe_load_all(f))
 
     forcing_data = None
     forcing_object_name = forcing_object.__name__
 
-    # Process the YAML documents to find the forcing data for the given object
     for doc in documents:
         if doc is None:
             continue
@@ -1774,21 +1593,19 @@ def from_yaml(forcing_object: type, filepath: str | Path) -> dict[str, Any]:
             f"No {forcing_object_name} configuration found in the YAML file."
         )
 
-    # Convert any date fields from ISO format if necessary
+    # Convert ISO date strings to datetime objects
     for key, value in forcing_data.items():
-        forcing_data[key] = _convert_from_iso_format(value)
+        forcing_data[key] = deserialize_datetime(value)
 
-    # Return the forcing data as a dictionary
-    return forcing_data
+    # Convert path-like strings back to Path objects
+    forcing_data = normalize_paths(forcing_data)
 
+    # Deserialize source and bgc_source nested dictionaries
+    for key in ["source", "bgc_source"]:
+        if key in forcing_data:
+            forcing_data[key] = deserialize_source_dict(forcing_data[key])
 
-def _convert_from_iso_format(value):
-    try:
-        # Return the parsed datetime object if successful
-        return datetime.fromisoformat(str(value))
-    except ValueError:
-        # Return None or raise an exception if parsing fails
-        return value
+    return forcing_data
 
 
 def handle_boundaries(field):
@@ -1861,38 +1678,6 @@ def get_boundary_coords():
     return bdry_coords
 
 
-def wrap_longitudes(grid_ds, straddle):
-    """Adjusts longitude values in a dataset to handle dateline crossing.
-
-    Parameters
-    ----------
-    grid_ds : xr.Dataset
-        The dataset containing longitude variables to adjust.
-    straddle : bool
-        If True, adjusts longitudes to the range [-180, 180] for datasets
-        that straddle the dateline. If False, adjusts longitudes to the
-        range [0, 360].
-
-    Returns
-    -------
-    xr.Dataset
-        The dataset with adjusted longitude values.
-    """
-    for lon_dim in ["lon_rho", "lon_u", "lon_v"]:
-        if straddle:
-            grid_ds[lon_dim] = xr.where(
-                grid_ds[lon_dim] > 180,
-                grid_ds[lon_dim] - 360,
-                grid_ds[lon_dim],
-            )
-        else:
-            grid_ds[lon_dim] = xr.where(
-                grid_ds[lon_dim] < 0, grid_ds[lon_dim] + 360, grid_ds[lon_dim]
-            )
-
-    return grid_ds
-
-
 def to_float(val):
     """Convert a value or list of values to float.
 
@@ -1967,260 +1752,101 @@ def validate_names(
     return names
 
 
-def check_dataset(
-    ds: xr.Dataset,
-    dim_names: dict[str, str],
-    var_names: dict[str, str],
-    opt_var_names: dict[str, str] | None = None,
-) -> None:
-    """Check if the dataset contains the specified variables and dimensions.
+def check_and_set_boundaries(
+    boundaries: dict[str, bool] | None,
+    mask: xr.DataArray,
+) -> dict[str, bool]:
+    """
+    Validate and finalize the `boundaries` dictionary.
 
     Parameters
     ----------
-    ds : xr.Dataset
-        The xarray Dataset to check.
-    dim_names: Dict[str, str], optional
-        Dictionary specifying the names of dimensions in the dataset.
-    var_names: Dict[str, str]
-        Dictionary of variable names that are required in the dataset.
-    opt_var_names : Optional[Dict[str, str]], optional
-        Dictionary of optional variable names.
-        These variables are not strictly required, and the function will not raise an error if they are missing.
-        Default is None, meaning no optional variables are considered.
+    boundaries : dict[str, bool] or None
+        User-supplied dictionary controlling which boundaries are active.
+        Keys may include any subset of {"south", "east", "north", "west"}.
+        Missing keys will be filled from mask-based defaults.
+        If None, all boundaries are inferred from the land mask.
 
+    mask : xr.DataArray
+        2D land/sea mask on rho-points. Used to determine which boundaries
+        contain at least one ocean point.
 
-    Raises
-    ------
-    ValueError
-        If the dataset does not contain the specified variables or dimensions.
+    Returns
+    -------
+    dict[str, bool]
+        Completed and validated boundary configuration.
     """
-    missing_dims = [dim for dim in dim_names.values() if dim not in ds.dims]
-    if missing_dims:
-        raise ValueError(
-            f"Dataset does not contain all required dimensions. The following dimensions are missing: {missing_dims}"
+    valid_keys = {"south", "east", "north", "west"}
+
+    # --------------------------------------------
+    # Case 1: boundaries not provided → infer them
+    # --------------------------------------------
+    if boundaries is None:
+        inferred = _infer_valid_boundaries_from_mask(mask)
+        logging.info(f"No `boundaries` provided. Using mask-based defaults: {inferred}")
+        return inferred
+
+    # --------------------------------------------
+    # Case 2: boundaries provided → validate
+    # --------------------------------------------
+    if not isinstance(boundaries, dict):
+        raise TypeError(
+            "`boundaries` must be a dict mapping boundary names to booleans."
         )
 
-    missing_vars = [var for var in var_names.values() if var not in ds.data_vars]
-    if missing_vars:
+    # Unknown keys?
+    unknown_keys = set(boundaries) - valid_keys
+    if unknown_keys:
         raise ValueError(
-            f"Dataset does not contain all required variables. The following variables are missing: {missing_vars}"
+            f"`boundaries` contains invalid keys: {unknown_keys}. "
+            "Allowed keys are: 'south', 'east', 'north', 'west'."
         )
 
-    if opt_var_names:
-        missing_optional_vars = [
-            var for var in opt_var_names.values() if var not in ds.data_vars
-        ]
-        if missing_optional_vars:
-            logging.warning(
-                f"Optional variables missing (but not critical): {missing_optional_vars}"
+    # Type-check provided values
+    for key, val in boundaries.items():
+        if not isinstance(val, bool):
+            raise TypeError(f"Boundary '{key}' must be a boolean.")
+
+    # Fill missing boundaries using defaults
+    inferred_defaults = _infer_valid_boundaries_from_mask(mask)
+    completed = boundaries.copy()
+
+    for key in valid_keys:
+        if key not in completed:
+            completed[key] = inferred_defaults[key]
+            logging.info(
+                f"`boundaries[{key!r}]` not provided — defaulting to "
+                f"{inferred_defaults[key]}"
             )
 
+    logging.info(f"Using boundary configuration: {completed}")
+    return completed
 
-def select_relevant_times(
-    ds: xr.Dataset,
-    time_dim: str,
-    start_time: datetime,
-    end_time: datetime | None = None,
-    climatology: bool = False,
-    allow_flex_time: bool = False,
-) -> xr.Dataset:
-    """
-    Select a subset of the dataset based on time constraints.
-
-    This function supports two main use cases:
-
-    1. **Time range selection (start_time + end_time provided):**
-       - Returns all records strictly between `start_time` and `end_time`.
-       - Ensures at least one record at or before `start_time` and one record at or
-         after `end_time` are included, even if they fall outside the strict range.
-
-    2. **Initial condition selection (start_time provided, end_time=None):**
-       - Delegates to `_select_initial_time`, which reduces the dataset to exactly one
-         time entry.
-       - If `allow_flex_time=True`, a +24-hour buffer around `start_time` is allowed,
-         and the closest timestamp is chosen.
-       - If `allow_flex_time=False`, requires an exact timestamp match.
-
-    Additional behavior:
-    - If `climatology=True`, the dataset must contain exactly 12 time steps. If valid,
-      the climatology dataset is returned without further filtering.
-    - If the dataset uses `cftime` datetime objects, these are converted to
-      `np.datetime64` before filtering.
 
-    Parameters
-    ----------
-    ds : xr.Dataset
-        The dataset to filter. Must contain a valid time dimension.
-    time_dim : str
-        Name of the time dimension in `ds`.
-    start_time : datetime
-        Start time for filtering.
-    end_time : datetime or None
-        End time for filtering. If `None`, the function assumes an initial condition
-        use case and selects exactly one timestamp.
-    climatology : bool, optional
-        If True, requires exactly 12 time steps and bypasses normal filtering.
-        Defaults to False.
-    allow_flex_time : bool, optional
-        Whether to allow a +24h search window after `start_time` when `end_time`
-        is None. If False (default), requires an exact match.
-
-    Returns
-    -------
-    xr.Dataset
-        A filtered dataset containing only the selected time entries.
-
-    Raises
-    ------
-    ValueError
-        - If `climatology=True` but the dataset does not contain exactly 12 time steps.
-        - If `climatology=False` and the dataset contains integer time values.
-        - If no valid records are found within the requested range or window.
-
-    Warns
-    -----
-    UserWarning
-        - If no records exist at or before `start_time` or at or after `end_time`.
-        - If the specified time dimension does not exist in the dataset.
-
-    Notes
-    -----
-    - For initial conditions (end_time=None), see `_select_initial_time` for details
-      on strict vs. flexible selection behavior.
-    - Logs warnings instead of failing hard when boundary records are missing, and
-      defaults to using the earliest or latest available time in such cases.
+def _infer_valid_boundaries_from_mask(mask: xr.DataArray) -> dict[str, bool]:
     """
-    if time_dim not in ds.variables:
-        logging.warning(
-            f"Dataset does not contain time dimension '{time_dim}'. "
-            "Please check variable naming or dataset structure."
-        )
-        return ds
-
-    time_type = get_time_type(ds[time_dim])
+    Determine which grid boundaries contain at least one ocean point.
 
-    if climatology:
-        if len(ds[time_dim]) != 12:
-            raise ValueError(
-                f"The dataset contains {len(ds[time_dim])} time steps, but the climatology flag is set to True, which requires exactly 12 time steps."
-            )
-    else:
-        if time_type == "int":
-            raise ValueError(
-                "The dataset contains integer time values, which are only supported when the climatology flag is set to True. However, your climatology flag is set to False."
-            )
-    if time_type == "cftime":
-        ds = ds.assign_coords({time_dim: convert_cftime_to_datetime(ds[time_dim])})
-
-    if not end_time:
-        # Assume we are looking for exactly one time record for initial conditions
-        return _select_initial_time(
-            ds, time_dim, start_time, climatology, allow_flex_time
-        )
-
-    if climatology:
-        return ds
-
-    # Identify records before or at start_time
-    before_start = ds[time_dim] <= np.datetime64(start_time)
-    if before_start.any():
-        closest_before_start = ds[time_dim].where(before_start, drop=True)[-1]
-    else:
-        logging.warning(f"No records found at or before the start_time: {start_time}.")
-        closest_before_start = ds[time_dim][0]
-
-    # Identify records after or at end_time
-    after_end = ds[time_dim] >= np.datetime64(end_time)
-    if after_end.any():
-        closest_after_end = ds[time_dim].where(after_end, drop=True).min()
-    else:
-        logging.warning(f"No records found at or after the end_time: {end_time}.")
-        closest_after_end = ds[time_dim].max()
-
-    # Select records within the time range and add the closest before/after
-    within_range = (ds[time_dim] > np.datetime64(start_time)) & (
-        ds[time_dim] < np.datetime64(end_time)
-    )
-    selected_times = ds[time_dim].where(
-        within_range
-        | (ds[time_dim] == closest_before_start)
-        | (ds[time_dim] == closest_after_end),
-        drop=True,
-    )
-    ds = ds.sel({time_dim: selected_times})
-
-    return ds
-
-
-def _select_initial_time(
-    ds: xr.Dataset,
-    time_dim: str,
-    ini_time: datetime,
-    climatology: bool,
-    allow_flex_time: bool = False,
-) -> xr.Dataset:
-    """Select exactly one initial time from dataset.
+    Any boundary consisting entirely of land is considered inactive.
 
     Parameters
     ----------
-    ds : xr.Dataset
-        The input dataset with a time dimension.
-    time_dim : str
-        Name of the time dimension.
-    ini_time : datetime
-        The desired initial time.
-    allow_flex_time : bool
-        - If True: allow a +24h window and pick the closest available timestamp.
-        - If False (default): require an exact match, otherwise raise ValueError.
+    mask : xr.DataArray
+        2D mask array on rho-points where 1 = ocean, 0 = land.
 
     Returns
     -------
-    xr.Dataset
-        Dataset reduced to exactly one timestamp.
-
-    Raises
-    ------
-    ValueError
-        If no matching time is found (when `allow_flex_time=False`), or no entries are
-        available within the +24h window (when `allow_flex_time=True`).
+    dict[str, bool]
+        Boolean availability for {south, east, north, west}.
     """
-    if climatology:
-        # Convert from timedelta64[ns] to fractional days
-        ds["time"] = ds["time"] / np.timedelta64(1, "D")
-        # Interpolate from climatology for initial conditions
-        return interpolate_from_climatology(ds, time_dim, ini_time)
-
-    if allow_flex_time:
-        # Look in time range [ini_time, ini_time + 24h)
-        end_time = ini_time + timedelta(days=1)
-        times = (np.datetime64(ini_time) <= ds[time_dim]) & (
-            ds[time_dim] < np.datetime64(end_time)
-        )
-
-        if np.all(~times):
-            raise ValueError(
-                f"No time entries found between {ini_time} and {end_time}."
-            )
+    bdry_coords = get_boundary_coords()
+    boundaries = {}
 
-        ds = ds.where(times, drop=True)
-        if ds.sizes[time_dim] > 1:
-            # Pick the time closest to start_time
-            ds = ds.isel({time_dim: 0})
+    for direction in ["south", "east", "north", "west"]:
+        coords = bdry_coords["rho"][direction]
+        bdry_mask = mask.isel(**coords)
 
-        logging.warning(
-            f"Selected time entry closest to the specified start_time in +24 hour range: {ds[time_dim].values}"
-        )
-
-    else:
-        # Strict match required
-        if not (ds[time_dim].values == np.datetime64(ini_time)).any():
-            raise ValueError(
-                f"No exact match found for initial time {ini_time}. Consider setting allow_flex_time to True."
-            )
-
-        ds = ds.sel({time_dim: np.datetime64(ini_time)})
+        # Boundary is valid if ANY ocean point exists
+        boundaries[direction] = bool(bdry_mask.values.any())
 
-    if time_dim not in ds.dims:
-        ds = ds.expand_dims(time_dim)
-
-    return ds
+    return boundaries