roms-tools 2.7.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

roms_tools/setup/cdr_forcing.py

@@ -1,389 +1,396 @@
-from dataclasses import dataclass, field
+import itertools
+import logging
+from collections import Counter
+from collections.abc import Iterator
 from datetime import datetime
 from pathlib import Path
-from typing import Optional, List, Dict, Union
-import numpy as np
-import xarray as xr
+from typing import Annotated
+
 import cartopy.crs as ccrs
-import logging
+import matplotlib.gridspec as gridspec
 import matplotlib.pyplot as plt
-import matplotlib.cm as cm
+import numpy as np
+import xarray as xr
+from matplotlib.axes import Axes
+from pydantic import (
+    BaseModel,
+    Field,
+    RootModel,
+    conlist,
+    model_serializer,
+    model_validator,
+)
+
 from roms_tools import Grid
-from roms_tools.constants import NUM_TRACERS
-from roms_tools.plot import _plot, _get_projection
-from roms_tools.regrid import LateralRegridFromROMS
-from roms_tools.utils import (
-    _generate_coordinate_range,
-    _remove_edge_nans,
-    save_datasets,
+from roms_tools.plot import get_projection, plot, plot_2d_horizontal_field
+from roms_tools.setup.cdr_release import (
+    Release,
+    ReleaseType,
+    TracerPerturbation,
+    VolumeRelease,
 )
 from roms_tools.setup.utils import (
-    gc_dist,
-    get_tracer_defaults,
-    get_tracer_metadata_dict,
     add_tracer_metadata_to_ds,
-    to_float,
-    _to_yaml,
-    _from_yaml,
+    convert_to_relative_days,
+    from_yaml,
+    gc_dist,
+    get_target_coords,
+    to_dict,
+    write_to_yaml,
+)
+from roms_tools.utils import (
+    normalize_longitude,
+    save_datasets,
 )
+from roms_tools.vertical_coordinate import compute_depth_coordinates
 
+INCLUDE_ALL_RELEASE_NAMES = "all"
 
-@dataclass(kw_only=True)
-class CDRVolumePointSource:
-    """Represents one or several volume sources of water with tracers at specific
-    location(s). This class is particularly useful for modeling point sources of Carbon
-    Dioxide Removal (CDR) forcing data, such as the injection of water and
-    biogeochemical tracers, e.g., alkalinity (ALK) or dissolved inorganic carbon (DIC),
-    through a pipe.
 
-    Parameters
-    ----------
-    grid : Grid, optional
-        Object representing the grid for spatial context.
-    start_time : datetime
-        Start time of the ROMS model simulation.
-    end_time : datetime
-        End time of the ROMS model simulation.
-    model_reference_date : datetime, optional
-        Reference date for converting absolute times to model-relative time. Defaults to Jan 1, 2000.
-    releases : dict, optional
-        A dictionary of existing releases. Defaults to empty dictionary.
-
-    Attributes
-    ----------
-    ds : xr.Dataset
-        The xarray dataset containing release metadata and forcing variables.
+class ReleaseSimulationManager(BaseModel):
+    """Validates and adjusts a single release against a ROMS simulation time window and
+    grid.
     """
 
-    grid: Optional["Grid"] = None
+    release: Release
+    grid: Grid | None = None
     start_time: datetime
     end_time: datetime
-    model_reference_date: datetime = datetime(2000, 1, 1)
-    releases: Optional[dict] = field(default_factory=dict)
 
-    ds: xr.Dataset = field(init=False, repr=False)
-
-    def __post_init__(self):
-        if self.start_time >= self.end_time:
-            raise ValueError("`start_time` must be earlier than `end_time`.")
-
-        # Start with an empty dataset representing zero releases
-        ds = xr.Dataset(
-            {
-                "cdr_time": (["time"], np.empty(0)),
-                "cdr_lon": (["ncdr"], np.empty(0)),
-                "cdr_lat": (["ncdr"], np.empty(0)),
-                "cdr_dep": (["ncdr"], np.empty(0)),
-                "cdr_hsc": (["ncdr"], np.empty(0)),
-                "cdr_vsc": (["ncdr"], np.empty(0)),
-                "cdr_volume": (["time", "ncdr"], np.empty((0, 0))),
-                "cdr_tracer": (
-                    ["time", "ntracers", "ncdr"],
-                    np.empty((0, NUM_TRACERS, 0)),
-                ),
-            },
-            coords={
-                "time": (["time"], np.empty(0)),
-                "release_name": (["ncdr"], np.empty(0, dtype=str)),
-            },
-        )
-        ds = add_tracer_metadata_to_ds(ds)
-        self.ds = ds
-
-        tracer_metadata = get_tracer_metadata_dict()
-        self.releases["_tracer_metadata"] = tracer_metadata
-
-        if self.releases:
-            if "_metadata" not in self.releases:
-                tracer_metadata = get_tracer_metadata_dict()
-                self.releases["_tracer_metadata"] = tracer_metadata
-
-            for name, params in self.releases.items():
-                if name == "_tracer_metadata":
-                    continue  # skip metadata entry
-                self._validate_release_location(
-                    name=name,
-                    lat=params["lat"],
-                    lon=params["lon"],
-                    depth=params["depth"],
-                )
-                self._add_release_to_ds(name=name, **params)
-
-    def add_release(
+    @model_validator(mode="after")
+    def check_release_times_within_simulation_window(
         self,
-        *,
-        name: str,
-        lat: float,
-        lon: float,
-        depth: float,
-        times: Optional[List[datetime]] = None,
-        volume_fluxes: Union[float, List[float]] = 0.0,
-        tracer_concentrations: Optional[Dict[str, Union[float, List[float]]]] = None,
-        fill_values: str = "auto",
-    ):
-        """Adds a release (point source) of water with tracers to the forcing dataset
-        and dictionary.
-
-        This method registers a point source at a specific location (latitude, longitude, and depth).
-        The release includes both a volume flux of water and tracer
-        concentrations, which can be constant or time-varying.
+    ) -> "ReleaseSimulationManager":
+        """Ensure the release times are within the [start_time, end_time] simulation
+        window.
+        """
+        times = self.release.times
+        if len(times) == 0:
+            return self
 
-        Parameters
-        ----------
-        name : str
-            Unique identifier for the release.
-        lat : float or int
-            Latitude of the release location in degrees North. Must be between -90 and 90.
-        lon : float or int
-            Longitude of the release location in degrees East. No restrictions on bounds.
-        depth : float or int
-            Depth of the release in meters. Must be non-negative.
-        times : list of datetime.datetime, optional
-            Explicit time points for volume fluxes and tracer concentrations. Defaults to [self.start_time, self.end_time] if None.
+        if times[0] < self.start_time:
+            raise ValueError(
+                f"First time in release '{self.release.name}' is before start_time ({self.start_time})."
+            )
 
-            Example: `times=[datetime(2022, 1, 1), datetime(2022, 1, 2), datetime(2022, 1, 3)]`
+        if times[-1] > self.end_time:
+            raise ValueError(
+                f"Last time in release '{self.release.name}' is after end_time ({self.end_time})."
+            )
 
-        volume_fluxes : float, int, or list of float/int, optional
+        return self
 
-            Volume flux(es) of the release in m³/s over time.
+    @model_validator(mode="after")
+    def validate_release_location(self) -> "ReleaseSimulationManager":
+        """Ensure the release is consistent with the simulation grid."""
+        _validate_release_location(self.grid, self.release)
+        return self
 
-            - Constant: applies uniformly across the entire simulation period.
-            - Time-varying: must match the length of `times`.
+    @model_validator(mode="after")
+    def extend_to_endpoints(self) -> "ReleaseSimulationManager":
+        """Extend the release time series to include the simulation time endpoints."""
+        self.release._extend_to_endpoints(self.start_time, self.end_time)
+        return self
 
-            Example:
 
-            - Constant: `volume_fluxes=1000.0` (uniform across the entire simulation period).
-            - Time-varying: `volume_fluxes=[1000.0, 1500.0, 2000.0]` (corresponds to each `times` entry).
+class ReleaseCollector(RootModel):
+    """Collects and validates multiple releases against each other."""
 
-        tracer_concentrations : dict, optional
+    root: conlist(
+        Annotated[
+            VolumeRelease | TracerPerturbation, Field(discriminator="release_type")
+        ],
+        min_length=1,
+    ) = Field(alias="releases")
 
-            Dictionary of tracer names and their concentration values. The concentration values can be either
-            a float/int (constant in time) or a list of float/int (time-varying).
+    _release_type: ReleaseType = None
 
-            - Constant: applies uniformly across the entire simulation period.
-            - Time-varying: must match the length of `times`.
+    def __iter__(self) -> Iterator[Release]:
+        return iter(self.root)
 
-            Default is an empty dictionary (`{}`) if not provided.
-            Example:
+    def __getitem__(self, item: int | str) -> Release:
+        if isinstance(item, int):
+            return self.root[item]
+        elif isinstance(item, str):
+            for release in self.root:
+                if release.name == item:
+                    return release
+            raise KeyError(f"Release named '{item}' not found.")
+        else:
+            raise TypeError(f"Invalid key type: {type(item)}. Must be int or str.")
 
-            - Constant: `{"ALK": 2000.0, "DIC": 1900.0}`
-            - Time-varying: `{"ALK": [2000.0, 2050.0, 2013.3], "DIC": [1900.0, 1920.0, 1910.2]}`
-            - Mixed: `{"ALK": 2000.0, "DIC": [1900.0, 1920.0, 1910.2]}`
+    @model_validator(mode="before")
+    @classmethod
+    def unpack_dict(cls, data):
+        """This helps directly translate a dict of {"releases": [...]} into just the
+        list of releases.
+        """
+        if isinstance(data, dict):
+            try:
+                return data["releases"]
+            except KeyError:
+                raise ValueError(
+                    "Expected a dictionary with a 'releases' key, or else a list of releases"
+                )
+        return data
 
-        fill_values : str, optional
+    @model_validator(mode="after")
+    def check_unique_name(self) -> "ReleaseCollector":
+        """Check that all releases have unique names."""
+        names = [release.name for release in self.root]
+        duplicates = [name for name, count in Counter(names).items() if count > 1]
 
-            Strategy for filling missing tracer concentration values. Options:
+        if duplicates:
+            raise ValueError(
+                f"Multiple releases share the following name(s): {', '.join(repr(d) for d in duplicates)}. "
+                "Each release must have a unique name."
+            )
 
-            - "auto" (default): automatically set values to non-zero defaults
-            - "zero": fill missing values with 0.0
-        """
-        # Check that the name is unique
-        if name in self.releases:
-            raise ValueError(f"A release with the name '{name}' already exists.")
+        return self
 
-        # Check that fill_values has proper string
-        if fill_values not in ("auto", "zero"):
+    @model_validator(mode="after")
+    def check_all_releases_same_type(self):
+        """Ensure all releases are of the same type, and set the release_type."""
+        release_types = set(r.release_type for r in self.root)
+        if len(release_types) > 1:
+            type_list = ", ".join(map(str, release_types))
             raise ValueError(
-                f"Invalid fill_values option: '{fill_values}'. "
-                "Must be 'auto' or 'zero'."
+                f"Not all releases have the same type. Received: {type_list}"
             )
+        return self
 
-        # Set default for times if None
-        if times is None:
-            times = []
-
-        # Set default for tracer_concentrations if None
-        if tracer_concentrations is None:
-            tracer_concentrations = {}
-
-        # Fill in missing tracer concentrations
-        defaults = get_tracer_defaults()
-        for tracer_name in self.ds.tracer_name.values:
-            if tracer_name not in tracer_concentrations:
-                tracer_name = str(tracer_name)
-                if tracer_name in ["temp", "salt"]:
-                    tracer_concentrations[tracer_name] = defaults[tracer_name]
-                else:
-                    if fill_values == "auto":
-                        tracer_concentrations[tracer_name] = defaults[tracer_name]
-                    elif fill_values == "zero":
-                        tracer_concentrations[tracer_name] = 0.0
-
-        # Check input parameters
-        self._input_checks(
-            name=name,
-            lat=lat,
-            lon=lon,
-            depth=depth,
-            times=times,
-            volume_fluxes=volume_fluxes,
-            tracer_concentrations=tracer_concentrations,
-        )
+    @property
+    def release_type(self):
+        """Type of all releases."""
+        release_types = set(r.release_type for r in self.root)
+        return release_types.pop()
 
-        # Convert integers to floats
-        lat = float(lat)
-        lon = float(lon)
-        depth = float(depth)
-        volume_fluxes = to_float(volume_fluxes)
-        tracer_concentrations = {
-            tracer: to_float(vals) for tracer, vals in tracer_concentrations.items()
-        }
 
-        # Extend volume fluxes and tracer_concentrations across simulation period if necessary
-        times, volume_fluxes, tracer_concentrations = self._handle_simulation_endpoints(
-            times, volume_fluxes, tracer_concentrations
-        )
+class CDRForcingDatasetBuilder:
+    """Constructs the xarray `Dataset` to be saved as NetCDF."""
 
-        # Validate release location
-        self._validate_release_location(name=name, lat=lat, lon=lon, depth=depth)
-
-        self._add_release_to_dict(
-            name=name,
-            lat=lat,
-            lon=lon,
-            depth=depth,
-            times=times,
-            volume_fluxes=volume_fluxes,
-            tracer_concentrations=tracer_concentrations,
-        )
+    def __init__(
+        self,
+        releases: ReleaseCollector,
+        model_reference_date: datetime,
+        release_type: ReleaseType,
+    ):
+        """
+        Initialize the dataset builder.
 
-        self._add_release_to_ds(
-            name=name,
-            lat=lat,
-            lon=lon,
-            depth=depth,
-            times=times,
-            volume_fluxes=volume_fluxes,
-            tracer_concentrations=tracer_concentrations,
+        Parameters
+        ----------
+        releases : list
+            List of release objects.
+        model_reference_date : datetime
+            Reference date for relative time conversion.
+        release_type : ReleaseType
+            Type of release.
+        """
+        self.releases = releases
+        self.model_reference_date = model_reference_date
+        self.release_type = release_type
+
+    def build(self) -> xr.Dataset:
+        """Build the CDR forcing dataset."""
+        all_times = itertools.chain.from_iterable(r.times for r in self.releases)
+        unique_times = np.unique(np.array(list(all_times), dtype="datetime64[ns]"))
+        unique_rel_times = convert_to_relative_days(
+            unique_times, self.model_reference_date
         )
 
-    def _add_release_to_ds(
-        self,
-        *,
-        name: str,
-        lat: float,
-        lon: float,
-        depth: float,
-        times: Optional[List[datetime]] = None,
-        tracer_concentrations: Optional[Dict[str, Union[float, List[float]]]] = None,
-        volume_fluxes: Union[float, List[float]] = 0.0,
-    ):
-        """Add the release data for a specific release to the forcing dataset."""
+        ds = self._initialize_dataset(unique_times, unique_rel_times)
 
-        # Convert times to datetime64[ns]
-        times = np.array(times, dtype="datetime64[ns]")
+        for ncdr, release in enumerate(self.releases):
+            times = np.array(release.times, dtype="datetime64[ns]")
+            rel_times = convert_to_relative_days(times, self.model_reference_date)
 
-        # Ensure reference date is also datetime64[ns]
-        ref = np.datetime64(self.model_reference_date, "ns")
+            if self.release_type == ReleaseType.volume:
+                ds["cdr_volume"].loc[{"ncdr": ncdr}] = np.interp(
+                    unique_rel_times, rel_times, release.volume_fluxes.values
+                )
+                tracer_key = "cdr_tracer"
+                tracer_data = release.tracer_concentrations
+            elif self.release_type == ReleaseType.tracer_perturbation:
+                tracer_key = "cdr_trcflx"
+                tracer_data = release.tracer_fluxes
+
+            for ntracer in range(ds.ntracers.size):
+                tracer_name = ds.tracer_name[ntracer].item()
+                ds[tracer_key].loc[{"ntracers": ntracer, "ncdr": ncdr}] = np.interp(
+                    unique_rel_times,
+                    rel_times,
+                    tracer_data[tracer_name].values,
+                )
 
-        # Compute model-relative times in days
-        rel_times = (times - ref) / np.timedelta64(1, "D")
+        return ds
 
-        # Merge with existing time dimension
-        existing_times = (
-            self.ds["time"].values
-            if len(self.ds["time"]) > 0
-            else np.array([], dtype="datetime64[ns]")
-        )
-        existing_rel_times = (
-            self.ds["cdr_time"].values if len(self.ds["cdr_time"]) > 0 else []
-        )
-        union_times = np.union1d(existing_times, times)
-        union_rel_times = np.union1d(existing_rel_times, rel_times)
+    def _initialize_dataset(self, unique_times, unique_rel_times) -> xr.Dataset:
+        """Create and initialize a CDR xarray.Dataset with metadata and empty variables.
+
+        Parameters
+        ----------
+        unique_times : array-like
+            Array of unique absolute times for the release.
+        unique_rel_times : array-like
+            Array of unique relative times (days since model reference date).
 
-        # Initialize a fresh dataset to accommodate the new release.
-        # xarray does not handle dynamic resizing of dimensions well (e.g., increasing 'ncdr' by 1),
-        # so we recreate the dataset with the updated size.
+        Returns
+        -------
+        xr.Dataset
+            Initialized dataset with time, location, and release-type-dependent variables.
+        """
         ds = xr.Dataset()
-        ds["time"] = ("time", union_times)
-        ds["cdr_time"] = ("time", union_rel_times)
-        ds = add_tracer_metadata_to_ds(ds)
-
-        release_names = np.concatenate([self.ds.release_name.values, [name]])
-        ds = ds.assign_coords({"release_name": (["ncdr"], release_names)})
-        ds["cdr_lon"] = xr.zeros_like(ds.ncdr, dtype=np.float64)
-        ds["cdr_lat"] = xr.zeros_like(ds.ncdr, dtype=np.float64)
-        ds["cdr_dep"] = xr.zeros_like(ds.ncdr, dtype=np.float64)
-        ds["cdr_hsc"] = xr.zeros_like(ds.ncdr, dtype=np.float64)
-        ds["cdr_vsc"] = xr.zeros_like(ds.ncdr, dtype=np.float64)
-
-        ds["cdr_volume"] = xr.zeros_like(ds.cdr_time * ds.ncdr, dtype=np.float64)
-        ds["cdr_tracer"] = xr.zeros_like(
-            ds.cdr_time * ds.ntracers * ds.ncdr, dtype=np.float64
+        ds["time"] = ("time", unique_times)
+        ds["cdr_time"] = ("time", unique_rel_times)
+        ds["cdr_lon"] = ("ncdr", [r.lon for r in self.releases])
+        ds["cdr_lat"] = ("ncdr", [r.lat for r in self.releases])
+        ds["cdr_dep"] = ("ncdr", [r.depth for r in self.releases])
+        ds["cdr_hsc"] = ("ncdr", [r.hsc for r in self.releases])
+        ds["cdr_vsc"] = ("ncdr", [r.vsc for r in self.releases])
+        ds = ds.assign_coords(
+            {"release_name": (["ncdr"], [r.name for r in self.releases])}
         )
 
-        # Retain previous experiment locations
-        if len(self.ds["ncdr"]) > 0:
-            for i in range(len(self.ds.ncdr)):
-                for var_name in ["cdr_lon", "cdr_lat", "cdr_dep", "cdr_hsc", "cdr_vsc"]:
-                    ds[var_name].loc[{"ncdr": i}] = self.ds[var_name].isel(ncdr=i)
-
-        # Add the new experiment location
-        for var_name, value in zip(
-            ["cdr_lon", "cdr_lat", "cdr_dep", "cdr_hsc", "cdr_vsc"],
-            [lon, lat, depth, 0.0, 0.0],
-        ):
-            ds[var_name].loc[{"ncdr": ds.sizes["ncdr"] - 1}] = np.float64(value)
-
-        # Interpolate and retain previous experiment volume fluxes and tracer concentrations
-        if len(self.ds["ncdr"]) > 0:
-            for i in range(len(self.ds.ncdr)):
-                interpolated = np.interp(
-                    union_rel_times,
-                    self.ds["cdr_time"].values,
-                    self.ds["cdr_volume"].isel(ncdr=i).values,
-                )
-                ds["cdr_volume"].loc[{"ncdr": i}] = interpolated
-
-                for n in range(len(self.ds.ntracers)):
-                    interpolated = np.interp(
-                        union_rel_times,
-                        self.ds["cdr_time"].values,
-                        self.ds["cdr_tracer"].isel(ntracers=n, ncdr=i).values,
-                    )
-                    ds["cdr_tracer"].loc[{"ntracers": n, "ncdr": i}] = interpolated
-
-        # Handle new experiment volume fluxes and tracer concentrations
-        if isinstance(volume_fluxes, list):
-            interpolated = np.interp(union_rel_times, rel_times, volume_fluxes)
-        else:
-            interpolated = np.full(len(union_rel_times), volume_fluxes)
-
-        ds["cdr_volume"].loc[{"ncdr": ds.sizes["ncdr"] - 1}] = interpolated
+        if self.release_type == ReleaseType.volume:
+            ds = add_tracer_metadata_to_ds(
+                ds, with_flux_units=False
+            )  # adds the coordinate "tracer_name"
+            ds["cdr_volume"] = xr.zeros_like(ds.cdr_time * ds.ncdr, dtype=np.float64)
+            ds["cdr_tracer"] = xr.zeros_like(
+                ds.cdr_time * ds.ntracers * ds.ncdr, dtype=np.float64
+            )
 
-        for n in range(len(self.ds.ntracers)):
-            tracer_name = ds.tracer_name[n].item()
-            if isinstance(tracer_concentrations[tracer_name], list):
-                interpolated = np.interp(
-                    union_rel_times, rel_times, tracer_concentrations[tracer_name]
-                )
-            else:
-                interpolated = np.full(
-                    len(union_rel_times), tracer_concentrations[tracer_name]
-                )
+        elif self.release_type == ReleaseType.tracer_perturbation:
+            ds = add_tracer_metadata_to_ds(
+                ds, with_flux_units=True
+            )  # adds the coordinate "tracer_name"
+            ds["cdr_trcflx"] = xr.zeros_like(
+                ds.cdr_time * ds.ntracers * ds.ncdr, dtype=np.float64
+            )
 
-            ds["cdr_tracer"].loc[
-                {"ntracers": n, "ncdr": ds.sizes["ncdr"] - 1}
-            ] = interpolated
+        # Assign attributes
+        attr_map = self._get_attr_map()
+        for var, attrs in attr_map.items():
+            if var in ds.data_vars or var in ds.coords:
+                ds[var].attrs.update(attrs)
 
-        self.ds = ds
+        return ds
 
-    def _add_release_to_dict(self, name: str, **params):
-        """Add the release data for a specific 'name' to the releases dictionary.
+    def _get_attr_map(self) -> dict[str, dict[str, str]]:
+        """Returns metadata (long name and units) for variables in the CDRForcing xarray
+        dataset.
 
-        Parameters
-        ----------
-        name : str
-            The unique name for the release to be added to the dictionary.
-        **params : keyword arguments
-            Parameters to be added for the specific release (e.g., location, volume fluxes, etc.).
+        Returns
+        -------
+        dict
+            Keys are variable names, values are dicts with 'long_name' and 'units'.
         """
-        # Add the parameters to the dictionary under the given name
-        if name not in self.releases:
-            self.releases[name] = {}
-        self.releases[name].update(params)
+        return {
+            "time": {"long_name": "absolute time"},
+            "cdr_time": {
+                "long_name": f"relative time: days since {self.model_reference_date}",
+                "units": "days",
+            },
+            "release_name": {"long_name": "Name of release"},
+            "cdr_lon": {
+                "long_name": "Longitude of CDR release",
+                "units": "degrees east",
+            },
+            "cdr_lat": {
+                "long_name": "Latitude of CDR release",
+                "units": "degrees north",
+            },
+            "cdr_dep": {"long_name": "Depth of CDR release", "units": "meters"},
+            "cdr_hsc": {
+                "long_name": "Horizontal scale of CDR release",
+                "units": "meters",
+            },
+            "cdr_vsc": {
+                "long_name": "Vertical scale of CDR release",
+                "units": "meters",
+            },
+            "cdr_trcflx": {
+                "long_name": "CDR tracer flux",
+                "description": "Tracer fluxes for CDR releases",
+            },
+            "cdr_volume": {
+                "long_name": "CDR volume flux",
+                "units": "m3/s",
+                "description": "Volume flux associated with CDR releases",
+            },
+            "cdr_tracer": {
+                "long_name": "CDR tracer concentration",
+                "description": "Tracer concentrations for CDR releases",
+            },
+        }
+
+
+class CDRForcing(BaseModel):
+    """Represents Carbon Dioxide Removal (CDR) forcing.
+
+    Parameters
+    ----------
+    grid : Grid, optional
+        Object representing the grid.
+    start_time : datetime
+        Start time of the ROMS model simulation.
+    end_time : datetime
+        End time of the ROMS model simulation.
+    model_reference_date : datetime, optional
+        Reference date for converting absolute times to model-relative time. Defaults to Jan 1, 2000.
+    releases : list of Release
+        A list of one or more CDR release objects.
+    """
 
-    def plot_volume_flux(self, start=None, end=None, releases="all"):
+    grid: Grid | None = None
+    """Object representing the grid."""
+    start_time: datetime
+    """Start time of the ROMS model simulation."""
+    end_time: datetime
+    """End time of the ROMS model simulation."""
+    model_reference_date: datetime = datetime(2000, 1, 1)
+    """The reference date for the ROMS simulation."""
+    releases: ReleaseCollector
+    """A list of one or more CDR release objects."""
+
+    # this is defined during init and shouldn't be serialized
+    _ds: xr.Dataset = None
+
+    @model_validator(mode="after")
+    def _validate(self):
+        if self.start_time >= self.end_time:
+            raise ValueError(
+                f"`start_time` ({self.start_time}) must be earlier than `end_time` ({self.end_time})."
+            )
+
+        for release in self.releases:
+            ReleaseSimulationManager(
+                release=release,
+                grid=self.grid,
+                start_time=self.start_time,
+                end_time=self.end_time,
+            )
+
+        builder = CDRForcingDatasetBuilder(
+            self.releases, self.model_reference_date, self.release_type
+        )
+        self._ds = builder.build()
+        return self
+
+    @property
+    def release_type(self) -> ReleaseType:
+        """Type of the release."""
+        return self.releases.release_type
+
+    @property
+    def ds(self) -> xr.Dataset:
+        """The xarray dataset containing release metadata and forcing variables."""
+        return self._ds
+
+    def plot_volume_flux(
+        self, start=None, end=None, release_names=INCLUDE_ALL_RELEASE_NAMES
+    ):
         """Plot the volume flux for each specified release within the given time range.
 
         Parameters
@@ -392,26 +399,38 @@ class CDRVolumePointSource:
             Start datetime for the plot. If None, defaults to `self.start_time`.
         end : datetime or None
             End datetime for the plot. If None, defaults to `self.end_time`.
-        releases : str, list of str, or "all", optional
-            A string or list of release names to plot.
-            If "all", the method will plot all releases.
-            The default is "all".
+        release_names : list[str], or str, optional
+            A list of release names to plot.
+            If a string equal to "all", all releases will be plotted.
+            Defaults to "all".
+
+        Raises
+        ------
+        ValueError
+            If self.releases are not of type VolumeRelease.
+            If `release_names` is not a list of strings or "all".
+            If any of the specified release names do not exist in `self.releases`.
         """
+        if self.release_type != ReleaseType.volume:
+            raise ValueError(
+                "plot_volume_flux is only supported when all releases are of type VolumeRelease."
+            )
 
         start = start or self.start_time
         end = end or self.end_time
 
-        # Handle "all" releases case
-        if releases == "all":
-            releases = [k for k in self.releases if k != "_tracer_metadata"]
-        # Validate input for release names
-        self._validate_release_input(releases)
+        valid_release_names = [r.name for r in self.releases]
+
+        if release_names == INCLUDE_ALL_RELEASE_NAMES:
+            release_names = valid_release_names
+
+        _validate_release_input(release_names, valid_release_names)
 
         data = self.ds["cdr_volume"]
 
         self._plot_line(
             data,
-            releases,
+            release_names,
             start,
             end,
             title="Volume flux of release(s)",
@@ -419,94 +438,180 @@ class CDRVolumePointSource:
         )
 
     def plot_tracer_concentration(
-        self, name: str, start=None, end=None, releases="all"
+        self,
+        tracer_name: str,
+        start=None,
+        end=None,
+        release_names=INCLUDE_ALL_RELEASE_NAMES,
     ):
         """Plot the concentration of a given tracer for each specified release within
         the given time range.
 
         Parameters
         ----------
-        name : str
+        tracer_name : str
             Name of the tracer to plot, e.g., "ALK", "DIC", etc.
         start : datetime or None
             Start datetime for the plot. If None, defaults to `self.start_time`.
         end : datetime or None
             End datetime for the plot. If None, defaults to `self.end_time`.
-        releases : str, list of str, or "all", optional
-            A string or list of release names to plot.
-            If "all", the method will plot all releases.
-            The default is "all".
+        release_names : list[str], or str, optional
+            A list of release names to plot.
+            If a string equal to "all", all releases will be plotted.
+            Defaults to "all".
+
+        Raises
+        ------
+        ValueError
+            If self.releases are not of type VolumeRelease.
+            If `release_names` is not a list of strings or "all".
+            If any of the specified release names do not exist in `self.releases`.
+            If `tracer_name` does not exist in self.ds["tracer_name"])
         """
+        if self.release_type != ReleaseType.volume:
+            raise ValueError(
+                "plot_tracer_concentration is only supported when all releases are of type VolumeRelease."
+            )
+
         start = start or self.start_time
         end = end or self.end_time
 
-        # Handle "all" releases case
-        if releases == "all":
-            releases = [k for k in self.releases if k != "_tracer_metadata"]
-        # Validate input for release names
-        self._validate_release_input(releases)
+        valid_release_names = [r.name for r in self.releases]
+
+        if release_names == INCLUDE_ALL_RELEASE_NAMES:
+            release_names = valid_release_names
+
+        _validate_release_input(release_names, valid_release_names)
 
         tracer_names = list(self.ds["tracer_name"].values)
-        if name not in tracer_names:
+        if tracer_name not in tracer_names:
             raise ValueError(
-                f"Tracer '{name}' not found. Available: {', '.join(tracer_names)}"
+                f"Tracer '{tracer_name}' not found. Available: {', '.join(tracer_names)}"
             )
 
-        tracer_index = tracer_names.index(name)
+        tracer_index = tracer_names.index(tracer_name)
         data = self.ds["cdr_tracer"].isel(ntracers=tracer_index)
 
-        if name == "temp":
+        if tracer_name == "temp":
             title = "Temperature of release water"
-        elif name == "salt":
+        elif tracer_name == "salt":
             title = "Salinity of release water"
         else:
-            title = f"{name} concentration of release(s)"
+            title = f"{tracer_name} concentration of release(s)"
 
         self._plot_line(
             data,
-            releases,
+            release_names,
             start,
             end,
             title=title,
             ylabel=f"{self.ds['tracer_unit'].isel(ntracers=tracer_index).values.item()}",
         )
 
-    def _plot_line(self, data, releases, start, end, title="", ylabel=""):
+    def plot_tracer_flux(
+        self,
+        tracer_name: str,
+        start=None,
+        end=None,
+        release_names=INCLUDE_ALL_RELEASE_NAMES,
+    ):
+        """Plot the flux of a given tracer for each specified release within the given
+        time range.
+
+        Parameters
+        ----------
+        tracer_name : str
+            Name of the tracer to plot, e.g., "ALK", "DIC", etc.
+        start : datetime or None
+            Start datetime for the plot. If None, defaults to `self.start_time`.
+        end : datetime or None
+            End datetime for the plot. If None, defaults to `self.end_time`.
+        release_names : list[str], or str, optional
+            A list of release names to plot.
+            If a string equal to "all", all releases will be plotted.
+            Defaults to "all".
+
+        Raises
+        ------
+        ValueError
+            If self.releases are not of type TracerPerturbation.
+            If `release_names` is not a list of strings or "all".
+            If any of the specified release names do not exist in `self.releases`.
+            If `tracer_name` does not exist in self.ds["tracer_name"])
+        """
+        if self.release_type != ReleaseType.tracer_perturbation:
+            raise ValueError(
+                "plot_tracer_flux is only supported when all releases are of type TracerPerturbation."
+            )
+
+        start = start or self.start_time
+        end = end or self.end_time
+
+        valid_release_names = [r.name for r in self.releases]
+
+        if release_names == INCLUDE_ALL_RELEASE_NAMES:
+            release_names = valid_release_names
+
+        _validate_release_input(release_names, valid_release_names)
+
+        tracer_names = list(self.ds["tracer_name"].values)
+        if tracer_name not in tracer_names:
+            raise ValueError(
+                f"Tracer '{tracer_name}' not found. Available: {', '.join(tracer_names)}"
+            )
+
+        tracer_index = tracer_names.index(tracer_name)
+        data = self.ds["cdr_trcflx"].isel(ntracers=tracer_index)
+
+        title = f"{tracer_name} flux of release(s)"
+
+        self._plot_line(
+            data,
+            release_names,
+            start,
+            end,
+            title=title,
+            ylabel=f"{self.ds['tracer_unit'].isel(ntracers=tracer_index).values.item()}",
+        )
+
+    def _plot_line(self, data, release_names, start, end, title="", ylabel=""):
         """Plots a line graph for the specified releases and time range."""
-        colors = self._get_release_colors()
+        valid_release_names = [r.name for r in self.releases]
+        colors = _get_release_colors(valid_release_names)
 
         fig, ax = plt.subplots(1, 1, figsize=(7, 4))
-        for release in releases:
-            ncdr = np.where(self.ds["release_name"].values == release)[0][0]
+        for name in release_names:
+            ncdr = np.where(self.ds["release_name"].values == name)[0].item()
             data.isel(ncdr=ncdr).plot(
                 ax=ax,
                 linewidth=2,
-                label=release,
-                color=colors[release],
+                label=name,
+                color=colors[name],
                 marker="x",
             )
 
-        if len(releases) > 0:
+        if len(release_names) > 0:
             ax.legend()
 
-        ax.set(title=title, ylabel=ylabel)
+        ax.set(title=title, ylabel=ylabel, xlabel="time")
         ax.set_xlim([start, end])
 
-    def plot_location_top_view(self, releases="all"):
-        """Plot the top-down view of release locations.
+    def plot_locations(self, release_names="all"):
+        """Plot centers of release locations in top-down view.
 
         Parameters
         ----------
-        releases : list of str or str, optional
-            A single release name (string) or a list of release names (strings) to plot.
-            Default is 'all', which will plot all releases.
+        release_names : list of str or "all", optional
+            A list of release names to plot.
+            If "all", the method will plot all releases.
+            The default is "all".
 
         Raises
         ------
         ValueError
+            If `release_names` is not a list of strings or "all".
+            If any of the specified release names do not exist in `self.releases`.
             If `self.grid` is not set.
-            If `releases` is not a string or list of strings.
-            If any of the specified releases do not exist in `self.releases`.
         """
         # Ensure that the grid is provided
         if self.grid is None:
@@ -514,155 +619,70 @@ class CDRVolumePointSource:
                 "A grid must be provided for plotting. Please pass a valid `Grid` object."
             )
 
-        # Handle "all" releases case
-        if releases == "all":
-            releases = [k for k in self.releases if k != "_tracer_metadata"]
+        valid_release_names = [r.name for r in self.releases]
 
-        # Validate input for release names
-        self._validate_release_input(releases)
+        if release_names == "all":
+            release_names = valid_release_names
+
+        _validate_release_input(release_names, valid_release_names)
 
-        # Proceed with plotting
-        field = self.grid.ds.mask_rho
         lon_deg = self.grid.ds.lon_rho
         lat_deg = self.grid.ds.lat_rho
         if self.grid.straddle:
             lon_deg = xr.where(lon_deg > 180, lon_deg - 360, lon_deg)
-        field = field.assign_coords({"lon": lon_deg, "lat": lat_deg})
+        trans = get_projection(lon_deg, lat_deg)
+        fig, ax = plt.subplots(1, 1, figsize=(13, 7), subplot_kw={"projection": trans})
 
+        # Plot blue background on map
+        field = self.grid.ds.mask_rho
+        field = field.where(field)
+        field = field.assign_coords({"lon": lon_deg, "lat": lat_deg})
         vmax = 6
         vmin = 0
         cmap = plt.colormaps.get_cmap("Blues")
+        cmap.set_bad(color="gray")
         kwargs = {"vmax": vmax, "vmin": vmin, "cmap": cmap}
+        plot_2d_horizontal_field(field, kwargs=kwargs, ax=ax, add_colorbar=False)
+
+        # Plot release locations
+        colors = _get_release_colors(valid_release_names)
+        _plot_location(
+            grid=self.grid,
+            releases=[self.releases[name] for name in release_names],
+            ax=ax,
+            colors=colors,
+        )
 
-        trans = _get_projection(lon_deg, lat_deg)
-
-        fig, ax = plt.subplots(1, 1, figsize=(13, 7), subplot_kw={"projection": trans})
-
-        _plot(field, kwargs=kwargs, ax=ax, c=None, add_colorbar=False)
-
-        proj = ccrs.PlateCarree()
-
-        colors = self._get_release_colors()
-
-        for name in releases:
-            # transform coordinates to projected space
-            transformed_lon, transformed_lat = trans.transform_point(
-                self.releases[name]["lon"],
-                self.releases[name]["lat"],
-                proj,
-            )
-
-            ax.plot(
-                transformed_lon,
-                transformed_lat,
-                marker="x",
-                markersize=8,
-                markeredgewidth=2,
-                label=name,
-                color=colors[name],
-            )
-
-        ax.set_title("Release locations")
-        ax.legend(loc="center left", bbox_to_anchor=(1.1, 0.5))
-
-    def plot_location_side_view(self, release: str = None):
-        """Plot the release location from a side view, showing bathymetry sections along
-        both fixed longitude and latitude.
+    def plot_distribution(self, release_name: str, mark_release_center: bool = True):
+        """Plot the release location from a top and side view.
 
-        This method creates two plots:
+        This method creates three plots:
 
-        - A bathymetry section along a fixed longitude (latitudinal view),
-          with the release location marked by an "x".
-        - A bathymetry section along a fixed latitude (longitudinal view),
-          with the release location also marked by an "x".
+        - A top view of the release distribution.
+        - A side view of the release distribution along a fixed longitude.
+        - A side view of the release distribution along a fixed latitude.
 
         Parameters
         ----------
-        release : str, optional
-            Name of the release to plot. If only one release is available,
-            it is used by default. If multiple releases are available, this must be specified.
+        release_name : str
+            Name of the release to plot.
+        mark_release_center : bool, default True
+            Whether to mark the center of the release distribution with an "x".
 
         Raises
         ------
         ValueError
-
             If `self.grid` is not set.
-            If the specified `release` does not exist in `self.releases`.
-            If no `release` is provided when multiple releases are available.
+            If the specified `release_name` does not exist in `self.releases`.
         """
         if self.grid is None:
             raise ValueError(
                 "A grid must be provided for plotting. Please pass a valid `Grid` object."
             )
 
-        valid_releases = [r for r in self.releases if r != "_tracer_metadata"]
-        if release is None:
-            if len(valid_releases) == 1:
-                release = valid_releases[0]
-            else:
-                raise ValueError(
-                    f"Multiple releases found: {valid_releases}. Please specify a single release to plot."
-                )
-
-        self._validate_release_input(release, list_allowed=False)
-
-        def _plot_bathymetry_section(
-            ax, h, dim, fixed_val, coord_deg, resolution, title
-        ):
-            """Plots a bathymetry section along a fixed latitude or longitude.
-
-            Parameters
-            ----------
-            ax : matplotlib.axes.Axes
-                The axis on which the plot will be drawn.
-
-            h : xarray.DataArray
-                The bathymetry data to plot.
-
-            dim : str
-                The dimension along which to plot the section, either "lat" or "lon".
-
-            fixed_val : float
-                The fixed value of latitude or longitude for the section.
-
-            coord_deg : xarray.DataArray
-                The array of latitude or longitude coordinates.
-
-            resolution : float
-                The resolution at which to generate the coordinate range.
-
-            title : str
-                The title for the plot.
-
-            Returns
-            -------
-            None
-                The function does not return anything. It directly plots the bathymetry section on the provided axis.
-            """
-            # Determine coordinate names and build target range
-            var_range = _generate_coordinate_range(
-                coord_deg.min().values, coord_deg.max().values, resolution
-            )
-            var_name = "lat" if dim == "lon" else "lon"
-            range_da = xr.DataArray(
-                var_range,
-                dims=[var_name],
-                attrs={"units": "°N" if var_name == "lat" else "°E"},
-            )
-
-            # Construct target coordinates for regridding
-            target_coords = {dim: [fixed_val], var_name: range_da}
-            regridder = LateralRegridFromROMS(h, target_coords)
-            section = regridder.apply(h)
-            section, _ = _remove_edge_nans(section, var_name)
-
-            # Plot the bathymetry section
-            section.plot(ax=ax, color="k")
-            ax.fill_between(section[var_name], section.squeeze(), y2=0, color="#deebf7")
-            ax.invert_yaxis()
-            ax.set_xlabel("Latitude [°N]" if var_name == "lat" else "Longitude [°E]")
-            ax.set_ylabel("Depth [m]")
-            ax.set_title(title)
+        valid_release_names = [r.name for r in self.releases]
+        _validate_release_input(release_name, valid_release_names, list_allowed=False)
+        release = self.releases[release_name]
 
         # Prepare grid coordinates
         lon_deg = self.grid.ds.lon_rho
@@ -670,74 +690,88 @@ class CDRVolumePointSource:
         if self.grid.straddle:
             lon_deg = xr.where(lon_deg > 180, lon_deg - 360, lon_deg)
 
-        resolution = self.grid._infer_nominal_horizontal_resolution()
-        h = self.grid.ds.h.assign_coords({"lon": lon_deg, "lat": lat_deg})
-
-        # Set up plot
-        fig, axs = plt.subplots(2, 1, figsize=(7, 8))
-
-        # Plot along fixed longitude
-        _plot_bathymetry_section(
-            ax=axs[0],
-            h=h,
-            dim="lon",
-            fixed_val=self.releases[release]["lon"],
-            coord_deg=lat_deg,
-            resolution=resolution,
-            title=f"Longitude: {self.releases[release]['lon']}°E",
+        # Setup figure
+        fig = plt.figure(figsize=(12, 5.5))
+        gs = gridspec.GridSpec(nrows=2, ncols=2, figure=fig)
+        trans = get_projection(lon_deg, lat_deg)
+        ax0 = fig.add_subplot(gs[:, 0], projection=trans)
+        ax1 = fig.add_subplot(gs[0, 1])
+        ax2 = fig.add_subplot(gs[1, 1])
+
+        # Top down view plot of depth-integrated Gaussian
+        depth_integrated_field = _map_horizontal_gaussian(self.grid, release)
+        depth_integrated_field = depth_integrated_field.assign_coords(
+            {"lon": lon_deg, "lat": lat_deg}
+        )
+        cmap = plt.colormaps.get_cmap("RdPu")
+        cmap.set_bad(color="gray")
+        plot_2d_horizontal_field(
+            field=depth_integrated_field.where(self.grid.ds.mask_rho),
+            ax=ax0,
+            kwargs={"cmap": cmap},
+            add_colorbar=False,
+            title="Depth-integrated distribution",
         )
+        if mark_release_center:
+            _plot_location(
+                grid=self.grid, releases=[release], ax=ax0, include_legend=False
+            )
 
-        colors = self._get_release_colors()
+        # Spread horizontal Gaussian field into the vertical
+        distribution_3d = _map_3d_gaussian(self.grid, release, depth_integrated_field)
 
-        axs[0].plot(
-            self.releases[release]["lat"],
-            self.releases[release]["depth"],
-            color=colors[release],
-            marker="x",
-            markersize=8,
-            markeredgewidth=2,
-        )
+        release_lon = normalize_longitude(release.lon, self.grid.straddle)
 
-        # Plot along fixed latitude
-        _plot_bathymetry_section(
-            ax=axs[1],
-            h=h,
-            dim="lat",
-            fixed_val=self.releases[release]["lat"],
-            coord_deg=lon_deg,
-            resolution=resolution,
-            title=f"Latitude: {self.releases[release]['lat']}°N",
+        plot(
+            field=distribution_3d,
+            grid_ds=self.grid.ds,
+            lon=release_lon,
+            ax=ax1,
+            cmap_name="RdPu",
+            add_colorbar=False,
         )
-        axs[1].plot(
-            self.releases[release]["lon"],
-            self.releases[release]["depth"],
-            color=colors[release],
-            marker="x",
-            markersize=8,
-            markeredgewidth=2,
+        ax1.set(title=f"Longitude: {release.lon}°E", xlabel="Latitude [°N]")
+
+        plot(
+            field=distribution_3d,
+            grid_ds=self.grid.ds,
+            lat=release.lat,
+            ax=ax2,
+            cmap_name="RdPu",
+            add_colorbar=False,
         )
+        ax2.set(title=f"Latitude: {release.lat}°N", xlabel="Longitude [°E]")
+
+        if mark_release_center:
+            kwargs = {
+                "color": "k",
+                "marker": "x",
+                "markersize": 8,
+                "markeredgewidth": 2,
+            }
+            ax1.plot(release.lat, release.depth, **kwargs)
+            ax2.plot(release_lon, release.depth, **kwargs)
 
         # Adjust layout and title
-        fig.subplots_adjust(hspace=0.4)
-        fig.suptitle(f"Release location for: {release}")
+        fig.subplots_adjust(hspace=0.45)
+        fig.suptitle(f"Release distribution for: {release_name}")
 
     def save(
         self,
-        filepath: Union[str, Path],
-    ) -> None:
+        filepath: str | Path,
+    ) -> list[Path]:
         """Save the volume source with tracers to netCDF4 file.
 
         Parameters
         ----------
-        filepath : Union[str, Path]
+        filepath : str | Path
             The base path and filename for the output files.
 
         Returns
         -------
-        List[Path]
+        list[Path]
             A list of `Path` objects for the saved files. Each element in the list corresponds to a file that was saved.
         """
-
         # Ensure filepath is a Path object
         filepath = Path(filepath)
 
@@ -752,375 +786,393 @@ class CDRVolumePointSource:
 
         return saved_filenames
 
-    def to_yaml(self, filepath: Union[str, Path]) -> None:
+    @model_serializer
+    def _serialize(self) -> dict:
+        return to_dict(self)
+
+    def to_yaml(self, filepath: str | Path) -> None:
         """Export the parameters of the class to a YAML file, including the version of
         roms-tools.
 
         Parameters
         ----------
-        filepath : Union[str, Path]
+        filepath : str | Path
             The path to the YAML file where the parameters will be saved.
         """
+        forcing_dict = self.model_dump()
+        metadata = self.releases[0].get_tracer_metadata()
+        forcing_dict["CDRForcing"]["_tracer_metadata"] = metadata
 
-        _to_yaml(self, filepath)
+        write_to_yaml(forcing_dict, filepath)
 
     @classmethod
-    def from_yaml(cls, filepath: Union[str, Path]) -> "CDRVolumePointSource":
-        """Create an instance of the CDRVolumePointSource class from a YAML file.
+    def from_yaml(cls, filepath: str | Path) -> "CDRForcing":
+        """Create an instance of the CDRForcing class from a YAML file.
 
         Parameters
         ----------
-        filepath : Union[str, Path]
+        filepath : str | Path
             The path to the YAML file from which the parameters will be read.
 
         Returns
         -------
-        CDRVolumePointSource
-            An instance of the CDRVolumePointSource class.
+        CDRForcing
+            An instance of the CDRForcing class.
         """
         filepath = Path(filepath)
 
         grid = Grid.from_yaml(filepath)
-        params = _from_yaml(cls, filepath)
+        params = from_yaml(cls, filepath)
+        params.pop("_tracer_metadata", None)
 
         return cls(grid=grid, **params)
 
-    def _input_checks(
-        self,
-        name,
-        lat,
-        lon,
-        depth,
-        times,
-        volume_fluxes,
-        tracer_concentrations,
-    ):
-        """Perform various input checks on release parameters.
-
-        - Checks that latitude is between -90 and 90.
-        - Checks that depth is non-negative.
-        - Ensures 'times' is a list of datetime objects and is monotonically increasing.
-        - Verifies that times are within the defined start and end time.
-        - Ensures volume fluxes is either a list of floats/ints or a single float/int.
-        - Ensures each tracer concentration is either a float/int or a list of floats/ints.
-        - Ensures the lengths of 'volume_fluxes' and 'tracer_concentrations' match the length of 'times' if they are lists.
-        - Ensures all entries in 'volume_fluxes' and 'tracer_concentrations' are non-negative.
-        """
 
-        # Check that lat is valid
-        if not (-90 <= lat <= 90):
-            raise ValueError(
-                f"Invalid latitude {lat}. Latitude must be between -90 and 90."
-            )
+def _validate_release_input(releases, valid_releases, list_allowed=True):
+    """Validates the input for release names in plotting methods to ensure they are in
+    an acceptable format and exist within the set of valid releases.
 
-        # Check that depth is non-negative
-        if depth < 0:
-            raise ValueError(
-                f"Invalid depth {depth}. Depth must be a non-negative number."
-            )
+    This method ensures that the `releases` parameter is either a single release name (string) or a list
+    of release names (strings), and checks that each release exists in the set of valid releases.
 
-        # Ensure that times is a list of datetimes
-        if not all(isinstance(t, datetime) for t in times):
-            raise ValueError(
-                f"If 'times' is provided, all entries must be datetime objects. Got: {[type(t) for t in times]}"
-            )
+    Parameters
+    ----------
+    releases : str or list of str
+        A single release name as a string, or a list of release names (strings) to validate.
+
+    list_allowed : bool, optional
+        If `True`, a list of release names is allowed. If `False`, only a single release name (string)
+        is allowed. Default is `True`.
+
+    Raises
+    ------
+    ValueError
+        If `releases` is not a string or list of strings, or if any release name is invalid (not in `self.releases`).
+
+    Notes
+    -----
+    This method checks that the `releases` input is in a valid format (either a string or a list of strings),
+    and ensures each release is present in the set of valid releases defined in `self.releases`. Invalid releases
+    are reported in the error message.
+
+    If `list_allowed` is set to `False`, only a single release name (string) will be accepted. Otherwise, a
+    list of release names is also acceptable.
+    """
+    # Ensure that a list of releases is only allowed if `list_allowed` is True
+    if not list_allowed and not isinstance(releases, str):
+        raise ValueError(
+            f"Only a single release name (string) is allowed. Got: {releases}"
+        )
 
-        if len(times) > 0:
-            if len(times) > 1:
-                # Check that times is strictly monotonically increasing sequence
-                if not all(t1 < t2 for t1, t2 in zip(times, times[1:])):
-                    raise ValueError(
-                        f"The 'times' list must be strictly monotonically increasing. Got: {[t for t in times]}"
-                    )
+    if isinstance(releases, str):
+        releases = [releases]  # Convert to list if a single string is provided
+    elif isinstance(releases, list):
+        if not all(isinstance(r, str) for r in releases):
+            raise ValueError("All elements in `releases` list must be strings.")
+    else:
+        raise ValueError(
+            "`releases` should be a string (single release name) or a list of strings (release names)."
+        )
 
-            # Check that first time is not before start_time
-            if times[0] < self.start_time:
-                raise ValueError(
-                    f"First entry in `times` ({times[0]}) cannot be before `self.start_time` ({self.start_time})."
-                )
+    # Validate that the specified releases exist in self.releases
+    invalid_releases = [
+        release for release in releases if release not in valid_releases
+    ]
+    if invalid_releases:
+        raise ValueError(f"Invalid releases: {', '.join(invalid_releases)}")
 
-            # Check that last time is not after end_time
-            if times[-1] > self.end_time:
-                raise ValueError(
-                    f"Last entry in `times` ({times[-1]}) cannot be after `self.end_time` ({self.end_time})."
-                )
 
-        # Ensure volume fluxes is either a list of floats/ints or a single float/int
-        if not isinstance(volume_fluxes, (float, int)) and not (
-            isinstance(volume_fluxes, list)
-            and all(isinstance(v, (float, int)) for v in volume_fluxes)
-        ):
-            raise ValueError(
-                "Invalid 'volume_fluxes' input: must be a float/int or a list of floats/ints."
-            )
+def _get_release_colors(valid_releases: list[str]) -> dict[str, tuple]:
+    """Returns a dictionary of colors for the valid releases, based on a consistent
+    colormap.
 
-        # Ensure each tracer concentration is either a float/int or a list of floats/ints
-        for key, val in tracer_concentrations.items():
-            if not isinstance(val, (float, int)) and not (
-                isinstance(val, list) and all(isinstance(v, (float, int)) for v in val)
-            ):
-                raise ValueError(
-                    f"Invalid tracer concentration for '{key}': must be a float/int or a list of floats/ints."
-                )
+    Parameters
+    ----------
+    valid_releases : List[str]
+        List of release names to assign colors to.
+
+    Returns
+    -------
+    Dict[str, tuple]
+        A dictionary where the keys are release names and the values are their corresponding colors,
+        assigned based on the order of releases in the valid releases list.
+
+    Raises
+    ------
+    ValueError
+        If the number of valid releases exceeds the available colormap capacity.
+
+    Notes
+    -----
+    The colormap is chosen dynamically based on the number of valid releases:
+
+    - If there are 10 or fewer releases, the "tab10" colormap is used.
+    - If there are more than 10 but fewer than or equal to 20 releases, the "tab20" colormap is used.
+    - For more than 20 releases, the "tab20b" colormap is used.
+    """
+    # Determine the colormap based on the number of releases
+    if len(valid_releases) <= 10:
+        color_map = plt.get_cmap("tab10")
+    elif len(valid_releases) <= 20:
+        color_map = plt.get_cmap("tab20")
+    else:
+        color_map = plt.get_cmap("tab20b")
+
+    # Ensure the number of releases doesn't exceed the available colormap capacity
+    if len(valid_releases) > color_map.N:
+        raise ValueError(
+            f"Too many releases. The selected colormap supports up to {color_map.N} releases."
+        )
 
-        # Ensure that time series for 'times', 'volume_fluxes', and 'tracer_concentrations' are all the same length
-        num_times = len(times)
+    # Create a dictionary of colors based on the release indices
+    colors = {name: color_map(i) for i, name in enumerate(valid_releases)}
 
-        # Check that volume fluxes is either a constant or has the same length as 'times'
-        if isinstance(volume_fluxes, list) and len(volume_fluxes) != num_times:
-            raise ValueError(
-                f"The length of `volume_fluxes` ({len(volume_fluxes)}) does not match the length of `times` ({num_times})."
-            )
+    return colors
 
-        # Check that tracer_concentrations are either constants or have the same length as 'times'
-        for key, tracer_values in tracer_concentrations.items():
-            if isinstance(tracer_values, list) and len(tracer_values) != num_times:
-                raise ValueError(
-                    f"The length of tracer '{key}' ({len(tracer_values)}) does not match the length of `times` ({num_times})."
-                )
 
-        # Check that volume fluxes and tracer concentrations are valid
-        if isinstance(volume_fluxes, (float, int)) and volume_fluxes < 0:
-            raise ValueError(f"Volume flux must be non-negative. Got: {volume_fluxes}")
-        elif isinstance(volume_fluxes, list) and not all(v >= 0 for v in volume_fluxes):
-            raise ValueError(
-                f"All entries in `volume_fluxes` must be non-negative. Got: {volume_fluxes}"
-            )
-        for key, tracer_values in tracer_concentrations.items():
-            if key != "temp":
-                if isinstance(tracer_values, (float, int)) and tracer_values < 0:
-                    raise ValueError(
-                        f"The concentration of tracer '{key}' must be non-negative. Got: {tracer_values}"
-                    )
-                elif isinstance(tracer_values, list) and not all(
-                    c >= 0 for c in tracer_values
-                ):
-                    raise ValueError(
-                        f"All entries in `tracer_concentrations['{key}']` must be non-negative. Got: {tracer_values}"
-                    )
-
-    def _handle_simulation_endpoints(self, times, volume_fluxes, tracer_concentrations):
-        """Ensure that the release time series starts at self.start_time and ends at
-        self.end_time.
-
-        If `volume_fluxes` is a list and does not cover the endpoints, zero volume fluxes are added.
-        Tracer concentrations are extended accordingly by duplicating endpoint values.
-        """
+def _validate_release_location(grid, release: Release):
+    """Validates the closest grid location for a release site.
 
-        if len(times) > 0:
-            # Handle start_time
-            if times[0] != self.start_time:
-                if isinstance(volume_fluxes, list):
-                    volume_fluxes.insert(0, 0.0)
+    This function ensures that the given release site (lat, lon, depth) lies
+    within the ocean portion of the model grid domain. It:
 
-                for key, vals in tracer_concentrations.items():
-                    if isinstance(vals, list):
-                        vals.insert(0, vals[0])
+    - Checks if the point is within the grid domain (with buffer for boundary artifacts).
+    - Verifies that the location is not on land.
+    - Verifies that the location is not below the seafloor.
+    """
+    if grid:
+        # Adjust longitude based on whether it crosses the International Date Line (straddle case)
+        if grid.straddle:
+            lon = xr.where(release.lon > 180, release.lon - 360, release.lon)
+        else:
+            lon = xr.where(release.lon < 0, release.lon + 360, release.lon)
 
-                times.insert(0, self.start_time)
+        dx = 1 / grid.ds.pm
+        dy = 1 / grid.ds.pn
 
-            # Handle end_time
-            if times[-1] != self.end_time:
-                if isinstance(volume_fluxes, list):
-                    volume_fluxes.append(0.0)
+        # Compute the maximum half-diagonal grid spacing across the domain
+        max_grid_spacing = (np.sqrt(dx**2 + dy**2) / 2).max()
 
-                for key, vals in tracer_concentrations.items():
-                    if isinstance(vals, list):
-                        vals.append(vals[-1])
+        # Apply a 10% safety margin
+        max_grid_spacing *= 1.1
 
-                times.append(self.end_time)
+        # Compute great-circle distance to all grid points
+        dist = gc_dist(grid.ds.lon_rho, grid.ds.lat_rho, lon, release.lat)
+        dist_min = dist.min(dim=["eta_rho", "xi_rho"])
 
-        else:
-            times = [self.start_time, self.end_time]
+        if dist_min > max_grid_spacing:
+            raise ValueError(
+                f"Release site '{release.name}' is outside of the grid domain. "
+                "Ensure the provided (lat, lon) falls within the model grid extent."
+            )
 
-        return times, volume_fluxes, tracer_concentrations
+        # Find the indices of the closest grid cell
+        indices = np.where(dist == dist_min)
+        eta_rho = indices[0][0]
+        xi_rho = indices[1][0]
 
-    def _validate_release_location(self, name, lat, lon, depth):
-        """Validates the closest grid location for a release site.
+        eta_max = grid.ds.sizes["eta_rho"] - 1
+        xi_max = grid.ds.sizes["xi_rho"] - 1
 
-        This function ensures that the given release site (lat, lon, depth) lies
-        within the ocean portion of the model grid domain. It:
+        if eta_rho in [0, eta_max] or xi_rho in [0, xi_max]:
+            raise ValueError(
+                f"Release site '{release.name}' is located too close to the grid boundary. "
+                "Place release location (lat, lon) away from grid boundaries."
+            )
 
-        - Checks if the point is within the grid domain (with buffer for boundary artifacts).
-        - Verifies that the location is not on land.
-        - Verifies that the location is not below the seafloor.
+        if grid.ds.mask_rho[eta_rho, xi_rho].values == 0:
+            raise ValueError(
+                f"Release site '{release.name}' is on land. "
+                "Please provide coordinates (lat, lon) over ocean."
+            )
 
-        Parameters
-        ----------
-        name : str
-            A unique identifier for the release location.
-        lat : float
-            Latitude of the release location.
-        lon : float
-            Longitude of the release location.
-        depth : float
-            Depth (positive, in meters) of the release location.
+        if grid.ds.h[eta_rho, xi_rho].values < release.depth:
+            raise ValueError(
+                f"Release site '{release.name}' lies below the seafloor. "
+                f"Seafloor depth is {grid.ds.h[eta_rho, xi_rho].values:.2f} m, "
+                f"but requested depth is {release.depth:.2f} m. Adjust depth or location (lat, lon)."
+            )
 
-        Raises
-        ------
-        ValueError
-            If the location is:
-                - Outside the model grid.
-                - On the boundary of the grid domain (eta_rho, xi_rho = 0 or max).
-                - On land (based on `mask_rho`).
-                - Below the ocean bottom (`h < depth`).
-        Warning
-            If no grid is available to validate the location.
-        """
-        if self.grid:
-            # Adjust longitude based on whether it crosses the International Date Line (straddle case)
-            if self.grid.straddle:
-                lon = xr.where(lon > 180, lon - 360, lon)
-            else:
-                lon = xr.where(lon < 0, lon + 360, lon)
-
-            dx = 1 / self.grid.ds.pm
-            dy = 1 / self.grid.ds.pn
-            max_grid_spacing = np.sqrt(dx**2 + dy**2) / 2
-
-            # Compute great-circle distance to all grid points
-            dist = gc_dist(self.grid.ds.lon_rho, self.grid.ds.lat_rho, lon, lat)
-            dist_min = dist.min(dim=["eta_rho", "xi_rho"])
-
-            if (dist_min > max_grid_spacing).all():
-                raise ValueError(
-                    f"Release site '{name}' is outside of the grid domain. "
-                    "Ensure the provided (lat, lon) falls within the model grid extent."
-                )
+    else:
+        logging.warning(
+            "Grid not provided: cannot verify whether the specified lat/lon/depth location is within the domain or on land. "
+            "Please check manually or provide a grid when instantiating the class."
+        )
 
-            # Find the indices of the closest grid cell
-            indices = np.where(dist == dist_min)
-            eta_rho = indices[0][0]
-            xi_rho = indices[1][0]
 
-            eta_max = self.grid.ds.sizes["eta_rho"] - 1
-            xi_max = self.grid.ds.sizes["xi_rho"] - 1
+def _map_horizontal_gaussian(grid: Grid, release: Release):
+    """Map a tracer release to the ROMS grid as a normalized 2D Gaussian distribution.
 
-            if eta_rho in [0, eta_max] or xi_rho in [0, xi_max]:
-                raise ValueError(
-                    f"Release site '{name}' is located too close to the grid boundary. "
-                    "Place release location (lat, lon) away from grid boundaries."
-                )
+    The tracer is centered at the nearest grid cell to the release location, then smoothed
+    using a Gaussian filter (via GCM-Filters) with horizontal scale `release.hsc`. Land points
+    are masked out, and the distribution is renormalized to integrate to 1 over the ocean.
 
-            if self.grid.ds.mask_rho[eta_rho, xi_rho].values == 0:
-                raise ValueError(
-                    f"Release site '{name}' is on land. "
-                    "Please provide coordinates (lat, lon) over ocean."
-                )
+    Parameters
+    ----------
+    grid : Grid
+        ROMS grid object with grid metrics and land mask.
+    release : Release
+        Release location and horizontal scale (hsc) in meters.
+
+    Returns
+    -------
+    delta_smooth : xarray.DataArray
+        Normalized 2D tracer distribution on the ROMS grid (zero over land).
+    """
+    # Find closest grid cell center
+    target_coords = get_target_coords(grid)
+    lon = release.lon
+    if target_coords["straddle"]:
+        lon = xr.where(lon > 180, lon - 360, lon)
+    else:
+        lon = xr.where(lon < 0, lon + 360, lon)
+    dist = gc_dist(target_coords["lon"], target_coords["lat"], lon, release.lat)
 
-            if self.grid.ds.h[eta_rho, xi_rho].values < depth:
-                raise ValueError(
-                    f"Release site '{name}' lies below the seafloor. "
-                    f"Seafloor depth is {self.grid.ds.h[eta_rho, xi_rho].values:.2f} m, "
-                    f"but requested depth is {depth:.2f} m. Adjust depth or location (lat, lon)."
-                )
+    if release.hsc == 0:
+        # Find the indices of the closest grid cell
+        indices = dist.argmin(dim=["eta_rho", "xi_rho"])
+        eta_rho = indices["eta_rho"].values
+        xi_rho = indices["xi_rho"].values
 
-        else:
-            logging.warning(
-                "Grid not provided: cannot verify whether the specified lat/lon/depth location is within the domain or on land. "
-                "Please check manually or provide a grid when instantiating the class."
-            )
+        # Create a delta function at the center of the Gaussian release
+        distribution_2d = xr.zeros_like(grid.ds.mask_rho)
+        distribution_2d[eta_rho, xi_rho] = 1
 
-    def _validate_release_input(self, releases, list_allowed=True):
-        """Validates the input for release names in plotting methods to ensure they are
-        in an acceptable format and exist within the set of valid releases.
+    else:
+        frac = np.exp(-((dist / release.hsc) ** 2))
+        distribution_2d = frac.where(frac > 1e-3, 0.0)
 
-        This method ensures that the `releases` parameter is either a single release name (string) or a list
-        of release names (strings), and checks that each release exists in the set of valid releases.
+        # Mask out land
+        distribution_2d = distribution_2d.where(grid.ds.mask_rho, 0.0)
 
-        Parameters
-        ----------
-        releases : str or list of str
-            A single release name as a string, or a list of release names (strings) to validate.
+        # Renormalize so the integral over ocean points sums to 1
+        integral = distribution_2d.sum(dim=["eta_rho", "xi_rho"])
+        distribution_2d = distribution_2d / integral
 
-        list_allowed : bool, optional
-            If `True`, a list of release names is allowed. If `False`, only a single release name (string)
-            is allowed. Default is `True`.
+    return distribution_2d
 
-        Raises
-        ------
-        ValueError
-            If `releases` is not a string or list of strings, or if any release name is invalid (not in `self.releases`).
 
-        Notes
-        -----
-        This method checks that the `releases` input is in a valid format (either a string or a list of strings),
-        and ensures each release is present in the set of valid releases defined in `self.releases`. Invalid releases
-        are reported in the error message.
+def _map_3d_gaussian(
+    grid: Grid, release: Release, distribution_2d: xr.DataArray
+) -> xr.DataArray:
+    """Extends 2D Gaussian to 3D Gaussian.
 
-        If `list_allowed` is set to `False`, only a single release name (string) will be accepted. Otherwise, a
-        list of release names is also acceptable.
-        """
+    Parameters
+    ----------
+    grid : Grid
+        ROMS grid object with methods and attributes used for horizontal resolution,
+        depth computation, and straddling logic.
+    release : Release
+        Release object containing coordinates (`lat`, `lon`, `depth`) and vertical
+        spread (`vsc`) for the Gaussian distribution.
+    distribution_2d : xr.DataArray
+        2D horizontal tracer field defined on the ROMS grid.
+
+    Returns
+    -------
+    xr.DataArray
+        3D tracer distribution (z vs lat/lon) with Gaussian vertical structure.
+    """
+    # Compute depth at rho-points (3D: s_rho, eta_rho, xi_rho)
+    depth = compute_depth_coordinates(
+        grid.ds, zeta=0, depth_type="layer", location="rho"
+    )
+
+    # Initialize 3D distribution with zeros
+    distribution_3d = xr.zeros_like(depth)
+
+    if release.vsc == 0:
+        # Find vertical index closest to release depth
+        abs_diff = abs(depth - release.depth)
+        vertical_idx = abs_diff.argmin(dim="s_rho")
+        # Stack 2D distribution at that vertical level
+        distribution_3d[{"s_rho": vertical_idx}] = distribution_2d
+    else:
+        # Compute layer thickness
+        depth_interface = compute_depth_coordinates(
+            grid.ds, zeta=0, depth_type="interface", location="rho"
+        )
+        dz = depth_interface.diff("s_w").rename({"s_w": "s_rho"})
 
-        # Ensure that a list of releases is only allowed if `list_allowed` is True
-        if not list_allowed and not isinstance(releases, str):
-            raise ValueError(
-                f"Only a single release name (string) is allowed. Got: {releases}"
-            )
+        # Compute vertical Gaussian shape
+        exponent = -(((depth - release.depth) / release.vsc) ** 2)
+        vertical_profile = np.exp(exponent)
 
-        if isinstance(releases, str):
-            releases = [releases]  # Convert to list if a single string is provided
-        elif isinstance(releases, list):
-            if not all(isinstance(r, str) for r in releases):
-                raise ValueError("All elements in `releases` list must be strings.")
-        else:
-            raise ValueError(
-                "`releases` should be a string (single release name) or a list of strings (release names)."
-            )
+        # Apply vertical Gaussian scaling
+        distribution_3d = distribution_2d * vertical_profile * dz
 
-        # Validate that the specified releases exist in self.releases
-        valid_releases = [k for k in self.releases if k != "_tracer_metadata"]
-        invalid_releases = [
-            release for release in releases if release not in valid_releases
-        ]
-        if invalid_releases:
-            raise ValueError(f"Invalid releases: {', '.join(invalid_releases)}")
+        # Normalize
+        distribution_3d /= release.vsc * np.sqrt(np.pi)
+        distribution_3d /= distribution_3d.sum()
 
-    def _get_release_colors(self):
-        """Returns a dictionary of colors for the valid releases, based on a consistent
-        colormap.
+    return distribution_3d
 
-        Parameters
-        ----------
-        None
 
-        Returns
-        -------
-        dict
-            A dictionary where the keys are release names and the values are their corresponding colors,
-            assigned based on the order of releases in the valid releases list.
+def _plot_location(
+    grid: Grid,
+    releases: ReleaseCollector,
+    ax: Axes,
+    colors: dict[str, tuple] | None = None,
+    include_legend: bool = True,
+) -> None:
+    """Plot the center location of each release on a top-down map view.
 
-        Raises
-        ------
-        ValueError
-            If the number of valid releases exceeds the available colormap capacity.
+    Each release is represented as a point on the map, with its color
+    determined by the `colors` dictionary.
 
-        Notes
-        -----
-        The colormap is chosen dynamically based on the number of valid releases:
+    Parameters
+    ----------
+    grid : Grid
+        The grid object defining the spatial extent and coordinate system for the plot.
 
-        - If there are 10 or fewer releases, the "tab10" colormap is used.
-        - If there are more than 10 but fewer than or equal to 20 releases, the "tab20" colormap is used.
-        - For more than 20 releases, the "tab20b" colormap is used.
-        """
+    releases : ReleaseCollector
+        Collection of `Release` objects to plot. Each `Release` must have `.lat`, `.lon`,
+        and `.name` attributes.
 
-        valid_releases = [k for k in self.releases if k != "_tracer_metadata"]
+    ax : matplotlib.axes.Axes
+        The Matplotlib axis object to plot on.
 
-        # Determine the colormap based on the number of releases
-        if len(valid_releases) <= 10:
-            color_map = cm.get_cmap("tab10")
-        elif len(valid_releases) <= 20:
-            color_map = cm.get_cmap("tab20")
-        else:
-            color_map = cm.get_cmap("tab20b")
+    colors : dict of str to tuple, optional
+        Optional dictionary mapping release names to RGBA color tuples. If not provided,
+        all releases are plotted in a default color (`"#dd1c77"`).
 
-        # Ensure the number of releases doesn't exceed the available colormap capacity
-        if len(valid_releases) > color_map.N:
-            raise ValueError(
-                f"Too many releases. The selected colormap supports up to {color_map.N} releases."
-            )
+    include_legend : bool, default True
+        Whether to include a legend showing release names.
 
-        # Create a dictionary of colors based on the release indices
-        colors = {name: color_map(i) for i, name in enumerate(valid_releases)}
+    Returns
+    -------
+    None
+    """
+    lon_deg = grid.ds.lon_rho
+    lat_deg = grid.ds.lat_rho
+    if grid.straddle:
+        lon_deg = xr.where(lon_deg > 180, lon_deg - 360, lon_deg)
+    trans = get_projection(lon_deg, lat_deg)
+
+    proj = ccrs.PlateCarree()
+
+    for release in releases:
+        # transform coordinates to projected space
+        transformed_lon, transformed_lat = trans.transform_point(
+            release.lon,
+            release.lat,
+            proj,
+        )
+
+        if colors is not None:
+            color = colors[release.name]
+        else:
+            color = "k"
+
+        ax.plot(
+            transformed_lon,
+            transformed_lat,
+            marker="x",
+            markersize=8,
+            markeredgewidth=2,
+            label=release.name,
+            color=color,
+        )
 
-        return colors
+    if include_legend:
+        ax.legend(loc="center left", bbox_to_anchor=(1.1, 0.5))