Hydrata - ANUGA Flood Simulation

Reviewed 1d ago.

• tools: 19 tools scanned
• metadata: scanned

No findings.

Tools (19)

• list_projects

  List ANUGA simulation projects accessible to the authenticated user. Returns a paginated list of projects with their names, projections, and base map references.

• get_project

  Get one ANUGA project: id, name, projection, visibility, your role, its base map — and the link to it. Returns the project record (`id`, `name`, `projection` (EPSG code), `simple_view_config`, `visibility`, `owner_username`, `my_role`, `base_map`) plus `ui_url`: the link that opens the project's map, for the user (`<site>/catalogue/#/map/<base_map>`; null while a new project's map is still being created). Scenarios are NOT listed here — use get_scenario with a scenario id.

• get_scenario

  Get a scenario's COMPACT state: its `computed_status`, inputs, estimate and price. Returns a compact record, never the raw ~50 KB detail: `scenario_id`, `computed_status`, `mesh_triangle_count_estimate` and its `_breakdown`, `latest_run_is_valid`, the latest run's `run_id`, `run_status`, `error_message`, `user_message`, `status_detail` and `mesh_triangle_count` — plus what the scenario IS and what it will cost: `name`, `description`, `project`, `resolution`, `duration`, the input row ids (`terrain`, `boundary`, `friction`, `inflow`, `rainfall`, `building`, `mesh_region`), `compute_cost_estimate` (USD), `vcpu_hours_estimate`, and `inflow_anchor_mismatch` (null unless an inflow series starts after the model does, whose first value is then held backwards). The `computed_status` field (there is NO `status` key on a scenario) is derived from the latest run and will be one of: created, building, built, queued, computing, processing, complete, error, or cancelled — `created` also means no r

• start_simulation

  Start a flood simulation run for a built scenario. The scenario must be in 'built' status. Returns 202 with the new run. The run transitions through: built → queued → computing → processing → complete. After starting, poll get_run_status to track progress. Returns 409 if the scenario is not in the correct state. The returned run record has its presigned `s3_*_url` links elided (6-hour capabilities).

• get_run_status

  Lightweight status check for a simulation run (fast, <50ms). Use this for polling instead of get_run. Returns only: id, status, `phase`, progress_pct (0-100), eta_seconds, error_message, and compute_backend. `phase` is never empty: it is `status`, except `preparing_inputs` while a `computing` run has no progress yet (it is downloading its input package and building the domain — minutes on a big model; this is NOT a stall). Poll every 5-10 seconds. Terminal states: complete, error, cancelled.

• get_run

  Get full details of a simulation run including timing and results. Returns the complete run record: status, progress, timing (start/end timestamps, duration), compute details (backend, instance type, cost), mesh info, error messages, and result log. Use get_run_status for lightweight polling; use this for final results. The presigned `s3_*_url` download links are ELIDED — each is a 6-hour capability and no tool relays one. The results stay viewable through the `gn_layer_*` entries (published WMS layers on the project's map).

• cancel_run

  Cancel an in-flight simulation run. Works on runs in built, queued, or computing status. Cleans up compute resources (terminates EC2 instance, Celery task, or Batch job). Returns 409 if the run is already in a terminal state (complete, cancelled, or error).

• retry_run

  Retry a failed simulation run. Resets an errored run back to 'created' status and triggers a new package build. The same run ID is reused. Only valid when status is 'error'. Returns 409 for any other state.

• list_runs

  List all simulation runs across all scenarios in a project. Returns a paginated list of runs. Optionally filter by status to find active, completed, or failed runs. Each row's presigned `s3_*_url` download links are elided (6-hour capabilities).

• create_project

  Create a new ANUGA project. Returns the project record including its id, base_map and ui_url. The caller's own account becomes the owner. `projection` is the projected CRS every scenario in the project is meshed and run in — pick the UTM zone covering the site. The project's map is created alongside it; `ui_url` opens it — give it to the user. Next step for a new project: presign_terrain_upload.

• presign_terrain_upload

  Step 1 of a terrain import: get a presigned S3 PUT URL for a GeoTIFF DEM. The agent moves the bytes itself — no tool accepts file contents. After this call, PUT the file straight to `upload_url`, sending the SAME Content-Type you passed here (it is part of the signature; a mismatch is a 403 SignatureDoesNotMatch before it is anything else): curl -sS -X PUT -H "Content-Type: image/tiff" --upload-file /path/dem.tif "$UPLOAD_URL" then call finalize_terrain_upload with the returned staging_key and process_id. Nothing exists in Hydrata until finalize; the URL expires after `expires_in` seconds (3600). Platform guidance: keep the terrain extent within 5° across and 40,000 km² (200 × 200 km). The API enforces that cap on its bbox-fetch path; an uploaded GeoTIFF is only rejected above 5 GiB, but a larger DEM will not mesh or run well. The GeoTIFF must carry a CRS; the import reprojects it to the site's UTM zone and builds a hillshade. Fallback when a presigned PUT is impossible: multip

• finalize_terrain_upload

  Step 2 of a terrain import: register the PUT GeoTIFF as a Terrain and start the import. Call this only after the presigned PUT returned 200. Creates the Terrain row (status `creating`) and queues the import chain — reproject to UTM, publish the layer + hillshade, style — which also seeds the project's six default boundary, friction, inflow, rainfall, building and mesh-region rows. Returns 202 with the terrain record; keep its `id` for get_terrain. A 400 UPLOAD_NOT_FOUND means no object is at `staging_key`: the PUT did not land (check its status code and Content-Type) — do not retry finalize until it has.

• get_terrain

  Poll a terrain's import until it is `ready` (or `error`), bounded by timeout_seconds. Returns `outcome` — exactly one of `ready`, `error`, `timed_out`, `not_found` (the project has no terrain yet; an unknown terrain_id is an API 404 error instead) — plus the last `status` seen (creating → styling → ready | error) and `phase` (that status, or `not_found`; never empty), `polls`, `elapsed_seconds` and the full `terrain` record (its `gn_layer` is the published elevation dataset pk once ready). An import takes minutes to tens of minutes (the SAME 32 MB 1 m DEM measured 4.5 min once and 26 min once — the worker's S3 download speed dominates), so `timed_out` is normal and NOT a failure: keep calling with the same arguments while `status` is still `creating`/`styling`; several calls in a row is expected. `error` is terminal — the import failed and no default input rows were seeded; upload a corrected GeoTIFF as a new terrain. `ready` is written by the import task; the project's default input

• create_time_series

  Create a time series (rain gauge, hydrograph, tide/stage) in a project. POSTs /projects/<id>/time-series/ with `series_type` and `units` as top-level fields. `series_type` is checked against the four choices and `data` against the {"rowData": [{timestamp, value}, ...]} shape before any request is made — the API answers 500 (not 400) to a malformed row. Returns a compact record — id, name, series_type, units, timezone, row_count, http_status — not the echoed rows; fetch the full row with the REST API (GET /projects/<id>/time-series/<id>/) if you need to round-trip it. A rainfall polygon references its gauge by the series NAME, so create the gauges with the exact names the rainfall GeoJSON's features carry.

• attach_input_layer

  Attach a GeoJSON you uploaded to GeoNode as the project's boundary, friction, inflow, rainfall, building or mesh_region layer. The agent moves the bytes: first upload the GeoJSON yourself, with the same credential, to GeoNode's upload endpoint at the site origin: curl -sS -u <user>:<password> -F "base_file=@/path/rainfall.geojson" https://<site>/api/v2/uploads/upload/ → JSON with `execution_id`. Then call this tool with it. The tool polls GET /api/v2/resource-service/execution-status/<execution_id> (bounded by timeout_seconds; statuses ready → running → finished | failed), reads the new dataset's pk, and PATCHes it onto the project's DEFAULT row of that kind ('Boundary 01' … 'MeshRegion 01' — the six rows the terrain import seeds ~30 s after get_terrain reports ready; if the list is still empty the tool says so: run finalize_terrain_upload / wait for get_terrain first). `outcome` is exactly one of: `attached` (row_id, gn_layer, dataset_pk, dataset_alternate — the WFS typename —

• list_inputs

  List every input layer row of a project, per kind, with whether it has features. For each of boundary, friction, inflow, rainfall, building and mesh_region: the rows (`row_id`, `title`, `gn_layer` — the dataset pk — and `dataset_alternate`, the `workspace:name` WFS typename) and `has_features`. `has_features` comes from the API for boundary, rainfall and mesh_region; for friction, inflow and building (whose records do not carry it) it is a WFS feature count, at most 24 lookups per call — past that, or when a lookup fails, it is null (unknown, not false). A row with no `gn_layer` has no layer yet (`has_features` false). Use the row ids with create_scenario; this is the listing primitive — no need to probe files.

• list_time_series

  List a project's time series (rain gauges, hydrographs, tides) — never their rows. Each series: `id`, `name` (a rainfall polygon binds to its gauge by this exact name), `series_type`, `units`, `timezone`, `row_count`, `first_timestamp` and `last_timestamp`. The data rows themselves are dropped (a project's list is megabytes); fetch one series with the REST API (GET /projects/<id>/time-series/<id>/) if you need its values.

• create_scenario

  Create a DRAFT scenario (no build, no run) and report its mesh-triangle estimate. POSTs /projects/<id>/scenarios/ with the write fields, then GETs the scenario detail — the create response carries NO estimate; the detail's `mesh_triangle_count_estimate` (+ `_breakdown`) does. Returns a compact record (the same fields get_scenario answers with): id, name, the FK ids as stored, resolution, duration, `computed_status` (`created` = no run yet), the estimate and its breakdown, the price (`compute_cost_estimate` in USD, `vcpu_hours_estimate`), `inflow_anchor_mismatch`, and http_status. Next step: build_scenario (which asks for confirm=true above 100,000 triangles). Nothing is meshed or queued here. Units: `resolution` — on the SCENARIO and on every MeshRegion FEATURE — is a LENGTH in metres; ANUGA maximum_triangle_area = resolution²/2 (FloatField default 100, not nullable; 0 makes the estimate None), and the estimate prices both the same way (TASK-3186). The smallest value becomes the rast

• build_scenario

  Build a scenario's package (mesh + inputs) after showing what it will cost, and poll until built. Order of operations, so the number is shown before anything is spent: 1. GET the scenario detail. A record with no `boundary`/`computed_status` keys is a non-member's read of a public project → refused: a build needs the EDITOR role. 2. Re-call checks on `latest_run` (a re-POST is NOT deduplicated after `built`/`complete` — it would dispatch a duplicate build): no run → proceed; run `created`/`building` → resume polling, no POST; run `built`/`queued`/`computing`/`processing`/`complete` with `latest_run_is_valid` not false → return that state, no POST unless rebuild=true; run `error`/`cancelled`, or `latest_run_is_valid` false (the scenario was edited since the build) → proceed. 3. Spend gates, each a refusal with `outcome: "refused"` and no POST: the scenario has no boundary or its boundary row has no features (the server would admit the build and fail it in