Python client and trajectories¶
forcingkit-client is a separate, lightweight distribution published from this repository
(client/). It reaches a running forcingkit service over HTTP and returns xarray objects. It
depends on httpx, numpy, pandas, scipy, xarray and zarr only, none of the
service’s data-access stack (GRIB, OPeNDAP, S3), so it installs into a simulator or an
application’s embedded Python (3.11 or newer).
from forcingkit_client import Client
fk = Client("http://localhost:9598")
box = (-70.9, 41.3, -70.6, 41.6) # west, south, east, north
ocean = fk.ocean(box, "2025-07-01", 24) # u, v, temp, salt, zeta on (time, z, lat, lon)
air = fk.atmosphere(box, "2025-07-01", 24) # HRRR u10, v10, t2m, q2m, sp, dswrf, dlwrf, prate
waves = fk.waves(box, "2025-07-01", 24, wfo="box", grid="CG1") # NWPS hs, tp, dir, shts, ws, wdir
buoy = fk.ndbc("44013", "2025-07-01", "2025-07-02", products=("stdmet", "adcp"))
elevation = fk.bathymetry(box, resolution_m=30)
AsyncClient has the same methods as coroutines, for callers that must not block an event
loop. Units are SI throughout; z is metres, positive up.
How a request is served¶
Building a store can take minutes on a cold cache, so the client does not hold a request open. It submits a job and polls it:
Route |
Purpose |
|---|---|
|
Queue the build that |
|
The same for |
|
The same for |
|
|
|
The finished store’s files, read-only, for reading the store remotely. |
The job id is the store id, which is a hash of the request. Identical submissions therefore share
one build, a request for a store that already exists succeeds at once, and a job whose store
finished before a service restart is still reported as succeeded. The service runs
FORCINGKIT_JOB_WORKERS builds at a time (default 2). The synchronous routes are unchanged.
The client opens the store named in the Item over HTTP through a local cache
(~/.cache/forcingkit-client), keyed by store id and store version. Only the chunks actually
read are transferred, each once; a store the service rebuilds under the same id (after
cache_bust) has a new version and is fetched afresh.
The result as a STAC Item¶
Each succeeded job’s result is a STAC Item, so a store describes
itself in the vocabulary that catalogue tools (pystac, pystac-client, odc-stac) read:
{
"type": "Feature", "stac_version": "1.1.0", "id": "obc_1f3a9c0e5b72",
"bbox": [-71.0, 41.2, -70.5, 41.7],
"properties": {
"datetime": null,
"start_datetime": "2025-07-01T00:00:00Z", "end_datetime": "2025-07-02T00:00:00Z",
"forcingkit:kind": "ocean", "forcingkit:schema": "z-v3",
"forcingkit:donor": "necofs", "forcingkit:store_version": "1761830400000000000"
},
"assets": {
"zarr": {
"href": "http://localhost:9598/api/v1/stores/obc_1f3a9c0e5b72.zarr",
"type": "application/vnd+zarr", "roles": ["data"],
"xarray:open_kwargs": {"consolidated": true, "zarr_format": 2}
}
}
}
Any Zarr reader can open the asset directly, for example
xr.open_zarr(href, consolidated=True, zarr_format=2).
Store layouts¶
The client returns one layout whatever the donor. z-v3 stores already have it. Stores from
donors not yet converted to z-v3 (schema legacy: HYCOM, NYOFS, DBOFS) are normalised on
opening: depth (positive down) becomes z (positive up), latitude and longitude
become lat and lon, and HYCOM’s 0 to 360 longitudes are wrapped to -180 to 180. A legacy
store on a curvilinear grid, and any schema the client does not know, is refused with a message
naming the schema.
Forcing along a trajectory¶
interpolate_trajectory returns forcing at each point of a moving platform’s path, such as a
tagged animal, a vessel or a drifter:
track = fk.interpolate_trajectory(
lon, lat, time, z, # degrees; UTC; metres, positive up (-25 is 25 m down)
variables=("u", "v", "temp"), # from the parent ocean
atmosphere=("u10", "v10"), # from HRRR, optional
trajectory_id="tag-01",
)
It fetches the trajectory’s bounding box (plus margin_deg, default 0.1 degree) and time window
(whole hours, plus one each side) once, then interpolates each variable linearly in time,
latitude, longitude and, for 3-D fields, z. Points above the shallowest level take its value,
matching the service’s own surface convention. Points on land, below the sea floor or outside the
grid are NaN, and each variable’s n_missing attribute counts them.
The result is a CF discrete sampling geometry (CF 1.11, featureType = "trajectory"): one value
per point and variable on an obs dimension, with time, lat, lon and z
coordinates, a trajectory variable carrying cf_role = "trajectory_id", and global
attributes naming each store used (id, version, donor, schema). to_netcdf writes a file that
CF-aware tools read as a trajectory.
Sampling density is the caller’s choice. The gridded sources resolve hours and kilometres (HYCOM is 3-hourly at 0.04 to 0.08 degrees), so a trajectory logged at many hertz loses nothing when thinned to about one point a minute first: about 550 points for a 9 hour deployment.
Extent. One bounding box suits trajectories of hours to days in one region. A multi-week track spanning hundreds of kilometres would pull a store far larger than its samples; segmenting such tracks server-side is on the Roadmap and Contributing.