numkong 7.0.0

package/include/numkong/geospatial.h

@@ -0,0 +1,453 @@
+/**
+ *  @brief SIMD-accelerated Geospatial Distances.
+ *  @file include/numkong/geospatial.h
+ *  @author Ash Vardanian
+ *  @date July 1, 2023
+ *
+ *  Contains following distance functions:
+ *
+ *  - Haversine (Great Circle) distance for 2 points
+ *  - Haversine (Great Circle) distance for 2 arrays of points
+ *  - Vincenty's distance function for Oblate Spheroid Geodesics
+ *
+ *  All outputs are in meters, and the input coordinates are in radians.
+ *
+ *  For dtypes:
+ *
+ *  - 64-bit IEEE-754 floating point → 64-bit
+ *  - 32-bit IEEE-754 floating point → 32-bit
+ *
+ *  Precision policy:
+ *
+ *  - `f32` remains the throughput-oriented lane and intentionally stays narrow end-to-end.
+ *  - `f64` is the higher-accuracy lane for the same formulas.
+ *  - We do not widen `f32` outputs here because the dominant error comes from the geodesic model
+ *    and transcendental approximations, not from long horizontal reductions.
+ *
+ *  For hardware architectures:
+ *
+ *  - Arm: NEON
+ *  - x86: Haswell, Skylake
+ *
+ *  @section haversine_similarity Low-Accuracy High-Performance Haversine Similarity
+ *
+ *  In most cases, for distance computations, we don't need the exact Haversine formula.
+ *  The very last part of the computation applies `asin(√x)` non-linear transformation.
+ *  Both `asin` and `sqrt` are monotonically increasing functions, so their product is also
+ *  monotonically increasing. This means, for relative similarity/closeness computation we
+ *  can avoid that expensive last step.
+ *
+ *  @section trig_approximations Trigonometric Approximations & SIMD Vectorization
+ *
+ *  The trigonometric functions (sin, cos, atan2) use polynomial approximations with SLEEF-level
+ *  error bounds (~3.5 ULP). For f64, this translates to ~1e-15 absolute error; for f32, ~1e-7.
+ *
+ *  @section accuracy_comparison Accuracy Comparison: Haversine vs Vincenty
+ *
+ *  Both algorithms compute geodesic distances, but with different Earth models:
+ *
+ *  - Haversine: Sphere (R=6335km), 0.3% - 0.6% vs WGS-84, fast approximation, ranking
+ *  - Vincenty: WGS-84 Ellipsoid, 0.01% - 0.2% vs WGS-84, high-precision navigation
+ *
+ *  Vincenty is ~3-20x more accurate than Haversine for most routes. The improvement is most
+ *  significant for long-distance routes and near-polar paths where Earth's oblateness matters.
+ *
+ *  @note   SIMD implementations may have slightly different results than serial due to
+ *          floating-point ordering in iterative algorithms. For Vincenty, expect <0.001%
+ *          difference between SIMD and serial implementations.
+ *
+ *  @section vincenty_precision High-Precision Vincenty's Formulae & Earth Ellipsoid
+ *
+ *  Several approximations of the Earth Ellipsoid exist, each defined by the Equatorial radius (m),
+ *  Polar radius (m), and Inverse flattening. The earliest ones date back to 1738, when Pierre Louis
+ *  Maupertuis in France suggested a shape, that is only 0.3% different from the most accurate modern
+ *  estimates by the International Earth Rotation and Reference Systems Service (IERS).
+ *  The Global Positioning System (GPS) uses the World Geodetic Systems's (WGS) WGS-84 standard.
+ *  NumKong uses the newer & more accurate @b IERS-2003 standard, but allows overriding default parameters:
+ *
+ *      #define NK_EARTH_ELLIPSOID_EQUATORIAL_RADIUS (6378136.6)
+ *      #define NK_EARTH_ELLIPSOID_POLAR_RADIUS (6356751.9)
+ *      #define NK_EARTH_ELLIPSOID_INVERSE_FLATTENING (298.25642)
+ *
+ *  To revert from oblate spheroids to spheres, use `NK_EARTH_MEDIATORIAL_RADIUS`.
+ *
+ *  @section x86_instructions Relevant x86 Instructions
+ *
+ *  Haversine and Vincenty formulas require sqrt for the final distance calculation and division
+ *  for Vincenty's iterative convergence. These are the most expensive operations (12-23 cycles)
+ *  but only execute once per point-pair. The polynomial trig approximations use FMA chains.
+ *  Note: ZMM sqrt is faster on Genoa (15c) than Ice Lake (19c) due to better 512-bit support.
+ *
+ *      Intrinsic               Instruction                     Ice         Genoa
+ *      _mm256_sqrt_ps          VSQRTPS (YMM, YMM)              12c @ p0    15c @ p01
+ *      _mm256_sqrt_pd          VSQRTPD (YMM, YMM)              13c @ p0    21c @ p01
+ *      _mm512_sqrt_ps          VSQRTPS (ZMM, ZMM)              19c @ p05   15c @ p01
+ *      _mm512_sqrt_pd          VSQRTPD (ZMM, ZMM)              23c @ p05   21c @ p01
+ *      _mm256_div_ps           VDIVPS (YMM, YMM, YMM)          11c @ p0    11c @ p01
+ *      _mm256_div_pd           VDIVPD (YMM, YMM, YMM)          13c @ p0    13c @ p01
+ *      _mm256_fmadd_ps         VFMADD231PS (YMM, YMM, YMM)     4c @ p01    4c @ p01
+ *      _mm256_fmadd_pd         VFMADD231PD (YMM, YMM, YMM)     4c @ p01    4c @ p01
+ *
+ *  @section arm_instructions Relevant ARM NEON/SVE Instructions
+ *
+ *  ARM sqrt (FSQRT) has low throughput as it uses a dedicated V02 execution unit. This is
+ *  acceptable since sqrt only appears once per distance calculation. FMA chains for trig
+ *  polynomial evaluation pipeline well across all 4 V-units.
+ *
+ *      Intrinsic               Instruction     M1 Firestorm    Graviton 3      Graviton 4
+ *      vfmaq_f32               FMLA.S (vec)    4c @ V0123      4c @ V0123      4c @ V0123
+ *      vfmaq_f64               FMLA.D (vec)    4c @ V0123      4c @ V0123      4c @ V0123
+ *      vsqrtq_f32              FSQRT.S (vec)   10c @ V02       10c @ V02       9c @ V02
+ *      vsqrtq_f64              FSQRT.D (vec)   13c @ V02       16c @ V02       16c @ V02
+ *
+ *  @section references References
+ *
+ *  - x86 intrinsics: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/
+ *  - Arm intrinsics: https://developer.arm.com/architectures/instruction-sets/intrinsics/
+ *  - Earth Ellipsoid: https://en.wikipedia.org/wiki/Earth_ellipsoid
+ *  - Oblate Spheroid Geodesic: https://mathworld.wolfram.com/OblateSpheroidGeodesic.html
+ *  - Staging experiments: https://github.com/ashvardanian/HaversineMathKong
+ *  - Speeding up atan2f by 50x: https://mazzo.li/posts/vectorized-atan2.html
+ *  - Simplifying the GNU C Sine Function: https://www.awelm.com/posts/simplifying-the-gnu-c-sine-function/
+ *
+ */
+#ifndef NK_GEOSPATIAL_H
+#define NK_GEOSPATIAL_H
+
+#include "numkong/types.h"
+#include "numkong/trigonometry.h"
+
+/*  Earth Ellipsoid Constants
+ *  The default values use the IERS-2003 standard, but can be overridden before including this header.
+ */
+#ifndef NK_EARTH_MEDIATORIAL_RADIUS
+#define NK_EARTH_MEDIATORIAL_RADIUS (6335439.0)
+#endif
+#ifndef NK_EARTH_ELLIPSOID_EQUATORIAL_RADIUS
+#define NK_EARTH_ELLIPSOID_EQUATORIAL_RADIUS (6378136.6)
+#endif
+#ifndef NK_EARTH_ELLIPSOID_POLAR_RADIUS
+#define NK_EARTH_ELLIPSOID_POLAR_RADIUS (6356751.9)
+#endif
+#ifndef NK_EARTH_ELLIPSOID_INVERSE_FLATTENING
+#define NK_EARTH_ELLIPSOID_INVERSE_FLATTENING (298.25642)
+#endif
+#ifndef NK_VINCENTY_MAX_ITERATIONS
+#define NK_VINCENTY_MAX_ITERATIONS 100
+#endif
+#ifndef NK_VINCENTY_CONVERGENCE_THRESHOLD_F64
+#define NK_VINCENTY_CONVERGENCE_THRESHOLD_F64 1e-12
+#endif
+#ifndef NK_VINCENTY_CONVERGENCE_THRESHOLD_F32
+#define NK_VINCENTY_CONVERGENCE_THRESHOLD_F32 1e-7f
+#endif
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/**
+ *  @brief Haversine distance between two arrays of points on a sphere.
+ *
+ *  @param[in] a_lats Latitudes of the first points, in radians.
+ *  @param[in] a_lons Longitudes of the first points, in radians.
+ *  @param[in] b_lats Latitudes of the second points, in radians.
+ *  @param[in] b_lons Longitudes of the second points, in radians.
+ *  @param[in] n The number of point pairs.
+ *  @param[out] results Output distances in meters, length `n`.
+ *
+ *  @note Inputs are in radians and outputs are in meters.
+ */
+NK_DYNAMIC void nk_haversine_f64(                   //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+
+/** @copydoc nk_haversine_f64 */
+NK_DYNAMIC void nk_haversine_f32(                   //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+
+/**
+ *  @brief Vincenty distance between two arrays of points on an oblate spheroid.
+ *
+ *  @param[in] a_lats Latitudes of the first points, in radians.
+ *  @param[in] a_lons Longitudes of the first points, in radians.
+ *  @param[in] b_lats Latitudes of the second points, in radians.
+ *  @param[in] b_lons Longitudes of the second points, in radians.
+ *  @param[in] n The number of point pairs.
+ *  @param[out] results Output distances in meters, length `n`.
+ *
+ *  @note Inputs are in radians and outputs are in meters.
+ *  @note Uses the Earth ellipsoid parameters configured via `NK_EARTH_ELLIPSOID_*`.
+ */
+NK_DYNAMIC void nk_vincenty_f64(                    //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+
+/** @copydoc nk_vincenty_f64 */
+NK_DYNAMIC void nk_vincenty_f32(                    //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_serial(             //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_serial(              //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_serial(             //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_serial(              //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+
+#if NK_TARGET_NEON
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_neon(               //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_neon(                //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_neon(               //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_neon(                //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+#endif // NK_TARGET_NEON
+
+#if NK_TARGET_HASWELL
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_haswell(            //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_haswell(             //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_haswell(            //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_haswell(             //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+#endif // NK_TARGET_HASWELL
+
+#if NK_TARGET_SKYLAKE
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_skylake(            //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_skylake(             //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_skylake(            //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_skylake(             //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+#endif // NK_TARGET_SKYLAKE
+
+#if NK_TARGET_V128RELAXED
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_v128relaxed(        //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_v128relaxed(         //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_v128relaxed(        //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_v128relaxed(         //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+#endif // NK_TARGET_V128RELAXED
+
+#if NK_TARGET_RVV
+/** @copydoc nk_haversine_f64 */
+NK_PUBLIC void nk_haversine_f64_rvv(                //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_vincenty_f64 */
+NK_PUBLIC void nk_vincenty_f64_rvv(                 //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results);
+/** @copydoc nk_haversine_f32 */
+NK_PUBLIC void nk_haversine_f32_rvv(                //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+/** @copydoc nk_vincenty_f32 */
+NK_PUBLIC void nk_vincenty_f32_rvv(                 //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results);
+#endif // NK_TARGET_RVV
+
+/**
+ *  @brief  Returns the output dtype for Haversine distance.
+ */
+NK_INTERNAL nk_dtype_t nk_haversine_output_dtype(nk_dtype_t dtype) {
+    switch (dtype) {
+    case nk_f64_k: return nk_f64_k;
+    case nk_f32_k: return nk_f32_k;
+    default: return nk_dtype_unknown_k;
+    }
+}
+
+/**
+ *  @brief  Returns the output dtype for Vincenty distance.
+ */
+NK_INTERNAL nk_dtype_t nk_vincenty_output_dtype(nk_dtype_t dtype) {
+    switch (dtype) {
+    case nk_f64_k: return nk_f64_k;
+    case nk_f32_k: return nk_f32_k;
+    default: return nk_dtype_unknown_k;
+    }
+}
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#include "numkong/geospatial/serial.h"
+#include "numkong/geospatial/neon.h"
+#include "numkong/geospatial/haswell.h"
+#include "numkong/geospatial/skylake.h"
+#include "numkong/geospatial/v128relaxed.h"
+#include "numkong/geospatial/rvv.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+#if !NK_DYNAMIC_DISPATCH
+
+NK_PUBLIC void nk_haversine_f64(                    //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results) {
+#if NK_TARGET_SKYLAKE
+    nk_haversine_f64_skylake(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_HASWELL
+    nk_haversine_f64_haswell(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_NEON
+    nk_haversine_f64_neon(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_V128RELAXED
+    nk_haversine_f64_v128relaxed(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_RVV
+    nk_haversine_f64_rvv(a_lats, a_lons, b_lats, b_lons, n, results);
+#else
+    nk_haversine_f64_serial(a_lats, a_lons, b_lats, b_lons, n, results);
+#endif
+}
+
+NK_PUBLIC void nk_haversine_f32(                    //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results) {
+#if NK_TARGET_SKYLAKE
+    nk_haversine_f32_skylake(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_HASWELL
+    nk_haversine_f32_haswell(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_NEON
+    nk_haversine_f32_neon(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_V128RELAXED
+    nk_haversine_f32_v128relaxed(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_RVV
+    nk_haversine_f32_rvv(a_lats, a_lons, b_lats, b_lons, n, results);
+#else
+    nk_haversine_f32_serial(a_lats, a_lons, b_lats, b_lons, n, results);
+#endif
+}
+
+NK_PUBLIC void nk_vincenty_f64(                     //
+    nk_f64_t const *a_lats, nk_f64_t const *a_lons, //
+    nk_f64_t const *b_lats, nk_f64_t const *b_lons, //
+    nk_size_t n, nk_f64_t *results) {
+#if NK_TARGET_SKYLAKE
+    nk_vincenty_f64_skylake(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_HASWELL
+    nk_vincenty_f64_haswell(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_NEON
+    nk_vincenty_f64_neon(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_V128RELAXED
+    nk_vincenty_f64_v128relaxed(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_RVV
+    nk_vincenty_f64_rvv(a_lats, a_lons, b_lats, b_lons, n, results);
+#else
+    nk_vincenty_f64_serial(a_lats, a_lons, b_lats, b_lons, n, results);
+#endif
+}
+
+NK_PUBLIC void nk_vincenty_f32(                     //
+    nk_f32_t const *a_lats, nk_f32_t const *a_lons, //
+    nk_f32_t const *b_lats, nk_f32_t const *b_lons, //
+    nk_size_t n, nk_f32_t *results) {
+#if NK_TARGET_SKYLAKE
+    nk_vincenty_f32_skylake(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_HASWELL
+    nk_vincenty_f32_haswell(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_NEON
+    nk_vincenty_f32_neon(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_V128RELAXED
+    nk_vincenty_f32_v128relaxed(a_lats, a_lons, b_lats, b_lons, n, results);
+#elif NK_TARGET_RVV
+    nk_vincenty_f32_rvv(a_lats, a_lons, b_lats, b_lons, n, results);
+#else
+    nk_vincenty_f32_serial(a_lats, a_lons, b_lats, b_lons, n, results);
+#endif
+}
+
+#endif // !NK_DYNAMIC_DISPATCH
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif

package/include/numkong/geospatial.hpp

@@ -0,0 +1,235 @@
+/**
+ *  @brief Geospatial kernels: haversine, vincenty.
+ *  @file include/numkong/geospatial.hpp
+ *  @author Ash Vardanian
+ *  @date February 5, 2026
+ */
+#ifndef NK_GEOSPATIAL_HPP
+#define NK_GEOSPATIAL_HPP
+
+#include <cstdint>     // `std::uint32_t`
+#include <type_traits> // `std::is_same_v`
+
+#include "numkong/geospatial.h"
+
+#include "numkong/types.hpp"
+
+namespace ashvardanian::numkong {
+
+/**
+ *  @brief Batched Haversine: 2R × arcsin(√(sin²(Δφ/2) + cos φ₁ × cos φ₂ × sin²(Δλ/2)))
+ *  @param[in] a_lats,a_lons Arrays of latitudes/longitudes for first points (radians)
+ *  @param[in] b_lats,b_lons Arrays of latitudes/longitudes for second points (radians)
+ *  @param[in] d Number of point pairs
+ *  @param[out] results Output array of distances (meters)
+ *
+ *  @tparam in_type_ Input coordinate type (f32_t, f64_t)
+ *  @tparam precision_type_ Precision type for scalar fallback computations, defaults to `in_type_`
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ *
+ *  @note Uses spherical Earth model with mediatorial radius (6335439.0 m)
+ *  @note Accuracy: 0.3-0.6% vs WGS-84, suitable for ranking/similarity
+ */
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void haversine(in_type_ const *a_lats, in_type_ const *a_lons, in_type_ const *b_lats, in_type_ const *b_lons,
+               std::size_t d, in_type_ *results) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k && std::is_same_v<in_type_, precision_type_>;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd)
+        nk_haversine_f64(&a_lats->raw_, &a_lons->raw_, &b_lats->raw_, &b_lons->raw_, d, &results->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd)
+        nk_haversine_f32(&a_lats->raw_, &a_lons->raw_, &b_lats->raw_, &b_lons->raw_, d, &results->raw_);
+    // Scalar fallback
+    else {
+        precision_type_ const earth_radius = precision_type_(6335439.0); // mediatorial radius in meters
+
+        for (std::size_t i = 0; i < d; i++) {
+            precision_type_ first_latitude = precision_type_(a_lats[i]);
+            precision_type_ first_longitude = precision_type_(a_lons[i]);
+            precision_type_ second_latitude = precision_type_(b_lats[i]);
+            precision_type_ second_longitude = precision_type_(b_lons[i]);
+
+            precision_type_ latitude_delta = second_latitude - first_latitude;
+            precision_type_ longitude_delta = second_longitude - first_longitude;
+
+            // Haversine formula: a = sin²(Δlat/2) + cos(lat1)×cos(lat2)×sin²(Δlon/2)
+            precision_type_ sin_latitude_delta_half = (latitude_delta * precision_type_(0.5)).sin();
+            precision_type_ sin_longitude_delta_half = (longitude_delta * precision_type_(0.5)).sin();
+            precision_type_ cos_first_latitude = first_latitude.cos();
+            precision_type_ cos_second_latitude = second_latitude.cos();
+
+            precision_type_ haversine_term = sin_latitude_delta_half * sin_latitude_delta_half +
+                                             cos_first_latitude * cos_second_latitude * sin_longitude_delta_half *
+                                                 sin_longitude_delta_half;
+
+            // Central angle: c = 2 * atan2(sqrt(a), sqrt(1-a))
+            precision_type_ sqrt_haversine = haversine_term.sqrt();
+            precision_type_ sqrt_complement = (precision_type_(1.0) - haversine_term).sqrt();
+            precision_type_ central_angle = precision_type_(2.0) * sqrt_haversine.atan2(sqrt_complement);
+
+            results[i] = in_type_(static_cast<double>(earth_radius * central_angle));
+        }
+    }
+}
+
+/**
+ *  @brief Batched Vincenty distance (geodesic on WGS-84 ellipsoid)
+ *  @param[in] a_lats,a_lons Arrays of latitudes/longitudes for first points (radians)
+ *  @param[in] b_lats,b_lons Arrays of latitudes/longitudes for second points (radians)
+ *  @param[in] d Number of point pairs
+ *  @param[out] results Output array of distances (meters)
+ *
+ *  @tparam in_type_ Input coordinate type (f32_t, f64_t)
+ *  @tparam precision_type_ Precision type for scalar fallback computations, defaults to `in_type_`
+ *  @tparam allow_simd_ Enable SIMD kernel dispatch when `prefer_simd_k`
+ *
+ *  @note Uses WGS-84/IERS-2003 ellipsoid model
+ *  @note Accuracy: 0.01-0.2% vs WGS-84, 3-20x more accurate than Haversine
+ *  @note Iterative algorithm with max 100 iterations
+ */
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void vincenty(in_type_ const *a_lats, in_type_ const *a_lons, in_type_ const *b_lats, in_type_ const *b_lons,
+              std::size_t d, in_type_ *results) noexcept {
+    constexpr bool simd = allow_simd_ == prefer_simd_k && std::is_same_v<in_type_, precision_type_>;
+
+    if constexpr (std::is_same_v<in_type_, f64_t> && simd)
+        nk_vincenty_f64(&a_lats->raw_, &a_lons->raw_, &b_lats->raw_, &b_lons->raw_, d, &results->raw_);
+    else if constexpr (std::is_same_v<in_type_, f32_t> && simd)
+        nk_vincenty_f32(&a_lats->raw_, &a_lons->raw_, &b_lats->raw_, &b_lons->raw_, d, &results->raw_);
+    // Scalar fallback
+    else {
+        precision_type_ const equatorial_radius = precision_type_(6378136.6);
+        precision_type_ const polar_radius = precision_type_(6356751.9);
+        precision_type_ const flattening = precision_type_(1.0) / precision_type_(298.25642);
+        precision_type_ const convergence_threshold = precision_type_(1e-12);
+        constexpr int max_iterations = 100;
+
+        for (std::size_t i = 0; i < d; i++) {
+            precision_type_ first_latitude = precision_type_(a_lats[i]);
+            precision_type_ second_latitude = precision_type_(b_lats[i]);
+            precision_type_ longitude_difference = precision_type_(b_lons[i]) - precision_type_(a_lons[i]);
+
+            // Reduced latitudes on the auxiliary sphere
+            precision_type_ tan_reduced_first = (precision_type_(1.0) - flattening) * first_latitude.tan();
+            precision_type_ tan_reduced_second = (precision_type_(1.0) - flattening) * second_latitude.tan();
+            precision_type_ cos_reduced_first = precision_type_(1.0) /
+                                                (precision_type_(1.0) + tan_reduced_first * tan_reduced_first).sqrt();
+            precision_type_ sin_reduced_first = tan_reduced_first * cos_reduced_first;
+            precision_type_ cos_reduced_second =
+                precision_type_(1.0) / (precision_type_(1.0) + tan_reduced_second * tan_reduced_second).sqrt();
+            precision_type_ sin_reduced_second = tan_reduced_second * cos_reduced_second;
+
+            // Iterative convergence of lambda (difference in longitude on auxiliary sphere)
+            precision_type_ lambda = longitude_difference;
+            precision_type_ lambda_previous = longitude_difference;
+            precision_type_ sin_angular_distance, cos_angular_distance, angular_distance;
+            precision_type_ sin_azimuth, cos_squared_azimuth, cos_double_angular_midpoint;
+            bool coincident = false;
+
+            for (unsigned int iteration = 0; iteration < max_iterations; iteration++) {
+                precision_type_ sin_lambda = lambda.sin();
+                precision_type_ cos_lambda = lambda.cos();
+
+                precision_type_ cross_term = cos_reduced_second * sin_lambda;
+                precision_type_ mixed_term = cos_reduced_first * sin_reduced_second -
+                                             sin_reduced_first * cos_reduced_second * cos_lambda;
+                sin_angular_distance = (cross_term * cross_term + mixed_term * mixed_term).sqrt();
+
+                if (sin_angular_distance == precision_type_(0.0)) {
+                    coincident = true;
+                    break;
+                }
+
+                cos_angular_distance = sin_reduced_first * sin_reduced_second +
+                                       cos_reduced_first * cos_reduced_second * cos_lambda;
+                angular_distance = sin_angular_distance.atan2(cos_angular_distance);
+
+                sin_azimuth = cos_reduced_first * cos_reduced_second * sin_lambda / sin_angular_distance;
+                cos_squared_azimuth = precision_type_(1.0) - sin_azimuth * sin_azimuth;
+
+                // Handle equatorial geodesic case
+                cos_double_angular_midpoint = (cos_squared_azimuth != precision_type_(0.0))
+                                                  ? cos_angular_distance - precision_type_(2.0) * sin_reduced_first *
+                                                                               sin_reduced_second / cos_squared_azimuth
+                                                  : precision_type_(0.0);
+
+                precision_type_ correction_factor =
+                    flattening / precision_type_(16.0) * cos_squared_azimuth *
+                    (precision_type_(4.0) +
+                     flattening * (precision_type_(4.0) - precision_type_(3.0) * cos_squared_azimuth));
+
+                lambda_previous = lambda;
+                lambda = longitude_difference +
+                         (precision_type_(1.0) - correction_factor) * flattening * sin_azimuth *
+                             (angular_distance +
+                              correction_factor * sin_angular_distance *
+                                  (cos_double_angular_midpoint +
+                                   correction_factor * cos_angular_distance *
+                                       (precision_type_(-1.0) + precision_type_(2.0) * cos_double_angular_midpoint *
+                                                                    cos_double_angular_midpoint)));
+
+                if ((lambda - lambda_previous).abs() < convergence_threshold) break;
+            }
+
+            if (coincident) {
+                results[i] = in_type_(0.0);
+                continue;
+            }
+
+            // Final distance calculation
+            precision_type_ u_squared = cos_squared_azimuth *
+                                        (equatorial_radius * equatorial_radius - polar_radius * polar_radius) /
+                                        (polar_radius * polar_radius);
+            precision_type_ series_a =
+                precision_type_(1.0) +
+                u_squared / precision_type_(16384.0) *
+                    (precision_type_(4096.0) +
+                     u_squared * (precision_type_(-768.0) +
+                                  u_squared * (precision_type_(320.0) - precision_type_(175.0) * u_squared)));
+            precision_type_ series_b = u_squared / precision_type_(1024.0) *
+                                       (precision_type_(256.0) +
+                                        u_squared *
+                                            (precision_type_(-128.0) +
+                                             u_squared * (precision_type_(74.0) - precision_type_(47.0) * u_squared)));
+
+            precision_type_ angular_correction =
+                series_b * sin_angular_distance *
+                (cos_double_angular_midpoint +
+                 series_b / precision_type_(4.0) *
+                     (cos_angular_distance *
+                          (precision_type_(-1.0) +
+                           precision_type_(2.0) * cos_double_angular_midpoint * cos_double_angular_midpoint) -
+                      series_b / precision_type_(6.0) * cos_double_angular_midpoint *
+                          (precision_type_(-3.0) + precision_type_(4.0) * sin_angular_distance * sin_angular_distance) *
+                          (precision_type_(-3.0) +
+                           precision_type_(4.0) * cos_double_angular_midpoint * cos_double_angular_midpoint)));
+
+            results[i] = in_type_(
+                static_cast<double>(polar_radius * series_a * (angular_distance - angular_correction)));
+        }
+    }
+}
+
+} // namespace ashvardanian::numkong
+
+#include "numkong/tensor.hpp"
+
+namespace ashvardanian::numkong {
+
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void haversine(vector_view<in_type_> a_lats, vector_view<in_type_> a_lons, vector_view<in_type_> b_lats,
+               vector_view<in_type_> b_lons, in_type_ *results) noexcept {
+    haversine<in_type_, precision_type_, allow_simd_>(a_lats.data(), a_lons.data(), b_lats.data(), b_lons.data(),
+                                                      a_lats.size(), results);
+}
+
+template <numeric_dtype in_type_, numeric_dtype precision_type_ = in_type_, allow_simd_t allow_simd_ = prefer_simd_k>
+void vincenty(vector_view<in_type_> a_lats, vector_view<in_type_> a_lons, vector_view<in_type_> b_lats,
+              vector_view<in_type_> b_lons, in_type_ *results) noexcept {
+    vincenty<in_type_, precision_type_, allow_simd_>(a_lats.data(), a_lons.data(), b_lats.data(), b_lons.data(),
+                                                     a_lats.size(), results);
+}
+
+} // namespace ashvardanian::numkong
+
+#endif // NK_GEOSPATIAL_HPP