forcingkit¶
Spatiotemporal forcing for computational Earth-system models. forcingkit selects, regrids and serves model-ready time series, with a record of where every value came from.
HRRR 10 m wind served by forcingkit through the 26 to 27 September 2026 nor’easter, NY Bight to Cape Cod, every 3 hours from 22 to 29 September (peak 25.9 m/s), as played by the cache viewer’s time slider.¶
What it does¶
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, the NOAA Operational Forecast Systems, NECOFS, HYCOM) that differ in grid type, vertical coordinate, time convention, file layout and access protocol, and 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 (for example through NumericalEarth). For a bounding box and a time window it:
picks the source (the “donor”) best suited to the box, and falls back to the next one if the first cannot deliver;
fetches only the subset it needs, over OPeNDAP, HTTPS or anonymous S3;
interpolates it to a regular longitude/latitude grid and, for the ocean, to fixed z levels in metres;
writes the result as a Zarr store with a versioned schema, its units, and the request that produced it; and
serves the same store again, without refetching, to any later request with the same parameters.
Store names are hashes of the request, including the schema version, so a run can be repeated months later against the same forcing, and a store written under an older schema is never served for a newer request.
What it serves¶
Route |
Delivers |
|---|---|
|
The parent ocean (u, v, temperature, salinity, sea surface height) on a regular
0.002 degree grid and fixed z levels, hourly, as schema |
|
HRRR surface fields (10 m wind, 2 m temperature and humidity, pressure, radiation,
precipitation) on a regular 0.03 degree grid, hourly, as schema |
|
The air above: HRRR wind, vertical velocity and temperature on its lowest native levels
(14 by default, about 10 m to 2.8 km above open water), over the same window and grid as
|
|
NWPS surface waves (significant height, peak period, direction of travel, swell height) and
the office’s forcing wind, hourly on the forecast office’s own grid, as schema
|
|
Freshwater discharge at each listed river mouth in the box, hourly, from the tide-free
USGS stream gauges upstream (chosen per request) scaled
to the drainage area at the mouth, as schema |
|
Observed water level at a NOAA CO-OPS station, for validation. |
|
NDBC buoy meteorology and ADCP current profiles, for validation. |
|
Water-column profiles from the UConn Marine Sciences ERDDAP server, by station or by box. |
|
The parent-ocean, atmosphere and waves builds as queued jobs, each result a STAC Item, and the
finished stores read-only over HTTP at |
|
The cache viewer: an inventory of every store, with a coverage map and timeline and 2D and 3D previews. See Cache viewer. |
Each generating route has /download/{zarr_id} and, for the parent ocean, /cache and
/predict-donor companions. The running service publishes its full OpenAPI description at
/docs.
From Python, the forcingkit-client package wraps these routes, returns xarray objects, and
interpolates forcing along a trajectory (a tagged animal, a vessel, a drifter); see
Python client and trajectories.
Parent-ocean donors at a glance¶
Donor |
Model and grid |
Resolution |
Coverage served |
Status in forcingkit |
|---|---|---|---|---|
POM, curvilinear, 7 sigma levels |
About 140 to 1000 m (median 340 m) |
NY/NJ Harbor; 2014 to the present |
Legacy output, not |
|
DBOFS |
ROMS, curvilinear |
About 100 m |
Delaware Bay and offshore New Jersey |
Legacy output, not |
FVCOM GOM7, unstructured, 45 sigma layers |
About 130 to 800 m in the NY Harbor and Long Island Sound region |
Gulf of Maine to the Mid-Atlantic Bight; daily archive from 2025-01-01 |
Streams |
|
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; tidal only from 2024-09-05 |
Doppio (ROMS, about 7 km, 40 s-levels; an hourly reanalysis for 2007 to 2024 and a real-time system from 2017) is read as a full-depth subset for comparison with NECOFS, not yet as a parent-ocean donor. Northeast Shelf Models and Reanalyses surveys the other models and reanalyses of the region.
Quick start¶
uv sync
uv run uvicorn service.forcingkit_serve.main:app --port 9598
Then request 24 hours of parent ocean for a box in central Long Island Sound, which NECOFS serves:
curl -s -X POST http://localhost:9598/api/v1/obc \
-H 'Content-Type: application/json' \
-d '{"bbox": {"min_lon": -73.20, "min_lat": 40.95, "max_lon": -73.00, "max_lat": 41.10},
"start_date": "2026-09-26T00:00:00Z", "duration_hours": 24}'
The response names the store (zarr_id, zarr_path, download_url), the donor that
delivered it (donor) and the donor ranked first for the box (predicted_donor). A
second identical request returns "status": "cached" immediately. Stores live under
FORCINGKIT_CACHE_DIR (default ~/.cache/forcingkit).
The data forcingkit serves belongs to the institutions that produce it; Sources and Citations lists them, with their terms of use and the papers to cite.
Contributions are welcome, from a corrected archive path to a new region. Roadmap and Contributing lists the parent-ocean and atmosphere sources that would add most next, coverage first and resolution second (Copernicus GLO12 and GLORYS12, the remaining NOAA forecast systems, the Doppio reanalysis, HRRR Alaska, and a first European pair from Copernicus Marine among them), and what a new source needs.
Source, issues and releases: https://github.com/lhzn-io/forcingkit. The package is published on
PyPI as forcingkit.
Sources
- Data Fetchers
- NECOFS: Northeast Coastal Ocean Forecast System (FVCOM)
- NYOFS: NOAA New York/New Jersey Operational Forecast System
- HYCOM: global ocean analyses and reanalysis
- Doppio (ROMS, Mid-Atlantic Bight and Gulf of Maine)
- Northeast Shelf Models and Reanalyses
- Atmospheric Forcing Datasets
- Surface Waves (NWPS)
- River Discharge