Adding restoring forces DIC/Alk

ci/environment-with-xesmf.yml

@@ -11,7 +11,9 @@ dependencies:
   - pytest
   - pytest-xdist
   - h5py
+  - h5netcdf
   - flake8
   - black
   - pre-commit==3.8.0
   - coverage
+  - gsw

ci/environment.yml

@@ -10,7 +10,9 @@ dependencies:
   - pytest
   - pytest-xdist
   - h5py
+  - h5netcdf
   - flake8
   - black
   - pre-commit==3.8.0
   - coverage
+  - gsw

conftest.py

@@ -971,7 +971,7 @@ def bgc_surface_forcing_from_mbl_co2(use_dask: bool) -> SurfaceForcing:
 def restoring_surface_forcing_from_unified_climatology(
     use_dask: bool,
 ) -> SurfaceForcing:
-    """Fixture for creating a SurfaceForcing object with restoring forces from climatology."""
+    """Fixture for creating a SurfaceForcing object with salinity restoring forces from unified climatology."""
     grid = Grid(
         nx=5,
         ny=5,
@@ -1003,7 +1003,7 @@ def restoring_surface_forcing_from_unified_climatology(
 def restoring_surface_forcing_from_woa_climatology(
     use_dask: bool,
 ) -> SurfaceForcing:
-    """Fixture for creating a SurfaceForcing object with restoring forces from climatology."""
+    """Fixture for creating a SurfaceForcing object with salinity restoring forces from WOA climatology."""
     grid = Grid(
         nx=5,
         ny=5,
@@ -1031,6 +1031,38 @@ def restoring_surface_forcing_from_woa_climatology(
     )
 
 
+@pytest.fixture(scope="session")
+def restoring_surface_forcing_from_soda(
+    use_dask: bool,
+) -> SurfaceForcing:
+    """Fixture for creating a SurfaceForcing object with DIC/ALK restoring forces from OceanSODA."""
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 2, 1)
+    end_time = datetime(2020, 2, 1)
+
+    fname_bgc = Path(download_test_data("coarsened_OceanSODA_dataset.nc"))
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        source={"name": "SODA", "path": fname_bgc},  # type: ignore[dict-item]
+        type="restoring",
+        restoring_forces=["sDIC", "sALK"],
+        coarse_grid_mode="never",
+        use_dask=use_dask,
+    )
+
+
 @pytest.fixture(scope="session")
 def river_forcing() -> RiverForcing:
     """Fixture for creating a RiverForcing object from the global Dai river dataset."""

docs/datasets.ipynb

@@ -522,7 +522,7 @@
      "data": {
       "text/plain": [
        "('co2_GHGreference.1785677502_surface.txt',\n",
-       " <http.client.HTTPMessage at 0x150a82333240>)"
+       " <http.client.HTTPMessage at 0x1546fb9b1450>)"
       ]
      },
      "execution_count": 18,
@@ -531,7 +531,61 @@
     }
    ],
    "source": [
-    "urllib.request.urlretrieve(url, 'co2_GHGreference.1785677502_surface.txt')"
+    "urllib.request.urlretrieve(url, \"co2_GHGreference.1785677502_surface.txt\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "625060a9-adb7-4435-bdfe-55b7d5a17a00",
+   "metadata": {},
+   "source": [
+    "## Downloading the OceanSODA-ETHZ Dataset\n",
+    "\n",
+    "This section demonstrates how to download a **monthly dataset from NOAA's NCEI**. This dataset is calculated from machine learning estimates of Total Alkalinity (TA) and the fugacity of carbon dioxide (fCO2), and the sea surface DIC and ALK data are used for restoring forces in `ROMS`. \n",
+    "\n",
+    "The dataset can be downloaded using the following procedure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "id": "3fae746b-4935-4014-b6bc-387e712cc9ab",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import urllib.request"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "id": "78ff97f1-e9a2-497e-bd4f-ddd1906e03ce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "url = \"https://www.ncei.noaa.gov/data/oceans/archive/arc0160/0220059/6.6/data/0-data/OceanSODA_ETHZ-v2025.OCADS.01-1982-2024.nc\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 21,
+   "id": "7f60d4d8-9bd6-4f6e-b015-219ee0c7f787",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('OceanSODA_ETHZ-v2025.OCADS.01-1982-2024.nc',\n",
+       " <http.client.HTTPMessage at 0x1546fb774c30>)"
+      ]
+     },
+     "execution_count": 21,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "urllib.request.urlretrieve(url, \"OceanSODA_ETHZ-v2025.OCADS.01-1982-2024.nc\")"
    ]
   },
   {
@@ -545,7 +599,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "grid_RT",
+   "display_name": "romstools-test",
    "language": "python",
    "name": "romstools-test"
   },
@@ -559,7 +613,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.12"
+   "version": "3.13.14"
   }
  },
  "nbformat": 4,

docs/datasets_overview.rst

@@ -52,13 +52,17 @@ ROMS-Tools relies on several external datasets. Some are accessed automatically;
      - No (auto-downloaded)
      - `NCAR RDA <https://rda.ucar.edu/datasets/d551000/dataaccess/>`_
    * - WOA
-     - Surface Restoring Forcing
+     - Surface Restoring Forcing, sea surface salinity (`sss`)
      - Yes
      - `WOA, NOAA <https://www.ncei.noaa.gov/products/world-ocean-atlas>`_
    * - MBL_co2
      - Time-varying CO2, Surface Forcing
      - No (auto-downloaded)
      - `MBL, GML, NOAA <https://gml.noaa.gov/ccgg/mbl/data.php>`_
+   * - SODA
+     - Surface Restoring Forcing, sea surface salinity (`sDIC`, `sALK`)
+     - No (auto-downloaded)
+     - `OceanSODA-ETHZ, NOAA <https://www.ncei.noaa.gov/access/metadata/landing-page/bin/iso?id=gov.noaa.nodc:0220059>`_
 
 
 Manual Downloads
@@ -226,7 +230,7 @@ WOA Salinity Data
 
 A collection of salinity (and other variables) means based on profile data from the World Ocean Database (WOD). The `s_an` variable provided is the 'Objectively analyzed mean fields for sea_water_salinity'.
 
-:Required for: Surface Forcing (Restoring Forces)
+:Required for: Surface Forcing (Restoring Forces; Salinity)
 :Available at: `NOAA website <https://www.ncei.noaa.gov/products/world-ocean-atlas>`_
 
 For download instructions see :doc:`datasets`.
@@ -370,7 +374,26 @@ Data are available for 1979 to 2025. Downloaded automatically by ROMS-Tools.
 
 :Version: 2019
 :Required for: River Forcing
-:Available at: `NOAA's GML, MBL <https://gml.noaa.gov/ccgg/mbl/data.php>`_t
+:Available at: `NOAA's GML, MBL <https://gml.noaa.gov/ccgg/mbl/data.php>`_
+
+
+Download Instructions
+---------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   datasets
+
+
+OceanSODA
+~~~~~~~~~~~~~~~
+
+A global gridded marine carbonate system dataset calculated from machine learning estimates of Total Alkalinity and the fugacity of carbon dioxide. Data taken from NOAA's OceanSODA-ETHZ version 2025. Monthly data for years 1982-2024 at 1 degree resolution for the surface water. Downloaded automatically by ROMS-Tools.
+
+:Version: 2025
+:Required for: Surface Forcing (Restoring Forces; DIC & ALK)
+:Available at: `NOAA's OceanSODA <https://www.ncei.noaa.gov/access/metadata/landing-page/bin/iso?id=gov.noaa.nodc:0220059>`_
 
 
 Download Instructions

docs/releases.md

@@ -33,6 +33,7 @@
 * RIVR2O concentrations vary by calendar year and are discharge-partitioned when rivers share a grid cell; missing annual files are linearly interpolated on the year axis
 * CDR metrics report CO2 uptake as mass in tonnes of CO2 for both the air-sea flux-difference and DIC-difference constructions (using CO2 molar mass and native flux or inventory units when available).
 * The CDR metrics figure from `ROMSOutput.cdr_metrics()` uses twin y-axes: CDR efficiency (dimensionless) and CO2 uptake (tonnes CO2), with title "CO2 uptake and CDR efficiency".
+* `SurfaceForcing` with `type='restoring'` now allows for making DIC and ALK restoring forces files ([#619](https://github.com/CWorthy-ocean/roms-tools/pull/619))
 
 
 ### Internal Changes