forcingkit 0.3.0__tar.gz → 0.4.0__tar.gz

{forcingkit-0.3.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.3.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.3.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.3.0 → forcingkit-0.4.0}/PKG-INFO

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

{forcingkit-0.3.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 <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.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.3.0"
+release = "0.4.0"
 
 extensions = [
     "sphinx.ext.autodoc",

{forcingkit-0.3.0 → forcingkit-0.4.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.4.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.4.0}/docs/source/index.rst

@@ -27,7 +27,8 @@ that change those details without notice.
 
 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;
@@ -107,7 +108,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
 -----------

{forcingkit-0.3.0 → forcingkit-0.4.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.4.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.3.0 → forcingkit-0.4.0}/docs/source/roadmap.rst

@@ -45,8 +45,9 @@ Current coverage
      - 2014-07-30 on
      - 3 km
 
-So today the only current-date parent ocean outside the US Northeast is HYCOM, at 1/12 degree and
-in the legacy output layout, and there is no atmosphere outside the contiguous US. Older years and other regions rely on ERA5 through NumericalEarth in the model.
+So today the only parent ocean outside the US Northeast is HYCOM, at 1/12 degree and in the
+legacy output layout, and there is no atmosphere outside the contiguous US: there, and before
+2014-07-30, the atmosphere comes from ERA5 through NumericalEarth in the model.
 
 Planned work
 ------------
@@ -57,13 +58,16 @@ Planned work
 
    * - Item
      - Detail
+   * - HYCOM as a ``z-v3`` parent
+     - The cheapest conversion, and the one that gives a ``z-v3`` parent everywhere: HYCOM is
+       already on a regular longitude/latitude grid at fixed depths in metres, with temperature
+       and salinity, so it needs regridding onto the ``z-v3`` grid and an hour-by-hour
+       ``iter_parent``, but no sigma-to-depth step. Tidal content changes at 2024-09-05
+       (:doc:`hycom`), so the store should record it.
    * - NYOFS and DBOFS as ``z-v3`` parents
      - Deliver both on true depths with geographic axes, like :doc:`necofs`. NYOFS carries no
        temperature or salinity, so those would come from another donor. The scope is in
        :doc:`nyofs`.
-   * - A global parent on ``z-v3``
-     - HYCOM reaches the present through ESPC-D-V02 (:doc:`hycom`), but at 1/12 degree and in the
-       legacy output layout. Copernicus GLO12 or RTOFS (below) would add a second global source.
    * - HRRR forecast mode
      - One cycle's f01 to f48 for forecasts, alongside the chained one-hour forecasts used for
        hindcasts (:doc:`atmospheric_forcing`).
@@ -89,25 +93,27 @@ Global parent ocean
        <https://data.marine.copernicus.eu/product/GLOBAL_ANALYSISFORECAST_PHY_001_024/description>`__)
      - NEMO, 1/12 degree, 50 levels, hourly and daily fields, from 2020-11-01 to 10 days ahead,
        global. Free registration; cloud-native (ARCO Zarr) access.
-     - The global fallback for current dates, and the backbone for any region outside the US.
+     - Hourly fields and a second, independent model to set against HYCOM; the backbone for
+       any region outside the US.
    * - **GLORYS12 reanalysis** (Mercator Ocean, `GLOBAL_MULTIYEAR_PHY_001_030
        <https://data.marine.copernicus.eu/product/GLOBAL_MULTIYEAR_PHY_001_030/description>`__)
      - NEMO with data assimilation, 1/12 degree, 50 levels, daily means from 1993-01-01 to
        2026-08 (Lellouche et al., 2021).
-     - A consistent parent for any year since 1993, anywhere; daily, so tides must come from
-       elsewhere.
+     - One continuous reanalysis from 1993, where HYCOM chains several experiments from 1994;
+       daily, so tides must come from elsewhere.
    * - **NOAA Global RTOFS** (`on AWS <https://registry.opendata.aws/noaa-rtofs/>`__)
      - HYCOM-based, 1/12 degree. Besides the global output, 6-hourly netCDF already on z levels
        for three US subdomains (``US_east``, ``US_west``, ``alaska``), from 2024-01-27.
-     - A NOAA global fallback whose US cuts need no vertical regridding.
+     - US subsets already on z levels, so they need no vertical regridding.
 
 US coasts without a parent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The rest of the NOAA Operational Forecast Systems. Each is on AWS (``noaa-nos-ofs-pds``) per day
-from late 2024 (2024-10-01 for CBOFS, 2024-11-19 for most) and at NCEI before that, in the layouts forcingkit's NYOFS and DBOFS readers
-already handle. The ROMS systems can share the DBOFS reader and the FVCOM systems the NECOFS mesh
-interpolation, so each is mostly configuration and a domain.
+from late 2024 (2024-10-01 for CBOFS, 2024-11-19 for most) and at NCEI before that, in the
+layouts forcingkit's NYOFS and DBOFS readers already handle. The ROMS systems can share the DBOFS
+reader and the FVCOM systems the NECOFS mesh interpolation, so each is mostly configuration and
+a domain.
 
 .. list-table::
    :header-rows: 1

{forcingkit-0.3.0 → forcingkit-0.4.0}/docs/source/sources.rst

@@ -35,7 +35,8 @@ Providers
      - Blumberg and Mellor (1987) for POM (NYOFS); Shchepetkin and McWilliams (2005) for ROMS
        (DBOFS); NOAA attribution as for HRRR.
    * - HYCOM
-     - The `HYCOM consortium <https://www.hycom.org/>`__ (US Navy, NOAA and academic partners)
+     - The `HYCOM consortium <https://www.hycom.org/>`__ (US Navy, NOAA and academic partners);
+       from 2024-09-05 the US Navy's ESPC-D-V02 analysis, served by the consortium
      - Bleck (2002) for the model; Chassignet et al. (2007) for the data-assimilative system.
    * - ERA5 (used through NumericalEarth, not served here)
      - `ECMWF <https://www.ecmwf.int/>`__ for the `Copernicus Climate Change Service

{forcingkit-0.3.0 → forcingkit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forcingkit"
-version = "0.3.0"
+version = "0.4.0"
 description = "Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance."
 readme = "README.md"
 requires-python = ">=3.11"

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/dispatcher.py

@@ -1,9 +1,12 @@
 import os
 import logging
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 import numpy as np
 from forcingkit import settings
 
+if TYPE_CHECKING:
+    import xarray as xr
+
 
 logger = logging.getLogger(__name__)
 
@@ -262,8 +265,7 @@ def dispatch_obc_request(
                 ds["time"] = ds.indexes["time"].to_datetimeindex()
             except AttributeError:
                 ds["time"] = pd.to_datetime(ds.indexes["time"].values)
-        # Interpolate to strictly hourly
-        ds = ds.resample(time="1h").interpolate("linear")
+        ds = _resample_hourly(ds)
 
     # REQ-1.3: Tidal boundary condition integration via GOT4.10c or EOT20 (pyTMD).
 
@@ -310,6 +312,34 @@ def dispatch_obc_request(
 _FULL_PRECISION_COORDS = ("lat", "lon", "z", "z_face")
 
 
+def _resample_hourly(ds: "xr.Dataset") -> "xr.Dataset":
+    """Linearly interpolate every time-dependent variable onto an hourly axis.
+
+    Variables may arrive at different cadences on one time axis: HYCOM ESPC-D-V02 has hourly
+    surface elevation and 3-hourly currents, temperature and salinity, which are NaN at the
+    hours in between. Each variable is therefore interpolated from the times at which it has
+    any data, so a coarser field is bridged between its own steps and a finer one keeps its
+    native values. A single `resample().interpolate()` would treat those NaNs as data.
+    """
+    import pandas as pd
+
+    times = ds.indexes["time"]
+    hourly = pd.date_range(times.min().floor("h"), times.max().floor("h"), freq="h")
+    out = ds.drop_dims("time").assign_coords(time=hourly)
+    for name, da in ds.data_vars.items():
+        if "time" not in da.dims:
+            continue
+        others = [d for d in da.dims if d != "time"]
+        valid = (da.notnull().any(others) if others else da.notnull()).values
+        da = da.isel(time=valid)
+        out[name] = (
+            da.interp(time=hourly, assume_sorted=True)
+            if da.sizes["time"] > 1
+            else da.reindex(time=hourly)
+        )
+    return out[list(ds.data_vars)]
+
+
 def atmosphere_key(
     bbox: list[float],
     start_time: str,

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/fetchers/erddap.py

@@ -20,7 +20,7 @@ def fetch_erddap_station_profiles(
 ) -> dict:
     """
     Fetches 3-depth temperature profiles for a given station.
-    Targeting LIS stations via UConn ERDDAP.
+    Targets Long Island Sound stations on the UConn ERDDAP server.
 
     Args:
         station_id: Station ID, e.g., "WLIS", "EXRX"
@@ -105,7 +105,8 @@ def fetch_erddap_stations_in_bbox(
     cache_bust: bool = False,
 ) -> dict:
     """
-    Finds all known LIS stations within the bounding box and fetches their profiles.
+    Finds the known Long Island Sound stations within the bounding box and fetches their
+    profiles.
     bbox: [max_lat, min_lon, min_lat, max_lon] or [min_lon, min_lat, max_lon, max_lat]
     """
     # Accept standard Julia order (min_lon, min_lat, max_lon, max_lat)

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/fetchers/hycom.py

@@ -34,6 +34,8 @@ class _Segment:
     name: str
     # One aggregated dataset, or one dataset per variable to be merged.
     urls: tuple[str, ...]
+    # Whether the experiment's sea surface height and currents contain the tide.
+    tidal: bool = False
 
 
 def _glb(path: str, start: str) -> _Segment:
@@ -57,7 +59,11 @@ def _glb(path: str, start: str) -> _Segment:
 # - Time. All use "hours since 2000-01-01 00:00:00", 3-hourly, with occasional gaps of up to
 #   51 h that are passed through unfilled. GLBv0.08/expt_93.0 steps back once.
 # - ESPC-D-V02 serves u, v, temperature and salinity (3-hourly) and surface elevation (hourly)
-#   as separate datasets, merged on the shared 3-hourly times.
+#   as separate datasets. They are merged on the union of their times, so surface elevation
+#   stays hourly and the other fields are NaN between their 3-hourly steps.
+# - Tides. The GLB experiments are run without tidal forcing; ESPC-D-V02 includes the tide
+#   (about 0.43 m semidiurnal amplitude south of Long Island against about 5 cm of non-tidal
+#   variation in GLBy0.08/expt_93.0). The record therefore turns tidal on 2024-09-05.
 _SEGMENTS: tuple[_Segment, ...] = (
     _glb("GLBv0.08/expt_53.X", "1994-01-01"),
     _glb("GLBv0.08/expt_56.3", "2015-12-31"),
@@ -73,6 +79,7 @@ _SEGMENTS: tuple[_Segment, ...] = (
         tuple(
             f"{_TDS}/ESPC-D-V02/{var}" for var in ("u3z", "v3z", "t3z", "s3z", "ssh")
         ),
+        tidal=True,
     ),
 )
 
@@ -122,6 +129,16 @@ def _split_window(
     return pieces
 
 
+def _tides(pieces: list[tuple[_Segment, pd.Timestamp, pd.Timestamp]]) -> str:
+    """Tidal content of a window: "included", "none", or "mixed" across a switch."""
+    tidal = {seg.tidal for seg, _, _ in pieces}
+    if tidal == {True}:
+        return "included"
+    if tidal == {False}:
+        return "none"
+    return "mixed"
+
+
 def _normalize_lons(lons: np.ndarray) -> np.ndarray:
     """Convert -180/180 to 0/360."""
     return np.where(lons < 0, lons + 360, lons)
@@ -149,6 +166,15 @@ def fetch_hycom_boundary_conditions(
         names = ", ".join(seg.name for seg, _, _ in pieces)
         logger.info(f"Hindcast spans HYCOM experiments; stitching {names}...")
 
+    tides = _tides(pieces)
+    if tides == "mixed":
+        switch = next(seg.start for seg, _, _ in pieces if seg.tidal)
+        logger.warning(
+            f"HYCOM window {start_dt} to {end_dt} crosses {switch}, where the record changes "
+            "from non-tidal (GLB experiments) to tidal (ESPC-D-V02); sea surface height and "
+            "currents gain the tide part way through."
+        )
+
     parts = []
     for seg, piece_start, piece_end in pieces:
         part = _fetch_segment(seg, piece_start, piece_end, bbox)
@@ -160,9 +186,9 @@ def fetch_hycom_boundary_conditions(
             return None
         parts.append(part)
 
-    if len(parts) == 1:
-        return parts[0]
-    return _stitch(parts)
+    ds = parts[0] if len(parts) == 1 else _stitch(parts)
+    ds.attrs["tides"] = tides
+    return ds
 
 
 def _fetch_segment(
@@ -180,9 +206,13 @@ def _fetch_segment(
         parts.append(part)
     if len(parts) == 1:
         return parts[0]
-    # The inner join keeps the 3-hourly times common to all variables (surface elevation is
-    # hourly).
-    return xr.merge(parts, join="inner")
+    # Surface elevation is hourly and the other fields 3-hourly. The outer join keeps every
+    # time, leaving the 3-hourly fields NaN in between (the dispatcher interpolates each field
+    # from its own steps). Times outside the span all fields share are dropped, so no field
+    # starts or ends with a step it has no data for.
+    first = max(part.indexes["time"][0] for part in parts)
+    last = min(part.indexes["time"][-1] for part in parts)
+    return xr.merge(parts, join="outer").sel(time=slice(first, last))
 
 
 def _stitch(parts: list[xr.Dataset]) -> xr.Dataset:
@@ -309,10 +339,13 @@ def _read_hycom_data(
     actual_rename = {k: v for k, v in _RENAME.items() if k in ds_subset.data_vars}
     ds_subset = ds_subset.rename(actual_rename)
 
-    # Explicitly decode the raw float time coordinate to pandas DatetimeIndex lengths
+    # Explicitly decode the raw float time coordinate to pandas DatetimeIndex lengths.
+    # ESPC-D-V02 `ssh` decodes a few hundred nanoseconds off the hour (01:00 as
+    # 00:59:59.999999791, read 2026-10-06); rounding to the second keeps its steps equal to
+    # those of the 3-hourly fields it is merged with.
     if time_var in ds_subset.coords:
-        ds_subset[time_var] = epoch + pd.to_timedelta(
-            ds_subset[time_var].values, unit="h"
-        )
+        ds_subset[time_var] = (
+            epoch + pd.to_timedelta(ds_subset[time_var].values, unit="h")
+        ).round("s")
 
     return ds_subset

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/fetchers/necofs.py

@@ -130,7 +130,8 @@ class Barycentric:
     barycentric weights computed once.
 
     Equivalent to `LinearNDInterpolator(tri, values)(targets)`, which repeats the search for every
-    call: per parent hour that is one search per layer per variable (181 for LIS), each over every
+    call: per parent hour that is one search per layer per variable (181 for 45 layers of four
+    fields plus sea surface height), each over every
     target point. Values may carry leading dimensions: (..., npoints) -> (..., *shape). Targets
     outside the triangulation are NaN.
     """

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/fetchers/noaa.py

@@ -64,7 +64,7 @@ def fetch_noaa_tide_data(
         "units": "metric",
         "time_zone": "gmt",
         "format": "json",
-        "application": "lhzn_coastal_sim",
+        "application": "forcingkit",
     }
 
     try:

{forcingkit-0.3.0 → forcingkit-0.4.0}/src/forcingkit/settings.py

@@ -12,10 +12,9 @@ from pathlib import Path
 
 logger = logging.getLogger("forcingkit")
 
-# New name -> old names still read, in order. The cache directory had two names: the service
-# routes read COASTAL_SIM_DATA_CACHE_DIR and the fetchers ECODATA_CACHE_CACHE_DIR.
+# New name -> old names still read, in order.
 LEGACY_ENV: dict[str, tuple[str, ...]] = {
-    "FORCINGKIT_CACHE_DIR": ("ECODATA_CACHE_CACHE_DIR", "COASTAL_SIM_DATA_CACHE_DIR"),
+    "FORCINGKIT_CACHE_DIR": ("ECODATA_CACHE_CACHE_DIR",),
     "FORCINGKIT_MAX_WORKERS": ("ECODATA_CACHE_MAX_WORKERS",),
     # The elevation service, renamed topobathysim -> topobathykit on 2026-10-05.
     "TOPOBATHYKIT_URL": ("TOPOBATHYSIM_URL",),

forcingkit-0.3.0/tests/integration/test_obc_mab.py → forcingkit-0.4.0/tests/integration/test_obc_offshore_nj.py

@@ -10,9 +10,9 @@ from forcingkit.dispatcher import dispatch_obc_request
 
 
 @pytest.mark.integration
-def test_dispatch_mab_obc_24h():
+def test_dispatch_offshore_nj_obc():
     """
-    Test a 24 hour OBC fetch over the Mid-Atlantic Bight to ensure
+    Test an OBC fetch off central New Jersey to ensure
     NECOFS does not crash (`import os` issue), and HYCOM gracefully
     passes over without issuing invalid empty slices (`tau[16809:1:16808]`).
     """
@@ -39,9 +39,9 @@ def test_dispatch_mab_obc_24h():
 
     assert len(ds.time) > 0, "No time steps fetched."
     print(
-        f"\nSuccessfully fetched MAB OBC data for {hours} hours on {ds.attrs.get('Description', 'NECOFS')}!"
+        f"\nFetched {hours} h of OBC data off central New Jersey from {ds.attrs.get('source', 'unknown')}"
     )
 
 
 if __name__ == "__main__":
-    test_dispatch_mab_obc_24h()
+    test_dispatch_offshore_nj_obc()

{forcingkit-0.3.0 → forcingkit-0.4.0}/tests/scripts/inspect_dem.py

@@ -1,10 +1,17 @@
-import zarr
+"""Report NaN content and range of the `elevation` array in a DEM Zarr store.
+
+Usage: uv run python tests/scripts/inspect_dem.py PATH_TO_DEM.zarr
+"""
+
+import sys
+
 import numpy as np
+import zarr
+
+if len(sys.argv) != 2:
+    sys.exit(__doc__)
 
-ds = zarr.open(
-    "/home/lhzn/Projects/lhzn-io/coastal-sim/config/topobathykit/policies/throgs_neck_dem.zarr",
-    mode="r",
-)
+ds = zarr.open(sys.argv[1], mode="r")
 elev = ds["elevation"][:]  # type: ignore
 print("Elevation contains NaN:", np.isnan(elev).any())  # type: ignore
 print("NaN count:", np.isnan(elev).sum())  # type: ignore

{forcingkit-0.3.0 → forcingkit-0.4.0}/tests/unit/test_hycom.py

@@ -1,9 +1,12 @@
+import logging
+
 import xarray as xr
 import pandas as pd
 import numpy as np
 import pytest
 from unittest.mock import patch
 
+from forcingkit.dispatcher import _resample_hourly
 from forcingkit.fetchers.hycom import (
     _SEGMENTS,
     _fetch_hycom_data,
@@ -125,8 +128,16 @@ def test_hycom_historical_stitch():
     assert not np.isnan(ds["u"].values).any()
 
 
+def _three_hourly(ds, var):
+    """Whether `var` has data exactly at the 3-hourly steps of `ds` and NaN in between."""
+    on_step = ds.indexes["time"].hour % 3 == 0
+    has_data = ds[var].notnull().any([d for d in ds[var].dims if d != "time"]).values
+    return bool((has_data == on_step).all())
+
+
 def test_espc_merges_per_variable_datasets():
-    """ESPC-D-V02 fetches each variable separately and keeps the 3-hourly common times."""
+    """ESPC-D-V02 fetches each variable separately; zeta keeps its hourly steps and the
+    3-hourly fields are NaN between theirs."""
     with patch("forcingkit.fetchers.hycom._fetch_hycom_data") as mock_fetch:
         mock_fetch.side_effect = _espc("2025-03-01", 48)
         ds = fetch_hycom_boundary_conditions("2025-03-01", 48, BBOX)
@@ -136,22 +147,99 @@ def test_espc_merges_per_variable_datasets():
     ]
     assert set(ds.data_vars) == {"u", "v", "temp", "salt", "zeta"}
     assert ds.indexes["time"].equals(
-        pd.date_range("2025-03-01", "2025-03-03", freq="3h")
+        pd.date_range("2025-03-01", "2025-03-03", freq="h")
     )
     assert not np.isnan(ds["zeta"].values).any()
+    for var in ("u", "v", "temp", "salt"):
+        assert _three_hourly(ds, var)
+    assert ds.attrs["tides"] == "included"
 
 
-def test_stitch_across_espc_switch():
-    """A window across 2024-09-05 stitches GLBy0.08/expt_93.0 with merged ESPC-D-V02."""
-    start_date = "2024-09-04"
+def test_espc_trims_to_shared_span():
+    """Hourly zeta past the last 3-hourly step is dropped, so no field ends on a step it has
+    no data for."""
+    parts = _espc("2025-03-01", 48)
+    parts[-1] = _ds("2025-02-28 23:00", 51, freq="h", var="zeta", depth=False)
     with patch("forcingkit.fetchers.hycom._fetch_hycom_data") as mock_fetch:
+        mock_fetch.side_effect = parts
+        ds = fetch_hycom_boundary_conditions("2025-03-01", 48, BBOX)
+    assert ds.indexes["time"][0] == pd.Timestamp("2025-03-01")
+    assert ds.indexes["time"][-1] == pd.Timestamp("2025-03-03")
+
+
+def test_glb_window_is_not_tidal(caplog):
+    with (
+        patch("forcingkit.fetchers.hycom._fetch_hycom_data") as mock_fetch,
+        caplog.at_level(logging.WARNING, logger="forcingkit.fetchers.hycom"),
+    ):
+        mock_fetch.side_effect = [_glb("2024-09-01", 9)]
+        ds = fetch_hycom_boundary_conditions("2024-09-01", 24, BBOX)
+    assert ds.attrs["tides"] == "none"
+    assert not caplog.records
+
+
+def test_stitch_across_espc_switch(caplog):
+    """A window across 2024-09-05 stitches GLBy0.08/expt_93.0 with merged ESPC-D-V02, is
+    marked as mixed and logs a warning."""
+    start_date = "2024-09-04"
+    with (
+        patch("forcingkit.fetchers.hycom._fetch_hycom_data") as mock_fetch,
+        caplog.at_level(logging.WARNING, logger="forcingkit.fetchers.hycom"),
+    ):
         mock_fetch.side_effect = [_glb(start_date, 9), *_espc("2024-09-05", 24)]
         ds = fetch_hycom_boundary_conditions(start_date, 48, BBOX)
 
     assert mock_fetch.call_count == 6
     assert set(ds.data_vars) == {"u", "v", "temp", "salt", "zeta"}
-    assert ds.indexes["time"].equals(pd.date_range(start_date, "2024-09-06", freq="3h"))
+    # 3-hourly before the switch, hourly after it.
+    expected = pd.date_range(start_date, "2024-09-05", freq="3h").append(
+        pd.date_range("2024-09-05 01:00", "2024-09-06", freq="h")
+    )
+    assert ds.indexes["time"].equals(expected)
     assert not np.isnan(ds["zeta"].values).any()
+    assert _three_hourly(ds, "u")
+    assert ds.attrs["tides"] == "mixed"
+    [record] = caplog.records
+    assert record.levelno == logging.WARNING
+    assert "2024-09-05" in record.getMessage() and "tidal" in record.getMessage()
+
+
+def test_resample_keeps_hourly_zeta():
+    """The dispatcher's hourly resample keeps hourly zeta at its native values and
+    interpolates the 3-hourly fields between their own steps. Treating the gaps as data
+    would leave the 3-hourly fields NaN at two hours in three."""
+    hours = np.arange(25)
+    time = pd.date_range("2025-03-01", periods=hours.size, freq="h")
+    # An M2 tide, which 3-hourly sampling and linear interpolation would flatten.
+    tide = 0.43 * np.sin(2 * np.pi * hours / 12.42)
+    u = np.where(hours % 3 == 0, hours.astype(float), np.nan)
+    land = np.full(hours.size, np.nan)
+    ds = xr.Dataset(
+        {
+            "zeta": (("time", "lat"), np.stack([tide, land], axis=1)),
+            "u": (("time", "lat"), np.stack([u, land], axis=1)),
+            "h": (("lat",), [10.0, 0.0]),
+        },
+        coords={"time": time, "lat": [40.0, 40.1]},
+        attrs={"tides": "included"},
+    )
+    out = _resample_hourly(ds)
+
+    assert out.indexes["time"].equals(time)
+    np.testing.assert_allclose(out["zeta"].values[:, 0], tide)
+    np.testing.assert_allclose(out["u"].values[:, 0], hours)
+    assert np.isnan(out["u"].values[:, 1]).all()
+    assert out["h"].values.tolist() == [10.0, 0.0]
+    assert out.attrs["tides"] == "included"
+
+
+def test_resample_regular_input_unchanged():
+    """A dataset with one cadence resamples as `resample().interpolate()` does."""
+    ds = _glb("2025-03-01", 9)
+    ds["u"][:] = np.arange(9.0)[:, None, None, None]
+    out = _resample_hourly(ds)
+    ref = ds.resample(time="1h").interpolate("linear")
+    xr.testing.assert_allclose(out, ref)
 
 
 def test_missing_piece_drops_window():
@@ -221,6 +309,23 @@ def test_fetch_non_monotonic_time():
     assert ds.indexes["time"].equals(expected)
 
 
+def test_fetch_rounds_times_to_the_second():
+    """Float hours that decode a few hundred nanoseconds off the hour (as ESPC-D-V02 `ssh`
+    does) come back on whole seconds, so they align with the other fields in the merge."""
+    t0 = (pd.Timestamp("2025-01-01 12:00") - pd.Timestamp("2000-01-01")).total_seconds()
+    time = t0 / 3600 + np.arange(4.0) - np.array([0.0, 2e-13, 0.0, -2e-13]) * 3600
+    raw = _raw(np.arange(0.0, 360.0), time=time)
+    with patch("forcingkit.fetchers.hycom.xr.open_dataset", return_value=raw):
+        ds = _fetch_hycom_data(
+            pd.Timestamp("2025-01-01 12:00"),
+            pd.Timestamp("2025-01-01 15:00"),
+            BBOX,
+            f"{TDS}/ESPC-D-V02/ssh",
+        )
+    expected = pd.date_range("2025-01-01 12:00", periods=4, freq="h")
+    assert ds.indexes["time"].equals(expected)
+
+
 def _fetch_2025(open_dataset):
     """`_fetch_hycom_data` for 2025-01-01 12:00 to 18:00 with `xr.open_dataset` and
     `time.sleep` patched; returns (result, open_dataset mock, sleep mock)."""

{forcingkit-0.3.0 → forcingkit-0.4.0}/tests/unit/test_settings.py

@@ -7,7 +7,6 @@ from forcingkit import settings
 ALL_NAMES = [
     "FORCINGKIT_CACHE_DIR",
     "ECODATA_CACHE_CACHE_DIR",
-    "COASTAL_SIM_DATA_CACHE_DIR",
     "FORCINGKIT_MAX_WORKERS",
     "TOPOBATHYKIT_URL",
     "TOPOBATHYSIM_URL",
@@ -38,13 +37,11 @@ def test_new_name_wins_over_legacy_names(clean_env, monkeypatch):
     assert settings.cache_dir() == "/new"
 
 
-@pytest.mark.parametrize(
-    "old", ["ECODATA_CACHE_CACHE_DIR", "COASTAL_SIM_DATA_CACHE_DIR"]
-)
-def test_legacy_cache_names_still_read_with_a_warning(clean_env, monkeypatch, old):
-    monkeypatch.setenv(old, "/old")
+def test_legacy_cache_name_still_read_with_a_warning(clean_env, monkeypatch):
+    monkeypatch.setenv("ECODATA_CACHE_CACHE_DIR", "/old")
     with pytest.warns(
-        FutureWarning, match=f"{old} is deprecated; use FORCINGKIT_CACHE_DIR"
+        FutureWarning,
+        match="ECODATA_CACHE_CACHE_DIR is deprecated; use FORCINGKIT_CACHE_DIR",
     ):
         assert settings.cache_dir("erddap") == os.path.join("/old", "erddap")
 

{forcingkit-0.3.0 → forcingkit-0.4.0}/uv.lock

@@ -873,7 +873,7 @@ wheels = [
 
 [[package]]
 name = "forcingkit"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "bottleneck" },