Simulation job API & parameter contracts
Full description: Read the full narrative
Request contract
Payloads are validated by a zod discriminated union on type whose bounds “mirror the physical ranges enforced by the simulator kernels… Validation MUST happen at this boundary, not inside the kernel, so bad input fails fast with a legible error. No synthetic fallbacks. If a value is required, the boundary throws.” src/services/kaggleSim.ts:8-14
| Field | Rule | Source |
|---|---|---|
| lat / lon | −90…90 / −180…180 | src/services/kaggleSim.ts:20-21 |
| grid_size | int 64…2048 | src/services/kaggleSim.ts:22 |
| extent_km | >0…40,000 (bbox derivation floors at 1.0) | src/services/kaggleSim.ts:23,263-272 |
| duration_hours | >0…720 | src/services/kaggleSim.ts:24 |
| terrain / landcover / bathymetry arrays | ≤ 65,536 cells; gs 2…256; row-major, row 0 = north | src/services/kaggleSim.ts:41-55,69-80,116-124,160-167,178-184,218-224 |
Per-scenario field tables (UI → wire → unit → range → default → meaning) are on the capability pages: earthquake · wildfire · hurricane · flood · tsunami · volcano · landslide. Branch source: src/services/kaggleSim.ts:28-240.
Wire semantics that matter to scientists
- Unit conversions happen once, in the builder: wind km/h → m/s (÷3.6) src/services/kaggleSim.ts:434,441,501; ash diameter µm → m (÷1e6) src/services/kaggleSim.ts:509.
- “Hours to Landfall” is doubled because the kernel places landfall at mid-duration src/services/kaggleSim.ts:485-490.
- Optional scientific knobs (vs30, heading, mu, xi, entrainment, ash_*) are omitted — never fabricated — when the user has not supplied a finite value src/services/kaggleSim.ts:390-415,461-463,493,504-511,531-537.
- Origin points are grid fractions (x = east, y = south, 0…1): epicentre / track / vent; default box centre src/services/kaggleSim.ts:98-106,152-159,194-200.
- The sim grid is a SQUARE of extent_km centred on the bbox centroid — not the bbox itself; vent fractions are computed against that square src/services/kaggleSim.ts:274-309.
- landslide duration is additionally capped to 300 simulated seconds inside the kernel kaggle-kernels/landslide-sim/main.py:435-442.
Job endpoints
| Method & path | Behaviour | Measured / source |
|---|---|---|
| POST /api/kaggle/simulate | Validate + enqueue; 400 with explicit message on missing type/lat/lon or unknown type; returns {jobId, status, type, streamUrl, createdAt} | server/kaggle/routes.ts:164-201 |
| GET /api/kaggle/simulate/:id | Status document (params echoed) | server/kaggle/routes.ts:204-223 |
| GET /api/kaggle/simulate/:id/stream | SSE progress: queued/running(+detail)/complete/error | server/kaggle/routes.ts:225-231 |
| POST /api/kaggle/simulate/:id/cancel | cooperative cancel; local runs take a SIGKILL path on timeout | server/kaggle/routes.ts:233-243 |
| GET /api/kaggle/simulate/:id/results | metadata.json + final_stats; 409 until complete | server/kaggle/routes.ts:245-261 200 + full metadata observed |
| GET /api/kaggle/simulate/:id/grid/:name | raw .npy or JSON (JSON capped at 5M elements; 413 above; .npy uncapped); name sanitised to [A-Za-z0-9_- | server/kaggle/routes.ts:263-307 296,648-byte npy observed |
| GET /api/kaggle/simulate/:id/geotiff/:name | WGS84 GeoTIFF (final frame of series) | server/kaggle/routes.ts:309-422 valid 128×128 TIFF observed |
| GET /api/kaggle/jobs · /kernels | job list; kernel availability + GPU flags | server/kaggle/routes.ts:424-477 flood gpu=true, others false (observed) |
| POST /api/kaggle/calibrate · /landslide/quantify · /volcano/calibrate · /volcano/quantify | local python3 in-process kernel runs (see hub page) | server/kaggle/routes.ts:479-810 |
Result formats
Local and Kaggle runners converge on one layout: kaggle-kernels/results/<jobId>/metadata.json + *.npy grids, “so the SSE stream, grid and GeoTIFF endpoints work unchanged” server/kaggle/simRunner.ts:126-141. Field dtypes/units are tabulated on each capability page; the kaggle-kernels/results/<jobId>/ tree is populated at runtime (metadata.json + *.npy) and is gitignored — the repository ships no archived example artifacts.
Failure modes worth knowing
| Condition | Observed behaviour | Source |
|---|---|---|
| Missing/invalid required UI value | builder throws (ZodError or explicit message) — never substitutes | src/services/kaggleSim.ts:390-415,544 |
| Kernel out-of-range (e.g. M 2.9) | kernel raises with named validity range; job → error with the last log lines surfaced | kaggle-kernels/earthquake-sim/main.py:244-249 observed |
| Local timeout | SIGKILL after LOCAL_SIM_TIMEOUT_MS (default 120 s) | server/kaggle/simRunner.ts:134 |
| No Kaggle token (Kaggle-routed types) | job errors early; local trio + analytical engine unaffected | server/kaggle/simRunner.ts:126-141 |
| Tsunami without real bathymetry | kernel aborts: “Real GEBCO bathymetry is required…” | kaggle-kernels/tsunami-sim/main.py:227-230 |
| Volcano without terrain | kernel aborts: “…no synthetic cone fallback is permitted…” | kaggle-kernels/volcano-sim/main.py:821-826 |