forcingkit 0.1.0.post1__tar.gz → 0.2.0__tar.gz

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forcingkit
-Version: 0.1.0.post1
+Version: 0.2.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
@@ -246,7 +246,9 @@ Description-Content-Type: text/markdown
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/lhzn-io/forcingkit/main/docs/source/_static/forcingkit-inventory-screenshot.png" alt="forcingkit Dashboard" />
+  <img src="https://raw.githubusercontent.com/lhzn-io/forcingkit/main/docs/source/_static/forcingkit-noreaster-wind.gif" alt="Animation of the HRRR 10 m wind from the NY Bight to Cape Cod, every 3 hours from 2026-09-22 00:00 to 2026-09-29 12:00 UTC" width="720" />
+  <br />
+  <sub>HRRR 10 m wind served by forcingkit through the 26-27 September 2026 nor'easter, NY Bight to Cape Cod, from the calm of 22 September to the calm of 29 September, every 3 hours (peak 25.9 m/s). The forcingkit viewer's time slider, played.</sub>
 </div>
 
 Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/README.md

@@ -5,7 +5,9 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 <div align="center">
-  <img src="https://raw.githubusercontent.com/lhzn-io/forcingkit/main/docs/source/_static/forcingkit-inventory-screenshot.png" alt="forcingkit Dashboard" />
+  <img src="https://raw.githubusercontent.com/lhzn-io/forcingkit/main/docs/source/_static/forcingkit-noreaster-wind.gif" alt="Animation of the HRRR 10 m wind from the NY Bight to Cape Cod, every 3 hours from 2026-09-22 00:00 to 2026-09-29 12:00 UTC" width="720" />
+  <br />
+  <sub>HRRR 10 m wind served by forcingkit through the 26-27 September 2026 nor'easter, NY Bight to Cape Cod, from the calm of 22 September to the calm of 29 September, every 3 hours (peak 25.9 m/s). The forcingkit viewer's time slider, played.</sub>
 </div>
 
 Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.

{forcingkit-0.1.0.post1 → forcingkit-0.2.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.1.0.post1"
+release = "0.2.0"
 
 extensions = [
     "sphinx.ext.autodoc",

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/docs/source/removed_endpoints.rst

@@ -18,7 +18,7 @@ and the routes then answer 404.
    * - Removed
      - Use instead
    * - ``POST /api/v1/ic/generate``, ``POST /api/v1/ic/regrid``
-     - ``POST /api/v1/obc``: the parent ocean on true z (schema ``z-v2``). Its first record is
+     - ``POST /api/v1/obc``: the parent ocean on true z (schema ``z-v3``). Its first record is
        the initial condition, already on regular lon/lat and fixed z levels, so no separate
        regrid step remains.
    * - ``POST /api/v1/ic/cache``, ``POST /api/v1/ic/predict-donor``,

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forcingkit"
-version = "0.1.0.post1"
+version = "0.2.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.1.0.post1 → forcingkit-0.2.0}/service/forcingkit_serve/main.py

@@ -131,7 +131,7 @@ class OBCRequest(BaseModel):
     sponge_cells: int = 0
     include_tides: bool = True
     tidal_model: str = "GOT4.10c"
-    # Parent-ocean options (schema z-v2): donor cells of padding beyond the bbox, so the parent
+    # Parent-ocean options (schema z-v3): donor cells of padding beyond the bbox, so the parent
     # brackets the child, and the spacing of the fixed z levels.
     pad_cells: int = 3
     vertical_spacing_m: float = 2.0

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/service/forcingkit_serve/routers/removed.py

@@ -19,7 +19,7 @@ REMOVED_ON = datetime(2026, 10, 5, tzinfo=timezone.utc)
 DOCS_URL = "https://forcingkit.docs.lhzn.io/removed_endpoints.html"
 
 _PARENT = (
-    "POST /api/v1/obc: the parent ocean on true z (schema z-v2); its first record is the "
+    "POST /api/v1/obc: the parent ocean on true z (schema z-v3); its first record is the "
     "initial condition"
 )
 _ATMOSPHERE = (

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/service/forcingkit_serve/routers/viewer.py

@@ -912,10 +912,16 @@ async def get_dataset_preview_3d(
 
         # Select time slice
         time_name = next((n for n in ["time", "ocean_time", "t"] if n in ds.dims), None)
+        frame_time = None
         if time_name and time_name in u_da.dims:
             t_idx = min(time_idx, u_da.sizes[time_name] - 1)
             u_da = u_da.isel({time_name: t_idx})
             v_da = v_da.isel({time_name: t_idx})
+            # The record's time, for the viewer's label (UTC, to the minute).
+            if time_name in ds.coords and ds[time_name].dtype.kind == "M":
+                frame_time = (
+                    str(ds[time_name].values[t_idx].astype("datetime64[m]")) + "Z"
+                )
 
         # Find the best lon/lat coordinate for each variable.
         # Staggered ROMS grids have per-variable coords (lon_u/lat_u, lon_v/lat_v).
@@ -1103,6 +1109,7 @@ async def get_dataset_preview_3d(
             "bounds": [min(all_lons), min(all_lats), max(all_lons), max(all_lats)],
             "depth_levels": sorted(set(v["depth"] for v in vectors)),
             "count": len(vectors),
+            "time": frame_time,
         }
 
         return Response(

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/src/forcingkit/fetchers/necofs.py

@@ -60,7 +60,7 @@ def get_necofs_url(target_dt: pd.Timestamp) -> str:
 
 # Parent-ocean delivery schema. Bump when the layout or meaning of the boundary store changes, so
 # a cached store built under an older schema can never be served for a newer request.
-OBC_SCHEMA = "z-v2"
+OBC_SCHEMA = "z-v3"
 
 
 def necofs_archive_file_date(t: pd.Timestamp) -> pd.Timestamp:
@@ -145,6 +145,11 @@ class Barycentric:
         self.vertices = tri.simplices[s]
         self.shape = shape
 
+    def restrict(self, inside: np.ndarray) -> "Barycentric":
+        """Also treat targets outside `inside` (flat, one per target) as outside."""
+        self.inside = self.inside & inside
+        return self
+
     def __call__(self, values: np.ndarray) -> np.ndarray:
         values = np.asarray(values, dtype=np.float64)
         out = np.einsum("...pk,pk->...p", values[..., self.vertices], self.weights)
@@ -152,6 +157,44 @@ class Barycentric:
         return out.reshape(values.shape[:-1] + self.shape)
 
 
+class MeshBarycentric(Barycentric):
+    """Linear interpolation on the triangles of an unstructured mesh, as FVCOM itself interpolates
+    node values within an element.
+
+    A Delaunay triangulation of the mesh nodes also covers land between them (a peninsula, an
+    island, the coast between two estuaries) and fills it with values blended across it. Here a
+    target takes values only from the mesh element that contains it, and a target inside no
+    element (land, or outside the mesh) is NaN. `triangles` are zero-based node indices, one row
+    per element.
+    """
+
+    def __init__(
+        self,
+        lon: np.ndarray,
+        lat: np.ndarray,
+        triangles: np.ndarray,
+        targets: np.ndarray,
+        shape: tuple[int, ...],
+    ):
+        from matplotlib.tri import Triangulation
+
+        mesh = Triangulation(lon, lat, triangles)
+        element = np.asarray(mesh.get_trifinder()(targets[:, 0], targets[:, 1]))
+        self.inside = element >= 0
+        self.vertices = triangles[np.where(self.inside, element, 0)]
+        x, y = lon[self.vertices], lat[self.vertices]
+        # Barycentric coordinates of each target in its element.
+        det = (y[:, 1] - y[:, 2]) * (x[:, 0] - x[:, 2]) + (x[:, 2] - x[:, 1]) * (
+            y[:, 0] - y[:, 2]
+        )
+        det = np.where(self.inside, det, 1.0)
+        dx, dy = targets[:, 0] - x[:, 2], targets[:, 1] - y[:, 2]
+        b0 = ((y[:, 1] - y[:, 2]) * dx + (x[:, 2] - x[:, 1]) * dy) / det
+        b1 = ((y[:, 2] - y[:, 0]) * dx + (x[:, 0] - x[:, 2]) * dy) / det
+        self.weights = np.column_stack([b0, b1, 1.0 - b0 - b1])
+        self.shape = shape
+
+
 PARENT_RECORD_DIMS = {
     "u": ("z", "lat", "lon"),
     "v": ("z", "lat", "lon"),
@@ -212,7 +255,9 @@ def iter_parent(
     parent brackets the child. The vertical axis is true depth: each FVCOM sigma layer is placed at
     z = siglay * (h + zeta) + zeta for its column and interpolated onto fixed levels every
     `vertical_spacing_m` metres, ordered bottom to top. Land, points outside the mesh and levels
-    below the sea floor are NaN.
+    below the sea floor are NaN. Land is what lies inside no element of the NECOFS mesh: node
+    fields are interpolated within the containing element, and element fields (u, v) are NaN
+    wherever the node mesh is.
 
     Raises rather than returning a short record: an unreachable archive file, a missing hour or a
     failed interpolation ends the delivery with an error.
@@ -259,16 +304,15 @@ def iter_parent(
             logger.info(
                 "Building NECOFS parent interpolation weights and vertical grid..."
             )
-            at_node = Barycentric(
-                Delaunay(np.column_stack((ds["lon"].values, ds["lat"].values))),
-                target_pts,
-                shape,
-            )
+            node_lon = np.asarray(ds["lon"].values, dtype=np.float64)
+            node_lat = np.asarray(ds["lat"].values, dtype=np.float64)
+            triangles = np.asarray(ds["nv"].values).T.astype(np.int64) - 1
+            at_node = MeshBarycentric(node_lon, node_lat, triangles, target_pts, shape)
             at_elem = Barycentric(
                 Delaunay(np.column_stack((ds["lonc"].values, ds["latc"].values))),
                 target_pts,
                 shape,
-            )
+            ).restrict(at_node.inside)
             h_grid = at_node(ds["h"].values)
             siglay_grid = at_node(np.asarray(ds["siglay"].values))  # surface first
             if not np.any(np.isfinite(h_grid)):

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/src/forcingkit/fetchers/noaa.py

@@ -8,6 +8,10 @@ from forcingkit import settings
 logger = logging.getLogger(__name__)
 
 
+# Water-level datums to request, in order of preference.
+TIDE_DATUMS = ("NAVD", "MSL")
+
+
 def fetch_noaa_tide_data(
     station_id: str,
     start_time: str,
@@ -57,7 +61,6 @@ def fetch_noaa_tide_data(
         "end_date": end_str,
         "station": station_id,
         "product": "water_level",
-        "datum": "NAVD",
         "units": "metric",
         "time_zone": "gmt",
         "format": "json",
@@ -65,16 +68,30 @@ def fetch_noaa_tide_data(
     }
 
     try:
-        response = requests.get(url, params=params, timeout=30)
-        response.raise_for_status()
-        data = response.json()
+        # NAVD88 where the station has it, so stations share a datum; otherwise MSL (New Haven,
+        # 8465705, publishes only tidal datums). The datum used is recorded in the metadata.
+        for datum in TIDE_DATUMS:
+            response = requests.get(url, params={**params, "datum": datum}, timeout=30)
+            data = response.json() if response.content else {}
+            message = (
+                data.get("error", {}).get("message", "")
+                if isinstance(data, dict)
+                else ""
+            )
+            if "datum" in message.lower() and datum != TIDE_DATUMS[-1]:
+                logger.info(
+                    f"NOAA station {station_id} has no {datum} datum; trying the next"
+                )
+                continue
+            response.raise_for_status()
+            break
 
         if "error" in data:
             logger.warning(
                 f"NOAA API returned error: {data['error'].get('message', 'Unknown error')}"
             )
-            # Return a dummy fallback or raise? For now, we'll raise to let dispatcher handle it
             raise RuntimeError(f"NOAA API Error: {data['error'].get('message')}")
+        data.setdefault("metadata", {})["datum"] = datum
 
         # Cache the successful response
         with open(cache_path, "w") as f:

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/static/app.js

@@ -316,8 +316,10 @@ document.addEventListener("DOMContentLoaded", () => {
         document.querySelectorAll(".dataset-card").forEach(c => c.classList.remove("selected"));
         cardElement.classList.add("selected");
 
+        setPlaying(false);
         selectedDataset = item;
         previewControls.classList.remove("hidden");
+        frameTime.textContent = "";
         timeRange.value = 0;
         timeIdxDisplay.textContent = "0";
 
@@ -434,6 +436,43 @@ document.addEventListener("DOMContentLoaded", () => {
         previewDebounce = setTimeout(updatePreview, 300);
     });
 
+    // Auto-play: step the time slider, waiting for each frame to render, and loop.
+    const playBtn = document.getElementById("playBtn");
+    const frameTime = document.getElementById("frameTime");
+    const FRAME_MS = 400;  // the fastest step; slower frames take as long as they take to load
+    let playing = false;
+
+    function setPlaying(on) {
+        playing = on;
+        if (playBtn) playBtn.textContent = on ? "Pause" : "Play";
+    }
+
+    async function playLoop() {
+        while (playing && selectedDataset) {
+            const last = parseInt(timeRange.max) || 0;
+            if (last < 1) break;
+            const next = (parseInt(timeRange.value) + 1) % (last + 1);
+            const started = performance.now();
+            timeRange.value = next;
+            if (window.currentDataCube && window.currentDataCube[next]) {
+                timeRange.dispatchEvent(new Event("input"));
+            } else {
+                timeIdxDisplay.textContent = `${next} (${selectedDataset.time_steps || '?'})`;
+                await updatePreview();
+            }
+            await new Promise(r => setTimeout(r, Math.max(0, FRAME_MS - (performance.now() - started))));
+        }
+        setPlaying(false);
+    }
+
+    if (playBtn) {
+        playBtn.addEventListener("click", () => {
+            if (playing) { setPlaying(false); return; }
+            setPlaying(true);
+            playLoop();
+        });
+    }
+
     const lodSelect = document.getElementById("lodSelect");
     if (lodSelect) {
         lodSelect.addEventListener("change", () => {
@@ -467,6 +506,7 @@ document.addEventListener("DOMContentLoaded", () => {
 
             try {
                 const info = await window.preview3d.load(id, parseInt(t));
+                frameTime.textContent = info.time ? info.time.replace("T", " ").replace("Z", " UTC") : "";
                 console.log(`3D preview: ${info.count} vectors (${info.u_var}/${info.v_var}), ${info.depths} depth levels`);
             } catch (err) {
                 console.error("3D preview failed:", err);

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/static/index.html

@@ -101,8 +101,11 @@
                             </div>
                         </div>
                         <div id="timeSliderGroup" class="control-group">
-                            <label for="timeRange">Time Index (<span id="timeIdxDisplay">0</span>)</label>
-                            <input type="range" id="timeRange" min="0" max="48" value="0" class="form-range">
+                            <label for="timeRange">Time Index (<span id="timeIdxDisplay">0</span>) <span id="frameTime" style="color:#8b949e;"></span></label>
+                            <div style="display:flex;align-items:center;gap:8px;">
+                                <button id="playBtn" type="button" class="btn" title="Step through the time steps and loop">Play</button>
+                                <input type="range" id="timeRange" min="0" max="48" value="0" class="form-range" style="flex:1;">
+                            </div>
                         </div>
                         <div id="snapshotLabel" class="control-group" style="display:none;">
                             <span style="color:#8b949e; font-size:0.85rem; font-style:italic;" id="snapshotLabelText"></span>

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/static/preview3d.js

@@ -8,6 +8,11 @@ let camera = null;
 let controls = null;
 let arrowGroup = null;
 let animId = null;
+let legendHost = null;
+// The dataset on screen and the largest speed seen in it, so stepping through time keeps the
+// camera where the user put it and colours that compare across frames.
+let currentDatasetId = null;
+let scaleMax = 0;
 
 // - Depth exaggeration (matches hydro viewer: 10x base * slider) -
 const DEPTH_EXAG = 8.0;  // equivalent to hydro viewer slider default
@@ -46,6 +51,55 @@ function depthColor(mag, maxMag, depthFrac) {
 }
 
 // - Merge simple geometries -
+// - Color map for single-level fields (atmosphere, or a surface-only ocean field): speed -
+// Plasma stops (matplotlib), perceptually uniform and legible on the dark background.
+const PLASMA = [
+    [0.00, [0.050, 0.031, 0.529]],
+    [0.25, [0.494, 0.012, 0.659]],
+    [0.50, [0.800, 0.278, 0.471]],
+    [0.75, [0.973, 0.584, 0.251]],
+    [1.00, [0.941, 0.976, 0.129]],
+];
+
+function speedColor(mag, maxMag) {
+    const t = Math.min(1, mag / Math.max(maxMag, 0.001));
+    for (let i = 1; i < PLASMA.length; i++) {
+        const [t1, c1] = PLASMA[i];
+        if (t <= t1) {
+            const [t0, c0] = PLASMA[i - 1];
+            const s = (t - t0) / (t1 - t0);
+            return new THREE.Color(
+                c0[0] + (c1[0] - c0[0]) * s,
+                c0[1] + (c1[1] - c0[1]) * s,
+                c0[2] + (c1[2] - c0[2]) * s,
+            );
+        }
+    }
+    return new THREE.Color(...PLASMA[PLASMA.length - 1][1]);
+}
+
+// A speed legend over the 3D canvas: the plasma ramp from 0 to the frame's maximum speed.
+function showSpeedLegend(maxMag) {
+    hideSpeedLegend();
+    if (!legendHost) return;
+    if (getComputedStyle(legendHost).position === 'static') legendHost.style.position = 'relative';
+    const stops = PLASMA.map(([s, c]) =>
+        `rgb(${c.map(x => Math.round(x * 255)).join(',')}) ${s * 100}%`).join(', ');
+    const el = document.createElement('div');
+    el.id = 'preview3dLegend';
+    el.style.cssText = 'position:absolute;right:16px;bottom:16px;padding:8px 10px;border-radius:6px;' +
+        'background:rgba(13,17,23,0.75);color:#c9d1d9;font:12px system-ui,sans-serif;pointer-events:none;';
+    el.innerHTML = `<div style="margin-bottom:4px">Speed (m/s)</div>` +
+        `<div style="width:160px;height:10px;border-radius:2px;background:linear-gradient(to right, ${stops})"></div>` +
+        `<div style="display:flex;justify-content:space-between;margin-top:2px"><span>0</span><span>${maxMag.toFixed(1)}</span></div>`;
+    legendHost.appendChild(el);
+}
+
+function hideSpeedLegend() {
+    const el = document.getElementById('preview3dLegend');
+    if (el) el.remove();
+}
+
 function mergeGeos(geos) {
     let totalV = 0, allIdx = [];
     for (const g of geos) { totalV += g.attributes.position.count; }
@@ -69,6 +123,7 @@ function mergeGeos(geos) {
 }
 
 function initThree(container) {
+    legendHost = container;
     const canvas = document.createElement('canvas');
     canvas.id = 'preview3dCanvas';
     container.appendChild(canvas);
@@ -120,6 +175,7 @@ function initThree(container) {
 }
 
 function clearArrows() {
+    hideSpeedLegend();
     if (arrowGroup) {
         scene.remove(arrowGroup);
         arrowGroup.traverse(c => { if (c.geometry) c.geometry.dispose(); if (c.material) c.material.dispose(); });
@@ -127,7 +183,7 @@ function clearArrows() {
     }
 }
 
-function buildVectorField(data) {
+function buildVectorField(data, fitCamera) {
     clearArrows();
     if (!data.vectors || data.vectors.length === 0) return;
 
@@ -151,6 +207,8 @@ function buildVectorField(data) {
         const mag = Math.sqrt(v.u * v.u + v.v * v.v);
         if (mag > maxMag) maxMag = mag;
     }
+    scaleMax = Math.max(scaleMax, maxMag);
+    maxMag = scaleMax;
 
     // Build arrow geometry (shaft + cone)
     const shaft = new THREE.CylinderGeometry(0.12, 0.12, 1, 6);
@@ -162,8 +220,13 @@ function buildVectorField(data) {
     const arrowGeo = mergeGeos([shaft, cone]);
 
     const count = data.vectors.length;
+    // One level (an atmosphere, or a surface-only ocean field): colour by speed, not depth.
+    const singleLevel = !data.depth_levels || data.depth_levels.length <= 1;
     // depthTest: false so subsurface arrows render through the grid plane
-    const mat = new THREE.MeshPhongMaterial({ flatShading: true, depthTest: false });
+    // Unlit for a single level, so the speed colour map shows true; shaded for depth layers.
+    const mat = singleLevel
+        ? new THREE.MeshBasicMaterial({ depthTest: false })
+        : new THREE.MeshPhongMaterial({ flatShading: true, depthTest: false });
     const mesh = new THREE.InstancedMesh(arrowGeo, mat, count);
     mesh.renderOrder = 10;
 
@@ -187,7 +250,7 @@ function buildVectorField(data) {
         dummy.scale.set(arrowLen, arrowLen, arrowLen);
         dummy.updateMatrix();
         mesh.setMatrixAt(i, dummy.matrix);
-        mesh.setColorAt(i, depthColor(mag, maxMag, v.depth_frac || 0));
+        mesh.setColorAt(i, singleLevel ? speedColor(mag, maxMag) : depthColor(mag, maxMag, v.depth_frac || 0));
     }
 
     mesh.instanceMatrix.needsUpdate = true;
@@ -211,8 +274,10 @@ function buildVectorField(data) {
     }
 
     scene.add(arrowGroup);
+    if (singleLevel) showSpeedLegend(maxMag);
 
-    // Fit camera to vector field bounds
+    // Fit camera to vector field bounds, only for a newly selected dataset
+    if (!fitCamera) return;
     const box = new THREE.Box3().setFromObject(arrowGroup);
     const center = box.getCenter(new THREE.Vector3());
     const size = box.getSize(new THREE.Vector3());
@@ -242,6 +307,7 @@ window.preview3d = {
         const canvas = document.getElementById('preview3dCanvas');
         if (canvas) canvas.style.display = 'none';
         this.active = false;
+        currentDatasetId = null;
         clearArrows();
     },
 
@@ -254,8 +320,10 @@ window.preview3d = {
                 throw new Error(err.detail || `HTTP ${res.status}`);
             }
             const data = await res.json();
-            buildVectorField(data);
-            return { count: data.count, u_var: data.u_var, v_var: data.v_var, depths: data.depth_levels.length };
+            const newDataset = datasetId !== currentDatasetId;
+            if (newDataset) { currentDatasetId = datasetId; scaleMax = 0; }
+            buildVectorField(data, newDataset);
+            return { count: data.count, u_var: data.u_var, v_var: data.v_var, depths: data.depth_levels.length, time: data.time };
         } catch (e) {
             console.error('3D preview failed:', e);
             throw e;

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/tests/unit/test_necofs_parent.py

@@ -1,4 +1,4 @@
-"""NECOFS parent-ocean delivery (schema z-v2): the vertical conversion, archive-file selection and
+"""NECOFS parent-ocean delivery (schema z-v3): the vertical conversion, archive-file selection and
 cache-key behaviour, on constructed data. No network.
 
 The conversion matters because the previous store labelled FVCOM sigma layers with fake depths in
@@ -113,7 +113,7 @@ def test_options_reach_only_fetchers_that_accept_them():
 
 
 def test_schema_tag_is_set():
-    assert OBC_SCHEMA == "z-v2"
+    assert OBC_SCHEMA == "z-v3"
 
 
 def test_barycentric_weights_match_linear_nd_interpolation():
@@ -138,3 +138,45 @@ def test_barycentric_weights_match_linear_nd_interpolation():
         want = LinearNDInterpolator(tri, values[k])(targets).reshape(gx.shape)
         np.testing.assert_allclose(got[k], want, rtol=1e-12, atol=1e-12, equal_nan=True)
     assert np.isnan(got[0, 0, 0])  # (-0.1, -0.1) is outside the hull
+
+
+def test_mesh_barycentric_leaves_land_between_elements_nan():
+    """Two triangles either side of a notch: a Delaunay triangulation of the four nodes would
+    bridge the notch, the mesh does not."""
+    from forcingkit.fetchers.necofs import MeshBarycentric
+
+    lon = np.array([0.0, 1.0, 0.0, 1.0, 0.5])
+    lat = np.array([0.0, 0.0, 1.0, 1.0, 0.2])
+    # Elements (0, 1, 4) along the bottom and (2, 4, 3) above leave the left and right gaps as land.
+    triangles = np.array([[0, 1, 4], [2, 4, 3]])
+    targets = np.array(
+        [
+            [0.5, 0.1],  # inside the bottom element
+            [0.5, 0.6],  # inside the top element
+            [0.1, 0.6],  # land: inside the nodes' convex hull, in no element
+            [2.0, 2.0],  # outside the mesh
+        ]
+    )
+    interp = MeshBarycentric(lon, lat, triangles, targets, (4,))
+    assert interp.inside.tolist() == [True, True, False, False]
+    # A linear field is reproduced exactly inside elements.
+    field = 2.0 * lon + 3.0 * lat + 1.0
+    out = interp(field)
+    expected = 2.0 * targets[:, 0] + 3.0 * targets[:, 1] + 1.0
+    np.testing.assert_allclose(out[:2], expected[:2], rtol=1e-12)
+    assert np.isnan(out[2:]).all()
+    # Leading dimensions (levels) pass through.
+    stacked = interp(np.vstack([field, 2 * field]))
+    np.testing.assert_allclose(stacked[1, :2], 2 * expected[:2], rtol=1e-12)
+
+
+def test_restrict_masks_element_fields_on_land():
+    from scipy.spatial import Delaunay
+
+    from forcingkit.fetchers.necofs import Barycentric
+
+    pts = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]])
+    targets = np.array([[0.25, 0.25], [0.75, 0.75]])
+    interp = Barycentric(Delaunay(pts), targets, (2,)).restrict(np.array([True, False]))
+    out = interp(np.array([1.0, 1.0, 1.0, 1.0]))
+    assert out[0] == 1.0 and np.isnan(out[1])

forcingkit-0.2.0/tests/unit/test_noaa_datum.py

@@ -0,0 +1,66 @@
+"""CO-OPS water level: NAVD88 where a station has it, MSL where it does not."""
+
+from unittest import mock
+
+from forcingkit.fetchers import noaa
+
+
+class FakeResponse:
+    def __init__(self, payload, status=200):
+        self._payload = payload
+        self.status_code = status
+        self.content = b"x"
+
+    def json(self):
+        return self._payload
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise RuntimeError(f"HTTP {self.status_code}")
+
+
+def _fetch(tmp_path, responses):
+    calls = []
+
+    def fake_get(url, params, timeout):
+        calls.append(params["datum"])
+        return responses[params["datum"]]
+
+    with mock.patch.object(noaa.requests, "get", side_effect=fake_get):
+        data = noaa.fetch_noaa_tide_data(
+            "8465705",
+            "2026-04-02T00:00:00",
+            "2026-04-02T04:00:00",
+            cache_dir=str(tmp_path),
+        )
+    return data, calls
+
+
+def test_falls_back_to_msl_when_navd_is_unsupported(tmp_path):
+    rows = {
+        "metadata": {"id": "8465705"},
+        "data": [{"t": "2026-04-02 00:00", "v": "0.1"}],
+    }
+    data, calls = _fetch(
+        tmp_path,
+        {
+            "NAVD": FakeResponse(
+                {
+                    "error": {
+                        "message": " The supported Datum values are: MHHW, MHW, MTL, MSL"
+                    }
+                },
+                status=400,
+            ),
+            "MSL": FakeResponse(rows),
+        },
+    )
+    assert calls == ["NAVD", "MSL"]
+    assert data["metadata"]["datum"] == "MSL"
+
+
+def test_uses_navd_when_available(tmp_path):
+    rows = {"metadata": {"id": "8516945"}, "data": []}
+    data, calls = _fetch(tmp_path, {"NAVD": FakeResponse(rows)})
+    assert calls == ["NAVD"]
+    assert data["metadata"]["datum"] == "NAVD"

{forcingkit-0.1.0.post1 → forcingkit-0.2.0}/uv.lock

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