forcingkit 0.2.0__tar.gz → 0.4.0__tar.gz

{forcingkit-0.2.0 → forcingkit-0.4.0}/.agents/forcingkit.md

@@ -3,8 +3,8 @@
 ## Mission
 
 Python microservice providing real-time and historical forcing (the parent ocean and
-the HRRR atmosphere) and validation observations to the `coastal-sim` Julia physics
-engine.
+the HRRR atmosphere) and validation observations to downstream ocean models, for
+example ones built on Oceananigans.jl or NumericalEarth.
 
 ## Environment
 
@@ -41,7 +41,7 @@ HTTP Request → service/forcingkit_serve/main.py
 *Note: Because the architecture is modular, a future roadmap item includes the integration of TPXO (via `tpxo.py`) given usage rights.*
 
 Atmospheric forcing: HRRR from 2014-07-30 (`hrrr_atmosphere.py`, `/api/v1/atmosphere`).
-Earlier runs use ERA5 through NumericalEarth in coastal-sim, not this service.
+Earlier runs use ERA5 through NumericalEarth in the model, not this service.
 
 ## Testing
 
@@ -89,7 +89,7 @@ uv run python -c "from forcingkit.fetchers import nyofs; print(nyofs.get_metadat
 - **Mocking strategy**: Dispatcher unit tests check tuple/dict return
   boundaries carefully. When modifying mocked fetchers, track
   keyword-argument vs positional argument boundaries.
-- **Grid normalization**: `coastal-sim` expects elevations positive
+- **Grid normalization**: downstream models expect elevations positive
   up (LMSL/NAVD88). Normalize any inverted datasets in the fetcher
   tier before the dispatcher sees them.
 - **Cache keys**: Cache Zarr keys are deterministic hashes of bbox

{forcingkit-0.2.0 → forcingkit-0.4.0}/.env.template

@@ -1,13 +1,12 @@
 # forcingkit environment variables
 # Copy this file to .env and fill in your credentials.
-# This file is loaded by coastal-sim/docker-compose.yml via env_file.
+# A docker-compose service can load it with env_file.
 
 # No credentials are required at present: HRRR, NOAA OFS, NECOFS, HYCOM, NDBC and
 # CO-OPS are all served without authentication.
 
-# Cache root for every store (default ~/.cache/forcingkit). The old names
-# ECODATA_CACHE_CACHE_DIR and COASTAL_SIM_DATA_CACHE_DIR are still read, with a
-# warning, until the next release.
+# Cache root for every store (default ~/.cache/forcingkit). The old name
+# ECODATA_CACHE_CACHE_DIR is still read, with a warning, until the next release.
 # FORCINGKIT_CACHE_DIR=~/.cache/forcingkit
 
 # Threads for parallel OPeNDAP reads (default 4; was ECODATA_CACHE_MAX_WORKERS).

{forcingkit-0.2.0 → forcingkit-0.4.0}/AGENTS.md

@@ -22,9 +22,10 @@ guidance in this repository.
 ## Repository Focus
 
 forcingkit is a Python microservice that fetches, harmonizes, regrids, and serves
-real-time and historical forcing to the `coastal-sim` Julia physics engine: the parent
-ocean (`/api/v1/obc`, schema z-v2), the HRRR atmosphere (`/api/v1/atmosphere`), tides,
-and station telemetry and NDBC observations for validation.
+real-time and historical forcing to downstream ocean models (for example ones built on
+Oceananigans.jl or NumericalEarth): the parent ocean (`/api/v1/obc`, schema z-v3), the
+HRRR atmosphere (`/api/v1/atmosphere`), tides, and station telemetry and NDBC
+observations for validation.
 
 ## Core Rules
 

{forcingkit-0.2.0 → forcingkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.2.0
+Version: 0.4.0
 Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
 Project-URL: Documentation, https://forcingkit.docs.lhzn.io
 Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
@@ -255,7 +255,7 @@ Spatiotemporal forcing for computational Earth-system models: selects, regrids a
 
 `forcingkit` sits between operational and archive data providers (NOAA HRRR, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`) and its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
 
-forcingkit was named ecodata-cache until 2026-10-05; GitHub redirects the old repository URLs. The Python package is `forcingkit` (was `ecodata_cache`), and environment variables use the `FORCINGKIT_` prefix; the old names are still read, with a warning, until the next release. Documentation: <https://forcingkit.docs.lhzn.io>, including the [routes removed on the same date](https://forcingkit.docs.lhzn.io/removed_endpoints.html).
+Documentation: <https://forcingkit.docs.lhzn.io>.
 
 ## Goals
 
@@ -273,14 +273,17 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
 
 ## Current Coverage
 
-- **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (Operational & Historical).
+- **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
 - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
 
 ## Roadmap
 
-- **Enhanced IOOS Coverage**: Expanding our data fetchers to support more regional nodes across the West Coast (WCOFS) and Gulf of Mexico (NGOFS2).
-- **Improved Caching Policies**: Implementing dynamic cache invalidation based on NOAA operational forecast updates to ensure realtime predictions stay synchronized.
-- **Variable Expansions**: Providing native spatiotemporal transformations for wave spectra and biogeochemical tracers.
+- **Coverage first**: a second global parent (Copernicus GLO12, GLORYS12 for 1993 on, NOAA RTOFS), the remaining NOAA forecast systems (West Coast, Gulf, Chesapeake, Great Lakes, Alaska), the Doppio reanalysis for 2007 to 2024 in the Northeast, HRRR Alaska and ECMWF IFS for the atmosphere, and a first European ocean source from Copernicus Marine (IBI or the North West Shelf).
+- **Resolution second**: the NYOFS fine grid, the Monterey Bay nests of WCOFS, and SFBOFS inside San Francisco Bay.
+- **NYOFS and DBOFS as z-v3 parents**: both on true depths with geographic axes.
+- **Forecast mode and cache policy**: HRRR forecast cycles, and invalidation of forecast-built stores when a newer cycle is published.
+
+The full list, with what each candidate offers, is at <https://forcingkit.docs.lhzn.io/roadmap.html>. Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Architecture overview
 

{forcingkit-0.2.0 → forcingkit-0.4.0}/README.md

@@ -14,7 +14,7 @@ Spatiotemporal forcing for computational Earth-system models: selects, regrids a
 
 `forcingkit` sits between operational and archive data providers (NOAA HRRR, NECOFS, NOAA OFS, HYCOM, NDBC, CO-OPS) and model codes such as `Oceananigans.jl`. It delivers a model's parent ocean on true z levels (`/api/v1/obc`) and its HRRR surface atmosphere on a regular grid (`/api/v1/atmosphere`), plus station observations for validation, as schema-versioned Zarr stores that record their sources.
 
-forcingkit was named ecodata-cache until 2026-10-05; GitHub redirects the old repository URLs. The Python package is `forcingkit` (was `ecodata_cache`), and environment variables use the `FORCINGKIT_` prefix; the old names are still read, with a warning, until the next release. Documentation: <https://forcingkit.docs.lhzn.io>, including the [routes removed on the same date](https://forcingkit.docs.lhzn.io/removed_endpoints.html).
+Documentation: <https://forcingkit.docs.lhzn.io>.
 
 ## Goals
 
@@ -32,14 +32,17 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
 
 ## Current Coverage
 
-- **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (Operational & Historical).
+- **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
 - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
 
 ## Roadmap
 
-- **Enhanced IOOS Coverage**: Expanding our data fetchers to support more regional nodes across the West Coast (WCOFS) and Gulf of Mexico (NGOFS2).
-- **Improved Caching Policies**: Implementing dynamic cache invalidation based on NOAA operational forecast updates to ensure realtime predictions stay synchronized.
-- **Variable Expansions**: Providing native spatiotemporal transformations for wave spectra and biogeochemical tracers.
+- **Coverage first**: a second global parent (Copernicus GLO12, GLORYS12 for 1993 on, NOAA RTOFS), the remaining NOAA forecast systems (West Coast, Gulf, Chesapeake, Great Lakes, Alaska), the Doppio reanalysis for 2007 to 2024 in the Northeast, HRRR Alaska and ECMWF IFS for the atmosphere, and a first European ocean source from Copernicus Marine (IBI or the North West Shelf).
+- **Resolution second**: the NYOFS fine grid, the Monterey Bay nests of WCOFS, and SFBOFS inside San Francisco Bay.
+- **NYOFS and DBOFS as z-v3 parents**: both on true depths with geographic axes.
+- **Forecast mode and cache policy**: HRRR forecast cycles, and invalidation of forecast-built stores when a newer cycle is published.
+
+The full list, with what each candidate offers, is at <https://forcingkit.docs.lhzn.io/roadmap.html>. Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Architecture overview
 

forcingkit-0.4.0/docs/source/_static/custom.css

@@ -0,0 +1,24 @@
+/* Use more of a wide screen: the theme caps the content column at 800 px. */
+.wy-nav-content {
+  max-width: 1200px;
+}
+
+/* Let table cells wrap instead of forcing a horizontal scrollbar. The theme sets nowrap on
+   every cell and puts tables in a scrolling container. */
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+  white-space: normal;
+}
+
+/* On wide screens wrapped tables fit, so drop the scroll container; on phones keep it, so a
+   table too wide even when wrapped scrolls rather than being clipped. */
+@media screen and (min-width: 768px) {
+  .wy-table-responsive {
+    overflow-x: visible;
+  }
+}
+
+/* Keep long code spans (archive paths, URLs) from widening a column past the page. */
+.wy-table-responsive table td code {
+  overflow-wrap: anywhere;
+}

{forcingkit-0.2.0 → forcingkit-0.4.0}/docs/source/atmospheric_forcing.rst

@@ -2,7 +2,8 @@ Atmospheric Forcing Datasets
 ============================
 
 As of 2026-10-04. Which atmospheric datasets can force a coastal ocean model through this service
-or through NumericalEarth, how they compare, and which one the CoastalSim configurations use.
+or through `NumericalEarth <https://github.com/NumericalEarth/NumericalEarth.jl>`__, how they
+compare, and which to choose.
 
 An ocean model's surface fluxes need, at every hour of the run: 10 m wind (eastward and
 northward), 2 m air temperature and specific humidity, surface pressure, precipitation, and
@@ -23,22 +24,23 @@ Summary
      - Output step
      - Coverage
      - Latency
-     - Path in our stack
-   * - **HRRR** (NOAA NCEP)
+     - Path to a model
+   * - **HRRR** (`NOAA GSL <https://gsl.noaa.gov/>`__, `NCEP <https://www.nco.ncep.noaa.gov/>`__)
      - Hourly-cycling forecast, 3 km convection-allowing, radar assimilation
      - 3 km, Lambert conformal over CONUS
      - 1 h (15 min for some fields)
      - CONUS; archive on AWS from 2014-07-30
      - About an hour after each cycle
-     - **forcingkit** ``/api/v1/atmosphere`` (schema ``hrrr-atm-v1``); default for CoastalSim
-   * - **ERA5** (ECMWF, Copernicus C3S)
+     - **forcingkit** ``/api/v1/atmosphere`` (schema ``hrrr-atm-v1``); the default
+   * - **ERA5** (`ECMWF <https://www.ecmwf.int/>`__, `Copernicus C3S
+       <https://climate.copernicus.eu/>`__)
      - Global reanalysis (4D-Var)
      - 0.25 degrees (about 31 km)
      - 1 h
      - 1940 to present
      - ERA5T about 5 days; final ERA5 2 to 3 months
-     - **NumericalEarth** ``ERA5PrescribedAtmosphere`` (coastal-sim ``atmosphere = "era5"``)
-   * - **RRFS v1** (NOAA NCEP)
+     - **NumericalEarth** ``ERA5PrescribedAtmosphere``
+   * - **RRFS v1** (`NOAA GSL <https://gsl.noaa.gov/rrfs/>`__, NCEP)
      - Hourly-cycling forecast, FV3 limited-area, 3 km
      - 3 km, North America
      - 1 h
@@ -52,28 +54,29 @@ Summary
      - Retired 2026-10-06 in favour of RRFS
      - Four cycles a day, to 60 h
      - Not integrated; do not adopt
-   * - **GFS** (NOAA NCEP)
+   * - **GFS** (`NOAA NCEP
+       <https://www.emc.ncep.noaa.gov/emc/pages/numerical_forecast_systems/gfs.php>`__)
      - Global forecast, FV3
      - 0.25 degrees
      - 1 h to 120 h, then 3 h
      - Global; NODD archive on AWS
      - Four cycles a day, to 384 h
      - Not integrated; the natural extension past HRRR's 48 h in forecast mode
-   * - **ECMWF IFS open data**
+   * - **ECMWF IFS** `open data <https://www.ecmwf.int/en/forecasts/datasets/open-data>`__
      - Global forecast
      - 0.25 degrees
      - 3 h, then 6 h
      - Global; real time
      - Four cycles a day, to 15 days (00 and 12 UTC)
      - Not integrated; CC-BY-4.0 since 2025-10-01
-   * - **JRA55-do** (JMA, MRI)
+   * - **JRA55-do** (JMA, `MRI <https://www.mri-jma.go.jp/index_en.html>`__)
      - Reanalysis adjusted for ocean-sea-ice models
      - About 0.5 degrees
      - 3 h
      - 1958-01-01 to 2024-02-01, final version 1.6.0
      - Discontinued (JRA-55 ended January 2024; successor JRA-3Q)
      - **NumericalEarth** ``JRA55PrescribedAtmosphere`` (its catalogue ends 2019-12-31)
-   * - **ECCO v4** (NASA JPL)
+   * - **ECCO v4** (`ECCO Consortium <https://ecco-group.org/>`__, NASA JPL)
      - Ocean state estimate's adjusted forcing
      - About 1 degree
      - Monthly
@@ -87,9 +90,13 @@ Datasets in use
 HRRR (default)
 ~~~~~~~~~~~~~~
 
-*Provenance.* NOAA NCEP's High-Resolution Rapid Refresh, version 4, a 3 km convection-allowing
-model that assimilates radar every 15 minutes and starts a new forecast every hour. Distributed
-through the NOAA Open Data Dissemination programme in the ``noaa-hrrr-bdp-pds`` bucket on AWS
+*Provenance.* NOAA's `High-Resolution Rapid Refresh <https://rapidrefresh.noaa.gov/hrrr/>`__,
+version 4, developed by the NOAA Global Systems Laboratory and run by NCEP: a 3 km
+convection-allowing model that assimilates radar every 15 minutes and starts a new forecast every
+hour (`Dowell et al., 2022 <https://doi.org/10.1175/WAF-D-21-0151.1>`__; `James et al., 2022
+<https://doi.org/10.1175/WAF-D-21-0130.1>`__). Distributed through the `NOAA Open Data
+Dissemination <https://www.noaa.gov/information-technology/open-data-dissemination>`__ programme
+in the `noaa-hrrr-bdp-pds <https://registry.opendata.aws/noaa-hrrr-pds/>`__ bucket on AWS
 (us-east-1), anonymous, from 2014-07-30 to the present. NOAA open data: free to use; NOAA asks
 for attribution and that modified products not be presented as NOAA's.
 
@@ -134,8 +141,8 @@ atmosphere regridder accepts. Records run from one hour before the run start to
 end; a missing message or hour raises, and the store is published only when complete. Building
 one hour takes about 6.5 s on a warm connection, so a 168 h window takes about 19 minutes.
 
-*Strengths.* Resolves the land-sea contrast, sea breezes and frontal timing at the scale of our
-domains (MAB is 15 by 17 km; LIS 85 by 65 km). Hourly radiation and precipitation. No credentials.
+*Strengths.* Resolves the land-sea contrast, sea breezes and frontal timing at the scale of
+coastal domains from about 15 to 85 km across. Hourly radiation and precipitation. No credentials.
 
 *Limits.* CONUS only. A forecast product, not a reanalysis: it carries forecast-model biases and is
 not homogeneous across HRRR versions (v4 since December 2020). Radiation is instantaneous.
@@ -143,24 +150,28 @@ not homogeneous across HRRR versions (v4 since December 2020). Radiation is inst
 ERA5 (fallback)
 ~~~~~~~~~~~~~~~
 
-*Provenance.* ECMWF's fifth-generation global reanalysis for the Copernicus Climate Change
-Service: 0.25 degree grid (about 31 km), hourly, 1940 to the present. ERA5T, the initial release,
+*Provenance.* `ECMWF <https://www.ecmwf.int/>`__'s fifth-generation global reanalysis for the
+`Copernicus Climate Change Service <https://climate.copernicus.eu/>`__ (`Hersbach et al., 2020
+<https://doi.org/10.1002/qj.3803>`__): 0.25 degree grid (about 31 km), hourly, 1940 to the present.
+ERA5T, the initial release,
 appears about five days behind real time and is overwritten by the final ERA5 two to three months
-later. Requires a free Copernicus Climate Data Store account (credentials in ``~/.cdsapirc``);
+later. Requires a free `Copernicus Climate Data Store <https://cds.climate.copernicus.eu/>`__
+account (credentials in ``~/.cdsapirc``);
 Copernicus licence, attribution required.
 
-*How it is used.* CoastalSim reads it through NumericalEarth's ``ERA5PrescribedAtmosphere`` and
-``ERA5PrescribedRadiation`` over the bbox padded by 0.5 degrees, with linear time indexing and one
-hour of padding past the end. Accumulated fields (precipitation, radiation) are hour-ending means
-that NumericalEarth places at the centre of their hour. NumericalEarth 0.8.1's catalogue stops at
-2025-12-31; coastal-sim extends it to six days before today until upstream rolls the date.
+*How it is used.* A model reads it through NumericalEarth's ``ERA5PrescribedAtmosphere`` and
+``ERA5PrescribedRadiation``, for example over the bbox padded by 0.5 degrees, with linear time
+indexing and one hour of padding past the end. Accumulated fields (precipitation, radiation) are
+hour-ending means that NumericalEarth places at the centre of their hour. NumericalEarth 0.8.1's
+catalogue stops at 2025-12-31; later dates need the catalogue extended until upstream rolls it.
 
 *Strengths.* Homogeneous, global, long, assimilates far more observations than any forecast; the
 standard against which forcing biases are judged.
 
-*Limits.* At 31 km a domain like MAB spans one or two ERA5 cells, so the forcing is nearly uniform
-and smears the coast: in the first hours of 2026-04-02 over MAB, the ERA5 box (which includes New
-Jersey land) was about 3 K warmer at 2 m and had about half HRRR's wind speed. Latency rules out
+*Limits.* At 31 km a 15 km coastal domain spans one or two ERA5 cells, so the forcing is nearly
+uniform and smears the coast: in the first hours of 2026-04-02 over such a domain off New Jersey,
+the ERA5 box (which includes New Jersey land) was about 3 K warmer at 2 m and had about half HRRR's
+wind speed. Latency rules out
 anything closer than five days to the present.
 
 Choosing
@@ -177,20 +188,43 @@ Choosing
    * - Hindcast before 2014-07-30, outside CONUS, or a reanalysis-grade comparison run
      - ERA5
    * - Forecast to 48 h
-     - HRRR forecast mode (planned, Sprint 4): one cycle's f01 to f48 from the 00, 06, 12 or 18 UTC
+     - HRRR forecast mode (planned): one cycle's f01 to f48 from the 00, 06, 12 or 18 UTC
        cycle
    * - Forecast beyond 48 h
      - HRRR to 48 h, then GFS or ECMWF IFS open data (not integrated); RRFS to 84 h once it is
        established in operations
    * - Multi-decade or climate-scale forcing
-     - ERA5, or JRA55-do through NumericalEarth (to 2019 in its catalogue)
+     - ERA5, or JRA55-do (`Tsujino et al., 2018 <https://doi.org/10.1016/j.ocemod.2018.07.002>`__)
+       through NumericalEarth (to 2019 in its catalogue)
 
 References
 ----------
 
+Citations
+~~~~~~~~~
+
+- Dowell, D. C., C. R. Alexander, E. P. James, et al. (2022). The High-Resolution Rapid Refresh
+  (HRRR): An hourly updating convection-allowing forecast model. Part I: Motivation and system
+  description. *Weather and Forecasting*, 37(8), 1371-1395.
+  `doi:10.1175/WAF-D-21-0151.1 <https://doi.org/10.1175/WAF-D-21-0151.1>`__
+- James, E. P., C. R. Alexander, D. C. Dowell, et al. (2022). The High-Resolution Rapid Refresh
+  (HRRR): An hourly updating convection-allowing forecast model. Part II: Forecast performance.
+  *Weather and Forecasting*, 37(8), 1397-1417.
+  `doi:10.1175/WAF-D-21-0130.1 <https://doi.org/10.1175/WAF-D-21-0130.1>`__
+- Hersbach, H., B. Bell, P. Berrisford, et al. (2020). The ERA5 global reanalysis. *Quarterly
+  Journal of the Royal Meteorological Society*, 146(730), 1999-2049.
+  `doi:10.1002/qj.3803 <https://doi.org/10.1002/qj.3803>`__
+- Tsujino, H., S. Urakawa, H. Nakano, et al. (2018). JRA-55 based surface dataset for driving
+  ocean-sea-ice models (JRA55-do). *Ocean Modelling*, 130, 79-139.
+  `doi:10.1016/j.ocemod.2018.07.002 <https://doi.org/10.1016/j.ocemod.2018.07.002>`__
+
+Links
+~~~~~
+
 - NOAA HRRR on AWS: https://registry.opendata.aws/noaa-hrrr-pds/
 - NOAA RRFS: https://gsl.noaa.gov/rrfs/ ; operational date and retirements:
   https://gribstream.com/blog/noaa-rrfs-refs-operational-august-2026
-- ERA5T latency: https://climate.copernicus.eu/key-update-climate-dataset-brings-data-five-days-behind-real-time
+- ERA5T latency:
+  https://climate.copernicus.eu/key-update-climate-dataset-brings-data-five-days-behind-real-time
 - ECMWF open data: https://www.ecmwf.int/en/forecasts/datasets/open-data
 - JRA55-do: https://climate.mri-jma.go.jp/pub/ocean/JRA55-do/

{forcingkit-0.2.0 → forcingkit-0.4.0}/docs/source/conf.py

@@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath("../../src"))
 project = "forcingkit"
 copyright = "2026, Long Horizon Observatory"
 author = "Daniel Fry"
-release = "0.2.0"
+release = "0.4.0"
 
 extensions = [
     "sphinx.ext.autodoc",
@@ -26,5 +26,6 @@ language = "en"
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 # CNAME for the custom domain forcingkit.docs.lhzn.io, copied to the site root.
 html_extra_path = ["_extra"]

forcingkit-0.4.0/docs/source/fetchers.rst

@@ -0,0 +1,200 @@
+Data Fetchers
+=============
+
+A fetcher (``forcingkit.fetchers``) talks to one external provider: it resolves where the data
+for a time lives, reads only the subset a request needs, and returns it in a common layout. The
+dispatcher (``forcingkit.dispatcher``) chooses among fetchers, falls back when one cannot deliver,
+and writes the result to the local Zarr cache, so a request is fetched from the provider once.
+
+Atmospheric forcing (``/api/v1/atmosphere``)
+--------------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 86
+
+   * - Source
+     - Notes
+   * - **HRRR**
+     - NOAA `High-Resolution Rapid Refresh <https://rapidrefresh.noaa.gov/hrrr/>`__ (developed by
+       the `NOAA Global Systems Laboratory <https://gsl.noaa.gov/>`__, run operationally by
+       `NCEP <https://www.nco.ncep.noaa.gov/>`__), 3 km, from the anonymous AWS S3 bucket
+       `noaa-hrrr-bdp-pds <https://registry.opendata.aws/noaa-hrrr-pds/>`__; the archive starts
+       2014-07-30. Surface fields are interpolated to a regular 0.03 degree grid and streamed hour
+       by hour (schema ``hrrr-atm-v1``). Earlier dates use `ERA5
+       <https://cds.climate.copernicus.eu/>`__ through `NumericalEarth
+       <https://github.com/NumericalEarth/NumericalEarth.jl>`__ in the model, outside this
+       service. See :doc:`atmospheric_forcing`.
+
+Parent ocean (``/api/v1/obc``)
+------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 86
+
+   * - Source
+     - Notes
+   * - **NECOFS**
+     - `Northeast Coastal Ocean Forecast System <https://fvcom.smast.umassd.edu/?p=20>`__, `FVCOM
+       <https://fvcom.smast.umassd.edu/>`__ GOM7 (`UMass Dartmouth SMAST
+       <https://www.umassd.edu/smast/>`__ and `WHOI <https://www.whoi.edu/>`__), unstructured mesh
+       with 45 sigma layers. Daily history files from 2025-01-01, then the rolling forecast.
+       The only donor that streams the ``z-v3`` parent store. See :doc:`necofs`.
+   * - **NYOFS**
+     - `NOAA New York/New Jersey Operational Forecast System
+       <https://tidesandcurrents.noaa.gov/ofs/nyofs/nyofs.html>`__ (`NOAA CO-OPS
+       <https://tidesandcurrents.noaa.gov/>`__), POM on a curvilinear grid with 7
+       sigma levels, NY/NJ Harbor. Ranked first inside its domain. 7-day CO-OPS aggregation,
+       then the nowcast archive (AWS S3 from 2024-11-19, NCEI from 2014). Legacy output layout
+       rather than ``z-v3``. See :doc:`nyofs`.
+   * - **DBOFS**
+     - `NOAA Delaware Bay Operational Forecast System
+       <https://tidesandcurrents.noaa.gov/ofs/dbofs/dbofs.html>`__ (NOAA CO-OPS),
+       `ROMS <https://www.myroms.org/>`__, about 100 m, domain
+       [-75.875, 37.810, -73.264, 40.206]. 7-day CO-OPS aggregation, then the hourly nowcast
+       archive (AWS S3 from 2024-11-19, NCEI from 2014). Legacy output layout.
+   * - :doc:`HYCOM <hycom>`
+     - `HYCOM <https://www.hycom.org/>`__ (1/12 degree, about 9 km, 40 z levels), global, from
+       the `HYCOM consortium data server <https://tds.hycom.org/thredds/catalog.html>`__, 1994 to
+       the present. The experiment follows the date: GLBv0.08 ``expt_53.X`` (reanalysis) to
+       2015, a chain of GLBv0.08 analysis experiments to 2018-12-04, GLBy0.08 ``expt_93.0`` to
+       2024-09-05, then ESPC-D-V02. A window that spans a switch is stitched; if any piece fails,
+       the whole window fails. Tidal only from 2024-09-05, recorded in the store's ``tides``
+       attribute (``"none"``, ``"included"`` or ``"mixed"``). Last-resort fallback; legacy
+       output layout.
+
+`TPXO10 <https://www.tpxo.net/>`__ tidal harmonics are a roadmap item, not integrated; the
+`pyTMD <https://github.com/pyTMD/pyTMD>`__ dependency was removed on
+2026-10-05. The ``include_tides`` and ``tidal_model`` request fields
+are still accepted and form part of the cache key, but no tide is added to the parent store.
+A parent that already contains the tide (a HYCOM store with ``tides = "included"``) should not
+have tides added again downstream; see :doc:`hycom`.
+
+Donor selection
+~~~~~~~~~~~~~~~
+
+Each parent-ocean fetcher declares a domain box and an approximate resolution. A donor is a
+candidate when it accepts the request box (NYOFS and DBOFS require the box to lie inside their
+domain; NECOFS accepts any overlap; HYCOM accepts everything). Candidates are ranked by **domain
+area first, smallest first**, then by resolution, on the reasoning that the most specialised
+system is the best local one:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 30 20 30
+
+   * - Donor
+     - Declared domain (lon/lat)
+     - Area (degree squared)
+     - Declared resolution
+   * - NYOFS
+     - [-74.475, 40.389, -73.743, 40.940]
+     - 0.40
+     - 100 m
+   * - DBOFS
+     - [-75.875, 37.810, -73.264, 40.206]
+     - 6.3
+     - 100 m
+   * - NECOFS
+     - [-77.0, 35.0, -65.0, 46.0]
+     - 132
+     - 200 m
+   * - HYCOM
+     - global
+     - 64800
+     - 9 km
+
+The dispatcher tries the candidates in order. A donor that returns nothing or raises is logged
+and skipped unless the request sets ``allow_donor_fallback: false``, in which case the first
+failure is an error. A donor that streams (NECOFS) either completes its store or fails; it never
+publishes a shortened one.
+
+Observations
+------------
+
+These serve validation rather than forcing:
+
+- **CO-OPS** water level (``/api/v1/tide``), from the `NOAA CO-OPS data API
+  <https://api.tidesandcurrents.noaa.gov/api/prod/>`__, with a datum
+  fallback to MSL where a station has no NAVD88 datum.
+- **NDBC** buoy meteorology and ADCP profiles (``/api/v1/ndbc``), from the `NOAA National Data
+  Buoy Center <https://www.ndbc.noaa.gov/>`__.
+- **UConn ERDDAP** water-column profiles (``/api/v1/telemetry/station`` and ``/bbox``), from the
+  `University of Connecticut Department of Marine Sciences <https://marinesciences.uconn.edu/>`__
+  `ERDDAP server <http://merlin.dms.uconn.edu:8080/erddap/index.html>`__.
+
+NOAA OFS archive locations
+--------------------------
+
+As checked on 2026-10-06, NYOFS and DBOFS output is available from three places:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 30 48
+
+   * - Location
+     - Span
+     - Layout
+   * - `CO-OPS THREDDS <https://opendap.co-ops.nos.noaa.gov/thredds/catalog/catalog.html>`__ FMRC
+       aggregation
+     - Rolling 7 days
+     - One virtual OPeNDAP dataset per system
+       (``opendap.co-ops.nos.noaa.gov/thredds/dodsC/<OFS>/fmrc/Aggregated_7_day_<OFS>_Fields_Forecast_best.ncd``).
+   * - `NOAA NCEI <https://www.ncei.noaa.gov/>`__ THREDDS (`model-nyofs-files
+       <https://www.ncei.noaa.gov/thredds/catalog/model-nyofs-files/catalog.html>`__,
+       ``model-dbofs-files``)
+     - 2014 to the present month, with occasional missing days (NYOFS 2024-06 has 25 of 30)
+     - One directory per month, ``{yyyy}/{mm}/``, with every file of the month in it. File names
+       changed with the 2024-09-09 cycles (from ``nos.<ofs>.fields.<n|f><hhh>.<yyyymmdd>.t<cc>z.nc``
+       and ``nos.nyofs.fields.<nowcast|forecast>.<yyyymmdd>.t<cc>z.nc`` to
+       ``<ofs>.t<cc>z.<yyyymmdd>.fields.<...>.nc``).
+   * - AWS S3 `noaa-nos-ofs-pds <https://registry.opendata.aws/noaa-ofs/>`__ (`NOAA Open Data
+       Dissemination <https://www.noaa.gov/information-technology/open-data-dissemination>`__)
+     - 2024 to the present, with gaps before 2024-11-19
+     - From 2024-11-19, one directory per day, ``<ofs>/netcdf/{yyyy}/{mm}/{dd}/``; the first day
+       holds only its last cycle. Before that, one flat directory per month,
+       ``<ofs>/netcdf/{yyyymm}/``, with a mix of file names (NYOFS 2024-07 uses the older names,
+       DBOFS 2024-07 the newer ones); several of those months are partial and some are absent
+       (NYOFS lacks 2024-01 to 2024-03, 2024-05 and 2024-06; DBOFS lacks 2024-02 and starts
+       2024-01 on the 29th).
+
+.. note::
+   An earlier version of this page said that NCEI stopped archiving at the end of November 2023,
+   that AWS began in January 2024, and that December 2023 was therefore missing. None of that
+   holds: NCEI has every day of December 2023 for both NYOFS and DBOFS (124 NYOFS and 744 DBOFS
+   field files) and has continued archiving through 2026, while the AWS archive is the one with
+   gaps.
+
+   The NYOFS and DBOFS fetchers read nowcast files only, so a window is a chain of analyses
+   rather than forecasts. For each file they try AWS (per-day layout) first when the date is
+   2024-11-19 or later, then NCEI, which covers every date; the flat AWS month directories are
+   not used. A window with a file missing from both is not served by that donor, and the
+   dispatcher falls back. DBOFS publishes one file per hour: file ``n001`` to ``n006`` of cycle
+   ``t<cc>z`` (00, 06, 12, 18 UTC) hold hours ``cc - 5`` to ``cc``. NYOFS publishes one file per
+   cycle (05, 11, 17, 23 UTC) holding the same six hours.
+
+   Both fetchers were corrected on 2026-10-06. Before that, every NYOFS archive date failed (see
+   :doc:`nyofs`), and DBOFS sent 2024 dates before 2024-11-19 to an AWS layout that does not
+   hold them, took some hours from the wrong file, joined NCEI files along a ``time`` dimension
+   they do not have (theirs is ``ocean_time``), and left the ROMS fill value (1e37) in land
+   cells read through NCEI.
+
+   For the AWS layout, see the `NOAA NODD OFS documentation
+   <https://github.com/NOAA-Big-Data-Program/nodd-data-docs/blob/main/OFS/README.md>`_ and the
+   `Registry of Open Data entry <https://registry.opendata.aws/noaa-ofs/>`_.
+
+Common processing
+-----------------
+
+- **Hourly time axis.** Non-streaming donors are resampled to a strict hourly index by linear
+  interpolation. Streaming donors deliver hourly records directly. HYCOM steps are 3 hours apart
+  with occasional gaps of up to 51 hours, which this bridges with a straight line; a store does
+  not yet record the longest gap it filled (:doc:`hycom`).
+- **Float32 fields, full-precision coordinates.** Data variables are cast to Float32 for the
+  model; ``lat``, ``lon``, ``z`` and ``z_face`` keep full precision, since Float32 longitudes near
+  -74 resolve only about 8e-6 degrees.
+- **Fill values.** Missing data is written as ``-9999`` (integers) or ``-9999.0`` (floats) in the
+  Zarr encoding, and as NaN in memory.
+- **Time in seconds.** ``z-v3`` stores encode time as seconds since their first record, which
+  the model's clock uses directly.