C · Dense Distances

Dense Distances

#include <numkong/spatial.h> 8.0.0-rc.1 · b1f866ab

The dense spatial kernels cover the SciPy-style sqeuclidean, euclidean, and angular family. The important difference is that storage type and output type are not forced to match.

nk_f16_t a[768];
nk_f16_t b[768];
nk_f32_t sqeuclidean = 0, euclidean = 0, angular = 0;

// `_Float16` support varies across compilers, and
// auto-vectorization targets `f32` — not `f16`.
nk_sqeuclidean_f16_best(a, b, 768, &sqeuclidean, capabilities, NULL);
nk_euclidean_f16_best(a, b, 768, &euclidean, capabilities, NULL);
nk_angular_f16_best(a, b, 768, &angular, capabilities, NULL);

For i8, u8, i4, u4, and u1, the widening is even more important. The output type is chosen to avoid the obvious overflow trap of same-width accumulation.

API

Functions

nk_euclidean_*_best× 12L2 (Euclidean) distance between two vectors.
spatial.h:168 ↗
nk_status_t nk_euclidean_f64_best(
    nk_f64_t const *a,
    nk_f64_t const *b,
    nk_size_t n,
    nk_f64_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);
Symbola, bresultBackends
nk_euclidean_f64_bestnk_f64_tnk_f64_t9
nk_euclidean_f32_bestnk_f32_tnk_f64_t9
nk_euclidean_f16_bestnk_f16_tnk_f32_t11
nk_euclidean_bf16_bestnk_bf16_tnk_f32_t12
nk_euclidean_e4m3_bestnk_e4m3_tnk_f32_t9
nk_euclidean_e5m2_bestnk_e5m2_tnk_f32_t8
nk_euclidean_e2m3_bestnk_e2m3_tnk_f32_t9
nk_euclidean_e3m2_bestnk_e3m2_tnk_f32_t9
nk_euclidean_i8_bestnk_i8_tnk_f32_t12
nk_euclidean_u8_bestnk_u8_tnk_f32_t12
nk_euclidean_i4_bestnk_i4x2_tnk_f32_t4
nk_euclidean_u4_bestnk_u4x2_tnk_f32_t4

Backends

  • nk_euclidean_f64serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_euclidean_f32serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_euclidean_f16serialneonsvehalfhaswellskylakediamondv128relaxedrvvrvvhalfpowervsxloongsonasx
  • nk_euclidean_bf16serialneonneonbfdotsvebfdothaswellgenoav128v128relaxedrvvrvvbf16powervsxloongsonasx
  • nk_euclidean_e4m3serialneonneonfp8haswellskylakeicelakediamondv128relaxedrvv
  • nk_euclidean_e5m2serialneonneonfp8haswellskylakediamondv128relaxedrvv
  • nk_euclidean_e2m3serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_euclidean_e3m2serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_euclidean_i8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_euclidean_u8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_euclidean_i4serialneonsdoticelakervv
  • nk_euclidean_u4serialneonsdoticelakervv

Parameters

ainThe first vector.
binThe second vector.
ninCounts dimensions, a multiple of the values per byte.
resultoutThe output distance value.
capabilitiesinOne device's capabilities, like nk_cpu_capabilities_enabled reports.
streaminNull on the CPU, or the GPU stream of that device to queue on.

Notes

  • The output distance value is non-negative.
  • The output distance value is zero if and only if the two vectors are identical.

Statuses

nk_sqeuclidean_*_best× 12Squared L2 (Euclidean) distance between two vectors.
spatial.h:221 ↗
nk_status_t nk_sqeuclidean_f64_best(
    nk_f64_t const *a,
    nk_f64_t const *b,
    nk_size_t n,
    nk_f64_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);
Symbola, bresultBackends
nk_sqeuclidean_f64_bestnk_f64_tnk_f64_t9
nk_sqeuclidean_f32_bestnk_f32_tnk_f64_t9
nk_sqeuclidean_f16_bestnk_f16_tnk_f32_t11
nk_sqeuclidean_bf16_bestnk_bf16_tnk_f32_t12
nk_sqeuclidean_e4m3_bestnk_e4m3_tnk_f32_t9
nk_sqeuclidean_e5m2_bestnk_e5m2_tnk_f32_t8
nk_sqeuclidean_e2m3_bestnk_e2m3_tnk_f32_t9
nk_sqeuclidean_e3m2_bestnk_e3m2_tnk_f32_t9
nk_sqeuclidean_i8_bestnk_i8_tnk_u32_t12
nk_sqeuclidean_u8_bestnk_u8_tnk_u32_t12
nk_sqeuclidean_i4_bestnk_i4x2_tnk_u32_t4
nk_sqeuclidean_u4_bestnk_u4x2_tnk_u32_t4

Backends

  • nk_sqeuclidean_f64serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_sqeuclidean_f32serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_sqeuclidean_f16serialneonsvehalfhaswellskylakediamondv128relaxedrvvrvvhalfpowervsxloongsonasx
  • nk_sqeuclidean_bf16serialneonneonbfdotsvebfdothaswellgenoav128v128relaxedrvvrvvbf16powervsxloongsonasx
  • nk_sqeuclidean_e4m3serialneonneonfp8haswellskylakeicelakediamondv128relaxedrvv
  • nk_sqeuclidean_e5m2serialneonneonfp8haswellskylakediamondv128relaxedrvv
  • nk_sqeuclidean_e2m3serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_sqeuclidean_e3m2serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_sqeuclidean_i8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_sqeuclidean_u8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_sqeuclidean_i4serialneonsdoticelakervv
  • nk_sqeuclidean_u4serialneonsdoticelakervv

Parameters

ainThe first vector.
binThe second vector.
ninCounts dimensions, a multiple of the values per byte.
resultoutThe output distance value.
capabilitiesinOne device's capabilities, like nk_cpu_capabilities_enabled reports.
streaminNull on the CPU, or the GPU stream of that device to queue on.

Notes

  • The output distance value is non-negative.
  • The output distance value is zero if and only if the two vectors are identical.

Statuses

nk_angular_*_best× 12Angular (cosine) distance between two vectors.
spatial.h:274 ↗
nk_status_t nk_angular_f64_best(
    nk_f64_t const *a,
    nk_f64_t const *b,
    nk_size_t n,
    nk_f64_t *result,
    nk_capability_t capabilities,
    nk_stream_t stream);
Symbola, bresultBackends
nk_angular_f64_bestnk_f64_tnk_f64_t9
nk_angular_f32_bestnk_f32_tnk_f64_t9
nk_angular_f16_bestnk_f16_tnk_f32_t11
nk_angular_bf16_bestnk_bf16_tnk_f32_t12
nk_angular_e4m3_bestnk_e4m3_tnk_f32_t9
nk_angular_e5m2_bestnk_e5m2_tnk_f32_t8
nk_angular_e2m3_bestnk_e2m3_tnk_f32_t9
nk_angular_e3m2_bestnk_e3m2_tnk_f32_t9
nk_angular_i8_bestnk_i8_tnk_f32_t12
nk_angular_u8_bestnk_u8_tnk_f32_t12
nk_angular_i4_bestnk_i4x2_tnk_f32_t4
nk_angular_u4_bestnk_u4x2_tnk_f32_t4

Backends

  • nk_angular_f64serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_angular_f32serialneonsvehaswellskylakev128relaxedrvvpowervsxloongsonasx
  • nk_angular_f16serialneonsvehalfhaswellskylakediamondv128relaxedrvvrvvhalfpowervsxloongsonasx
  • nk_angular_bf16serialneonneonbfdotsvebfdothaswellgenoav128v128relaxedrvvrvvbf16powervsxloongsonasx
  • nk_angular_e4m3serialneonneonfp8haswellskylakeicelakediamondv128relaxedrvv
  • nk_angular_e5m2serialneonneonfp8haswellskylakediamondv128relaxedrvv
  • nk_angular_e2m3serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_angular_e3m2serialneonneonfp8haswellskylakeicelakesierraalderv128relaxed
  • nk_angular_i8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_angular_u8serialneonsdotsvesdothaswellicelakesierraalderv128v128relaxedrvvpowervsxloongsonasx
  • nk_angular_i4serialneonsdoticelakervv
  • nk_angular_u4serialneonsdoticelakervv

Parameters

ainThe first vector.
binThe second vector.
ninCounts dimensions, a multiple of the values per byte.
resultoutThe output distance value.
capabilitiesinOne device's capabilities, like nk_cpu_capabilities_enabled reports.
streaminNull on the CPU, or the GPU stream of that device to queue on.

Notes

  • The output distance value is non-negative.
  • The output distance value is zero if and only if the two vectors are identical.

Statuses

nk_euclidean_output_dtypeReturns the output dtype for L2 (Euclidean) distance.
spatial.h:1390 ↗
nk_dtype_t nk_euclidean_output_dtype(nk_dtype_t dtype);
nk_sqeuclidean_output_dtypeReturns the output dtype for L2 squared distance.
spatial.h:1416 ↗
nk_dtype_t nk_sqeuclidean_output_dtype(nk_dtype_t dtype);
nk_angular_output_dtypeReturns the output dtype for angular/cosine distance.
spatial.h:1435 ↗
nk_dtype_t nk_angular_output_dtype(nk_dtype_t dtype);
nk_sqeuclidean_error_boundReturns the error bound of squared Euclidean distances, per nk_accumulation_error_bound of their output.
spatial.h:1462 ↗
nk_f64_t nk_sqeuclidean_error_bound(nk_dtype_t dtype);
nk_euclidean_error_boundReturns the error bound of Euclidean distances, per nk_accumulation_error_bound of their output.
spatial.h:1468 ↗
nk_f64_t nk_euclidean_error_bound(nk_dtype_t dtype);
nk_angular_error_boundReturns the error bound of angular distances, per nk_accumulation_error_bound of their output.
spatial.h:1474 ↗
nk_f64_t nk_angular_error_bound(nk_dtype_t dtype);
nk_spatial_sum_error_boundReturns the error bound each term adds to the sums of a distance: none for F64 inputs, whose sums are compensated, and that of the terms themselves for the rest.
spatial.h:1480 ↗
nk_f64_t nk_spatial_sum_error_bound(nk_dtype_t dtype);
nk_spatial_find_kernelFinds the spatial kernel of kind for dtype, from the best of capabilities.
spatial.h:1496 ↗
nk_status_t nk_spatial_find_kernel(
    nk_kernel_kind_t kind,
    nk_dtype_t dtype,
    nk_capability_t capabilities,
    nk_kernel_punned_t *kernel,
    nk_capability_t *capability);

Parameters

kindinThe verb whose kernel to find.
dtypeinThe input type the kernel reads.
capabilitiesinThe mask to pick the best capability from.
kerneloutThe kernel, or null when none of capabilities has it.
capabilityoutThe capability the kernel belongs to, or zero.

Statuses