forcingkit 0.3.0__tar.gz → 0.5.0__tar.gz

{forcingkit-0.3.0 → forcingkit-0.5.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.5.0/.env.template

@@ -0,0 +1,20 @@
+# forcingkit environment variables
+# Copy this file to .env and fill in your credentials.
+# A docker-compose service can load it with env_file.
+
+# No credentials are required: HRRR, NOAA OFS, NECOFS, HYCOM, NDBC, CO-OPS and the
+# USGS Water Data APIs are all served without authentication.
+
+# Optional USGS Water Data API key (free from https://api.waterdata.usgs.gov/signup/).
+# Without it, river discharge requests still work at a lower hourly rate limit.
+# USGS_API_KEY=
+
+# 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_MAX_WORKERS=4
+
+# The topobathykit elevation service (default http://localhost:9595; was TOPOBATHYSIM_URL).
+# TOPOBATHYKIT_URL=http://localhost:9595

{forcingkit-0.3.0 → forcingkit-0.5.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.3.0 → forcingkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.3.0
+Version: 0.5.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

{forcingkit-0.3.0 → forcingkit-0.5.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 <https://github.com/NumericalEarth/NumericalEarth.jl>`__, how they compare, and which to choose.
+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
@@ -151,9 +152,11 @@ ERA5 (fallback)
 
 *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,
+<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 <https://cds.climate.copernicus.eu/>`__ 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.* A model reads it through NumericalEarth's ``ERA5PrescribedAtmosphere`` and
@@ -167,7 +170,8 @@ standard against which forcing biases are judged.
 
 *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
+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
@@ -220,6 +224,7 @@ 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.3.0 → forcingkit-0.5.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.3.0"
+release = "0.5.0"
 
 extensions = [
     "sphinx.ext.autodoc",

{forcingkit-0.3.0 → forcingkit-0.5.0}/docs/source/fetchers.rst

@@ -19,11 +19,12 @@ Atmospheric forcing (``/api/v1/atmosphere``)
      - 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`.
+       `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``)
 ------------------------------
@@ -37,7 +38,8 @@ Parent ocean (``/api/v1/obc``)
    * - **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.
+       <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
@@ -58,12 +60,16 @@ Parent ocean (``/api/v1/obc``)
        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. Last-resort fallback; legacy output layout.
+       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
 ~~~~~~~~~~~~~~~
@@ -149,8 +155,9 @@ As checked on 2026-10-06, NYOFS and DBOFS output is available from three places:
      - 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).
+       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,
@@ -181,7 +188,9 @@ Common processing
 -----------------
 
 - **Hourly time axis.** Non-streaming donors are resampled to a strict hourly index by linear
-  interpolation. Streaming donors deliver hourly records directly.
+  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.

{forcingkit-0.3.0 → forcingkit-0.5.0}/docs/source/hycom.rst

@@ -8,7 +8,9 @@ live against it on the same day.
 HYCOM is forcingkit's global parent ocean and the dispatcher's last-resort donor: it accepts any
 box and is tried after NYOFS, DBOFS and NECOFS (:doc:`fetchers`). It covers 1994 to the present
 by switching between several experiments, and delivers the legacy output layout rather than the
-``z-v3`` parent store.
+``z-v3`` parent store. Its fields are already on a regular longitude/latitude grid at fixed
+depths in metres, with temperature and salinity, so it is the donor closest to ``z-v3``
+(:doc:`roadmap`).
 
 System overview
 ---------------
@@ -73,6 +75,7 @@ Experiments forcingkit reads
 Each experiment serves from the time in the third column until the next one starts. Where two
 overlap, the switch is at the newer one's first time step, with one exception: GLBy0.08
 ``expt_93.0`` is kept to its last step on 2024-09-05 although ESPC-D-V02 begins on 2024-08-10.
+The GLB experiments carry no tides; ESPC-D-V02 does (see `Tides`_).
 Times before 1994-01-01 are not served.
 
 Grids
@@ -105,6 +108,48 @@ experiments carry all five in one dataset, 3-hourly, plus ``tau`` (analysis time
 field: ``u3z``, ``v3z``, ``t3z`` and ``s3z`` are 3-hourly; ``ssh`` is hourly. All use the time
 unit "hours since 2000-01-01 00:00:00".
 
+Tides
+~~~~~
+
+The record changes character at 2024-09-05. Sea surface height sampled on 2026-10-06 at
+40.40 N, 72.48 W (open water south of Long Island) shows:
+
+- **ESPC-D-V02** (hourly ``ssh``): a semidiurnal tide of about 0.43 m amplitude with a period
+  near 12.4 hours.
+- **GLBy0.08** ``expt_93.0`` (3-hourly): variations within about 5 cm and no tidal period. The
+  GLB experiments are run without tidal forcing.
+
+So a window before 2024-09-05 is a non-tidal ocean and a window after it is a tidal one, and a
+window across the date changes from one to the other. The fetcher records which in the
+``tides`` attribute of the output, which the dispatcher carries into the store:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - ``tides``
+     - Window
+   * - ``"none"``
+     - Entirely before 2024-09-05 (GLB experiments).
+   * - ``"included"``
+     - Entirely from 2024-09-05 (ESPC-D-V02).
+   * - ``"mixed"``
+     - Spans 2024-09-05: non-tidal before the switch, tidal after it. The fetcher also logs a
+       warning.
+
+Two consequences:
+
+- **Do not add tides twice.** A tidal parent (``tides = "included"``) already carries the tide
+  in ``zeta`` and in the currents. A downstream model that adds its own tidal boundary forcing
+  (harmonic constituents from TPXO, FES or similar) should do so only when ``tides`` is
+  ``"none"``; adding it to a tidal parent doubles the tide. A ``"mixed"`` window has no single
+  correct treatment and is best split at 2024-09-05 or avoided.
+- **Tidal sampling.** ESPC-D-V02's ``zeta`` is kept at its native hourly steps (step 3 below),
+  and the dispatcher's hourly resample leaves those values unchanged. Velocities, temperature
+  and salinity are published only 3-hourly, so the tidal currents are sampled four times per
+  semidiurnal cycle and linearly interpolated to hourly in between, which flattens their peaks
+  by up to about 30 percent.
+
 Where the data lives
 --------------------
 
@@ -127,9 +172,13 @@ How forcingkit reads it
    dataset's own convention (-180..180 or 0..360, detected per dataset); a box that crosses the
    dataset's seam is read in two parts. Only the five fields above are downloaded.
 3. **ESPC-D-V02 merge.** The five per-field datasets are read separately and merged on the
-   times they share, so hourly ``zeta`` is reduced to the 3-hourly steps.
+   union of their times, so ``zeta`` keeps its hourly steps and ``u``, ``v``, ``temp`` and
+   ``salt`` are NaN at the two hours between their 3-hourly steps. Times outside the span that
+   all five fields share are dropped, so no field begins or ends on a step it has no data for.
 4. **Clean-up.** Longitudes are returned on 0..360 for every experiment. Times are sorted,
-   duplicates dropped, and decoded to datetimes.
+   duplicates dropped, decoded to datetimes and rounded to the second (ESPC-D-V02 ``ssh``
+   decodes a few hundred nanoseconds off the hour, which would otherwise keep its steps apart
+   from those of the other fields in step 3).
 5. **Stitch.** Pieces from different experiments are concatenated in time. A piece on a
    different grid is interpolated (bilinear) onto the grid of the first piece. The step at a
    switch is read from both experiments; the newer one's copy is kept.
@@ -139,9 +188,12 @@ How forcingkit reads it
    data in a dataset's time range is not retried.
 
 Output is a Dataset with ``u``, ``v``, ``temp``, ``salt`` (``time, depth, lat, lon``) and
-``zeta`` (``time, lat, lon``). Land and cells below the sea floor are NaN. The dispatcher then
-resamples to hourly by linear interpolation, casts to Float32, and writes the store with
-``schema = "legacy"``.
+``zeta`` (``time, lat, lon``), and the ``tides`` attribute (see `Tides`_). Land and cells below
+the sea floor are NaN. The time axis is 3-hourly for GLB experiments and hourly for ESPC-D-V02,
+where only ``zeta`` has data at every step. The dispatcher then resamples to hourly by linear
+interpolation, each variable from the steps at which it has data (so the 3-hourly fields are
+bridged between their own steps and hourly ``zeta`` is kept as is), casts to Float32, and
+writes the store with ``schema = "legacy"``.
 
 Known issues
 ~~~~~~~~~~~~
@@ -161,8 +213,8 @@ Known issues
 - **GLBv0.08 ``expt_93.0`` steps back.** Its time axis goes from 2018-06-21 09:00 to 06:00,
   repeating 06:00. The fetcher selects by position and drops the duplicate.
 - **Dead path for ``expt_53.X``.** ``GLBy0.08/expt_53.X`` answers HTTP 200 with an empty
-  dataset description; the reanalysis lives under ``GLBv0.08``. forcingkit read the GLBy0.08
-  path before 2026-10-06, so HYCOM served nothing before 2018-12-04 until then.
+  dataset description; the reanalysis lives under ``GLBv0.08``, which is the path forcingkit
+  reads.
 - **GLBy0.08 ``expt_93.0`` starts at 12:00.** Its first step is 2018-12-04 12:00, not the
   midnight that the catalogue date suggests; the switch from GLBv0.08 ``expt_93.0`` is at
   12:00.
@@ -186,27 +238,35 @@ these returned all five fields on 10 x 5 cells and 40 depths:
    * - 2018-12-03 18:00, 12 h
      - GLBv0.08 ``expt_93.0``
      - 5 steps, in 12 s.
-   * - 2026-10-01 00:00, 6 h
+   * - 2026-10-01 00:00, 24 h
      - ESPC-D-V02 (five datasets)
-     - 3 steps, in 216 s; ``zeta`` reduced from hourly to 3-hourly.
+     - 25 hourly steps, ``zeta`` at all 25 and the other fields at 9, in 547 s (one read
+       retried); ``tides = "included"``. After the dispatcher's resample, ``zeta`` was
+       unchanged (a tidal range of about 0.8 m at one cell) and the surface ``u`` had no
+       gaps.
    * - 2018-12-04 06:00, 12 h
      - GLBv0.08 then GLBy0.08 ``expt_93.0``
      - 5 steps, in 367 s; 12:00 read from both, kept once.
    * - 2024-09-04 18:00, 12 h
      - GLBy0.08 ``expt_93.0`` then ESPC-D-V02
-     - 5 steps, in 334 s. ESPC-D-V02 marks a few more cells as land or below the sea floor
-       than GLBy0.08 in this box.
+     - 9 steps (3-hourly to 2024-09-05 00:00, then hourly), 13 after the dispatcher's
+       resample, in 623 s (one read retried); ``tides = "mixed"`` and the crossing warning
+       logged. An earlier attempt failed after two timeouts on ``v3z``. ESPC-D-V02 marks a
+       few more cells as land or below the sea floor than GLBy0.08 in this box.
 
-Before the per-dataset retry was added, five earlier attempts at the two stitched windows each
-stopped on one read timeout (see `Known issues`_).
+The times are for windows of 6 to 12 hours; multi-day windows have not been timed. Most of the
+time goes to per-request latency on the server rather than to data volume, so a longer window
+need not take proportionally longer, but plan for minutes per fetch and see `Known issues`_.
 
 Tests
 -----
 
 - ``tests/unit/test_hycom.py``: experiment resolution and window splitting at every switch,
   the URLs for GLBv0.08 and the ESPC-D-V02 fields, stitching across 2018-12-04 (regridding and
-  the duplicated switch step) and across 2024-09-05 (merged ESPC-D-V02 fields), the all or
-  nothing rule, the retry after a failed read (and none for an empty time range), both
+  the duplicated switch step) and across 2024-09-05 (merged ESPC-D-V02 fields), hourly ``zeta``
+  in the ESPC-D-V02 merge and through the dispatcher's hourly resample, trimming to the span
+  all fields share, rounding decoded times to the second, the ``tides`` attribute and the warning for a window across 2024-09-05, the
+  all or nothing rule, the retry after a failed read (and none for an empty time range), both
   longitude conventions and the seam, and the non-monotonic time axis. No network.
 
 .. code-block:: bash

{forcingkit-0.3.0 → forcingkit-0.5.0}/docs/source/index.rst

@@ -17,17 +17,20 @@ and serves model-ready time series, with a record of where every value came from
 What it does
 ------------
 
-A regional ocean model needs two things from outside its own domain: the state of a larger
-"parent" ocean along its open boundaries, and the atmosphere above its surface. Both come from
+A regional ocean model needs three things from outside its own domain: the state of a larger
+"parent" ocean along its open boundaries, the atmosphere above its surface, and the rivers that
+flow into it. The first two come from
 operational and archive systems (NOAA's `HRRR <https://rapidrefresh.noaa.gov/hrrr/>`__, the NOAA
 `Operational Forecast Systems <https://tidesandcurrents.noaa.gov/models.html>`__,
 `NECOFS <https://fvcom.smast.umassd.edu/?p=20>`__, `HYCOM <https://www.hycom.org/>`__) that
 differ in grid type, vertical coordinate, time convention, file layout and access protocol, and
-that change those details without notice.
+that change those details without notice. River discharge comes from stream gauges, which
+measure flow upstream of the head of tide rather than at the mouth.
 
 forcingkit is a FastAPI service that sits between those providers and model codes such as
 `Oceananigans.jl <https://github.com/CliMA/Oceananigans.jl>`__ (for example through
-`NumericalEarth <https://github.com/NumericalEarth/NumericalEarth.jl>`__). For a bounding box and a time window it:
+`NumericalEarth <https://github.com/NumericalEarth/NumericalEarth.jl>`__). For a bounding box and a
+time window it:
 
 1. picks the source (the "donor") best suited to the box, and falls back to the next one if the
    first cannot deliver;
@@ -60,6 +63,10 @@ What it serves
      - HRRR surface fields (10 m wind, 2 m temperature and humidity, pressure, radiation,
        precipitation) on a regular 0.03 degree grid, hourly, as schema ``hrrr-atm-v1``. See
        :doc:`atmospheric_forcing`.
+   * - ``POST /api/v1/rivers``
+     - Freshwater discharge at each listed river mouth in the box, hourly, from the tide-free
+       `USGS <https://waterdata.usgs.gov/>`__ stream gauges upstream (chosen per request) scaled
+       to the drainage area at the mouth, as schema ``river-v1``. See :doc:`rivers`.
    * - ``POST /api/v1/tide``
      - Observed water level at a `NOAA CO-OPS <https://tidesandcurrents.noaa.gov/>`__ station, for
        validation.
@@ -107,7 +114,7 @@ Parent-ocean donors at a glance
      - HYCOM GLBv0.08, GLBy0.08 and ESPC-D-V02, regular
      - 1/12 degree (about 9 km)
      - Global; 1994 to the present
-     - Legacy output; last-resort fallback
+     - Legacy output; last-resort fallback; tidal only from 2024-09-05
 
 Quick start
 -----------
@@ -153,6 +160,7 @@ PyPI as ``forcingkit``.
    nyofs
    hycom
    atmospheric_forcing
+   rivers
 
 .. toctree::
    :maxdepth: 1

{forcingkit-0.3.0 → forcingkit-0.5.0}/docs/source/necofs.rst

@@ -20,7 +20,8 @@ Regional Association of Coastal Ocean Observing Systems <https://neracoos.org/>`
 It is built on `FVCOM <https://fvcom.smast.umassd.edu/>`__, the unstructured-grid, finite-volume,
 free-surface, primitive-equation coastal ocean model introduced by `Chen, Liu and Beardsley
 (2003) <https://doi.org/10.1175/1520-0426(2003)020%3C0159:AUGFVT%3E2.0.CO;2>`__ and developed by
-Changsheng Chen's group at SMAST with Robert C. Beardsley at WHOI. forcingkit reads its **GOM7** configuration, which
+Changsheng Chen's group at SMAST with Robert C. Beardsley at WHOI. forcingkit reads its **GOM7**
+configuration, which
 spans the Gulf of Maine, Georges Bank, southern New England, Long Island Sound, New York Harbor
 and the Mid-Atlantic Bight shelf.
 

{forcingkit-0.3.0 → forcingkit-0.5.0}/docs/source/nyofs.rst

@@ -321,7 +321,9 @@ Institutions and data services
   <https://opendap.co-ops.nos.noaa.gov/thredds/catalog/catalog.html>`__
 - `NOAA NCEI <https://www.ncei.noaa.gov/>`__: `NYOFS files
   <https://www.ncei.noaa.gov/thredds/catalog/model-nyofs-files/catalog.html>`__
-- `NOAA Open Data Dissemination <https://www.noaa.gov/information-technology/open-data-dissemination>`__:
+- `NOAA Open Data Dissemination
+  <https://www.noaa.gov/information-technology/open-data-dissemination>`__:
   `OFS on AWS <https://github.com/NOAA-Big-Data-Program/nodd-data-docs/blob/main/OFS/README.md>`__
-- `Stevens Institute of Technology, Davidson Laboratory <https://www.stevens.edu/davidson-laboratory>`__:
+- `Stevens Institute of Technology, Davidson Laboratory
+  <https://www.stevens.edu/davidson-laboratory>`__:
   `NYHOPS <https://hudson.dl.stevens-tech.edu/maritimeforecast/>`__

forcingkit-0.5.0/docs/source/rivers.rst

@@ -0,0 +1,177 @@
+River Discharge
+===============
+
+``POST /api/v1/rivers`` delivers hourly freshwater discharge at the mouth of every listed river
+in a box (or at mouths passed with the request), for point or surface sources in an ocean model. A nested regional model otherwise
+receives river water only through its open boundaries and initial state, so a river that enters
+inside the domain is missing as a source and its freshwater decays over the run.
+
+Method
+------
+
+The method is common practice for gauge-driven river forcing. The NOAA Operational Forecast
+Systems map US Geological Survey real-time gauges onto model cells with a per-river scale factor
+and fall back to climatology. Regional estuary models scale gauged flow to ungauged area by the
+ratio of drainage areas.
+
+1. **Gauges, derived for every request.** Only a river's mouth is listed. From its NHDPlus
+   outlet flowline, forcingkit asks the USGS `NLDI <https://waterdata.usgs.gov/blog/nldi-intro/>`__
+   for every USGS site upstream, then keeps a site if:
+
+   - USGS classes it as a stream site (``ST``). Tidal streams (``ST-TS``) and estuaries (``ES``)
+     are left out, because their flow reverses with the tide; on the Connecticut River that rules
+     out Hartford and Middle Haddam;
+   - it has a drainage area, and a discharge record (15-minute or daily) covering the window;
+   - it drains at least ``min_share`` of the mouth's area (default 0.01), so headwater brooks
+     drop out;
+   - no other kept site lies downstream of it, which leaves the lowest gauge on each branch.
+
+   The kept gauges then measure disjoint parts of the basin. The selection follows the window: a
+   gauge that opened in 2010 is used from 2010 on, and one that closed is dropped from then on.
+2. **Discharge at the mouth.** The sum of the river's gauges, scaled by the drainage area at the
+   mouth over the gauged area:
+
+   .. math::
+
+      Q_\text{mouth} = \frac{A_\text{mouth}}{\sum_k A_k} \sum_k Q_k
+
+   Gauge areas come from the USGS monitoring-location records; the mouth's area is that of the
+   outlet's NLDI basin.
+3. **Time base.** The 15-minute record from the USGS Water Data APIs (``continuous``), averaged to
+   hourly values centred on the hour. The store holds ``hours + 1`` records, from ``start_time``
+   to ``start_time + hours``.
+4. **Gaps.** A gap of up to ``max_gap_hours`` (default 6) with values on both sides is
+   interpolated. A longer gap takes that day's mean from the ``daily`` record. A day with neither
+   is an error, unless ``allow_climatology`` is set; then it takes the USGS day-of-year median of
+   daily flow. Every filled hour is flagged in ``fill`` (0 measured, 1 interpolated, 2 daily
+   mean, 3 climatology median), and the store's ``provenance`` attribute counts them per river.
+5. **Water properties.** Salinity is zero. Water temperature (``temperature``) comes from the first
+   gauge on the river that measures it (USGS parameter 00010), and is NaN where none does.
+6. **Provisional data.** USGS values are provisional until approved, typically months later, and
+   provisional values are revised. A store containing any provisional value is marked
+   ``provisional = True`` and is served from the cache for one day only; after that a request
+   rebuilds it.
+7. **Travel time.** None by default. A mouth entry may set ``lag_hours``; gauge values are then
+   taken that many hours earlier.
+
+Mouths
+------
+
+Mouths are listed in ``forcingkit/data/rivers/*.json`` and in any ``*.json`` file in the directory
+named by ``FORCINGKIT_RIVER_MOUTHS_DIR``; a later entry with the same name replaces an earlier one.
+A request may instead pass its own ``mouths``. Adding a river needs a mouth entry and no code or
+release:
+
+.. code-block:: json
+
+   {"mouths": [
+     {"name": "Connecticut", "lon": -72.3305, "lat": 41.2726, "comid": 7703046},
+     {"name": "Saugatuck", "lon": -73.36, "lat": 41.10, "trace_from": "USGS-01208990"}
+   ]}
+
+- ``name``, ``lon``, ``lat`` (required): the point places the mouth for the bbox test.
+- ``comid``: the NHDPlus outlet flowline. Otherwise ``trace_from`` names any NLDI feature on the
+  river (a USGS site such as ``USGS-01184000``) and the outlet is the end of its downstream trace.
+  Failing both, the point is snapped to the nearest flowline, with a warning: at an estuary the
+  nearest flowline can be a short coastal one rather than the river.
+- ``include`` and ``exclude``: USGS site numbers to pin or rule out where judgement beats the rule
+  (for example a gauge below a dam whose releases should not drive the forcing). A pinned set that
+  drains more than the mouth's area is refused as double counting.
+- ``lag_hours``: travel time from the gauges to the mouth, applied to the gauge window.
+
+The id of a store includes the mouth entries and ``min_share``, but not the derived gauges, which
+are recorded in the store instead. NLDI facts about a mouth (its outlet, basin area, upstream sites
+and which sites lie downstream of which) are cached for 30 days under ``usgs/derivations`` in the
+cache directory, so only the first request for a mouth takes long (about a minute for the
+Connecticut, whose basin holds 1,375 USGS sites).
+
+The packaged mouths are the rivers into Long Island Sound. For a request over the Sound in April
+2026 the derivation chose:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 16 46 13 13 12
+
+   * - River
+     - USGS gauges kept
+     - Gauged (mi²)
+     - Mouth (mi²)
+     - Scale
+   * - Housatonic
+     - 01205500 at Stevenson; 01208500 Naugatuck at Beacon Falls
+     - 1,804
+     - 1,944
+     - 1.08
+   * - Quinnipiac
+     - 01196500 at Wallingford; 01196620 Mill River near Hamden; 01196561 Muddy River near East
+       Wallingford
+     - 148
+     - 204
+     - 1.37
+   * - Connecticut
+     - 01184000 at Thompsonville; 01189995 Farmington at Tariffville
+     - 10,237
+     - 11,242
+     - 1.10
+   * - Thames
+     - 01127000 Quinebaug at Jewett City; 011230695 Shetucket at Taftville; 01127500 Yantic at
+       Yantic
+     - 1,314
+     - 1,470
+     - 1.12
+
+The Quinnipiac's outlet basin is New Haven Harbor's, so its scaled flow also stands for the
+harbour's other streams. The Housatonic at Stevenson is below a hydroelectric dam, so its hourly
+flow follows the dam's releases. The Bronx River gauge (01302020) has no record before the 2000s,
+so a request for an earlier window fails unless ``skip_ungauged`` is set, which leaves such a
+river out and lists it in the store's ``skipped_rivers``.
+
+Request and store
+-----------------
+
+.. code-block:: bash
+
+   curl -s -X POST localhost:9598/api/v1/rivers -H 'Content-Type: application/json' -d '{
+     "bbox": {"min_lon": -73.855, "min_lat": 40.75, "max_lon": -71.9, "max_lat": 41.45},
+     "start_time": "2026-04-02T00:00:00Z", "hours": 48}'
+
+Optional fields: ``mouths``, ``min_share`` (default 0.01), ``max_gap_hours`` (default 6),
+``allow_climatology`` and ``skip_ungauged`` (both default false), and ``cache_bust``.
+
+For that request (four rivers, 49 records), the mean discharges over the 48 hours were 1,553 m³/s
+for the Connecticut, 147 for the Housatonic, 148 for the Thames and 13 for the Quinnipiac.
+
+The store (schema ``river-v1``) has a ``river`` dimension:
+
+- ``discharge`` (time, river): m³ s⁻¹, ``water_volume_transport_in_river_channel``.
+- ``temperature`` (time, river): °C.
+- ``fill`` (time, river): the flags above.
+- ``mouth_lon``, ``mouth_lat``, ``scale_factor``, ``salinity`` (river).
+- Attributes: ``river_names``; ``provenance`` (JSON: per river, the gauges kept, the areas, the
+  scale factor, the outlet, and the dropped candidates counted by reason); ``derivation_dropped``
+  (JSON: every dropped candidate with its reason); ``skipped_rivers``; ``provisional``; and
+  ``built_utc``.
+
+A JSON sidecar next to the store repeats the request, the mouths and the derivation. ``GET /api/v1/rivers/download/{zarr_id}``
+returns the store as a zip.
+
+Credentials
+-----------
+
+None are required. A free USGS Water Data API key (``USGS_API_KEY``, from
+`api.waterdata.usgs.gov/signup <https://api.waterdata.usgs.gov/signup/>`__) raises the hourly rate
+limit; it is sent in the ``X-Api-Key`` header. forcingkit uses the modernized APIs, not the
+legacy ``waterservices.usgs.gov``, which USGS plans to retire in 2027.
+
+Limits
+------
+
+- Mouths are not found automatically within a box: each river needs a mouth entry. Finding
+  coastal outlets from NHDPlus would remove that step.
+- The selection rule cannot tell a regulated gauge from a natural one; use ``exclude`` where dam
+  operations should not reach the forcing.
+- Gauges measure surface runoff. Groundwater discharge (most of Long Island's freshwater input) is
+  not represented.
+- A model that applies discharge as a surface freshwater flux on fixed levels dilutes salinity
+  but adds no volume. Whether the volume is added depends on the model's vertical coordinate, not
+  on this store.