# Scalar Types > NumKong for Rust The scalar wrappers are storage-first types. They are not decorative aliases over `f32`. | Type | Layout | Bytes | Range | Inf | NaN | | :----- | :------------ | ----: | -----------: | :-: | :-: | | `f16` | 1+5+10 | 2 | ±65504 | yes | yes | | `bf16` | 1+8+7 | 2 | ±3.4×10³⁸ | yes | yes | | `e4m3` | 1+4+3 | 1 | ±448 | no | yes | | `e5m2` | 1+5+2 | 1 | ±57344 | yes | yes | | `e2m3` | 1+2+3 (6 bit) | 1 | ±7.5 | no | no | | `e3m2` | 1+3+2 (6 bit) | 1 | ±28 | no | no | | `u1x8` | 8 packed bits | 1 | 0–1 per bit | … | … | | `u4x2` | 2×4-bit uint | 1 | 0–15 per nib | … | … | | `i4x2` | 2×4-bit int | 1 | −8–7 per nib | … | … | The trait hierarchy documents intent: - `StorageElement` — raw storable element type. - `NumberLike` — adds numeric conversion and ordering. - `FloatConvertible` — adds unpacking and float-domain conversion. The output type is intentionally wider than the storage type for many operations. For example, `i8::dot` returns `i32`. `f32::dot` returns a wider accumulator type. Moments reductions widen even more aggressively. ### Type Casting The `cast` function performs bulk conversion between contiguous slices. Any pair of types that implement `CastDType` (all `NumberLike` scalars) can be converted. ```rust use numkong::{cast, f16, bf16}; let src: Vec = vec![1.0, 2.0, 3.0]; let mut dst: Vec = vec![f16::from(0.0_f32); 3]; cast(&src, &mut dst).unwrap(); assert!((dst[0].to_f32() - 1.0).abs() < 0.01); ``` `Tensor`, `TensorView`, and `TensorSpan` expose casting via the `CastOps` trait. `cast()` allocates a new tensor; `cast_into()` writes into a pre-allocated `TensorSpan`. Strided and non-contiguous views are supported: the implementation scans strides from the innermost dimension outward to find the longest contiguous tail, then walks the outer dimensions and casts each contiguous block in a single kernel call. ```rust use numkong::{Tensor, f16}; let src = Tensor::::full(&[4, 4], 1.0).unwrap(); let mut dst = Tensor::::zeros(&[4, 4]).unwrap(); src.view().cast_into(&mut dst.span()).unwrap(); ``` `use numkong::bf16;` `use numkong::e2m1x2;` `use numkong::e2m3;` `use numkong::e3m2;` `use numkong::e4m3;` `use numkong::e5m2;` `use numkong::f16;` `use numkong::i4x2;` `use numkong::u1x8;` `use numkong::u4x2;` `use numkong::FloatConvertible;` `use numkong::FloatLike;` `use numkong::NumberLike;` `use numkong::StorageElement;` `use numkong::Ue4m3;` `use numkong::Ue8m0;` `use numkong::Roots;` `use numkong::CastDType;` `use numkong::CastOps;` `use numkong::DenseToScaledOps;` `use numkong::BlockScaledDescriptor;` `use numkong::BlockScaledFormat;` `use numkong::Mxfp4;` `use numkong::Mxfp6E2m3;` `use numkong::Mxfp6E3m2;` `use numkong::Mxfp8E4m3;` `use numkong::Mxfp8E5m2;` `use numkong::Mxint8;` `use numkong::Nvfp4;` `use numkong::types::complex;` `use numkong::*;` ## f16c Half-precision (32-bit) complex number — two [`f16`](#f16) components. ```rust pub type f16c = complex; ``` Kernel outputs are widened to f32c. ## bf16c BFloat16 (32-bit) complex number — two [`bf16`](#bf16) components. ```rust pub type bf16c = complex; ``` Kernel outputs widened to f32c. ## f32c Single-precision (64-bit) complex number — two `f32` components. ```rust pub type f32c = complex; ``` ## f64c Double-precision (128-bit) complex number — two `f64` components. ```rust pub type f64c = complex; ``` ## bf16 BFloat16 (16-bit) floating-point number — truncated IEEE 754 single-precision. ```rust pub struct bf16(pub u16); ``` Layout: sign(1) + exponent(8) + mantissa(7), bias=127. Range: ±3.39×10³⁸, same dynamic range as f32, epsilon at 1.0 ≈ 7.81×10⁻³. 32 514 of 65 280 finite values (49.8%) fall in [−1, +1]. Wider dynamic range than f16 but lower precision, 7 vs 10 mantissa bits. - `0` `u16` Examples: ``` use numkong::bf16; let brain = bf16::from_f32(3.14); let float = brain.to_f32(); ``` Implements: `[ProbabilitySimilarity](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#ProbabilitySimilarity)`, `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[Attention](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Attention)`, `[AttentionRope](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#AttentionRope)`, `[CastDType](#CastDType)`, `[Bilinear](https://www.unum.cloud/docs/numkong/rust/curved-metrics.md#Bilinear)`, `[Mahalanobis](https://www.unum.cloud/docs/numkong/rust/curved-metrics.md#Mahalanobis)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachSwiGlu](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSwiGlu)`, `[EachRmsNorm](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsNorm)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[MaxSim](https://www.unum.cloud/docs/numkong/rust/maxsim.md#MaxSim)`, `[KullbackLeibler](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#KullbackLeibler)`, `[JensenShannon](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#JensenShannon)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[bf16](#bf16)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## attention_packed_gradients Compute the gradients of [`attention_packed`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#attention_packed) with respect to the queries, keys and values over the task window `tasks_begin..tasks_end` of the `(segment, kv_head)` grid, the end clipped to the grid. ```rust pub unsafe fn attention_packed_gradients( head_count: usize, heads: usize, depth: usize, query_offsets: *const u32, query_token_count: usize, scale: f32, keys_before: usize, keys_after: usize, queries: *const Self, query_stride: usize, key_value_packed: *const u8, output: *const f32, output_gradient: *const f32, output_stride: usize, log_sum_exp: *const f32, query_gradient: *mut f32, query_gradient_stride: usize, key_gradient: *mut f32, value_gradient: *mut f32, key_value_gradient_stride: usize, tasks_begin: usize, tasks_end: usize, ) -> Result<(), Error> ``` `output` and `log_sum_exp` are the forward's results. The query gradient holds one row of `head_count * depth` values per query token, spaced `query_gradient_stride` bytes apart. Key and value gradients hold one row of `heads * depth` values per key token at `key_offsets[segment] + token` of the offsets the cache was packed with, spaced `key_value_gradient_stride` bytes apart; rows past a segment's key count are never written, and all others are overwritten. Safety: - the forward's safety contract holds for `queries`, `key_value_packed`, `query_offsets` and `query_token_count` - every gradient buffer must be writable for its extent, and `output` and `output_gradient` share `output_stride` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE Positive one. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## NAN Quiet NaN, i.e. ```rust pub const NAN: Self = _; ``` Not a Number. ## from_f32 Converts an `f32` value to [`bf16`](#bf16). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::bf16; // bf16 matches f32's ±3.39e38 range but with only 7 bits of mantissa. let brain = bf16::from_f32(1.0e30); assert!((brain.to_f32() - 1.0e30).abs() < 1.0e28); ``` ## to_*_f32 Converts this value back to `f32`. ```rust pub fn to__f32(self) -> f32 ``` Examples: ``` use numkong::f16; let half = f16::from_f32(-2.5); assert_eq!(half.to_f32(), -2.5); ``` ## is_*_nan Returns true if this value is NaN. ```rust pub fn is__nan(self) -> bool ``` E2M3FN has no infinities - all special values are NaN. ## is_*_infinite Returns true if this value is positive or negative infinity. ```rust pub fn is__infinite(self) -> bool ``` E2M3FN has no infinities. ## is_*_finite Returns true if this number is neither infinite nor NaN. ```rust pub fn is__finite(self) -> bool ``` Note: E2M3FN format has no infinities or NaN. Note: the E4M3 format has no infinities at all. ## * Returns the absolute value of self. ```rust pub fn abs(self) -> Self ``` ## attention_pack_*_pack_size Returns bytes enough to pack `token_count` keys in `segment_count` segments, however split. ```rust fn attention_pack__pack_size( heads: usize, depth: usize, token_count: usize, segment_count: usize, ) -> Result ``` ## attention_packed_*_packed_shape Reads the KV-cache geometry — heads, depth, segments — from the packed header. # Safety [`packed`](#packed) must point to a buffer produced by [`attention_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#attention_pack). ```rust unsafe fn attention_packed__packed_shape(packed: *const u8) -> Result<(usize, usize, usize), Error> ``` ## attention_*_pack Pack a window of the `(segment, kv_head)` task grid into the KV-cache blob. # Safety - `k` / `v` must point to token matrices with `key_stride` / `value_stride` byte rows covering every token addressed by `key_offsets` + `key_lengths` - `key_offsets` holds `segment_count + 1` non-decreasing slot boundaries, and `key_lengths` is null or holds one count per segment, at most its slot's width - `key_value_packed` must have at least `attention_pack_size(..)` bytes ```rust unsafe fn attention__pack( heads: usize, depth: usize, key_offsets: *const u32, key_lengths: *const u32, segment_count: usize, keys: *const Self, key_stride: usize, values: *const Self, value_stride: usize, key_value_packed: *mut u8, tasks_begin: usize, tasks_end: usize, ) -> Result<(), Error> ``` Windows run in any order: the one starting at task 0 also writes the header and directory, which no window reads. ## attention_*_packed Compute attention over the half-open task window `tasks_begin..tasks_end` of the `(query token, head)` grid, task `token * head_count + head`, the end clipped to the grid. ```rust unsafe fn attention__packed( head_count: usize, heads: usize, depth: usize, query_offsets: *const u32, query_token_count: usize, scale: f32, keys_before: usize, keys_after: usize, queries: *const Self, query_stride: usize, key_value_packed: *const u8, output: *mut f32, output_stride: usize, log_sum_exp: *mut f32, tasks_begin: usize, tasks_end: usize, ) -> Result<(), Error> ``` Each segment's queries align to the end of its keys: row `r` of a segment with `q` queries and `k` keys sits at position `p = r + k - q` and sees key `j` when `p - keys_before <= j <= p + keys_after`. `usize::MAX` leaves a side unbounded, so causal is `(usize::MAX, 0)`, a sliding window of `w` keys is `(w - 1, 0)` and bidirectional is `(usize::MAX, usize::MAX)`. Rows that see no key are written as zeros. Safety: - `key_value_packed` must have been produced by [`attention_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#attention_pack) with matching geometry - `queries` rows addressed by `query_offsets` must be valid, `output` writable with `output_stride` byte rows - `query_token_count` equals `query_offsets[segments]` - `log_sum_exp` is null or writable for one value per query token and head ## attention_rope_*_rope_into Rotates a 2D __[rows,head_count × depth]__ tensor in place using the __[rows,depth/2]__ [`cos`](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#cos)/[`sin`](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#sin) angle grids, shared across heads, for an even [`depth`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#depth) of channels per head. ```rust fn attention_rope__rope_into( x: &mut XMut, cos: &[f32], sin: &[f32], head_count: usize, depth: usize, ) -> Result<(), Error> where XMut: TensorMut + ?Sized, ``` The row stride is read from the tensor, so `x` may be a non-contiguous sub-span, for example the Q or K column-section of a fused QKV buffer. Returns `Err` on a shape mismatch. ## bilinear Computes the bilinear form aᵀ × C × b. ```rust fn bilinear(a: &[Self], b: &[Self], c: &[Self]) -> Result ``` Arguments: - `a` - First vector of length n - `b` - Second vector of length n - `c` - Metric tensor, symmetric __[n,n]__ matrix in row-major order, flattened to length n² Errors: [`Error::InvalidShape`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#InvalidShape) for empty vectors, [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if lengths are incompatible, or [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status. ## mahalanobis Computes the Mahalanobis distance √((a−b)ᵀ × C × (a−b)). ```rust fn mahalanobis(a: &[Self], b: &[Self], c: &[Self]) -> Result ``` Arguments: - `a` - First vector of length n - `b` - Second vector of length n - `c` - Inverse covariance matrix, a symmetric __[n,n]__ matrix in row-major order, flattened to length n² Errors: [`Error::InvalidShape`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#InvalidShape) for empty vectors, [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if lengths are incompatible, or [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status. ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## each_*_scale Writes resultᵢ = α × aᵢ + β into the pre-sized output slice. ```rust fn each__scale(a: &[Self], alpha: f32, beta: f32, result: &mut [Self]) -> Result<(), Error> ``` Both slices, `a` and `result`, must have identical length — the kernel does not allocate. Examples: ``` use numkong::EachScale; let input = [1.0_f32, 2.0, 3.0]; let mut output = [0.0_f32; 3]; // Rescale to [-1, 1]: alpha = 2/(max-min) = 1.0, beta = -1 - 1*min = -2.0 f32::each_scale(&input, 1.0, -2.0, &mut output).unwrap(); assert_eq!(output, [-1.0, 0.0, 1.0]); ``` ## each_scale_*_scale_inplace In-place affine: dataᵢ = α × dataᵢ + β. ```rust fn each_scale__scale_inplace(data: &mut [Self], alpha: f32, beta: f32) -> Result<(), Error> ``` Both source and destination pointers are derived from the single `&mut`, so no aliased `&[Self]` + `&mut [Self]` over the same storage is formed. ## each_*_sum Writes resultᵢ = aᵢ + bᵢ into the pre-sized output slice. ```rust fn each__sum(a: &[Self], b: &[Self], result: &mut [Self]) -> Result<(), Error> ``` ## each_sum_*_sum_inplace In-place sum: dataᵢ = dataᵢ + otherᵢ. ```rust fn each_sum__sum_inplace(data: &mut [Self], other: &[Self]) -> Result<(), Error> ``` `data` is both the `a` operand and the result; its source and destination pointers come from the single `&mut`, while `other` is disjoint storage — no aliased `&[Self]` + `&mut [Self]` over the same buffer is formed. ## each_*_blend Writes resultᵢ = α × aᵢ + β × bᵢ into the pre-sized output slice. ```rust fn each__blend( a: &[Self], b: &[Self], alpha: f32, beta: f32, result: &mut [Self], ) -> Result<(), Error> ``` ## each_blend_*_blend_inplace In-place blend: dataᵢ = α × dataᵢ + β × otherᵢ. ```rust fn each_blend__blend_inplace(data: &mut [Self], other: &[Self], alpha: f32, beta: f32) -> Result<(), Error> ``` `data` is both the `a` operand and the result; its source and destination pointers come from the single `&mut`, while `other` is disjoint storage — no aliased `&[Self]` + `&mut [Self]` over the same buffer is formed. ## each_*_fma Writes resultᵢ = α × aᵢ × bᵢ + β × cᵢ into the pre-sized output slice. ```rust fn each__fma( a: &[Self], b: &[Self], c: &[Self], alpha: f32, beta: f32, result: &mut [Self], ) -> Result<(), Error> ``` ## each_fma_*_fma_inplace In-place fused multiply-add with the `c` operand bound to `a`: dataᵢ = α × dataᵢ × bᵢ + β × dataᵢ. ```rust fn each_fma__fma_inplace(data: &mut [Self], b: &[Self], alpha: f32, beta: f32) -> Result<(), Error> ``` `data` is the `a` operand, the `c` operand, and the result — all derived from the single `&mut`, while `b` is disjoint storage. This matches out-of-place [`mul_tensor`](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#mul_tensor), which wires `c = self` and is the only in-place FMA caller. No aliased `&[Self]` + `&mut [Self]` over the same buffer is formed. ## swiglu_*_into Fused SwiGLU of 2D tensors: y = silu(gate_scale × gate) × up × output_scale. ```rust fn swiglu__into( gate: &GIn, up: Option<&UIn>, y: &mut YOut, gate_scale: f32, output_scale: f32, ) -> Result<(), Error> where GIn: TensorRef + ?Sized, UIn: TensorRef + ?Sized, YOut: TensorMut + ?Sized, ``` Strides are read from the tensors, so `gate`, `up`, and `y` may be independent strided sub-spans, for example the two column halves of a __[rows,2×columns]__ gate|up buffer, while `up = None` reduces to plain SiLU. Returns `Err` on a shape mismatch. ## rmsnorm_*_into Grouped RMSNorm of a 2D __[rows,groups×columns]__ tensor into `y` of the same shape. ```rust fn rmsnorm__into( x: &XIn, gamma: Option<&[f32]>, y: &mut YOut, groups: usize, epsilon: f32, ) -> Result<(), Error> where XIn: TensorRef + ?Sized, YOut: TensorMut + ?Sized, ``` Row strides are read from the tensors, so `x` and `y` may be non-contiguous sub-spans, for example a strided section of a fused activation buffer. `gamma` is an optional per-column gain of length `columns` (`None` = unit scale). Returns `Err` on a shape mismatch. ## rmscast_*_into Grouped RMSNorm of a 2D __[rows,groups×columns]__ tensor of [`Self::Input`](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Input) into `y`, a tensor of `Self` of the same shape, with ε added to the mean square of the raw input. ```rust fn rmscast__into( x: &XIn, gamma: Option<&[f32]>, y: &mut YOut, groups: usize, epsilon: f32, ) -> Result<(), Error> where XIn: TensorRef + ?Sized, YOut: TensorMut + ?Sized, ``` Returns `Err` on a shape mismatch. ## maxsim_pack_*_pack_size Returns the packed buffer size in bytes for [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) vectors of given [`depth`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#depth). ```rust fn maxsim_pack__pack_size(vectors: usize, depth: usize) -> Result ``` ## maxsim_packed_*_packed_shape Reads the packed vector count and depth from the buffer header. # Safety [`packed`](#packed) must point to a buffer produced by [`maxsim_pack`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#maxsim_pack). ```rust unsafe fn maxsim_packed__packed_shape(packed: *const u8) -> Result<(usize, usize), Error> ``` ## maxsim_*_pack Pack vectors into backend-specific quantized format. ```rust unsafe fn maxsim__pack( data: *const Self, vectors: usize, depth: usize, stride: usize, packed: *mut u8, ) -> Result<(), Error> ``` Packing fuses no transposition, so depth-major vectors are transposed in a separate pass first. Safety: - `data` must point to [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) rows of [`depth`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#depth) elements, byte stride `stride` - [`packed`](#packed) must have at least `maxsim_pack_size(vectors, depth)` bytes ## maxsim_*_packed Compute MaxSim score on pre-packed buffers. ```rust unsafe fn maxsim__packed( queries: *const u8, documents: *const u8, query_count: usize, document_count: usize, depth: usize, result: *mut Self::Score, ) -> Result<(), Error> ``` Safety: - Both buffers must have been produced by [`maxsim_pack`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#maxsim_pack) with matching depth - `result` must point to valid, writable memory for [`Self::Score`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#Score) ## kullbackleibler Computes the Kullback-Leibler divergence of `a` from `b`. ```rust fn kullbackleibler(a: &[Self], b: &[Self]) -> Result ``` ## kl Alias for [`kullbackleibler`](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#kullbackleibler). ```rust fn kl(a: &[Self], b: &[Self]) -> Result ``` ## jensenshannon Computes the Jensen-Shannon divergence between `a` and `b`. ```rust fn jensenshannon(a: &[Self], b: &[Self]) -> Result ``` ## js Alias for [`jensenshannon`](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#jensenshannon). ```rust fn js(a: &[Self], b: &[Self]) -> Result ``` ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## dots_pack_*_pack_size Returns the size in bytes needed for the packed B matrix buffer. ```rust fn dots_pack__pack_size(columns: usize, depth: usize) -> Result ``` ## dots_packed_*_packed_shape Reads the packed B matrix's columns and depth from its header. # Safety [`packed`](#packed) must point to a buffer produced by [`dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack). ```rust unsafe fn dots_packed__packed_shape(packed: *const u8) -> Result<(usize, usize), Error> ``` ## dots_*_pack Packs the B matrix into an optimized backend-specific layout. ```rust unsafe fn dots__pack( matrix: *const Self, columns: usize, depth: usize, matrix_stride: usize, packed: *mut u8, columns_begin: usize, columns_end: usize, ) -> Result<(), Error> ``` Packing fuses no transposition, so a transposed B is transposed in a separate pass first. Safety: - `b` must point to valid memory for `columns * depth` elements - [`packed`](#packed) must point to a buffer of at least `dots_pack_size(columns, depth)` bytes ## dots_*_packed Computes C = A × Bᵀ using packed B. ```rust unsafe fn dots__packed( queries: *const Self, packed: *const u8, output: *mut Self::Accumulator, rows: usize, columns: usize, depth: usize, query_stride: usize, output_stride: usize, ) -> Result<(), Error> ``` Safety: - `a` must point to valid memory for `rows * depth` elements with given stride - [`packed`](#packed) must be a buffer filled by [`dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack) - `c` must point to valid memory for [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) × `columns` elements with given stride ## dots_*_symmetric Computes C = A × Aᵀ where C is symmetric. ```rust unsafe fn dots__symmetric( vectors: *const Self, vector_count: usize, depth: usize, stride: usize, result: *mut Self::Accumulator, result_stride: usize, rows_begin: usize, rows_end: usize, ) -> Result<(), Error> ``` Given input matrix A of shape __[n,k]__, computes the symmetric matrix of all pairwise dot products. Only the upper triangle is computed, then mirrored to the lower triangle. Safety: - [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) must point to valid memory for `vector_count × depth` elements with given stride - `result` must point to valid memory for `vector_count×vector_count` elements, given stride - Strides are in bytes, not elements - `rows_begin <= rows_end`; `rows_end` is clamped to `vector_count` ## angulars_*_packed Computes angular distances between A rows and packed B columns. ```rust unsafe fn angulars__packed( queries: *const Self, packed: *const u8, output: *mut Self::SpatialResult, rows: usize, columns: usize, depth: usize, query_stride: usize, output_stride: usize, ) -> Result<(), Error> ``` Safety: - `a` must point to valid memory for `rows * depth` elements with given stride - [`packed`](#packed) must be a buffer filled by [`Dots::dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack) - `c` must point to valid memory for [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) × `columns` result elements with given stride ## angulars_*_symmetric Computes symmetric angular distance matrix. ```rust unsafe fn angulars__symmetric( vectors: *const Self, vector_count: usize, depth: usize, stride: usize, result: *mut Self::SpatialResult, result_stride: usize, rows_begin: usize, rows_end: usize, ) -> Result<(), Error> ``` Safety: - [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) must point to valid memory for `vector_count * depth` elements - `result` must point to valid memory for `vector_count * vector_count` result elements ## euclideans_*_packed Computes euclidean distances between A rows and packed B columns. ```rust unsafe fn euclideans__packed( queries: *const Self, packed: *const u8, output: *mut Self::SpatialResult, rows: usize, columns: usize, depth: usize, query_stride: usize, output_stride: usize, ) -> Result<(), Error> ``` Safety: - `a` must point to valid memory for `rows * depth` elements with given stride - [`packed`](#packed) must be a buffer filled by [`Dots::dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack) - `c` must point to valid memory for [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) × `columns` result elements with given stride ## euclideans_*_symmetric Computes symmetric euclidean distance matrix. ```rust unsafe fn euclideans__symmetric( vectors: *const Self, vector_count: usize, depth: usize, stride: usize, result: *mut Self::SpatialResult, result_stride: usize, rows_begin: usize, rows_end: usize, ) -> Result<(), Error> ``` Safety: - [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) must point to valid memory for `vector_count * depth` elements - `result` must point to valid memory for `vector_count * vector_count` result elements ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## dimensions_per_*_per_value Number of logical dimensions packed into one storage value. ```rust fn dimensions_per__per_value() -> usize ``` Default: 1 for all normal types. Override for sub-byte packed types. ## dimensions_to_*_to_values Storage values needed to hold [`dims`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#dims) logical dimensions. ```rust fn dimensions_to__to_values(dims: usize) -> usize ``` [`dims`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#dims) counts dimensions, a multiple of the values per byte, so the division is exact, and every bounds check that guards a storage offset must be written in these units, the conversion between the two counts a packed container tracks — a check counting dimensions paired with an offset counting storage values is how an index eight times too large passes as in-range. ## locate_*_dim Split a logical dimension index into the storage value holding it and its position inside. ```rust fn locate__dim(dim_index: usize) -> DimLocation ``` The counterpart to [`dimensions_to_values`](#dimensions_to_values), for the callers that must reach an individual dimension rather than count them. Pair it with [`FloatConvertible::unpack`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#unpack) to read the dimension out, or with [`DimMut`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#DimMut) to write one back. ## has_*_infinity Whether the type can represent infinity. ```rust fn has__infinity() -> bool ``` ## has_*_nan Whether the type can represent NaN. ```rust fn has__nan() -> bool ``` ## has_*_subnormals Whether the type can represent subnormal values. ```rust fn has__subnormals() -> bool ``` ## max_*_value Largest finite value of the type, as f32. ```rust fn max__value() -> f32 ``` ## min_*_positive Smallest positive normal value of the type, as f32. ```rust fn min__positive() -> f32 ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## to_*_f64 Convert from this type to f64 — by default via an f32 roundtrip. ```rust fn to__f64(self) -> f64 ``` ## * Unpack all logical sub-dimensions from this packed value. ```rust fn unpack(self) -> [bf16; 1] ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [bf16; 1]) -> Self ``` ## e2m1x2 Packed FP4, E2M1, element pair: two 4-bit elements share one byte. ```rust pub struct e2m1x2(pub u8); ``` This is the storage scalar for the [`elements`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#elements) tensor of NVFP4 / MXFP4. Like the other sub-byte packers ([`u4x2`](#u4x2)), it reports `dimensions_per_value() == 2` so a tensor of logical shape __[rows,columns]__ allocates `rows * columns / 2` bytes, as `nk_block_scaled_elements_size`. Bytes are produced and consumed by the C kernel (`element_dtype = nk_e2m1_k`); Rust never unpacks the nibbles itself. - `0` `u8` Implements: `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `[StorageElement](#StorageElement)` ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## e2m3 6-bit E2M3 micro-float, padded to 8-bit storage. ```rust pub struct e2m3(pub u8); ``` Layout: sign(1) + exponent(2) + mantissa(3), bias=1. Range: ±7.5, no infinities. Only 64 total codes; 18 (28.1%) fall in [−1, +1]. 72% of codes lie outside [−1, +1] — poor resolution for normalized vectors. Exact integer dot products via exponent-sum binning across 15 bins. - `0` `u8` Examples: ``` use numkong::e2m3; let fp6 = e2m3::from_f32(2.5); let float = fp6.to_f32(); ``` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[CastDType](#CastDType)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[e2m3](#e2m3)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE Positive one. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## from_f32 Convert an `f32` value to [`e2m3`](#e2m3). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::e2m3; // e2m3 covers ±7.5 with 3 mantissa bits — suitable for fine ratios // in a narrow dynamic range. let tiny = e2m3::from_f32(1.5); assert_eq!(tiny.to_f32(), 1.5); ``` ## to_*_f32 Convert from this type to f32. ```rust pub fn to__f32(self) -> f32 ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [e2m3; 1]) -> Self ``` ## e3m2 6-bit E3M2 micro-float, padded to 8-bit storage. ```rust pub struct e3m2(pub u8); ``` Layout: sign(1) + exponent(3) + mantissa(2), bias=3. Range: ±28, supports infinities. Only 64 total codes; 26 (40.6%) fall in [−1, +1]. Exact integer dot products via exponent-sum binning across 15 bins. - `0` `u8` Examples: ``` use numkong::e3m2; let fp6 = e3m2::from_f32(2.5); let float = fp6.to_f32(); ``` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[CastDType](#CastDType)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[e3m2](#e3m2)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE Positive one. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## from_f32 Convert an `f32` value to [`e3m2`](#e3m2). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::e3m2; // e3m2 trades mantissa bits for a larger range (±28). let tiny = e3m2::from_f32(16.0); assert_eq!(tiny.to_f32(), 16.0); ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [e3m2; 1]) -> Self ``` ## e4m3 8-bit E4M3 floating-point number, OCP FP8. ```rust pub struct e4m3(pub u8); ``` Layout: sign(1) + exponent(4) + mantissa(3), bias=7. Range: ±448, no infinities, all-ones exponent means NaN. 114 of 254 finite values (44.9%) fall in [−1, +1]. Exact integer dot products via exponent-sum binning across 29 bins. - `0` `u8` Examples: ``` use numkong::e4m3; let fp8 = e4m3::from_f32(2.5); let float = fp8.to_f32(); ``` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[Attention](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Attention)`, `[AttentionRope](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#AttentionRope)`, `[CastDType](#CastDType)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachSwiGlu](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSwiGlu)`, `[EachRmsNorm](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsNorm)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[e4m3](#e4m3)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE One. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## NAN Quiet NaN, i.e. ```rust pub const NAN: Self = _; ``` Not a Number. ## from_f32 Converts an `f32` value to [`e4m3`](#e4m3). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::e4m3; // e4m3 quantises to ~4 effective decimal digits inside ±448. let fp8 = e4m3::from_f32(3.5); assert_eq!(fp8.to_f32(), 3.5); ``` ## is_*_infinite Returns true if this value is ±∞. ```rust pub fn is__infinite(self) -> bool ``` Always false for E4M3 — no infinities. ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [e4m3; 1]) -> Self ``` ## e5m2 8-bit E5M2 floating-point number, OCP FP8. ```rust pub struct e5m2(pub u8); ``` Layout: sign(1) + exponent(5) + mantissa(2), bias=15. Range: ±57 344, supports infinities. Only 4 mantissa levels per exponent. 122 of 248 finite values (49.2%) fall in [−1, +1]. High cancellation risk in dot products — consider compensated accumulation. - `0` `u8` Examples: ``` use numkong::e5m2; let fp8 = e5m2::from_f32(2.5); let float = fp8.to_f32(); ``` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[CastDType](#CastDType)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[e5m2](#e5m2)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE Positive one. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## NAN Quiet NaN, i.e. ```rust pub const NAN: Self = _; ``` Not a Number. ## from_f32 Convert an `f32` value to [`e5m2`](#e5m2). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::e5m2; // e5m2 trades mantissa precision for wider range (up to ~57 344). let fp8 = e5m2::from_f32(1024.0); assert_eq!(fp8.to_f32(), 1024.0); ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [e5m2; 1]) -> Self ``` ## f16 Half-precision (16-bit) IEEE 754 floating-point number. ```rust pub struct f16(pub u16); ``` Layout: sign(1) + exponent(5) + mantissa(10), bias=15. Range: ±65504, epsilon at 1.0 ≈ 9.77×10⁻⁴, subnormal min ≈ 5.96×10⁻⁸. 30 722 of 63 488 finite values (48.4%) fall in [−1, +1]. All arithmetic via f32 upcast/downcast. - `0` `u16` Examples: ``` use numkong::f16; // Create from f32 let half = f16::from_f32(3.14); // Convert back to f32 let float = half.to_f32(); // Direct access to bits let bits = half.0; ``` Implements: `[ProbabilitySimilarity](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#ProbabilitySimilarity)`, `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[Trigonometry](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Trigonometry)`, `[FloatLike](#FloatLike)`, `[Attention](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Attention)`, `[CastDType](#CastDType)`, `[Bilinear](https://www.unum.cloud/docs/numkong/rust/curved-metrics.md#Bilinear)`, `[Mahalanobis](https://www.unum.cloud/docs/numkong/rust/curved-metrics.md#Mahalanobis)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[EachScale](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachScale)`, `[EachSum](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachSum)`, `[EachBlend](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachBlend)`, `[EachFma](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachFma)`, `[EachRmsCast](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#EachRmsCast)`, `[MaxSim](https://www.unum.cloud/docs/numkong/rust/maxsim.md#MaxSim)`, `[KullbackLeibler](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#KullbackLeibler)`, `[JensenShannon](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#JensenShannon)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Roots](#Roots)`, `[Shapes](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#Shapes)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[TrigSin](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#TrigSin)`, `[TrigCos](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#TrigCos)`, `[TrigAtan](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#TrigAtan)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `PartialOrd`, `From`, `From<[f16](#f16)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## ZERO Positive zero. ```rust pub const ZERO: Self = _; ``` ## ONE Positive one. ```rust pub const ONE: Self = _; ``` ## NEG_ONE Negative one. ```rust pub const NEG_ONE: Self = _; ``` ## NAN Quiet NaN, i.e. ```rust pub const NAN: Self = _; ``` Not a Number. ## from_f32 Converts an `f32` value to [`f16`](#f16). ```rust pub fn from_f32(value: f32) -> Self ``` ```rust fn from_f32(v: f32) -> Self ``` Convert from f32 to this type. Out-of-range values saturate. Examples: ``` use numkong::f16; // Roundtrip a value well inside f16's ±65504 range. let half = f16::from_f32(3.14); assert!((half.to_f32() - 3.14).abs() < 1e-2); ``` ## abs Returns |self|. ```rust pub fn abs(self) -> Self ``` ## bilinear Computes the bilinear form aᵀ × C × b. ```rust fn bilinear(a: &[Self], b: &[Self], c: &[Self]) -> Result ``` Arguments: - `a` - First vector of length n - `b` - Second vector of length n - `c` - Metric tensor, symmetric __[n,n]__ matrix in row-major order, flattened to length n² Errors: [`Error::InvalidShape`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#InvalidShape) for empty vectors, [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if lengths are incompatible, or [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status. ## mahalanobis Computes the Mahalanobis distance √((a−b)ᵀ × C × (a−b)). ```rust fn mahalanobis(a: &[Self], b: &[Self], c: &[Self]) -> Result ``` Arguments: - `a` - First vector of length n - `b` - Second vector of length n - `c` - Inverse covariance matrix, a symmetric __[n,n]__ matrix in row-major order, flattened to length n² Errors: [`Error::InvalidShape`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#InvalidShape) for empty vectors, [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if lengths are incompatible, or [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status. ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## kullbackleibler Computes the Kullback-Leibler divergence of `a` from `b`. ```rust fn kullbackleibler(a: &[Self], b: &[Self]) -> Result ``` ## kl Alias for [`kullbackleibler`](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#kullbackleibler). ```rust fn kl(a: &[Self], b: &[Self]) -> Result ``` ## jensenshannon Computes the Jensen-Shannon divergence between `a` and `b`. ```rust fn jensenshannon(a: &[Self], b: &[Self]) -> Result ``` ## js Alias for [`jensenshannon`](https://www.unum.cloud/docs/numkong/rust/probability-metrics.md#jensenshannon). ```rust fn js(a: &[Self], b: &[Self]) -> Result ``` ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## * Non-negative square root of `self`, routed through NumKong's runtime-dispatched kernel. ```rust fn sqrt(self) -> Self ``` ## * Reciprocal square root 1 / √x of `self` as a single primitive op where the hardware allows. ```rust fn rsqrt(self) -> Self ``` ## shapes_pack_size Returns the bytes a pack of [`points`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#points) points takes. ```rust fn shapes_pack_size(points: usize) -> Result ``` ## shapes_pack Packs one cloud: centers it and rotates it onto its principal axes. ```rust unsafe fn shapes_pack(points: &[[Self; 3]], packed: *mut u8) -> Result<(), Error> ``` Safety: [`packed`](#packed) must have `shapes_pack_size(points.len())` writable bytes on an `nk_default_alignment_k` boundary. ## shapes_pack_normalized Packs one cloud like [`Shapes::shapes_pack`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#shapes_pack), also dividing it by its RMS distance from the centroid, which the pack keeps as its scale, or by 1 when the cloud has no spread. ```rust unsafe fn shapes_pack_normalized(points: &[[Self; 3]], packed: *mut u8) -> Result<(), Error> ``` Safety: The contract of [`Shapes::shapes_pack`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#shapes_pack). ## shapes_packed_shape Reads the pose and bounds of a pack into every non-null output: its number of points, its mean input point, the unit quaternion (x, y, z, w) rotating the centered cloud onto its principal axes, what the rotated cloud was divided by, the descending eigenvalues of the packed points' second moments, and the largest packed point norm. ```rust unsafe fn shapes_packed_shape( packed: *const u8, points: *mut usize, centroid: *mut f32, frame: *mut f32, scale: *mut f32, spreads: *mut f32, max_radius: *mut f32, ) -> Result<(), Error> ``` Safety: [`packed`](#packed) must point to a pack of `Self`, and the non-null outputs must hold 1, 3, 4, 1, 3 and 1 writable values in that order. ## shapes_unpack Writes the cloud of a pack back interleaved, in its original pose and scale, within one rounding to `Self`. ```rust unsafe fn shapes_unpack(packed: *const u8, points: *mut [Self; 3]) -> Result<(), Error> ``` Safety: [`packed`](#packed) must point to a pack of `Self`, and [`points`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#points) must hold as many writable points as it packed. ## rmsds_packed Superposed RMSDs between every row cloud and every column cloud of equally many points. ```rust unsafe fn rmsds_packed( a_packed: *const *const u8, rows: usize, b_packed: *const *const u8, columns: usize, results: *mut f32, results_stride: usize, capabilities: Capabilities, stream: *mut c_void, ) -> Result<(), Error> ``` Safety: - `a_packed` and `b_packed` must hold [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) and `columns` pointers to packs of `Self` - `results` must hold [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) rows of `columns` distances, `results_stride` bytes apart - [`stream`](https://www.unum.cloud/docs/numkong/rust/runtime-dispatch.md#stream) must be null or a live stream of the group [`capabilities`](https://www.unum.cloud/docs/numkong/rust/external-memory.md#capabilities) name, null on the CPU, and on a GPU everything above must stay alive and untouched until that stream joins ## hausdorffs_packed Hausdorff distances between every row cloud and every column cloud. ```rust unsafe fn hausdorffs_packed( a_packed: *const *const u8, rows: usize, b_packed: *const *const u8, columns: usize, results: *mut f32, results_stride: usize, rotations: *mut f32, limit: f32, capabilities: Capabilities, stream: *mut c_void, ) -> Result<(), Error> ``` Safety: The contract of [`Shapes::rmsds_packed`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#rmsds_packed), plus `rotations` must be null or hold `rows × columns × 9` writable values. ## chamfers_workspace_size Returns the workspace bytes Chamfer needs between clouds of up to `row_points` and `column_points` points. ```rust fn chamfers_workspace_size( row_points: usize, column_points: usize, capabilities: Capabilities, ) -> Result ``` ## chamfers_packed Chamfer distances between every row cloud and every column cloud. ```rust unsafe fn chamfers_packed( a_packed: *const *const u8, rows: usize, b_packed: *const *const u8, columns: usize, results: *mut f32, results_stride: usize, rotations: *mut f32, limit: f32, workspace: *mut u8, workspace_bytes: usize, capabilities: Capabilities, stream: *mut c_void, ) -> Result<(), Error> ``` Safety: The contract of [`Shapes::hausdorffs_packed`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#hausdorffs_packed), plus `workspace` must have `workspace_bytes` writable bytes, on the default alignment, as [`Shapes::chamfers_workspace_size`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#chamfers_workspace_size) reports for the largest clouds. ## wassersteinprocrustes_workspace_size Returns the workspace bytes Wasserstein-Procrustes needs between clouds of up to `row_points` and `column_points` points. ```rust fn wassersteinprocrustes_workspace_size( row_points: usize, column_points: usize, capabilities: Capabilities, ) -> Result ``` ## wassersteinprocrustes_packed Wasserstein-Procrustes distances between every row cloud and every column cloud. ```rust unsafe fn wassersteinprocrustes_packed( a_packed: *const *const u8, rows: usize, b_packed: *const *const u8, columns: usize, results: *mut f32, results_stride: usize, rotations: *mut f32, workspace: *mut u8, workspace_bytes: usize, capabilities: Capabilities, stream: *mut c_void, ) -> Result<(), Error> ``` Safety: The contract of [`Shapes::chamfers_packed`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#chamfers_packed), plus `workspace` must have `workspace_bytes` writable bytes on an `nk_default_alignment_k` boundary. ## gromovwassersteins_workspace_size Returns the workspace bytes Gromov-Wasserstein needs between clouds of up to `row_points` and `column_points` points. ```rust fn gromovwassersteins_workspace_size( row_points: usize, column_points: usize, capabilities: Capabilities, ) -> Result ``` ## gromovwassersteins_packed Gromov-Wasserstein distances between every row cloud and every column cloud. ```rust unsafe fn gromovwassersteins_packed( a_packed: *const *const u8, rows: usize, b_packed: *const *const u8, columns: usize, results: *mut f32, results_stride: usize, rotations: *mut f32, workspace: *mut u8, workspace_bytes: usize, capabilities: Capabilities, stream: *mut c_void, ) -> Result<(), Error> ``` Safety: The contract of [`Shapes::wassersteinprocrustes_packed`](https://www.unum.cloud/docs/numkong/rust/mesh-alignment.md#wassersteinprocrustes_packed). ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## sin Writes the sine of every input element, in radians, into the output slice. ```rust fn sin(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error> ``` ## sin_inplace In-place sine: `data[i] = sin(data[i])`. ```rust fn sin_inplace(data: &mut [Self]) -> Result<(), Error> ``` Both source and destination pointers are derived from the single `&mut`, so no aliased `&[Self]` + `&mut [Self]` over the same storage is formed. ## cos Writes the cosine of every input element, in radians, into the output slice. ```rust fn cos(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error> ``` ## cos_inplace In-place cosine: `data[i] = cos(data[i])`. ```rust fn cos_inplace(data: &mut [Self]) -> Result<(), Error> ``` Both source and destination pointers are derived from the single `&mut`, so no aliased `&[Self]` + `&mut [Self]` over the same storage is formed. ## atan Writes the arctangent of every input element, in radians, into the output slice. ```rust fn atan(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error> ``` ## atan_inplace In-place arctangent: `data[i] = atan(data[i])`. ```rust fn atan_inplace(data: &mut [Self]) -> Result<(), Error> ``` Both source and destination pointers are derived from the single `&mut`, so no aliased `&[Self]` + `&mut [Self]` over the same storage is formed. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [f16; 1]) -> Self ``` ## i4x2 Packed 4-bit signed integer pair (2 × i4 in one byte). ```rust pub struct i4x2(pub u8); ``` Layout: high nibble = first element, low nibble = second element, two's complement. Range per element: [−8, +7]. Elements sign-extended to i8 for arithmetic. - `0` `u8` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `From<(i8, i8)>`, `From<[i4x2](#i4x2)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## new Create from raw packed byte. ```rust pub const fn new(packed: u8) -> Self ``` ## * Get the raw packed byte. ```rust pub const fn packed(self) -> u8 ``` ## from_i8s Construct from two i8 values with saturation to -8..7, `first` in the high nibble. ```rust pub const fn from_i8s(first: i8, second: i8) -> Self ``` ## to_i8s Extract to two i8 values, sign-extended from 4 bits, the high nibble first. ```rust pub const fn to_i8s(self) -> (i8, i8) ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f32 Convert from f32 to this type. ```rust fn from_f32(v: f32) -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## * Absolute value. ```rust fn abs(self) -> Self ``` ## is_*_nan Whether the value is NaN. ```rust fn is__nan(self) -> bool ``` ## is_*_finite Whether the value is neither infinite nor NaN. ```rust fn is__finite(self) -> bool ``` ## is_*_infinite Whether the value is infinite. ```rust fn is__infinite(self) -> bool ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [i8; 2]) -> Self ``` ## u1x8 Packed 8-bit bit-vector — 8 booleans in one byte. ```rust pub struct u1x8(pub u8); ``` Layout: 8 bits packed into one byte, MSB = dimension 0. Used for Hamming distance and Jaccard similarity via popcount. - `0` `u8` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[BinarySimilarity](https://www.unum.cloud/docs/numkong/rust/set-similarity.md#BinarySimilarity)`, `[FloatLike](#FloatLike)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Hamming](https://www.unum.cloud/docs/numkong/rust/set-similarity.md#Hamming)`, `[Jaccard](https://www.unum.cloud/docs/numkong/rust/set-similarity.md#Jaccard)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Hammings](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Hammings)`, `[Jaccards](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Jaccards)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `From<(bool, bool, bool, bool, bool, bool, bool, bool)>`, `From<[u1x8](#u1x8)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## new Create from raw packed bits. ```rust pub const fn new(bits: u8) -> Self ``` ## bits Get the raw packed bits. ```rust pub const fn bits(self) -> u8 ``` ## from_bools Construct from 8 booleans (b0 = MSB, b7 = LSB). ```rust pub const fn from_bools( b0: bool, b1: bool, b2: bool, b3: bool, b4: bool, b5: bool, b6: bool, b7: bool, ) -> Self ``` ## to_bools Extract to 8 booleans (b0 = MSB, b7 = LSB). ```rust pub const fn to_bools(self) -> (bool, bool, bool, bool, bool, bool, bool, bool) ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## hamming Computes the Hamming distance between two equally long slices. ```rust fn hamming(a: &[Self], b: &[Self]) -> Result ``` ## jaccard Computes the Jaccard distance between two equally long slices. ```rust fn jaccard(a: &[Self], b: &[Self]) -> Result ``` ## hammings_packed Computes Hamming distances between values matrix rows and packed query rows. ```rust unsafe fn hammings_packed( queries: *const Self, packed: *const u8, result: *mut u32, rows: usize, columns: usize, depth: usize, v_stride: usize, r_stride: usize, ) -> Result<(), Error> ``` Safety: - `a` must point to valid memory for the values matrix - [`packed`](#packed) must be a buffer filled by [`Dots::dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack) - `result` must point to valid memory for [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) × `columns` u32 elements ## hammings_symmetric Computes symmetric Gram matrix of Hamming distances: C = A × Aᵀ. ```rust unsafe fn hammings_symmetric( vectors: *const Self, vector_count: usize, depth: usize, stride: usize, result: *mut u32, result_stride: usize, rows_begin: usize, rows_end: usize, ) -> Result<(), Error> ``` Safety: - [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) must point to valid memory for the input matrix - `result` must point to valid memory for `vector_count * vector_count` u32 elements ## jaccards_packed Computes Jaccard distances between values matrix rows and packed query rows. ```rust unsafe fn jaccards_packed( queries: *const Self, packed: *const u8, result: *mut Self::JaccardResult, rows: usize, columns: usize, depth: usize, v_stride: usize, r_stride: usize, ) -> Result<(), Error> ``` Safety: - `a` must point to valid memory for the values matrix - [`packed`](#packed) must be a buffer filled by [`Dots::dots_pack`](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#dots_pack) - `result` must point to valid memory for [`rows`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#rows) × `columns` elements ## jaccards_symmetric Computes symmetric Gram matrix of Jaccard distances. ```rust unsafe fn jaccards_symmetric( vectors: *const Self, vector_count: usize, depth: usize, stride: usize, result: *mut Self::JaccardResult, result_stride: usize, rows_begin: usize, rows_end: usize, ) -> Result<(), Error> ``` Safety: - [`vectors`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#vectors) must point to valid memory for the input matrix - `result` must point to valid memory for `vector_count * vector_count` elements ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f32 Convert from f32 to this type. ```rust fn from_f32(v: f32) -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [u8; 8]) -> Self ``` ## u4x2 Packed 4-bit unsigned integer pair (2 × u4 in one byte). ```rust pub struct u4x2(pub u8); ``` Layout: high nibble = first element, low nibble = second element. Range per element: [0, 15]. Elements zero-extended to u8 for arithmetic. - `0` `u8` Implements: `[Reductions](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Reductions)`, `[SpatialSimilarity](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#SpatialSimilarity)`, `[FloatLike](#FloatLike)`, `[Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot)`, `[VDot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#VDot)`, `[ReduceMoments](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMoments)`, `[ReduceMinMax](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#ReduceMinMax)`, `[Angular](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Angular)`, `[Euclidean](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#Euclidean)`, `[Dots](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Dots)`, `[Angulars](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Angulars)`, `[Euclideans](https://www.unum.cloud/docs/numkong/rust/matrix-kernels.md#Euclideans)`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `Display`, `LowerHex`, `UpperHex`, `Binary`, `From<(u8, u8)>`, `From<[u4x2](#u4x2)>`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## new Create from raw packed byte. ```rust pub const fn new(packed: u8) -> Self ``` ## from_u8s Construct from two u8 values with saturation to 0..15, `first` in the high nibble. ```rust pub const fn from_u8s(first: u8, second: u8) -> Self ``` ## to_u8s Extract to two u8 values (0..15 each), the high nibble first. ```rust pub const fn to_u8s(self) -> (u8, u8) ``` ## dot Computes the dot product of two equally long slices. ```rust fn dot(first: &[Self], second: &[Self]) -> Result ``` ## inner Alias for [`dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot). ```rust fn inner(first: &[Self], second: &[Self]) -> Result ``` ## vdot Hermitian inner product. ```rust fn vdot(first: &[Self], second: &[Self]) -> Result ``` On real-valued types this falls back to [`Dot::dot`](https://www.unum.cloud/docs/numkong/rust/dot-products.md#dot); on complex types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by [`Dot::Output`](https://www.unum.cloud/docs/numkong/rust/sparse-operations.md#Output). ## reduce_moments Compute `(sum, sum_of_squares)` for `data` with the given stride in bytes. ```rust fn reduce_moments( data: &[Self], stride: usize, ) -> Result<(Self::SumOutput, Self::SumSqOutput), Error> ``` Use `stride = size_of::()` for contiguous data. Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## reduce_minmax Returns `Ok(Some(MinMaxResult))` for the given data with the specified stride, or `Ok(None)` if all elements are NaN. ```rust fn reduce_minmax(data: &[Self], stride: usize) -> Result>, Error> ``` Reads `data.len()` logical elements starting at `data.as_ptr()`, advancing by `stride` between each — pass `size_of::()` for contiguous storage. ## angular Computes the angular distance between two equally long slices. ```rust fn angular(a: &[Self], b: &[Self]) -> Result ``` ## cosine Alias for [`angular`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#angular). ```rust fn cosine(a: &[Self], b: &[Self]) -> Result ``` ## sqeuclidean Squared Euclidean distance, i.e. ```rust fn sqeuclidean(a: &[Self], b: &[Self]) -> Result ``` L2². Faster than [`euclidean`](https://www.unum.cloud/docs/numkong/rust/dense-distances.md#euclidean) for comparisons. ## euclidean Euclidean distance, i.e. ```rust fn euclidean(a: &[Self], b: &[Self]) -> Result ``` L2. True metric distance. ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f32 Convert from f32 to this type. ```rust fn from_f32(v: f32) -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [u8; 2]) -> Self ``` ## FloatConvertible Trait for types that can unpack/pack logical sub-dimensions. ```rust pub trait FloatConvertible: NumberLike ``` For normal scalar types (`dimensions_per_value() == 1`), `DimScalar = Self` and `Unpacked = [Self; 1]`. For packed sub-byte types, [`DimScalar`](#DimScalar) is the natural scalar type for individual sub-dimensions, such as `i8` for [`i4x2`](#i4x2). Implementors: - `impl [FloatConvertible](#FloatConvertible) for [complex](#complex)` - `impl [FloatConvertible](#FloatConvertible) for f32` - `impl [FloatConvertible](#FloatConvertible) for f64` - `impl [FloatConvertible](#FloatConvertible) for [f16](#f16)` - `impl [FloatConvertible](#FloatConvertible) for [bf16](#bf16)` - `impl [FloatConvertible](#FloatConvertible) for [e4m3](#e4m3)` - `impl [FloatConvertible](#FloatConvertible) for [e5m2](#e5m2)` - `impl [FloatConvertible](#FloatConvertible) for [e2m3](#e2m3)` - `impl [FloatConvertible](#FloatConvertible) for [e3m2](#e3m2)` - `impl [FloatConvertible](#FloatConvertible) for i8` - `impl [FloatConvertible](#FloatConvertible) for u8` - `impl [FloatConvertible](#FloatConvertible) for i16` - `impl [FloatConvertible](#FloatConvertible) for u16` - `impl [FloatConvertible](#FloatConvertible) for i32` - `impl [FloatConvertible](#FloatConvertible) for u32` - `impl [FloatConvertible](#FloatConvertible) for i64` - `impl [FloatConvertible](#FloatConvertible) for u64` - `impl [FloatConvertible](#FloatConvertible) for [i4x2](#i4x2)` - `impl [FloatConvertible](#FloatConvertible) for [u4x2](#u4x2)` - `impl [FloatConvertible](#FloatConvertible) for [u1x8](#u1x8)` ## DimScalar Scalar type for individual sub-dimensions. ```rust type DimScalar: Copy + Default + NumberLike; ``` ## Unpacked Fixed-size array holding all unpacked sub-dimensions. ```rust type Unpacked: AsRef<[Self::DimScalar]> + AsMut<[Self::DimScalar]> + Copy + Default; ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: Self::Unpacked) -> Self ``` ## FloatLike Backward-compatible alias: any type implementing [`NumberLike`](#NumberLike) also implements [`FloatLike`](#FloatLike). ```rust pub trait FloatLike: NumberLike ``` Implementors: - `impl [FloatLike](#FloatLike) for Scalar` ## NumberLike Trait for types that support conversion to/from f32 with classification and constants. ```rust pub trait NumberLike: StorageElement ``` Provides a unified interface for all numeric types used in NumKong, including half-precision floats, mini-floats, integers, and packed types. Implementors: - `impl [NumberLike](#NumberLike) for f32` - `impl [NumberLike](#NumberLike) for f64` - `impl [NumberLike](#NumberLike) for [f16](#f16)` - `impl [NumberLike](#NumberLike) for [bf16](#bf16)` - `impl [NumberLike](#NumberLike) for [e4m3](#e4m3)` - `impl [NumberLike](#NumberLike) for [e5m2](#e5m2)` - `impl [NumberLike](#NumberLike) for [e2m3](#e2m3)` - `impl [NumberLike](#NumberLike) for [e3m2](#e3m2)` - `impl [NumberLike](#NumberLike) for i8` - `impl [NumberLike](#NumberLike) for u8` - `impl [NumberLike](#NumberLike) for i32` - `impl [NumberLike](#NumberLike) for u32` - `impl [NumberLike](#NumberLike) for i16` - `impl [NumberLike](#NumberLike) for u16` - `impl [NumberLike](#NumberLike) for i64` - `impl [NumberLike](#NumberLike) for u64` - `impl [NumberLike](#NumberLike) for [i4x2](#i4x2)` - `impl [NumberLike](#NumberLike) for [u4x2](#u4x2)` - `impl [NumberLike](#NumberLike) for [u1x8](#u1x8)` - `impl [NumberLike](#NumberLike) for [complex](#complex)` ## from_f32 Convert from f32 to this type. ```rust fn from_f32(v: f32) -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## StorageElement Minimal trait for types that can be stored in vectors and tensors. ```rust pub trait StorageElement: Sized + Copy + Clone + Default + Debug ``` Provides identity elements ([`zero`](#zero), [`one`](#one)) and sub-byte packing metadata. Does not require numeric conversion — use [`NumberLike`](#NumberLike) for that. Implementors: - `impl [StorageElement](#StorageElement) for [Ue4m3](#Ue4m3)` - `impl [StorageElement](#StorageElement) for [Ue8m0](#Ue8m0)` - `impl [StorageElement](#StorageElement) for f32` - `impl [StorageElement](#StorageElement) for f64` - `impl [StorageElement](#StorageElement) for [f16](#f16)` - `impl [StorageElement](#StorageElement) for [bf16](#bf16)` - `impl [StorageElement](#StorageElement) for [e4m3](#e4m3)` - `impl [StorageElement](#StorageElement) for [e5m2](#e5m2)` - `impl [StorageElement](#StorageElement) for [e2m3](#e2m3)` - `impl [StorageElement](#StorageElement) for [e3m2](#e3m2)` - `impl [StorageElement](#StorageElement) for i8` - `impl [StorageElement](#StorageElement) for u8` - `impl [StorageElement](#StorageElement) for i32` - `impl [StorageElement](#StorageElement) for u32` - `impl [StorageElement](#StorageElement) for i16` - `impl [StorageElement](#StorageElement) for u16` - `impl [StorageElement](#StorageElement) for i64` - `impl [StorageElement](#StorageElement) for u64` - `impl [StorageElement](#StorageElement) for usize` - `impl [StorageElement](#StorageElement) for [i4x2](#i4x2)` - `impl [StorageElement](#StorageElement) for [u4x2](#u4x2)` - `impl [StorageElement](#StorageElement) for [e2m1x2](#e2m1x2)` - `impl [StorageElement](#StorageElement) for [u1x8](#u1x8)` - `impl [StorageElement](#StorageElement) for [complex](#complex)` ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## Ue4m3 NVFP4 per-block scale byte: an unsigned E4M3 magnitude with the sign bit forced to 0. ```rust pub struct Ue4m3(pub u8); ``` Stores one scale per 16-element NVFP4 block. Layout matches `nk_ue4m3_t` (1 byte). Decodes to a positive `f32` multiplier; [`from_f32`](#from_f32) takes the absolute value. - `0` `u8` Examples: ``` use numkong::Ue4m3; let scale = Ue4m3::from_f32(2.0); assert_eq!(scale.to_f32(), 2.0); ``` Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `[StorageElement](#StorageElement)` ## ZERO The all-zero byte — decodes to 0.0. ```rust pub const ZERO: Self = _; ``` ## from_f32 Encodes an `f32` magnitude into a UE4M3 scale byte — absolute value, round-to-nearest. ```rust pub fn from_f32(value: f32) -> Self ``` UE4M3 is E4M3 with the sign bit forced to 0, so this reuses the linkable E4M3 encoder on `|value|` and masks off the sign. NaN maps to the E4M3 NaN code (`0x7F`). ## to_f32 Decodes this UE4M3 scale byte to a non-negative `f32` multiplier. ```rust pub fn to_f32(self) -> f32 ``` ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## Ue8m0 MX-family per-block scale byte: an unsigned power-of-two exponent, UE8M0. ```rust pub struct Ue8m0(pub u8); ``` Stores one scale per 32-element MX block, a 1-byte layout matching `nk_ue8m0_t`. Decodes to a positive power-of-two `f32` multiplier; [`from_f32`](#from_f32) rounds the magnitude UP to the smallest power of two that is ≥ `|value|`. - `0` `u8` Examples: ``` use numkong::Ue8m0; let scale = Ue8m0::from_f32(4.0); assert_eq!(scale.to_f32(), 4.0); ``` Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Default`, `Debug`, `[StorageElement](#StorageElement)` ## from_f32 Encodes an `f32` magnitude into a UE8M0 scale byte. ```rust pub fn from_f32(value: f32) -> Self ``` Rounds the magnitude to the nearest power of two — round-to-nearest in log2 space, the OCP MX convention; the split point is the geometric midpoint √2·2ᵉ. NaN → `0xFF`, block-NaN sentinel, zero/subnormal → `0x00`, overflow/±∞ → `0xFE`. ## to_f32 Decodes this UE8M0 scale byte to a power-of-two `f32` multiplier. ```rust pub fn to_f32(self) -> f32 ``` `0x00` → `0.0`, `0xFF` → NaN, otherwise 2^(byte − 127). ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## Roots Scalar square-root and reciprocal-square-root operations backed by NumKong's exported kernels. ```rust pub trait Roots: Sized ``` Unlike [`f32::sqrt`](#sqrt) / [`f64::sqrt`](#sqrt), this routes into the hand-tuned NumKong C kernels; on ISAs with a dedicated reciprocal-sqrt, such as `vrsqrte` on NEON or `vrsqrt14` on AVX-512, [`rsqrt`](#rsqrt) uses a single Newton refinement to ~1 ULP — roughly 2-4× faster than computing 1 / √x explicitly. Implementors: - `impl [Roots](#Roots) for f32` - `impl [Roots](#Roots) for f64` - `impl [Roots](#Roots) for [f16](#f16)` ## CastDType Trait for types that can participate in cast operations. ```rust pub trait CastDType: Sealed + StorageElement ``` This trait is sealed - users cannot implement it for their own types. Implementors: - `impl [CastDType](#CastDType) for f64` - `impl [CastDType](#CastDType) for f32` - `impl [CastDType](#CastDType) for [f16](#f16)` - `impl [CastDType](#CastDType) for [bf16](#bf16)` - `impl [CastDType](#CastDType) for [e4m3](#e4m3)` - `impl [CastDType](#CastDType) for [e5m2](#e5m2)` - `impl [CastDType](#CastDType) for [e2m3](#e2m3)` - `impl [CastDType](#CastDType) for [e3m2](#e3m2)` - `impl [CastDType](#CastDType) for [f64c](#f64c)` - `impl [CastDType](#CastDType) for [f32c](#f32c)` - `impl [CastDType](#CastDType) for [f16c](#f16c)` - `impl [CastDType](#CastDType) for [bf16c](#bf16c)` - `impl [CastDType](#CastDType) for i8` - `impl [CastDType](#CastDType) for i16` - `impl [CastDType](#CastDType) for i32` - `impl [CastDType](#CastDType) for i64` - `impl [CastDType](#CastDType) for u8` - `impl [CastDType](#CastDType) for u16` - `impl [CastDType](#CastDType) for u32` - `impl [CastDType](#CastDType) for u64` ## CastOps Extension trait: type casting for any [`TensorRef`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#TensorRef) implementor. ```rust pub trait CastOps: TensorRef ``` Implementors: - `impl> [CastOps](#CastOps) for C` ## cast Casts every element to `Destination`, returning a new tensor of the same shape. ```rust fn cast( &self, ) -> Result, Error> where Self::Alloc: Clone, ``` ## cast_into Cast into a pre-allocated sink. ```rust fn cast_into(&self, out: &mut OutputTensor) -> Result<(), Error> where Destination: Clone + CastDType, OutputTensor: TensorMut + ?Sized, ``` The destination may be a `&mut Tensor<...>` or a `&mut TensorSpan<...>`, any [`TensorMut`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#TensorMut); a strided sub-span works too. ## DenseToScaledOps Encode a dense `f32` matrix into a [`ScaledTensor`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#ScaledTensor). ```rust pub trait DenseToScaledOps: TensorRef ``` The source must be a contiguous 2D __[rows,columns]__ view with `columns` divisible by [`F::BLOCK_SIZE`](#BLOCK_SIZE). For formats with a per-tensor scale, such as NVFP4, the multiplier is derived from the tensor amax by the kernel — we seed the buffer with `0.0` and read it back. Extension trait: encode any dense `f32` tensor into a block-scaled [`ScaledTensor`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#ScaledTensor). Blanket-implemented for every [`TensorRef`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#TensorRef), so `Tensor`, `TensorView`, and `TensorSpan` all expose `.cast_to_scaled::()` without an intervening `.view()`. Implementors: - `impl + ?Sized> [DenseToScaledOps](#DenseToScaledOps) for C` ## cast_to_scaled Encodes the tensor into the block-scaled format `F`. ```rust fn cast_to_scaled(&self) -> Result, Error> where Self::Alloc: Clone, ``` ## BlockScaledDescriptor `#[repr(C)]` mirror of `nk_block_scaled_format_t`. ```rust pub struct BlockScaledDescriptor ``` Field order and types match the C struct exactly so a `*const` can be handed to `nk_cast_best`. The `tensor_scale_dtype` field is `nk_f32_k` for NVFP4 and `nk_dtype_unknown_k` (0) for the MX family; `block_size` is `0` for plain buffers. - `element_dtype` `u32`: Type of the packed elements. - `scale_dtype` `u32`: Type of the per-block scales. - `tensor_scale_dtype` `u32`: Type of the per-tensor scale, `nk_dtype_unknown_k` when there is none. - `block_size` `usize`: Elements per scaled block, `0` for plain buffers. Implements: `Clone`, `Copy`, `Debug`, `StructuralPartialEq`, `PartialEq`, `Eq` ## plain `nk_plain(dtype)` — a non-block-scaled buffer of `element_dtype`. ```rust pub fn plain(element_dtype: u32) -> Self ``` ## elements_size Element storage bytes for `count` logical elements — mirrors `nk_block_scaled_elements_size`: `count * element_bits / 8`. ```rust pub fn elements_size(&self, count: usize) -> usize ``` `count` counts dimensions, a multiple of the values per byte. ## scales_size Scale storage bytes for `count` logical elements — mirrors `nk_block_scaled_scales_size`: `0` when plain, else `round_up(count, block_size)`. ```rust pub fn scales_size(&self, count: usize) -> usize ``` ## BlockScaledFormat Compile-time description of a block-scaled tensor layout. ```rust pub trait BlockScaledFormat ``` Each implementor is a zero-sized tag ([`Nvfp4`](#Nvfp4), [`Mxfp4`](#Mxfp4), …). The associated types name the storage scalars of the two composed tensors: [`Element`](#Element) for the packed values and [`Scale`](#Scale) for the per-block scale bytes. Implementors: - `impl [BlockScaledFormat](#BlockScaledFormat) for [Nvfp4](#Nvfp4)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxfp4](#Mxfp4)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxfp6E2m3](#Mxfp6E2m3)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxfp6E3m2](#Mxfp6E3m2)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxfp8E4m3](#Mxfp8E4m3)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxfp8E5m2](#Mxfp8E5m2)` - `impl [BlockScaledFormat](#BlockScaledFormat) for [Mxint8](#Mxint8)` ## Element Storage scalar of the [`elements`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#elements) tensor, e.g. ```rust type Element: StorageElement + Clone; ``` [`e2m1x2`](#e2m1x2), [`e4m3`](#e4m3), `i8`. ## Scale Storage scalar of the [`block_scales`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#block_scales) tensor ([`Ue4m3`](#Ue4m3) or [`Ue8m0`](#Ue8m0)). ```rust type Scale: StorageElement + Clone; ``` ## BLOCK_SIZE Logical elements per block; quantization is on the last axis. ```rust const BLOCK_SIZE: usize; ``` ## HAS_TENSOR_SCALE Whether this format carries a per-tensor f32 multiplier ([`tensor_scale`](https://www.unum.cloud/docs/numkong/rust/tensors-and-views.md#tensor_scale)). ```rust const HAS_TENSOR_SCALE: bool; ``` ## * The C descriptor literal for this format. ```rust fn descriptor() -> BlockScaledDescriptor ``` ## Mxfp4 OCP MXFP4: E2M1 elements, UE8M0 block scale (block=32), no tensor scale. ```rust pub struct Mxfp4; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Mxfp6E2m3 OCP MXFP6 (E2M3 variant): E2M3 elements, UE8M0 block scale (block=32). ```rust pub struct Mxfp6E2m3; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Mxfp6E3m2 OCP MXFP6 (E3M2 variant): E3M2 elements, UE8M0 block scale (block=32). ```rust pub struct Mxfp6E3m2; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Mxfp8E4m3 OCP MXFP8 (E4M3 variant): E4M3 elements, UE8M0 block scale (block=32). ```rust pub struct Mxfp8E4m3; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Mxfp8E5m2 OCP MXFP8 (E5M2 variant): E5M2 elements, UE8M0 block scale (block=32). ```rust pub struct Mxfp8E5m2; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Mxint8 OCP MXINT8: i8 elements, UE8M0 block scale (block=32). ```rust pub struct Mxint8; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## Nvfp4 NVIDIA NVFP4: E2M1 elements, UE4M3 block scale (block=16), per-tensor f32 scale. ```rust pub struct Nvfp4; ``` Implements: `Clone`, `Copy`, `Debug`, `Default`, `[BlockScaledFormat](#BlockScaledFormat)` ## complex Complex number with adjacent real and imaginary components of type [`Scalar`](https://www.unum.cloud/docs/numkong/rust/elementwise-and-reductions.md#Scalar). ```rust pub struct complex ``` Layout: `{re: Scalar, im: Scalar}`. Supports conjugate, norm², and component access. Concrete aliases: [`f16c`](#f16c), [`bf16c`](#bf16c), [`f32c`](#f32c), [`f64c`](#f64c). - `re` `Scalar`: Real component. - `im` `Scalar`: Imaginary component. Implements: `[FloatLike](#FloatLike)`, `Debug`, `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Default`, `From`, `Add`, `Sub`, `Mul`, `Div`, `Neg`, `Display`, `[StorageElement](#StorageElement)`, `[NumberLike](#NumberLike)`, `[FloatConvertible](#FloatConvertible)` ## from_real_imag Builds a complex number from its real and imaginary components. ```rust pub const fn from_real_imag(re: Scalar, im: Scalar) -> Self ``` ## to_real_imag Splits the complex number into its real and imaginary components. ```rust pub const fn to_real_imag(self) -> (Scalar, Scalar) where Scalar: Copy, ``` ## conj Complex conjugate. ```rust pub fn conj(self) -> Self ``` ## norm_sqr Squared magnitude, re² + im². ```rust pub fn norm_sqr(self) -> Scalar::Norm ``` ## zero The additive identity. ```rust fn zero() -> Self ``` ## one The multiplicative identity. ```rust fn one() -> Self ``` ## from_f32 Convert from f32 to this type. ```rust fn from_f32(v: f32) -> Self ``` ## from_f64 Convert from f64 to this type — by default via an f32 roundtrip. ```rust fn from_f64(v: f64) -> Self ``` ## pack Pack sub-dimension scalars into a single storage value. ```rust fn pack(dims: [complex; 1]) -> Self ``` ## cast Cast source slice elements to destination slice. ```rust pub fn cast(source: &[S], dest: &mut [D]) -> Result<(), Error> ``` Converts elements from source type `S` to destination type `D` using hardware-accelerated SIMD operations when available. Arguments: - `source` - Source slice of elements to cast - `dest` - Destination slice to receive cast elements; must be same length as source Errors: - [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if slices have different lengths - [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status when it refuses the pair Examples: ``` use numkong::{f16, cast}; let f16_data: Vec<f16> = vec![f16::from_f32(1.0), f16::from_f32(2.0)]; let mut f32_data: Vec<f32> = vec![0.0; f16_data.len()]; cast(&f16_data, &mut f32_data); ```