Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Geostatistics and computation

energyml-analysis holds what is computed from EnergyML shapes, as opposed to what a file states (which is energyml-geometry’s job). Interpolators, surface meshing, structural and well computations all follow the same contract:

  • inputs are plain slices of samples and query points; nothing here reads a package, so the crate builds for WebAssembly and works with any storage;
  • a NaN sample is set aside and counted, never averaged;
  • refusals are named: an interpolated NaN and a malformed call are different news;
  • a function says what it measured and in which unit, and converts nothing the caller did not ask it to.

The neutral part (interpolation, meshing, small tools; no energyml-* dependency) is its own crate, energyml-geostat, usable in hydrogeology, environmental or civil work; the domain part stays in energyml-analysis. This page lists the modules by family. The modules of the tables below are in energyml-geostat, except surface, intersect, project, fault_throw, fault_sticks, horizon_law, t2d, survey, well_plan, tops, profile, well_logs, fake, step_rate, hall, flow_law, ion_balance, water_diagrams and combine, which are in energyml-analysis.

Three pictures from the Lutetia reference model, with the call that draws each in the Gallery:

Citations: what is and is not referenced

A reference is listed only when the source code already cites it, copied as written there. Where the method is standard but the code names no publication, the entry says TODO(reference): a citation is added only after the work has actually been checked against it. Some entries in the code say the source was “cited from memory, no copy in this repository”: those are kept as written and flagged for verification.

Interpolation

ModuleWhat it doesReference
idwInverse-distance weighting (Shepard’s method): the value at a point is the weighted mean of the samples, with an exponent and optional radius. Deliberately the plain interpolator; exact at samplesTODO(reference): Shepard’s method is named in the code without a citation
variogramThe empirical variogram (mean pair distance per class, semivariance, pair counts) and fitted models, spherical and exponential. range is the practical range for the exponential model (about 95% of the sill)TODO(reference)
krigingOrdinary kriging with the kriging variance as the model’s statement of uncertainty. The dense system is LU-factorised once; each query is a back-substitutionTODO(reference)
rbfRadial basis function interpolation: thin-plate spline, multiquadric, linear, Gaussian kernels, with the polynomial term each kernel requires decided by the kernel and not exposedTODO(reference)
mba, mba_frameMultilevel B-spline Approximation: extends a surface while keeping its general shape where points are sparse, with a least-squares plane removed first (the paper’s own initialisation). mba_frame fits in a tilted local frame for surfaces MBA cannot fit in world coordinatesLee, Wolberg, Shin, “Scattered Data Interpolation with Multilevel B-Splines”, IEEE Transactions on Visualization and Computer Graphics, vol. 3, n° 3, 1997, p. 228-244 (DOI 10.1109/2945.620490)
solveA dense LU factorisation with partial pivoting shared by kriging and RBF (the Lagrange border of kriging and the polynomial border of RBF make the systems symmetric but not positive definite)-
barrierFaults as barriers: a sample on the far side of a fault says nothing about this side- (original method)

Surfaces and meshes

ModuleWhat it doesReference
triangulate2D Delaunay and constrained Delaunay triangulation of a point cloud (faults as constraints), each point keeping its own z. Built on the spade crate for its exact geometric predicates, because floating-point predicates give overlapping triangles over nearly collinear points such as an alignment of boreholesspade library; TODO(reference)
isocontourIso-lines of a per-node scalar over a triangulated surface. Inside one triangle a linear field crosses a level along one segment or not at all, so there is no ambiguous case; segments are then chained into polylinesTODO(reference)
isosurfaceThe iso-surface of a scalar over a structured lattice of ni x nj x nl nodes, by marching tetrahedra: each cell is cut into six tetrahedra by the Kuhn subdivision, which all share one diagonal, so two neighbouring cells cut their common face the same way (no crack) and a tetrahedron has no ambiguous case (no table of 256 cases). Vertices are keyed by the edge of the lattice they lie on, so the mesh is welded and the same lattice gives the same mesh bit for bit. The value may vary linearly or linearly in its base-10 logarithm along an edge. When nothing is cut the answer says why (Crossing::AllBelow, AllAbove, Grazed, InSetAsideCells), never a silent empty mesh. A lattice that folds back on itself gives a wrong surface and the function cannot see it: the caller refuses first, with the fold check of the well geometryKuhn (1960) for the subdivision, Doi and Koide (1991) for the method; TODO(reference): neither has been re-read
surfaceDip, dip azimuth and curvature (mean, Gaussian, principal) of a triangulated surface, with the cotangent Laplacian over the mixed areaMeyer, Desbrun, Schröder and Barr (2003), Discrete Differential-Geometry Operators for Triangulated 2-Manifolds. TODO(reference): venue and DOI are not in the code
resample, densifyResample a polyline at a spacing, or add points between vertices while keeping every vertex-
loftA surface between polylines (two lines, or successive sticks of a fault)-
outlineThe boundary of a triangulated surface, or the convex hull of anything else-
extendExtend a polyline or a surface past its border-
intersectIntersection of two triangulated surfaces, as polylines-
project, heightsVertical projection of nodes onto a surface or a level; exact heights of a surface under a plan position (triangles linear, quadrilaterals bilinear)-
nodesWhat erasing nodes or moving them does to a shape-
cells, ijk, ijk_faultsCells in an IJK box or crossed by a wellbore path (a column that leans or is no parallelogram is refused by name only where the path meets it, as blocked-wellbore reads only the cells near the path: an irregular column far from the path refuses nothing); an IJK grid between horizons (pillars, K gaps); an IJK grid cut by faults (split coordinate lines, stated throw)-
measure, thickness, groupsAreas, lengths and volumes of shapes; thickness between two horizons at every node; values split by a key (zone, stratigraphic unit)-
samples (private)What the point interpolators (idw, kriging, rbf, variogram, mba) share before computing: the set-aside of samples with a non-finite value or position, the Euclidean distance, and the refusal of coincident samples-
bucketsThe one grid of buckets for “which of these many things lie near here?”: boxes filed once in a regular grid sized to about one per bucket. query returns exactly the boxes a linear scan with the same closed-box test returns (ascending ids), nearest the lowest-id minimum of the caller’s own distance, candidates_at the ids filed in the bucket of a position. A box with a non-finite bound is left out and counted, never lost silently. Used by the surface extension (the band of a border node), the blocking of a path in IJK cells, the faces of heights, the projection of nodes on a fault trace, the cells of a grid cut by a section and the crosslines of a fence; each confronts it with the scan in a test-
vector, vector::planThe one place the 3D and plan-view vector arithmetic is written: add, subtract, scale, dot, cross, norm, distance, the unit vector with the caller’s floor, the distance of a point to a chord or a segment, and the exact intersection test of two segments. energyml_geometry::vector re-exports it, so every crate reaches the same functions. See ADR 0044-

Structural computations

ModuleWhat it doesReference
fault_throwA horizon triangulated with fault traces as constraints, torn along each trace, hanging wall offset by a throw that dies out at both ends. It also holds the one reading of a fault trace (orient, read_trace) and the one hanging-wall rule (hanging_wall_side), which ijk_faults (a grid cut by its faults) calls too, so a torn horizon and a cut grid cannot disagree on which side goes down-
fault_sticksFault sticks drawn from a plane and the orientation of the surface they make-
horizon_lawA horizon laid by a law over a reference surface-
t2dAnalytic time-to-depth with a linear velocity-depth law V(z) = V0 + k z; k = 0 is a legitimate constant-velocity lawTODO(reference)

Derived values

ModuleWhat it doesReference
combineTwo sets of values combined cell by cell: a ratio, a difference, the log of a ratio. The combinations are a registry (Combines, the caller’s own tried first). The second input is converted to the unit of the first when they are two units of one family, and refused otherwise. A pair where an input is absent (NaN) and a pair whose result is undefined (a division by zero, the logarithm of a value <= 0) are counted apart, and the cell is NaN, never an infinity. The result is a list of values: writing it back as a property is the combine operation of Creating objects-

Wells

ModuleWhat it doesReference
surveyA survey read back from stations: inclination, azimuth and dogleg by the minimum curvature method, invertedAPI Bulletin D20 (Directional Drilling Survey Calculation Methods and Terminology, 1985); Sawaryn & Thorogood, A Compendium of Directional Calculations Based on the Minimum Curvature Method (SPE 84246, SPE Drilling & Completion 20(1), 2005) - as cited in well_plan
well_planA wellbore from a drilling plan: straight holds and circular arcs, surveyed by minimum curvaturesame as above
topsWhere a well crosses a surface (computed tops)-
profile, wells_profileWells projected on a long profile: which heads fall in the band around a track, where along it, how far and on which side-
well_logsValues given by a law of depth along a wellbore (geothermal gradient, hydrostatic pressure)-
fakeFake dated data for tests: vertical polylines from a point cloud-

Tests and hydraulics

ModuleWhat it doesReference
step_rateWhich steps of a step-rate injection test have settled, and the injectivity index they give-
hallThe Hall plot of an injection (cumulative pressure against cumulative volume; the slope is the inverse of the injectivity index under steady radial flow)Hall, H.N. (1963), How to Analyze Waterflood Injection Well Performance, World Oil - cited from memory in the code, to be verified
flow_law, time_lawA flow rate over time and what it delivers between two instants; a value that drifts with time-

Water chemistry

ModuleWhat it doesReference
ion_balanceWhether a water analysis is electrically neutral: 100 (sum cations - sum anions) / (sum cations + sum anions) in meq/L. The module computes; the tolerance is the caller’smolar masses: IUPAC standard atomic weights (abridged, CIAAW 2021), as cited in the code
water_diagramsPiper and Stiff diagrams. An analysis that does not balance is refused before anything is drawn; an absent ion is never drawn as zero (the caller may declare an ion absent, and the result carries the declaration)Piper, A.M. (1944), A graphic procedure in the geochemical interpretation of water-analyses, Transactions, American Geophysical Union 25; Stiff, H.A. Jr. (1951), The interpretation of chemical water analysis by means of patterns, Journal of Petroleum Technology 3; Hem, J.D. (1985), Study and Interpretation of the Chemical Characteristics of Natural Water, USGS Water-Supply Paper 2254 (all three “cited from memory” in the code, to be verified)

Testing the algorithms

Tests are unit tests over fabricated numbers. Where a publication gives a worked numerical example, the plan is to reproduce it in a test with the numbers typed in and the citation in a comment; nothing reads a file. TODO(reference): add such tests as references are verified. A provenance audit (no code ported from a licence incompatible with Apache-2.0) is part of the release checklist.