Crate petektools

Expand description

§petekTools

Standalone numerics & geostatistics kernels for Rust — the layer Rust is missing. Mature crates cover linear algebra (faer), statistics/distributions (statrs, rand_distr), FFT (rustfft) and spatial indexing (kiddo, rstar), but there is no production-grade scattered-data gridding / geostatistics crate. petekTools fills exactly that gap and curates the rest behind one front-door.

§The pillars (module map)

gridding — the core gap: scattered-data → grid kernels (nearest, idw, min_curvature), warm-start / ConvergentGridder, the Gridder trait + OrdinaryKriging, and the grid → grid resample (native regular grid onto a foreign Lattice, bilinear/nearest).
geostat — the geostatistics workflow beyond one global krige: experimental variogram + Variogram::fit, moving-neighbourhood LocalKriging (scales to tens of thousands of points), the NormalScore transform, and conditional sgs simulation (with collocated cokriging).
stats — curated descriptive statistics (unweighted + weighted).
sampling — reproducible draws from the common appraisal distributions (incl. truncated/clamped bounding), plus the realization-set helpers reservoir_summary (P90=low digest) and aggregate.
units — domain-agnostic unit conversions (imperial + SI).
container — a domain-agnostic single-file section container.
store — a domain-agnostic chunked, memory-mapped lane store: the spill-to-disk backing for larger-than-memory models (k-slab-major lanes, f32/f64/u16/u32, deterministic layout, zero-copy views).
formula — domain-free assignment parsing, dependency ordering, and vectorized scalar/array expression evaluation.
foundation — the shared vocabulary (Lattice, BBox, AlgoError).

A thin PyO3 wheel (petektools on PyPI) re-exports the Python-relevant front-door — sampling (all Sampler variants + a seeded Rng giving the same stream as this crate), stats, reservoir_summary/aggregate, and the geostat kernels. It lives in the py/ workspace member (maturin, publish = false); API.md §“Python (PyO3) surface” is its contract.

gridding and foundation are re-exported at the crate root for the common path; stats / sampling / units / container stay deliberately namespaced (import e.g. petektools::stats::percentile, petektools::units::bbl_to_m3).

§Charter (what belongs here — and what does not)

In: scattered-data gridding/interpolation (minimum-curvature, IDW, nearest today; kriging / RBF later), plus thin curation over the mature numeric crates.
Out: file I/O of any kind (that is petekio), and reservoir-domain modeling — PVT, rel-perm, material balance, decline, GRV (that is peteksim). The deliberate exceptions are container — a domain-agnostic file container lifted here so every layer shares one framing — and store, the domain-agnostic mmap lane store; both do generic, opaque array/blob I/O only (domain/format I/O stays in petekio).

§Dependency rule: this crate is a pure leaf

It depends only on general-purpose numeric crates — never on petekio or peteksim. petekio depends on petekTools (for the gridding kernels); peteksim depends on both. One direction, no cycles.

§Type-agnostic boundary

Kernels speak Lattice (this crate’s own geometry vocabulary) + plain [[f64; 3]] coordinate arrays — never a consumer’s domain type. petekio’s GridGeometry maps onto Lattice field-for-field, so a future delegation is a 1:1 conversion at the call site, not a rewrite.

§Status

GATE-0 is locked (the Lattice / GridMethod / grid contract + the three kernels ported from petekio 0.2.0). Shipped since (unreleased, on the way to 0.2.0): warm-start / ConvergentGridder gridding, the Gridder trait + OrdinaryKriging, the curated stats and sampling front-doors, the units / container modules, and the PyO3 petektools wheel (the py/ member) over the front-door. See API.md for the contract.

Re-exports§

pub use foundation::AlgoError;
pub use foundation::BBox;
pub use foundation::Lattice;
pub use foundation::Result;
pub use gridding::grid;
pub use gridding::grid_min_curvature_conditioned;
pub use gridding::grid_min_curvature_seeded;
pub use gridding::resample;
pub use gridding::AnisotropicVariogram;
pub use gridding::Conditioning;
pub use gridding::ConvergentGridder;
pub use gridding::GridMethod;
pub use gridding::Gridder;
pub use gridding::MinCurvatureOperator;
pub use gridding::OrdinaryKriging;
pub use gridding::ResampleMethod;
pub use gridding::SpatialVariogram;
pub use gridding::Variogram;
pub use gridding::VariogramModel;
pub use interp::interp1d;
pub use interp::CubicSpline1d;
pub use interp::Interp1dMethod;

Modules§

container: container — a domain-agnostic single-file section container.
formula: Domain-free formula parsing and vectorized evaluation.
foundation: foundation — the type-agnostic vocabulary every kernel speaks: the error type, the Result alias, and the rotatable Lattice (with its BBox).
geostat: geostat — the geostatistics workflow beyond a single global krige: build a spatial-continuity model from data, krige at scale with a moving neighbourhood, and draw conditional realizations (sequential Gaussian simulation, optionally steered by a collocated secondary variable).
gridding: gridding — interpolate scattered (x, y, z) samples onto a regular Lattice, producing a dense Array2<f64> of node values (NaN where a node is undefined).
interp: One-dimensional interpolation kernels.
sampling: sampling — a curated, validated front-door for reproducible random draws from the distributions an appraisal Monte-Carlo actually uses.
stats: stats — a curated, validated front-door for descriptive statistics.
store: store — a domain-agnostic chunked, memory-mapped lane store: the spill-to-disk backing for larger-than-memory models (out-of-core ruling R1, petekSuite/dev-docs/designs/out-of-core-strategy.md).
synth: synth — believable synthetic subsurface data: seeded, deterministic generators for logs, facies, structural surfaces, trend maps, wells and trajectories. The generators the fixture factories and user demos compose into a whole synthetic asset — a full stand-in for a real (confidential) dataset.
units: units — domain-agnostic oilfield-unit conversion constants and helpers.