kira-spatial-core

kira-spatial-core is a deterministic, SoA-first Rust library for spatial primitives shared across Kira tools.

Scope (Stage 0)

• Core types and invariants (SpatialDomain, Field, geometry types)
• Deterministic numeric helpers and quantization
• Deterministic tile planning (row-major)
• SIMD capability scaffold with scalar fallback stubs
• Grid field operators: gradient, laplacian, hessian, window
• Advanced spatial operators: structure-tensor, divergence, curl, distance-transform, curvature, fractal-dimension, skeletonization, diffusion, multiscale-log, cross-gradient
• Spatial statistics: global/local Moran's I and Geary's C on regular lattices

Non-goals (Stage 0)

• Spatial indexing and graph algorithms
• Neighborhood operators and solvers
• Production SIMD kernels

Relationship to kira-spatial-io

kira-spatial-core owns in-memory contracts, numeric policy, and deterministic traversal rules. kira-spatial-io should handle file formats and ingestion, then hand validated data to this crate.

Build and test

cargo test

Optional features:

• parallel: enable Rayon work-stealing in stencil operators and diffusion
• force_scalar: force the SIMD-availability detector to return false
• f64_fields: store field payloads as f64 instead of f32
• ndarray: enable interop::ndarray_io adapters
• mmap: enable interop::mmap_io::MmapField for zero-copy OOC inputs (transitively pulls memmap2 + bytemuck)
• simd-reduce: route widening sums (field::reducer::sum_f64) through an 8-wide wide::f32x8 path. Numerically equivalent to scalar.

Compatibility

• MSRV: Rust 1.95 (Edition 2024). The crate uses let-chains in if/while, so a stable toolchain at or above 1.95 is required.
• The crate uses #![deny(unsafe_code)]. The only module that opts back in (via #[allow(unsafe_code)]) is interop::mmap_io, gated behind the mmap feature; it wraps memmap2 for OOC inputs. Every other module is unsafe-free.
• All public numeric entry points reject NaN/Inf; see docs/NUMERIC.md.
• Public enums are marked #[non_exhaustive]: external match arms must include a _ => … fallback so future variants do not break downstream.
• SIMD capability is detected at runtime on x86_64 (AVX2) and aarch64 (NEON). The force_scalar feature pins the detector to false.

Examples

See examples/ for a runnable end-to-end gradient/diffusion pipeline against a synthetic grid:

cargo run --example gradient_diffusion

Operator flags (for downstream CLI wiring)

Use SpatialOperator names as canonical --op values:

• gradient
• laplacian
• structure-tensor
• divergence
• curl
• distance-transform
• curvature
• fractal-dimension
• skeletonization
• diffusion
• multiscale-log
• cross-gradient