ras_commander_fast_map/
lib.rs

1//! Native 2D flood inundation mapping: horizontal, sloping, and ras2fim-2D Step05.
2//!
3//! Extends the immutable baseline prototype `prototype/kernel` (RasMapper_Stored_Maps_Rust,
4//! 2026-10-22, CLB Engineering): the barycentric evaluation, the `100 * DBL_EPSILON` inclusion
5//! test and the lowest-simplex-id tie rule are copied from that kernel. Upstream algorithm:
6//! Andy Carter, PE / University of Texas at Austin, ras2fim-2d `3146f647`, Step05 (BSD-3-Clause).
7//!
8//! The application uses [`step05`], which preserves the upstream float32 sequence
9//! and native approximate reprojection over supplied SciPy transforms and axes.
10//! The older [`session`] diagnostic retains its distinct f64 arithmetic.
11//! Step05 and triangulated-session scope boundaries:
12//! - Interpolation topology is always caller-supplied global SciPy/Qhull simplices. There is no
13//!   native triangulation and never a per-AOI or per-tile retriangulation.
14//! - Wet masks and sample preparation are caller-supplied (upstream/Python adapters).
15//! - Native terrain is same-CRS, north-up, single-band float32 GeoTIFF read through terrio with
16//!   an explicit sampling formula. Other terrain types require separate qualification.
17//! - The diagnostic session's f64 arithmetic does not replace the Step05 float32 sequence.
18//!
19//! Independent [`horizontal`] and [`sloping_session`] methods prepare pixel ownership
20//! directly from cell polygons. Plain sloping reconstructs hydraulic connectivity
21//! and corner interpolation rather than using the Step05 SciPy topology.
22#![forbid(unsafe_code)]
23
24/// Version of the standalone crate and Python wheel.
25pub const ENGINE_VERSION: &str = env!("CARGO_PKG_VERSION");
26/// Source revision of an official build, or `unknown` for an unversioned archive.
27pub const ENGINE_COMMIT: &str = env!("FAST_MAP_ENGINE_COMMIT");
28
29pub mod aoi;
30pub mod boundary_contour;
31pub mod boundary_session;
32pub mod cache;
33pub mod horizontal;
34pub mod interp;
35pub mod model;
36pub mod ownership;
37pub mod scipy_interp;
38pub mod session;
39pub mod sink;
40pub mod sloping;
41mod sloping_binary;
42pub mod sloping_session;
43pub mod step05;
44pub mod terrain;
45pub mod terrain_scope;
46pub mod velocity;
47pub mod whole_simulation;
48
49use std::fmt;
50
51/// Identifies the method semantics. Changing any recorded convention must change this string.
52pub const METHOD_VERSION: &str = "ras2fim-batch-prototype/0.1.0 method-r1";
53
54/// Identifies the output/failure/budget contract (not the numerical method, which is unchanged).
55pub const CONTRACT_VERSION: &str = "ras2fim-batch-prototype contract-r2-hardening";
56
57/// Errors are typed so callers can distinguish invalid input, budgets and unsupported cases.
58#[derive(Debug, Clone, PartialEq)]
59pub enum MapError {
60    Invalid(String),
61    Budget(String),
62    Unsupported(String),
63    Io(String),
64    Terrain(String),
65    /// A caught panic or broken internal invariant (never a silent partial result).
66    Internal(String),
67}
68
69impl fmt::Display for MapError {
70    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
71        match self {
72            MapError::Invalid(s) => write!(f, "invalid input: {s}"),
73            MapError::Budget(s) => write!(f, "budget exceeded: {s}"),
74            MapError::Unsupported(s) => write!(f, "unsupported: {s}"),
75            MapError::Io(s) => write!(f, "io error: {s}"),
76            MapError::Terrain(s) => write!(f, "terrain error: {s}"),
77            MapError::Internal(s) => write!(f, "internal error: {s}"),
78        }
79    }
80}
81
82impl std::error::Error for MapError {}
83
84impl From<std::io::Error> for MapError {
85    fn from(e: std::io::Error) -> Self {
86        MapError::Io(e.to_string())
87    }
88}
89
90impl MapError {
91    pub fn kind(&self) -> &'static str {
92        match self {
93            MapError::Invalid(_) => "invalid",
94            MapError::Budget(_) => "budget",
95            MapError::Unsupported(_) => "unsupported",
96            MapError::Io(_) => "io",
97            MapError::Terrain(_) => "terrain",
98            MapError::Internal(_) => "internal",
99        }
100    }
101}
102
103/// Static description of the implemented semantics, emitted in every report.
104pub fn method_record() -> serde_json::Value {
105    serde_json::json!({
106        "method_version": METHOD_VERSION,
107        "interpolation": {
108            "topology": "caller-supplied global SciPy/Qhull simplices only; no native or per-AOI triangulation",
109            "evaluation": "f64 barycentric linear interpolation (baseline prototype kernel)",
110            "inclusion_tolerance": "all barycentric coordinates >= -100*DBL_EPSILON",
111            "tie_rule": "lowest supplied simplex index among containing simplices (order independent)",
112            "degenerate_simplices": "skipped when determinant == 0 or exact 1-norm reciprocal condition < 1000*DBL_EPSILON; modeled on SciPy's singular-transform skip, not verified bit-identical to SciPy's LAPACK estimate",
113            "scipy_eps_broad_fallback": "not implemented; no claim of SciPy find_simplex walk parity",
114            "query_point": "x = x0 + col*dx, y = y0 + row*dy in f64 (explicit grid); terrain-aligned grid: x = gt0 + (abs_col + 0.5)*gt1, y = gt3 + (abs_row + 0.5)*gt5"
115        },
116        "mask": "caller-supplied rasterized wet union on the profile grid (upstream/Python adapter); unmasked pixels are nodata",
117        "depth_wse": "depth = raw_wse - ground (f64); wet iff ground present and depth >= 0; wse = raw_wse where wet. Baseline prototype semantics; upstream float32 writes, '<0 -> NaN' sequencing and the Step05 nudge are NOT replicated",
118        "terrain_modes": {
119            "caller_buffer": "per-profile pre-aligned f64 terrain buffer, null/NaN = nodata (old oracle parity mode)",
120            "native_geotiff": {
121                "format": "same-CRS, north-up (gt2 == gt4 == 0, gt1 > 0, gt5 < 0), single-band float32 GeoTIFF/BigTIFF via terrio 0.4.2 lazy tile reads",
122                "sample_formula": "col = floor((xs - gt0) / gt1), row = floor((ys - gt3) / gt5) in f64",
123                "query_convention": "explicit per session: pixel_center (xs = x0 + (col + 0.5)*dx, ys = y0 + (row + 0.5)*dy) or query_point (xs, ys = query point)",
124                "nodata_policy": "explicit per session: dry (declared-nodata sentinel -> dry) or raw_value (sentinel subtracted as a number, upstream-like raw subtraction; not qualified)",
125                "outside_extent": "dry",
126                "nan_value": "dry",
127                "reprojection": "never; terrain EPSG must equal the declared session EPSG",
128                "not_qualified": "GDAL Warp nearest-neighbour, Step05 inverted-bounds lattice, nudge, upstream raw-sentinel behaviour; rasterio rowcol uses a linear solve and may differ at exact pixel-boundary ties (counted as terrain_near_boundary_samples)"
129            }
130        },
131        "nonfinite_terrain": "NaN terrain is dry; declared NaN or +/-inf nodata is accepted (a pixel is the sentinel iff v == nodata as f32, GDAL-like; report states whether that cast is exact); any other infinite terrain value that is sampled is rejected (native: typed terrain error failing the profile; caller_buffer: invalid request)",
132        "aoi": "pixel windows on each profile's own grid; AOI output equals the crop of the full-grid output by construction (same tiles, same per-pixel formula); bounds select pixels whose center lies in [min, max)",
133        "outputs": "per (profile, AOI) unit: little-endian f64 rasters with NaN nodata, simplex_id as i64 with -1 nodata, row-major in grid row order",
134        "output_contract": {
135            "contract_version": CONTRACT_VERSION,
136            "commit": "unit.json status in_progress is written before any data; data is written as <product>.bin.partial, fsynced (errors propagate), renamed to .bin, directory synced where supported, then unit.json is atomically replaced with status complete. A .bin is valid only when unit.json says complete",
137            "failure": "a failed unit, or every open unit after a session error or caught panic, has its data removed and unit.json status failed; report.json is still written with status aborted when possible (otherwise stderr says so and in_progress/.partial names remain)",
138            "json_writes": "<name>.partial, fsync, rename",
139            "ids": "[A-Za-z0-9_.-]{1,64}, unique case-insensitively, no trailing '.', no Windows device names (CON, PRN, AUX, NUL, COM0-9, LPT0-9, with any extension)"
140        },
141        "bounds": {
142            "enforced": "decoded resident terrain tiles <= max_cache_bytes; evaluated tile buffers <= effective_tiles_in_flight x output_tile^2 x 40 bytes; plan tiles per profile <= 4194304",
143            "admission_estimates": "per-profile load+prepare peak from request content / file lengths before any read (binary/inline: buffer sizes plus an assumed one-copy R-tree bulk-load; legacy JSON: 64 x file length heuristic) checked against max_profile_bytes; optional max_session_bytes packs batches over accounted static terms + batch load peaks + plan metadata",
144            "not_bounded": "decoder transients (estimated only), allocator fragmentation, thread stacks, codec state, JSON transients; no hard total memory bound is claimed"
145        }
146    })
147}
ras_commander_fast_map/lib.rs

ras_commander_fast_map/
lib.rs
