forcingkit 0.20.1__tar.gz → 0.21.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. {forcingkit-0.20.1 → forcingkit-0.21.0}/.env.template +6 -0
  2. {forcingkit-0.20.1 → forcingkit-0.21.0}/PKG-INFO +3 -2
  3. {forcingkit-0.20.1 → forcingkit-0.21.0}/README.md +2 -1
  4. forcingkit-0.21.0/docs/source/cache_viewer.rst +67 -0
  5. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/conf.py +1 -1
  6. forcingkit-0.21.0/docs/source/doppio.rst +136 -0
  7. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/fetchers.rst +6 -2
  8. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/index.rst +10 -1
  9. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/layered_mesh.rst +5 -0
  10. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/necofs.rst +15 -6
  11. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/roadmap.rst +3 -1
  12. forcingkit-0.21.0/docs/source/shelf_models.rst +270 -0
  13. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/sources.rst +9 -0
  14. {forcingkit-0.20.1 → forcingkit-0.21.0}/pyproject.toml +1 -1
  15. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/routers/viewer.py +277 -6
  16. forcingkit-0.21.0/src/forcingkit/fetchers/doppio.py +504 -0
  17. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/necofs.py +67 -16
  18. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/layered_mesh.py +41 -1
  19. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/mesh_frames.py +3 -6
  20. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/app.js +31 -12
  21. forcingkit-0.21.0/static/coverage.js +372 -0
  22. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/index.html +27 -1
  23. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/styles.css +119 -0
  24. forcingkit-0.21.0/tests/unit/data/doppio_reanalysis_20220811_corner.nc +0 -0
  25. forcingkit-0.21.0/tests/unit/test_cache_inventory.py +90 -0
  26. forcingkit-0.21.0/tests/unit/test_doppio.py +217 -0
  27. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_necofs_hindcast.py +209 -0
  28. {forcingkit-0.20.1 → forcingkit-0.21.0}/uv.lock +1 -1
  29. {forcingkit-0.20.1 → forcingkit-0.21.0}/.agents/forcingkit.md +0 -0
  30. {forcingkit-0.20.1 → forcingkit-0.21.0}/.claude/CLAUDE.md +0 -0
  31. {forcingkit-0.20.1 → forcingkit-0.21.0}/.github/copilot-instructions.md +0 -0
  32. {forcingkit-0.20.1 → forcingkit-0.21.0}/.github/workflows/docs.yml +0 -0
  33. {forcingkit-0.20.1 → forcingkit-0.21.0}/.github/workflows/publish-client.yml +0 -0
  34. {forcingkit-0.20.1 → forcingkit-0.21.0}/.github/workflows/publish.yml +0 -0
  35. {forcingkit-0.20.1 → forcingkit-0.21.0}/.github/workflows/tests.yml +0 -0
  36. {forcingkit-0.20.1 → forcingkit-0.21.0}/.gitignore +0 -0
  37. {forcingkit-0.20.1 → forcingkit-0.21.0}/.markdownlint.yaml +0 -0
  38. {forcingkit-0.20.1 → forcingkit-0.21.0}/.pre-commit-config.yaml +0 -0
  39. {forcingkit-0.20.1 → forcingkit-0.21.0}/.python-version +0 -0
  40. {forcingkit-0.20.1 → forcingkit-0.21.0}/AGENTS.md +0 -0
  41. {forcingkit-0.20.1 → forcingkit-0.21.0}/CONTRIBUTING.md +0 -0
  42. {forcingkit-0.20.1 → forcingkit-0.21.0}/Dockerfile +0 -0
  43. {forcingkit-0.20.1 → forcingkit-0.21.0}/LICENSE +0 -0
  44. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/LICENSE +0 -0
  45. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/README.md +0 -0
  46. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/pyproject.toml +0 -0
  47. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/src/forcingkit_client/__init__.py +0 -0
  48. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/src/forcingkit_client/client.py +0 -0
  49. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/src/forcingkit_client/schema.py +0 -0
  50. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/src/forcingkit_client/store.py +0 -0
  51. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/src/forcingkit_client/trajectory.py +0 -0
  52. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/tests/conftest.py +0 -0
  53. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/tests/test_client.py +0 -0
  54. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/tests/test_schema.py +0 -0
  55. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/tests/test_trajectory.py +0 -0
  56. {forcingkit-0.20.1 → forcingkit-0.21.0}/client/uv.lock +0 -0
  57. {forcingkit-0.20.1 → forcingkit-0.21.0}/docker-compose.yml +0 -0
  58. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/Makefile +0 -0
  59. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/make.bat +0 -0
  60. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/requirements-docs.txt +0 -0
  61. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/_extra/CNAME +0 -0
  62. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/_static/forcingkit-noreaster-wind.gif +0 -0
  63. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/atmospheric_forcing.rst +0 -0
  64. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/client.rst +0 -0
  65. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/hycom.rst +0 -0
  66. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/mesh_frames.rst +0 -0
  67. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/nyofs.rst +0 -0
  68. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/rivers.rst +0 -0
  69. {forcingkit-0.20.1 → forcingkit-0.21.0}/docs/source/waves.rst +0 -0
  70. {forcingkit-0.20.1 → forcingkit-0.21.0}/main.py +0 -0
  71. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/__init__.py +0 -0
  72. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/__init__.py +0 -0
  73. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/jobs.py +0 -0
  74. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/main.py +0 -0
  75. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/routers/bathymetry.py +0 -0
  76. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/routers/plotly_api.py +0 -0
  77. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/routers/removed.py +0 -0
  78. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/routers/stores.py +0 -0
  79. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/forcingkit_serve/stac.py +0 -0
  80. {forcingkit-0.20.1 → forcingkit-0.21.0}/service/run_server.py +0 -0
  81. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/__init__.py +0 -0
  82. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/data/rivers/northeast_us.json +0 -0
  83. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/dispatcher.py +0 -0
  84. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/coastwatch.py +0 -0
  85. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/dbofs.py +0 -0
  86. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/erddap.py +0 -0
  87. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hfradar.py +0 -0
  88. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hrdps.py +0 -0
  89. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hrrr.py +0 -0
  90. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hrrr_atmosphere.py +0 -0
  91. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hrrr_levels.py +0 -0
  92. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hrrr_points.py +0 -0
  93. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hycom.py +0 -0
  94. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/hydrography.py +0 -0
  95. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/ndbc.py +0 -0
  96. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/noaa.py +0 -0
  97. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/nwps.py +0 -0
  98. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/nyofs.py +0 -0
  99. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/usgs.py +0 -0
  100. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/fetchers/usgs_rivers.py +0 -0
  101. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/ramps/currents_lis.csv +0 -0
  102. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/ramps/currents_lis_dark.csv +0 -0
  103. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/ramps/currents_lis_deep.csv +0 -0
  104. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/ramps/currents_lis_haline.csv +0 -0
  105. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/render.py +0 -0
  106. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/settings.py +0 -0
  107. {forcingkit-0.20.1 → forcingkit-0.21.0}/src/forcingkit/zarr_stream.py +0 -0
  108. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/favicon.ico +0 -0
  109. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/favicon.svg +0 -0
  110. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/logo.svg +0 -0
  111. {forcingkit-0.20.1 → forcingkit-0.21.0}/static/preview3d.js +0 -0
  112. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/__init__.py +0 -0
  113. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_auth.py +0 -0
  114. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_erddap_fetch.py +0 -0
  115. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_mesh_frames_necofs.py +0 -0
  116. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_necofs_volume_live.py +0 -0
  117. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_nwps_nomads.py +0 -0
  118. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_nyofs_obc_fetch.py +0 -0
  119. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_obc_offshore_nj.py +0 -0
  120. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_ofs_archive_paths.py +0 -0
  121. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/integration/test_s3_roms_fetchers.py +0 -0
  122. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/scripts/inspect_dem.py +0 -0
  123. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/scripts/inspect_grib.py +0 -0
  124. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/scripts/inspect_zarr.py +0 -0
  125. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_coastwatch.py +0 -0
  126. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_dbofs.py +0 -0
  127. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_dispatcher.py +0 -0
  128. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_erddap.py +0 -0
  129. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hfradar.py +0 -0
  130. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hrdps.py +0 -0
  131. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hrrr_atm.py +0 -0
  132. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hrrr_idx.py +0 -0
  133. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hrrr_levels.py +0 -0
  134. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hrrr_points.py +0 -0
  135. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_hycom.py +0 -0
  136. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_jobs.py +0 -0
  137. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_layered_mesh.py +0 -0
  138. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_main.py +0 -0
  139. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_mesh_frames.py +0 -0
  140. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_ndbc.py +0 -0
  141. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_necofs_mesh_cache.py +0 -0
  142. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_necofs_parent.py +0 -0
  143. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_necofs_volume.py +0 -0
  144. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_noaa_currents.py +0 -0
  145. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_noaa_datum.py +0 -0
  146. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_nwps.py +0 -0
  147. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_nyofs.py +0 -0
  148. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_obc_donor_report.py +0 -0
  149. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_obc_pipeline.py +0 -0
  150. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_removed_routes.py +0 -0
  151. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_settings.py +0 -0
  152. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_usgs.py +0 -0
  153. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_usgs_rivers.py +0 -0
  154. {forcingkit-0.20.1 → forcingkit-0.21.0}/tests/unit/test_zarr_stream.py +0 -0
@@ -13,6 +13,12 @@
13
13
  # ECODATA_CACHE_CACHE_DIR is still read, with a warning, until the next release.
14
14
  # FORCINGKIT_CACHE_DIR=~/.cache/forcingkit
15
15
 
16
+ # Relief basemap for the cache viewer's coverage map: a folder of <name>.pmtiles raster
17
+ # archives (optional <name>.coast.geojson shorelines) and their credit line. Unset, the map
18
+ # uses the OpenFreeMap dark style.
19
+ # FORCINGKIT_BASEMAP_DIR=
20
+ # FORCINGKIT_BASEMAP_ATTRIBUTION=
21
+
16
22
  # Threads for parallel OPeNDAP reads (default 4; was ECODATA_CACHE_MAX_WORKERS).
17
23
  # FORCINGKIT_MAX_WORKERS=4
18
24
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: forcingkit
3
- Version: 0.20.1
3
+ Version: 0.21.0
4
4
  Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
5
5
  Project-URL: Documentation, https://forcingkit.docs.lhzn.io
6
6
  Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
@@ -280,13 +280,14 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
280
280
  ## Current Coverage
281
281
 
282
282
  - **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
283
+ - **Ocean Model Comparison**: Doppio full-depth subsets on its own grid (Mid-Atlantic Bight and Gulf of Maine, about 7 km, hourly from 2007), in the NECOFS volume field names and units; not yet a parent-ocean donor.
283
284
  - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
284
285
  - **Forecasts at Points**: HRRR (to 48 h) and ECCC's HRDPS (2.5 km, 10 m wind and gust to 48 h, from the MSC Datamart's 30-day window). HRDPS data: Data Source: Environment and Climate Change Canada ([license](https://eccc-msc.github.io/open-data/licence/readme_en/)).
285
286
  - **Surface Waves**: NWPS (one forecast office's grid per request, for example OKX CG1 at about 1.8 km, hourly, not regridded). NOMADS keeps about five days; older windows need an NWPS archive (`FORCINGKIT_NWPS_ARCHIVE`).
286
287
 
287
288
  ## Roadmap
288
289
 
289
- - **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).
290
+ - **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), Doppio as a parent-ocean donor for 2007 to 2024 in the Northeast (its subsets are readable today), HRRR Alaska and ECMWF IFS for the atmosphere, and a first European ocean source from Copernicus Marine (IBI or the North West Shelf).
290
291
  - **Resolution second**: the NYOFS fine grid, the Monterey Bay nests of WCOFS, and SFBOFS inside San Francisco Bay.
291
292
  - **NYOFS and DBOFS as z-v3 parents**: both on true depths with geographic axes.
292
293
  - **Forecast mode and cache policy**: HRRR forecast cycles, and invalidation of forecast-built stores when a newer cycle is published.
@@ -33,13 +33,14 @@ The primary goal of forcingkit is to provide clean, standardized ocean and atmos
33
33
  ## Current Coverage
34
34
 
35
35
  - **Oceanic Forcing**: NYOFS, NECOFS, DBOFS, HYCOM (global, 1994 to present).
36
+ - **Ocean Model Comparison**: Doppio full-depth subsets on its own grid (Mid-Atlantic Bight and Gulf of Maine, about 7 km, hourly from 2007), in the NECOFS volume field names and units; not yet a parent-ocean donor.
36
37
  - **Atmospheric Forcing**: HRRR (3 km, hourly, 2014-07-30 to present), regridded to 0.03 degrees.
37
38
  - **Forecasts at Points**: HRRR (to 48 h) and ECCC's HRDPS (2.5 km, 10 m wind and gust to 48 h, from the MSC Datamart's 30-day window). HRDPS data: Data Source: Environment and Climate Change Canada ([license](https://eccc-msc.github.io/open-data/licence/readme_en/)).
38
39
  - **Surface Waves**: NWPS (one forecast office's grid per request, for example OKX CG1 at about 1.8 km, hourly, not regridded). NOMADS keeps about five days; older windows need an NWPS archive (`FORCINGKIT_NWPS_ARCHIVE`).
39
40
 
40
41
  ## Roadmap
41
42
 
42
- - **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).
43
+ - **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), Doppio as a parent-ocean donor for 2007 to 2024 in the Northeast (its subsets are readable today), HRRR Alaska and ECMWF IFS for the atmosphere, and a first European ocean source from Copernicus Marine (IBI or the North West Shelf).
43
44
  - **Resolution second**: the NYOFS fine grid, the Monterey Bay nests of WCOFS, and SFBOFS inside San Francisco Bay.
44
45
  - **NYOFS and DBOFS as z-v3 parents**: both on true depths with geographic axes.
45
46
  - **Forecast mode and cache policy**: HRRR forecast cycles, and invalidation of forecast-built stores when a newer cycle is published.
@@ -0,0 +1,67 @@
1
+ Cache viewer
2
+ ============
3
+
4
+ The service serves a page at ``/ui/`` that lists every store in ``FORCINGKIT_CACHE_DIR``: the
5
+ Zarr stores it built and the raw GRIB and NetCDF files it fetched. The page polls
6
+ ``/api/v1/cache/inventory`` every two seconds, so new stores appear while a request is still
7
+ running.
8
+
9
+ Coverage
10
+ --------
11
+
12
+ The **Coverage** tab answers which stores cover a place and a time:
13
+
14
+ - **Map.** Each store's footprint is drawn as an outline, colored by its source family (NECOFS,
15
+ Doppio, HRRR, HYCOM, HF radar and so on). Hovering an outline names the store, its kind and its
16
+ time span; clicking it selects the store and opens its preview.
17
+ - **Coverage strip.** One row per source family and one column per UTC day. The shade is the
18
+ number of hours of that day covered by the stores in the current map view, so panning or
19
+ zooming the map changes the strip. Clicking a cell filters the list and the map to that day.
20
+
21
+ The filters above the list apply to both: the family chips (click to hide or show a family,
22
+ double-click to show only it), the kind, a date range, and **In map view**, which lists only
23
+ the stores that overlap the map.
24
+
25
+ Inventory fields
26
+ ----------------
27
+
28
+ Besides the display strings, each inventory entry carries structured fields for other tools:
29
+
30
+ .. list-table::
31
+ :header-rows: 1
32
+ :widths: 20 80
33
+
34
+ * - Field
35
+ - Meaning
36
+ * - ``bbox``
37
+ - ``[west, south, east, north]`` in degrees (longitudes in -180 to 180), from the store's
38
+ longitude and latitude coordinates or variables (mesh nodes and river mouths included),
39
+ else from its ``bbox`` or ``requested_bbox`` attribute. ``null`` when neither exists.
40
+ * - ``time_start``, ``time_end``
41
+ - ISO 8601 UTC times of the first and last records, or the target date of a snapshot.
42
+ * - ``family``
43
+ - The source model or provider, read from the store's path and its ``type``, ``source``
44
+ and donor attributes.
45
+ * - ``kind``
46
+ - ``ocean boundary``, ``ocean volume``, ``initial condition``, ``atmosphere``,
47
+ ``atmosphere levels``, ``waves``, ``rivers``, ``surface currents (radar)`` or
48
+ ``raw donor file``.
49
+
50
+ Entries are cached per store and rebuilt only when the store's metadata files change.
51
+
52
+ Basemap
53
+ -------
54
+
55
+ By default the map uses the `OpenFreeMap <https://openfreemap.org/>`__ dark vector style
56
+ (OpenStreetMap data), which needs no key. To draw your own relief instead, put PMTiles archives of raster tiles (WebP or PNG, 256 px) in a folder and point the
57
+ service at it:
58
+
59
+ .. code-block:: bash
60
+
61
+ export FORCINGKIT_BASEMAP_DIR=/path/to/basemaps
62
+ export FORCINGKIT_BASEMAP_ATTRIBUTION="Relief: NOAA, USGS"
63
+
64
+ Every ``<name>.pmtiles`` in the folder is drawn, coarsest first (by deepest zoom), dimmed for the
65
+ dark page; a ``<name>.coast.geojson`` beside it is drawn as a shoreline. The page reads the
66
+ archives in byte ranges from ``/api/v1/cache/basemap/files/<file>``, and
67
+ ``/api/v1/cache/basemap`` lists them.
@@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath("../../src"))
9
9
  project = "forcingkit"
10
10
  copyright = "2026, Long Horizon Observatory"
11
11
  author = "Daniel Fry"
12
- release = "0.20.1"
12
+ release = "0.21.0"
13
13
 
14
14
  extensions = [
15
15
  "sphinx.ext.autodoc",
@@ -0,0 +1,136 @@
1
+ Doppio (ROMS, Mid-Atlantic Bight and Gulf of Maine)
2
+ ===================================================
3
+
4
+ Doppio is a `ROMS <https://www.myroms.org/>`__ configuration for the Mid-Atlantic Bight and the
5
+ Gulf of Maine, run by the `Rutgers University Ocean Modeling Group
6
+ <https://rucool.marine.rutgers.edu/>`__ for `MARACOOS <https://maracoos.org/>`__ (López et al.,
7
+ 2020). Rutgers runs it in two forms, both with data assimilation and both served hourly from the
8
+ `Rutgers THREDDS server <https://tds.marine.rutgers.edu/thredds/catalog/roms/doppio/catalog.html>`__:
9
+
10
+ - the **reanalysis** DopAnV3R3-ini2007 (4D-Var; Wilkin et al., 2022), 2007-01-02 01:00 to
11
+ 2024-12-31 00:00 UTC, every hour with no gaps; and
12
+ - the **real-time system** (2017_da), 2017-11-02 01:00 UTC to about two days ahead, as the "Best"
13
+ time series of a forecast model run collection.
14
+
15
+ ``forcingkit.fetchers.doppio`` reads either as a full-depth subset in the same layout as the
16
+ NECOFS volume (:doc:`necofs`, schema ``volume-v1``), so a comparison between the two models, or
17
+ between either and a downstream ocean model, can treat them alike. It is a library function: no
18
+ service route or parent-ocean (``z-v3``) delivery uses it yet.
19
+
20
+ Underlying model
21
+ ----------------
22
+
23
+ Checked against the aggregations' OPeNDAP metadata on 2026-11-17.
24
+
25
+ - **Grid**: curvilinear Arakawa C-grid, 106 x 242 rho points (``eta_rho``, ``xi_rho``), about
26
+ 7 km, from 80.5 W to 59.7 W and 32.2 N to 46.6 N. The grid's xi axis is turned about 37 degrees
27
+ from east (``angle``), so ``u`` and ``v`` in the files are along the grid, not east and north.
28
+ - **Vertical coordinate**: 40 terrain-following s-levels (``s_rho``, bottom first), Vtransform 2,
29
+ Vstretching 4, theta_s 7, theta_b 2, hc 250 m.
30
+ - **Fields**: ``u`` (on u faces), ``v`` (on v faces), ``w`` (on the 41 ``s_w`` interfaces),
31
+ ``temp`` (potential temperature, Celsius), ``salt``, ``zeta``, plus ``ubar``, ``vbar``, mixing
32
+ coefficients and surface fluxes. The real-time aggregation also carries ``u_eastward`` and
33
+ ``v_northward`` at rho points, but they are empty (fill values) for 2022 and populated for
34
+ recent dates.
35
+ - **Datum**: the free surface is relative to the model mean sea level; the Rutgers metadata
36
+ states no geodetic datum, so do not compare it with NAVD88 water levels without an offset.
37
+ - **Time**: ``ocean_time`` in seconds since 2006-01-01 (reanalysis); ``time`` in hours since
38
+ 2017-11-01 (real time).
39
+
40
+ The full-depth subset
41
+ ---------------------
42
+
43
+ ``volume(bbox, start, end)`` returns every s-level for the index rectangle around the cells
44
+ whose centers lie in the box, hourly from ``start`` to ``end`` inclusive, with no horizontal
45
+ regridding and no vertical conversion. ``read_volume(bbox, start_time, hours, dap_url=None)``
46
+ reads one aggregation.
47
+
48
+ .. code-block:: python
49
+
50
+ from forcingkit.fetchers.doppio import volume
51
+
52
+ bbox = [-69.89, 39.66, -69.26, 40.14] # Veatch Canyon mouth and the shelf break above it
53
+ vol = volume(bbox, "2022-08-11T00Z", "2022-08-14T00Z") # 73 hourly records
54
+
55
+ .. list-table::
56
+ :header-rows: 1
57
+ :widths: 22 30 48
58
+
59
+ * - Name
60
+ - Dimensions
61
+ - Meaning
62
+ * - ``u``, ``v``
63
+ - (time, siglay, eta_rho, xi_rho)
64
+ - Eastward and northward velocity at the cell centers, m s-1: the two faces either side of
65
+ each center averaged (a land face counts as zero flow, as in ROMS's own ``u2rho``), then
66
+ rotated by ``angle``. On 2026-11-10 this matched the real-time aggregation's own
67
+ ``u_eastward`` and ``v_northward`` to 6e-8 m s-1.
68
+ * - ``ww``
69
+ - (time, siglay, eta_rho, xi_rho)
70
+ - ROMS ``w`` (upward velocity in z), averaged from the interfaces above and below each
71
+ layer center; the name follows the NECOFS volume.
72
+ * - ``temp``, ``salinity``
73
+ - (time, siglay, eta_rho, xi_rho)
74
+ - Potential temperature (degree_Celsius) and salinity (1e-3).
75
+ * - ``zeta``; ``h``
76
+ - (time, eta_rho, xi_rho); (eta_rho, xi_rho)
77
+ - Surface elevation relative to the model mean sea level (m, positive up); depth (m, positive down).
78
+ * - ``siglay``, ``siglev``
79
+ - (siglay, eta_rho, xi_rho), (siglev, eta_rho, xi_rho)
80
+ - The fraction of the water column at layer centers and interfaces, surface first:
81
+ ``(hc * s + h * Cs) / (hc + h)``, which for Vtransform 2 makes the depth of a layer center
82
+ :math:`\sigma (h + \zeta) + \zeta`, the NECOFS formula.
83
+ * - ``lon``, ``lat``, ``mask``, ``angle``
84
+ - (eta_rho, xi_rho)
85
+ - Cell centers in degrees (``lon`` and ``lat`` are 2D auxiliary coordinates, so CF tools
86
+ and the cache viewer place the cells), water mask, and the grid angle in radians.
87
+ * - ``in_bbox``
88
+ - (eta_rho, xi_rho)
89
+ - The cell center lies in the box. The rectangle's corners may not, since the grid is
90
+ rotated: for the box above, 59 of the 100 cells.
91
+ * - ``eta_rho``, ``xi_rho`` (coordinates)
92
+ - (eta_rho), (xi_rho)
93
+ - Each row's and column's index in the full grid.
94
+
95
+ Field names and units match the NECOFS volume (``u``, ``v``, ``ww``, ``temp``, ``salinity``,
96
+ ``zeta``, ``h``, ``siglay``, ``siglev``). The horizontal layout differs: NECOFS returns elements
97
+ and nodes of an unstructured mesh, Doppio rows and columns of a curvilinear grid, with every field
98
+ at the cell centers. Land cells are NaN in the time-varying fields.
99
+
100
+ ``variables`` and ``layers`` select as for NECOFS: ``variables`` among ``u``, ``v``, ``ww``,
101
+ ``temp``, ``salinity``, ``zeta``; ``layers`` as zero-based indices, surface first, negative ones
102
+ from the bottom, returned with a ``layer`` coordinate.
103
+
104
+ ``volume`` uses the reanalysis when it holds the whole window, else the real-time system, else
105
+ raises; ``dap_url`` names an aggregation explicitly. It raises if any requested hour is missing.
106
+ Results are cached as Zarr under ``$FORCINGKIT_CACHE_DIR/doppio/volume/``, keyed by the schema,
107
+ the aggregation, the box, the window and the selection. The 73 hours above (10 x 10 cells, 40
108
+ levels, 6 MB) took 45 s from Rutgers on 2026-11-17, and 0.1 s from the cache.
109
+
110
+ ``forcingkit.layered_mesh.doppio(bbox, start, end)`` returns the same subset as a
111
+ ``LayeredMesh`` (see :doc:`layered_mesh`) for rendering and sections next to NECOFS.
112
+
113
+ Limits
114
+ ------
115
+
116
+ - **Resolution.** Cells are about 7 km across (6 to 7 km over the box above), so features under
117
+ about 15 to 20 km, such as the flow inside a single shelf-break canyon, are not resolved. Use
118
+ Doppio for the slope current, stratification and tides at shelf scale, and NECOFS or a finer
119
+ model inside canyons.
120
+ - **Sea level datum.** ``zeta`` is relative to the model's own mean sea level; the Rutgers
121
+ metadata names no geodetic datum.
122
+ - **Cache viewer.** The cache viewer (:doc:`cache_viewer`) lists the stores under
123
+ ``doppio/volume/`` and draws their footprints on its coverage map. Its image preview opens
124
+ only stores at the top of the cache directory, so it does not yet preview Doppio or NECOFS
125
+ volume stores.
126
+
127
+ Credit
128
+ ------
129
+
130
+ The Doppio catalog describes the data as "Freely available". Cite the model (López et al.,
131
+ 2020), the reanalysis (Wilkin et al., 2022) and, for the reanalysis output, the dataset as its
132
+ catalog asks: Wilkin, J. and J. Levin (2022), SEANOE,
133
+ `doi:10.17882/89673 <https://doi.org/10.17882/89673>`__. The observations it assimilated are on
134
+ `Rutgers ERDDAP
135
+ <https://tds.marine.rutgers.edu/erddap/tabledap/DOPPIO_REANALYSIS_Ver3_OBS.graph>`__. See
136
+ :doc:`shelf_models` for the other models of the region.
@@ -67,8 +67,8 @@ Parent ocean (``/api/v1/obc``)
67
67
  - `Northeast Coastal Ocean Forecast System <https://fvcom.smast.umassd.edu/?p=20>`__, `FVCOM
68
68
  <https://fvcom.smast.umassd.edu/>`__ GOM7 (`UMass Dartmouth SMAST
69
69
  <https://www.umassd.edu/smast/>`__ and `WHOI <https://www.whoi.edu/>`__), unstructured mesh
70
- with 45 sigma layers. Monthly hindcast from 1978 (GOM3 mesh to 2016), daily history files from
71
- 2025-01-01, then the rolling forecast.
70
+ with 45 sigma layers. Daily history files from 2025-01-01, else a monthly file (the hindcast
71
+ from 1978, GOM3 mesh to 2016; the monthly GOM7 archive for 2025), then the rolling forecast.
72
72
  The only donor that streams the ``z-v3`` parent store. See :doc:`necofs`.
73
73
  * - **NYOFS**
74
74
  - `NOAA New York/New Jersey Operational Forecast System
@@ -93,6 +93,10 @@ Parent ocean (``/api/v1/obc``)
93
93
  attribute (``"none"``, ``"included"`` or ``"mixed"``). Last-resort fallback; legacy
94
94
  output layout.
95
95
 
96
+ :doc:`Doppio <doppio>` is not a donor yet: ``forcingkit.fetchers.doppio.volume`` returns its
97
+ full-depth subsets on the model's own grid for comparison with NECOFS, and the dispatcher does
98
+ not rank it.
99
+
96
100
  `TPXO10 <https://www.tpxo.net/>`__ tidal harmonics are a roadmap item, not integrated; the
97
101
  `pyTMD <https://github.com/pyTMD/pyTMD>`__ dependency was removed on
98
102
  2026-10-05. The ``include_tides`` and ``tidal_model`` request fields
@@ -92,7 +92,8 @@ What it serves
92
92
  finished stores read-only over HTTP at ``/api/v1/stores/``. Used by the Python client; see
93
93
  :doc:`client`.
94
94
  * - ``/api/v1/cache/...`` and ``/ui/``
95
- - The cache viewer: an inventory of every store, with 2D and 3D previews.
95
+ - The cache viewer: an inventory of every store, with a coverage map and timeline and 2D
96
+ and 3D previews. See :doc:`cache_viewer`.
96
97
 
97
98
  Each generating route has ``/download/{zarr_id}`` and, for the parent ocean, ``/cache`` and
98
99
  ``/predict-donor`` companions. The running service publishes its full OpenAPI description at
@@ -135,6 +136,11 @@ Parent-ocean donors at a glance
135
136
  - Global; 1994 to the present
136
137
  - Legacy output; last-resort fallback; tidal only from 2024-09-05
137
138
 
139
+ :doc:`Doppio <doppio>` (ROMS, about 7 km, 40 s-levels; an hourly reanalysis for 2007 to 2024 and
140
+ a real-time system from 2017) is read as a full-depth subset for comparison with NECOFS, not yet
141
+ as a parent-ocean donor. :doc:`shelf_models` surveys the other models and reanalyses of the
142
+ region.
143
+
138
144
  Quick start
139
145
  -----------
140
146
 
@@ -178,6 +184,8 @@ PyPI as ``forcingkit``.
178
184
  necofs
179
185
  nyofs
180
186
  hycom
187
+ doppio
188
+ shelf_models
181
189
  atmospheric_forcing
182
190
  waves
183
191
  rivers
@@ -187,6 +195,7 @@ PyPI as ``forcingkit``.
187
195
  :caption: Reference
188
196
 
189
197
  client
198
+ cache_viewer
190
199
  mesh_frames
191
200
  layered_mesh
192
201
  sources
@@ -89,6 +89,11 @@ the box, hourly: 45 sigma layers with ``zeta``, element ``u``, ``v`` and ``w`` (
89
89
  m/s, up positive) and node ``T`` (degC) and ``S`` (PSU). ``from_necofs_volume(ds)`` converts a
90
90
  dataset already read.
91
91
 
92
+ ``doppio(bbox, start, end)`` reads Doppio ROMS through ``forcingkit.fetchers.doppio.volume`` (see
93
+ :doc:`doppio`) and passes its water cells to ``structured`` (below), with the same field names as
94
+ the NECOFS adapter. ``structured`` takes fixed layer heights, so the 40 s-levels are placed at
95
+ the window's mean surface elevation. ``from_doppio_volume(ds)`` converts a dataset already read.
96
+
92
97
  ``structured(lon, lat, mask, z, times=..., fields=...)`` turns a regular grid (1-D axes) or a
93
98
  curvilinear one (2-D centres) into two triangles per cell, both carrying the cell's own value, so
94
99
  cells are drawn flat, as the model holds them. Cell corners lie midway between centres (for a
@@ -97,6 +97,13 @@ All access is OPeNDAP from ``http://www.smast.umassd.edu:8080/thredds/dodsC/mode
97
97
  - ``Archive/Seaplan_33_Hindcast_v1/necofs_{yyyy}/NECOFS_{yyyy}{mm}.nc``
98
98
  - 2017 to 2024 (as of 2026-10-31). Hourly, from 00:00 on the 1st to 00:00 on the 1st of the
99
99
  next month (745 records for a 31-day month); same mesh and variables as the daily history.
100
+ * - Monthly GOM7 archive
101
+ - ``Archive/NECOFS_GOM/{yyyy}/necofs_{yyyy}{mm}.nc``
102
+ - All twelve months of 2025 (as of 2026-11-17). The GOM7 system's own output concatenated by
103
+ month, on the same mesh as the GOM7-mesh hindcast (node and element coordinates, ``nv``,
104
+ ``h`` and ``siglay`` identical) with the same variables and time units. Hourly, from 00:00
105
+ on the 1st to 23:00 on the last day (744 records for a 31-day month), so the 00:00 record
106
+ of the next month is read from the next month's file.
100
107
  * - Monthly hindcast, GOM3 mesh
101
108
  - ``Archive/Seaplan_33_Hindcast_v1/gom3_{yyyy}{mm}.nc``
102
109
  - 1978 to 2016, on the coarser GOM3 mesh (48,451 nodes against GOM7's 207,081), with the same
@@ -106,7 +113,8 @@ All access is OPeNDAP from ``http://www.smast.umassd.edu:8080/thredds/dodsC/mode
106
113
  - The current run; 193 time records on 2026-10-06.
107
114
 
108
115
  The history archive held 577 files on 2026-10-06, from 2025-01-01 to 2026-10-05. **66 days are
109
- missing**, so a run that needs one of them cannot be built from NECOFS:
116
+ missing**. A run that needs a 2025 day among them reads the monthly GOM7 archive instead; one that
117
+ needs a 2026 day cannot be built from NECOFS:
110
118
 
111
119
  - 2025-01-12 to 2025-01-25 (14 days, the longest gap);
112
120
  - 2025: 03-08, 04-01, 04-13, 05-22, 05-24 to 05-26, 06-06, 06-08, 06-14, 06-23, 07-27, 07-29,
@@ -114,9 +122,10 @@ missing**, so a run that needs one of them cannot be built from NECOFS:
114
122
  - 2026: 01-03, 02-16, 02-25, 03-08, 03-24, 05-16 to 05-17, 05-28, 06-06 to 06-09, 06-17,
115
123
  07-02 to 07-03, 07-13 to 07-15, 08-25.
116
124
 
117
- Dates before 2025 come from the monthly hindcast (``Seaplan_33_Hindcast_v1``); there is no hindcast
118
- for 2025 yet, so the gaps above still cannot be filled. Because each history file also holds the
119
- first hour of its own date, a missing file *D* removes hours 01:00 to 23:00 of *D* - 1 and the
125
+ Dates before 2025 come from the monthly hindcast (``Seaplan_33_Hindcast_v1``). There is no hindcast
126
+ for 2025 yet, so the 2025 gaps above are filled from the monthly GOM7 archive (``NECOFS_GOM``);
127
+ the 2026 gaps still cannot be filled. Because each history file also holds the first hour of its
128
+ own date, a missing file *D* removes hours 01:00 to 23:00 of *D* - 1 and the
120
129
  00:00 record of *D*. The ``necofs_2022`` folder also holds an empty stray, ``NECOFS_2022010.nc``,
121
130
  beside the real ``NECOFS_202210.nc``; forcingkit never asks for it.
122
131
 
@@ -128,8 +137,8 @@ vertical_spacing_m=2.0)`` is a generator; the dispatcher writes what it yields s
128
137
 
129
138
  1. **File choice.** For each hour the fetcher picks the history file that holds it and probes
130
139
  it (an HTTP request for its ``.dds``, 5 s timeout). If that probe fails, it probes the monthly
131
- hindcast file for the month (30 s timeout; files seen to exist are remembered), and failing
132
- that opens the rolling forecast, which serves recent hours and fails for older ones. The store
140
+ hindcast file for the month and, from 2025, the monthly GOM7 archive file (30 s timeout each;
141
+ files seen to exist are remembered), and failing that opens the rolling forecast, which serves recent hours and fails for older ones. The store
133
142
  records the first file read as ``necofs_product`` and ``necofs_url``. A window that crosses the
134
143
  GOM3 to GOM7 mesh change (the end of 2016) is refused; request it in two parts.
135
144
  2. **Target grid.** A regular 0.002 degree longitude/latitude grid (about 170 m east-west and
@@ -224,7 +224,9 @@ Earlier years in the Northeast
224
224
  - ROMS with 4D-Var data assimilation, 7 km, 40 s-levels, hourly sea level, velocity,
225
225
  temperature and salinity from 2007-01-02 to 2024-12-31, Mid-Atlantic Bight and Gulf of
226
226
  Maine (López et al., 2020; Wilkin et al., 2022).
227
- - A shelf-scale parent for 2007 to 2024, before the NECOFS archive begins.
227
+ - A shelf-scale parent for 2007 to 2024, before the NECOFS archive begins. Read today as a
228
+ full-depth subset on its own grid (:doc:`doppio`); the parent-ocean (``z-v3``) delivery
229
+ is still to do.
228
230
  * - **Doppio real time** (`Rutgers THREDDS
229
231
  <https://tds.marine.rutgers.edu/thredds/catalog/roms/doppio/catalog.html>`__)
230
232
  - The same model run forward with assimilation: hourly, from 2017-11-02 to two days ahead,