pub type f16c = complex<f16>;Kernel outputs are widened to f32c.
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.
use numkong::{cast, f16, bf16};
let src: Vec<f32> = vec![1.0, 2.0, 3.0];
let mut dst: Vec<f16> = 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.
use numkong::{Tensor, f16};
let src = Tensor::<f32>::full(&[4, 4], 1.0).unwrap();
let mut dst = Tensor::<f16>::zeros(&[4, 4]).unwrap();
src.view().cast_into(&mut dst.span()).unwrap();API
Types
f16cHalf-precision (32-bit) complex number — two f16 components.
bf16cBFloat16 (32-bit) complex number — two bf16 components.
f32cSingle-precision (64-bit) complex number — two f32 components.
pub type f32c = complex<f32>;f64cDouble-precision (128-bit) complex number — two f64 components.
pub type f64c = complex<f64>;Structbf16BFloat16 (16-bit) floating-point number — truncated IEEE 754 single-precision.69
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.
Fields
0 | u16 |
|---|
Examples
use numkong::bf16;
let brain = bf16::from_f32(3.14);
let float = brain.to_f32();
Implements
ProbabilitySimilarity, Reductions, SpatialSimilarity, FloatLike, Attention, AttentionRope, CastDType, Bilinear, Mahalanobis, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachSwiGlu, EachRmsNorm, EachRmsCast, MaxSim, KullbackLeibler, JensenShannon, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<bf16>, StorageElement, NumberLike, FloatConvertibleattention_packed_gradientsCompute the gradients of 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.
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_offsetsandquery_token_count - every gradient buffer must be writable for its extent, and
outputandoutput_gradientshareoutput_stride
ZEROPositive zero.
pub const ZERO: Self = _;ONEPositive one.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;NANQuiet NaN, i.e.
from_f32Converts an f32 value to bf16.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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× 3Converts this value back to f32.
pub fn to__f32(self) -> f32Examples
use numkong::f16;
let half = f16::from_f32(-2.5);
assert_eq!(half.to_f32(), -2.5);
is_*_nan× 6Returns true if this value is NaN.
is_*_infinite× 4Returns true if this value is positive or negative infinity.
is_*_finite× 6Returns true if this number is neither infinite nor NaN.
pub fn is__finite(self) -> boolNote: E2M3FN format has no infinities or NaN.
Note: the E4M3 format has no infinities at all.
*× 5Returns the absolute value of self.
pub fn abs(self) -> Selfattention_pack_*_pack_size× 3Returns bytes enough to pack token_count keys in segment_count segments, however split.
Inherited from Attention
fn attention_pack__pack_size(
heads: usize,
depth: usize,
token_count: usize,
segment_count: usize,
) -> Result<usize, Error>attention_packed_*_packed_shape× 3Reads the KV-cache geometry — heads, depth, segments — from the packed header. # Safety packed must point to a buffer produced by attention_pack.
Inherited from Attention
unsafe fn attention_packed__packed_shape(packed: *const u8) -> Result<(usize, usize, usize), Error>attention_*_pack× 3Pack 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
Inherited from Attention
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× 3Compute 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.
Inherited from Attention
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_packedmust have been produced byattention_packwith matching geometryqueriesrows addressed byquery_offsetsmust be valid,outputwritable withoutput_stridebyte rowsquery_token_countequalsquery_offsets[segments]log_sum_expis null or writable for one value per query token and head
attention_rope_*_rope_into× 2Rotates a 2D [rows,head_count × depth] tensor in place using the [rows,depth/2] cos/sin angle grids, shared across heads, for an even depth of channels per head.
Inherited from AttentionRope
fn attention_rope__rope_into<XMut, const RX: usize>(
x: &mut XMut,
cos: &[f32],
sin: &[f32],
head_count: usize,
depth: usize,
) -> Result<(), Error>
where
XMut: TensorMut<Self, RX> + ?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.
bilinearComputes the bilinear form aᵀ × C × b.
Inherited from Bilinear
fn bilinear(a: &[Self], b: &[Self], c: &[Self]) -> Result<Self::Output, Error>Arguments
a- First vector of length nb- Second vector of length nc- Metric tensor, symmetric [n,n] matrix in row-major order, flattened to length n²
Errors
Error::InvalidShape for empty vectors, Error::ShapeMismatch if lengths
are incompatible, or Error::KernelFailed carrying the kernel's status.
mahalanobisComputes the Mahalanobis distance √((a−b)ᵀ × C × (a−b)).
Inherited from Mahalanobis
fn mahalanobis(a: &[Self], b: &[Self], c: &[Self]) -> Result<Self::Output, Error>Arguments
a- First vector of length nb- Second vector of length nc- Inverse covariance matrix, a symmetric [n,n] matrix in row-major order, flattened to length n²
Errors
Error::InvalidShape for empty vectors, Error::ShapeMismatch if lengths
are incompatible, or Error::KernelFailed carrying the kernel's status.
dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
each_*_scale× 6Writes resultᵢ = α × aᵢ + β into the pre-sized output slice.
Inherited from EachScale
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× 6In-place affine: dataᵢ = α × dataᵢ + β.
Inherited from EachScale
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× 6Writes resultᵢ = aᵢ + bᵢ into the pre-sized output slice.
Inherited from EachSum
fn each__sum(a: &[Self], b: &[Self], result: &mut [Self]) -> Result<(), Error>each_sum_*_sum_inplace× 6In-place sum: dataᵢ = dataᵢ + otherᵢ.
Inherited from EachSum
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× 6Writes resultᵢ = α × aᵢ + β × bᵢ into the pre-sized output slice.
Inherited from EachBlend
fn each__blend(
a: &[Self],
b: &[Self],
alpha: f32,
beta: f32,
result: &mut [Self],
) -> Result<(), Error>each_blend_*_blend_inplace× 6In-place blend: dataᵢ = α × dataᵢ + β × otherᵢ.
Inherited from EachBlend
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× 6Writes resultᵢ = α × aᵢ × bᵢ + β × cᵢ into the pre-sized output slice.
Inherited from EachFma
fn each__fma(
a: &[Self],
b: &[Self],
c: &[Self],
alpha: f32,
beta: f32,
result: &mut [Self],
) -> Result<(), Error>each_fma_*_fma_inplace× 6In-place fused multiply-add with the c operand bound to a: dataᵢ = α × dataᵢ × bᵢ + β × dataᵢ.
Inherited from EachFma
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, 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× 2Fused SwiGLU of 2D tensors: y = silu(gate_scale × gate) × up × output_scale.
Inherited from EachSwiGlu
fn swiglu__into<GIn, UIn, YOut, const RG: usize, const RU: usize, const RY: usize>(
gate: &GIn,
up: Option<&UIn>,
y: &mut YOut,
gate_scale: f32,
output_scale: f32,
) -> Result<(), Error>
where
GIn: TensorRef<Self, RG> + ?Sized,
UIn: TensorRef<Self, RU> + ?Sized,
YOut: TensorMut<Self, RY> + ?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× 2Grouped RMSNorm of a 2D [rows,groups×columns] tensor into y of the same shape.
Inherited from EachRmsNorm
fn rmsnorm__into<XIn, YOut, const RX: usize, const RY: usize>(
x: &XIn,
gamma: Option<&[f32]>,
y: &mut YOut,
groups: usize,
epsilon: f32,
) -> Result<(), Error>
where
XIn: TensorRef<Self, RX> + ?Sized,
YOut: TensorMut<Self, RY> + ?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× 6Grouped RMSNorm of a 2D [rows,groups×columns] tensor of Self::Input into y, a tensor of Self of the same shape, with ε added to the mean square of the raw input.
Inherited from EachRmsCast
fn rmscast__into<XIn, YOut, const RX: usize, const RY: usize>(
x: &XIn,
gamma: Option<&[f32]>,
y: &mut YOut,
groups: usize,
epsilon: f32,
) -> Result<(), Error>
where
XIn: TensorRef<Self::Input, RX> + ?Sized,
YOut: TensorMut<Self, RY> + ?Sized,Returns Err
on a shape mismatch.
maxsim_pack_*_pack_size× 2Returns the packed buffer size in bytes for vectors vectors of given depth.
Inherited from MaxSim
fn maxsim_pack__pack_size(vectors: usize, depth: usize) -> Result<usize, Error>maxsim_packed_*_packed_shape× 2Reads the packed vector count and depth from the buffer header. # Safety packed must point to a buffer produced by maxsim_pack.
Inherited from MaxSim
unsafe fn maxsim_packed__packed_shape(packed: *const u8) -> Result<(usize, usize), Error>maxsim_*_pack× 2Pack vectors into backend-specific quantized format.
Inherited from MaxSim
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
maxsim_*_packed× 2Compute MaxSim score on pre-packed buffers.
Inherited from MaxSim
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_packwith matching depth resultmust point to valid, writable memory forSelf::Score
kullbackleiblerComputes the Kullback-Leibler divergence of a from b.
Inherited from KullbackLeibler
fn kullbackleibler(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>klAlias for kullbackleibler.
Inherited from KullbackLeibler
fn kl(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>jensenshannonComputes the Jensen-Shannon divergence between a and b.
Inherited from JensenShannon
fn jensenshannon(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>jsAlias for jensenshannon.
Inherited from JensenShannon
fn js(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
dots_pack_*_pack_size× 10Returns the size in bytes needed for the packed B matrix buffer.
Inherited from Dots
fn dots_pack__pack_size(columns: usize, depth: usize) -> Result<usize, Error>dots_packed_*_packed_shape× 10Reads the packed B matrix's columns and depth from its header. # Safety packed must point to a buffer produced by dots_pack.
Inherited from Dots
unsafe fn dots_packed__packed_shape(packed: *const u8) -> Result<(usize, usize), Error>dots_*_pack× 10Packs the B matrix into an optimized backend-specific layout.
Inherited from Dots
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
bmust point to valid memory forcolumns * depthelementspackedmust point to a buffer of at leastdots_pack_size(columns, depth)bytes
dots_*_packed× 10Computes C = A × Bᵀ using packed B.
Inherited from Dots
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
dots_*_symmetric× 10Computes C = A × Aᵀ where C is symmetric.
Inherited from Dots
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
vectorsmust point to valid memory forvector_count × depthelements with given strideresultmust point to valid memory forvector_count×vector_countelements, given stride- Strides are in bytes, not elements
rows_begin <= rows_end;rows_endis clamped tovector_count
angulars_*_packed× 9Computes angular distances between A rows and packed B columns.
Inherited from Angulars
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
amust point to valid memory forrows * depthelements with given stridepackedmust be a buffer filled byDots::dots_packcmust point to valid memory forrows×columnsresult elements with given stride
angulars_*_symmetric× 9Computes symmetric angular distance matrix.
Inherited from Angulars
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
vectorsmust point to valid memory forvector_count * depthelementsresultmust point to valid memory forvector_count * vector_countresult elements
euclideans_*_packed× 9Computes euclidean distances between A rows and packed B columns.
Inherited from Euclideans
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
amust point to valid memory forrows * depthelements with given stridepackedmust be a buffer filled byDots::dots_packcmust point to valid memory forrows×columnsresult elements with given stride
euclideans_*_symmetric× 9Computes symmetric euclidean distance matrix.
Inherited from Euclideans
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
vectorsmust point to valid memory forvector_count * depthelementsresultmust point to valid memory forvector_count * vector_countresult elements
zeroThe additive identity.
oneThe multiplicative identity.
dimensions_per_*_per_value× 14Number of logical dimensions packed into one storage value.
Inherited from StorageElement
fn dimensions_per__per_value() -> usizeDefault: 1 for all normal types. Override for sub-byte packed types.
dimensions_to_*_to_values× 14Storage values needed to hold dims logical dimensions.
Inherited from StorageElement
fn dimensions_to__to_values(dims: usize) -> usizedims 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× 14Split a logical dimension index into the storage value holding it and its position inside.
Inherited from StorageElement
fn locate__dim(dim_index: usize) -> DimLocationThe counterpart to dimensions_to_values, for the callers
that must reach an individual dimension rather than count them. Pair it with
FloatConvertible::unpack to read the dimension out, or with DimMut to write one
back.
has_*_infinity× 11Whether the type can represent infinity.
has_*_nan× 11Whether the type can represent NaN.
has_*_subnormals× 11Whether the type can represent subnormal values.
max_*_value× 11Largest finite value of the type, as f32.
min_*_positive× 11Smallest positive normal value of the type, as f32.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
to_*_f64× 11Convert from this type to f64 — by default via an f32 roundtrip.
*× 11Unpack all logical sub-dimensions from this packed value.
packPack sub-dimension scalars into a single storage value.
Structe2m1x2Packed FP4, E2M1, element pair: two 4-bit elements share one byte.2
pub struct e2m1x2(pub u8);This is the storage scalar for the elements tensor of NVFP4 / MXFP4. Like the other sub-byte
packers (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.
Fields
0 | u8 |
|---|
Implements
Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, StorageElementzeroThe additive identity.
oneThe multiplicative identity.
Structe2m36-bit E2M3 micro-float, padded to 8-bit storage.18
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.
Fields
0 | u8 |
|---|
Examples
use numkong::e2m3;
let fp6 = e2m3::from_f32(2.5);
let float = fp6.to_f32();
Implements
Reductions, SpatialSimilarity, FloatLike, CastDType, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachRmsCast, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<e2m3>, StorageElement, NumberLike, FloatConvertibleZEROPositive zero.
pub const ZERO: Self = _;ONEPositive one.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;from_f32Convert an f32 value to e2m3.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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× 8Convert from this type to f32.
pub fn to__f32(self) -> f32dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structe3m26-bit E3M2 micro-float, padded to 8-bit storage.17
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.
Fields
0 | u8 |
|---|
Examples
use numkong::e3m2;
let fp6 = e3m2::from_f32(2.5);
let float = fp6.to_f32();
Implements
Reductions, SpatialSimilarity, FloatLike, CastDType, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachRmsCast, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<e3m2>, StorageElement, NumberLike, FloatConvertibleZEROPositive zero.
pub const ZERO: Self = _;ONEPositive one.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;from_f32Convert an f32 value to e3m2.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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);
dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structe4m38-bit E4M3 floating-point number, OCP FP8.19
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.
Fields
0 | u8 |
|---|
Examples
use numkong::e4m3;
let fp8 = e4m3::from_f32(2.5);
let float = fp8.to_f32();
Implements
Reductions, SpatialSimilarity, FloatLike, Attention, AttentionRope, CastDType, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachSwiGlu, EachRmsNorm, EachRmsCast, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<e4m3>, StorageElement, NumberLike, FloatConvertibleZEROPositive zero.
pub const ZERO: Self = _;ONEOne.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;NANQuiet NaN, i.e.
from_f32Converts an f32 value to e4m3.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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× 2Returns true if this value is ±∞.
dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structe5m28-bit E5M2 floating-point number, OCP FP8.18
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.
Fields
0 | u8 |
|---|
Examples
use numkong::e5m2;
let fp8 = e5m2::from_f32(2.5);
let float = fp8.to_f32();
Implements
Reductions, SpatialSimilarity, FloatLike, CastDType, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachRmsCast, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<e5m2>, StorageElement, NumberLike, FloatConvertibleZEROPositive zero.
pub const ZERO: Self = _;ONEPositive one.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;NANQuiet NaN, i.e.
from_f32Convert an f32 value to e5m2.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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);
dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structf16Half-precision (16-bit) IEEE 754 floating-point number.46
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.
Fields
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, Reductions, SpatialSimilarity, Trigonometry, FloatLike, Attention, CastDType, Bilinear, Mahalanobis, Dot, VDot, EachScale, EachSum, EachBlend, EachFma, EachRmsCast, MaxSim, KullbackLeibler, JensenShannon, ReduceMoments, ReduceMinMax, Roots, Shapes, Angular, Euclidean, TrigSin, TrigCos, TrigAtan, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, Add, Sub, Mul, Div, Neg, PartialOrd, From<f32>, From<f16>, StorageElement, NumberLike, FloatConvertibleZEROPositive zero.
pub const ZERO: Self = _;ONEPositive one.
pub const ONE: Self = _;NEG_ONENegative one.
pub const NEG_ONE: Self = _;NANQuiet NaN, i.e.
from_f32Converts an f32 value to f16.
pub fn from_f32(value: f32) -> Selffn from_f32(v: f32) -> SelfConvert 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);
absReturns |self|.
pub fn abs(self) -> SelfbilinearComputes the bilinear form aᵀ × C × b.
Inherited from Bilinear
fn bilinear(a: &[Self], b: &[Self], c: &[Self]) -> Result<Self::Output, Error>Arguments
a- First vector of length nb- Second vector of length nc- Metric tensor, symmetric [n,n] matrix in row-major order, flattened to length n²
Errors
Error::InvalidShape for empty vectors, Error::ShapeMismatch if lengths
are incompatible, or Error::KernelFailed carrying the kernel's status.
mahalanobisComputes the Mahalanobis distance √((a−b)ᵀ × C × (a−b)).
Inherited from Mahalanobis
fn mahalanobis(a: &[Self], b: &[Self], c: &[Self]) -> Result<Self::Output, Error>Arguments
a- First vector of length nb- Second vector of length nc- Inverse covariance matrix, a symmetric [n,n] matrix in row-major order, flattened to length n²
Errors
Error::InvalidShape for empty vectors, Error::ShapeMismatch if lengths
are incompatible, or Error::KernelFailed carrying the kernel's status.
dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
kullbackleiblerComputes the Kullback-Leibler divergence of a from b.
Inherited from KullbackLeibler
fn kullbackleibler(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>klAlias for kullbackleibler.
Inherited from KullbackLeibler
fn kl(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>jensenshannonComputes the Jensen-Shannon divergence between a and b.
Inherited from JensenShannon
fn jensenshannon(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>jsAlias for jensenshannon.
Inherited from JensenShannon
fn js(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
*× 2Non-negative square root of self, routed through NumKong's runtime-dispatched kernel.
*× 2Reciprocal square root 1 / √x of self as a single primitive op where the hardware allows.
shapes_pack_sizeReturns the bytes a pack of points points takes.
shapes_packPacks one cloud: centers it and rotates it onto its principal axes.
Inherited from Shapes
unsafe fn shapes_pack(points: &[[Self; 3]], packed: *mut u8) -> Result<(), Error>Safety
packed must have shapes_pack_size(points.len()) writable bytes on an
nk_default_alignment_k boundary.
shapes_pack_normalizedPacks one cloud like Shapes::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.
Inherited from Shapes
unsafe fn shapes_pack_normalized(points: &[[Self; 3]], packed: *mut u8) -> Result<(), Error>Safety
The contract of Shapes::shapes_pack.
shapes_packed_shapeReads 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.
Inherited from Shapes
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 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_unpackWrites the cloud of a pack back interleaved, in its original pose and scale, within one rounding to Self.
Inherited from Shapes
unsafe fn shapes_unpack(packed: *const u8, points: *mut [Self; 3]) -> Result<(), Error>Safety
rmsds_packedSuperposed RMSDs between every row cloud and every column cloud of equally many points.
Inherited from Shapes
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_packedandb_packedmust holdrowsandcolumnspointers to packs ofSelfresultsmust holdrowsrows ofcolumnsdistances,results_stridebytes apartstreammust be null or a live stream of the groupcapabilitiesname, null on the CPU, and on a GPU everything above must stay alive and untouched until that stream joins
hausdorffs_packedHausdorff distances between every row cloud and every column cloud.
Inherited from Shapes
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, plus rotations must be null or hold
rows × columns × 9 writable values.
chamfers_workspace_sizeReturns the workspace bytes Chamfer needs between clouds of up to row_points and column_points points.
Inherited from Shapes
fn chamfers_workspace_size(
row_points: usize,
column_points: usize,
capabilities: Capabilities,
) -> Result<usize, Error>chamfers_packedChamfer distances between every row cloud and every column cloud.
Inherited from Shapes
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, plus workspace must have workspace_bytes
writable bytes, on the default alignment, as Shapes::chamfers_workspace_size reports for
the largest clouds.
wassersteinprocrustes_workspace_sizeReturns the workspace bytes Wasserstein-Procrustes needs between clouds of up to row_points and column_points points.
Inherited from Shapes
fn wassersteinprocrustes_workspace_size(
row_points: usize,
column_points: usize,
capabilities: Capabilities,
) -> Result<usize, Error>wassersteinprocrustes_packedWasserstein-Procrustes distances between every row cloud and every column cloud.
Inherited from Shapes
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, plus workspace must have workspace_bytes
writable bytes on an nk_default_alignment_k boundary.
gromovwassersteins_workspace_sizeReturns the workspace bytes Gromov-Wasserstein needs between clouds of up to row_points and column_points points.
Inherited from Shapes
fn gromovwassersteins_workspace_size(
row_points: usize,
column_points: usize,
capabilities: Capabilities,
) -> Result<usize, Error>gromovwassersteins_packedGromov-Wasserstein distances between every row cloud and every column cloud.
Inherited from Shapes
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.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
sinWrites the sine of every input element, in radians, into the output slice.
Inherited from TrigSin
fn sin(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error>sin_inplaceIn-place sine: data[i] = sin(data[i]).
Inherited from TrigSin
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.
cosWrites the cosine of every input element, in radians, into the output slice.
Inherited from TrigCos
fn cos(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error>cos_inplaceIn-place cosine: data[i] = cos(data[i]).
Inherited from TrigCos
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.
atanWrites the arctangent of every input element, in radians, into the output slice.
Inherited from TrigAtan
fn atan(inputs: &[Self], outputs: &mut [Self]) -> Result<(), Error>atan_inplaceIn-place arctangent: data[i] = atan(data[i]).
Inherited from TrigAtan
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.
zeroThe additive identity.
oneThe multiplicative identity.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structi4x2Packed 4-bit signed integer pair (2 × i4 in one byte).22
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.
Fields
0 | u8 |
|---|
Implements
Reductions, SpatialSimilarity, FloatLike, Dot, VDot, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, From<(i8, i8)>, From<i4x2>, StorageElement, NumberLike, FloatConvertiblenewCreate from raw packed byte.
pub const fn new(packed: u8) -> Self*× 2Get the raw packed byte.
pub const fn packed(self) -> u8from_i8sConstruct from two i8 values with saturation to -8..7, first in the high nibble.
pub const fn from_i8s(first: i8, second: i8) -> Selfto_i8sExtract to two i8 values, sign-extended from 4 bits, the high nibble first.
pub const fn to_i8s(self) -> (i8, i8)dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f32Convert from f32 to this type.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
*× 5Absolute value.
is_*_nan× 5Whether the value is NaN.
is_*_finite× 5Whether the value is neither infinite nor NaN.
is_*_infinite× 5Whether the value is infinite.
packPack sub-dimension scalars into a single storage value.
Structu1x8Packed 8-bit bit-vector — 8 booleans in one byte.20
pub struct u1x8(pub u8);Layout: 8 bits packed into one byte, MSB = dimension 0. Used for Hamming distance and Jaccard similarity via popcount.
Fields
0 | u8 |
|---|
Implements
Reductions, BinarySimilarity, FloatLike, Dot, VDot, ReduceMoments, ReduceMinMax, Hamming, Jaccard, Dots, Hammings, Jaccards, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, From<(bool, bool, bool, bool, bool, bool, bool, bool)>, From<u1x8>, StorageElement, NumberLike, FloatConvertiblenewCreate from raw packed bits.
pub const fn new(bits: u8) -> SelfbitsGet the raw packed bits.
pub const fn bits(self) -> u8from_boolsConstruct from 8 booleans (b0 = MSB, b7 = LSB).
pub const fn from_bools(
b0: bool,
b1: bool,
b2: bool,
b3: bool,
b4: bool,
b5: bool,
b6: bool,
b7: bool,
) -> Selfto_boolsExtract to 8 booleans (b0 = MSB, b7 = LSB).
pub const fn to_bools(self) -> (bool, bool, bool, bool, bool, bool, bool, bool)dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
hammingComputes the Hamming distance between two equally long slices.
Inherited from Hamming
fn hamming(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>jaccardComputes the Jaccard distance between two equally long slices.
Inherited from Jaccard
fn jaccard(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>hammings_packedComputes Hamming distances between values matrix rows and packed query rows.
Inherited from Hammings
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
amust point to valid memory for the values matrixpackedmust be a buffer filled byDots::dots_packresultmust point to valid memory forrows×columnsu32 elements
hammings_symmetricComputes symmetric Gram matrix of Hamming distances: C = A × Aᵀ.
Inherited from Hammings
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
vectorsmust point to valid memory for the input matrixresultmust point to valid memory forvector_count * vector_countu32 elements
jaccards_packedComputes Jaccard distances between values matrix rows and packed query rows.
Inherited from Jaccards
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
amust point to valid memory for the values matrixpackedmust be a buffer filled byDots::dots_packresultmust point to valid memory forrows×columnselements
jaccards_symmetricComputes symmetric Gram matrix of Jaccard distances.
Inherited from Jaccards
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
vectorsmust point to valid memory for the input matrixresultmust point to valid memory forvector_count * vector_countelements
zeroThe additive identity.
oneThe multiplicative identity.
from_f32Convert from f32 to this type.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Structu4x2Packed 4-bit unsigned integer pair (2 × u4 in one byte).17
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.
Fields
0 | u8 |
|---|
Implements
Reductions, SpatialSimilarity, FloatLike, Dot, VDot, ReduceMoments, ReduceMinMax, Angular, Euclidean, Dots, Angulars, Euclideans, Clone, Copy, StructuralPartialEq, PartialEq, Eq, Default, Debug, Display, LowerHex, UpperHex, Binary, From<(u8, u8)>, From<u4x2>, StorageElement, NumberLike, FloatConvertiblenewCreate from raw packed byte.
pub const fn new(packed: u8) -> Selffrom_u8sConstruct from two u8 values with saturation to 0..15, first in the high nibble.
pub const fn from_u8s(first: u8, second: u8) -> Selfto_u8sExtract to two u8 values (0..15 each), the high nibble first.
pub const fn to_u8s(self) -> (u8, u8)dotComputes the dot product of two equally long slices.
Inherited from Dot
fn dot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>innerAlias for dot.
Inherited from Dot
fn inner(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>vdotHermitian inner product.
Inherited from VDot
fn vdot(first: &[Self], second: &[Self]) -> Result<Self::Output, Error>On real-valued types this falls back to Dot::dot; on complex
types it returns ∑ᵢ conj(aᵢ) × bᵢ computed in the widened accumulator described by
Dot::Output.
reduce_momentsCompute (sum, sum_of_squares) for data with the given stride in bytes.
Inherited from ReduceMoments
fn reduce_moments(
data: &[Self],
stride: usize,
) -> Result<(Self::SumOutput, Self::SumSqOutput), Error>Use stride = size_of::<Self>() for contiguous data.
Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
reduce_minmaxReturns Ok(Some(MinMaxResult)) for the given data with the specified stride, or Ok(None) if all elements are NaN.
Inherited from ReduceMinMax
fn reduce_minmax(data: &[Self], stride: usize) -> Result<Option<MinMaxResult<Self::Output>>, Error>Reads data.len() logical elements starting at data.as_ptr(), advancing by stride
between each — pass size_of::<Self>() for contiguous storage.
angularComputes the angular distance between two equally long slices.
Inherited from Angular
fn angular(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>cosineAlias for angular.
Inherited from Angular
fn cosine(a: &[Self], b: &[Self]) -> Result<Self::Output, Error>sqeuclideanSquared Euclidean distance, i.e.
Inherited from Euclidean
fn sqeuclidean(a: &[Self], b: &[Self]) -> Result<Self::SqEuclideanOutput, Error>L2². Faster than euclidean for comparisons.
euclideanEuclidean distance, i.e.
Inherited from Euclidean
fn euclidean(a: &[Self], b: &[Self]) -> Result<Self::EuclideanOutput, Error>L2. True metric distance.
zeroThe additive identity.
oneThe multiplicative identity.
from_f32Convert from f32 to this type.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
TraitFloatConvertibleTrait for types that can unpack/pack logical sub-dimensions.3
pub trait FloatConvertible: NumberLikeFor normal scalar types (dimensions_per_value() == 1), DimScalar = Self and Unpacked = [Self; 1]. For packed sub-byte types, DimScalar is the natural scalar type for individual
sub-dimensions, such as i8 for i4x2.
Implementors
impl<Scalar: ComplexComponent> FloatConvertible for complex<Scalar>impl FloatConvertible for f32impl FloatConvertible for f64impl FloatConvertible for f16impl FloatConvertible for bf16impl FloatConvertible for e4m3impl FloatConvertible for e5m2impl FloatConvertible for e2m3impl FloatConvertible for e3m2impl FloatConvertible for i8impl FloatConvertible for u8impl FloatConvertible for i16impl FloatConvertible for u16impl FloatConvertible for i32impl FloatConvertible for u32impl FloatConvertible for i64impl FloatConvertible for u64impl FloatConvertible for i4x2impl FloatConvertible for u4x2impl FloatConvertible for u1x8
DimScalarScalar type for individual sub-dimensions.
type DimScalar: Copy + Default + NumberLike;UnpackedFixed-size array holding all unpacked sub-dimensions.
type Unpacked: AsRef<[Self::DimScalar]> + AsMut<[Self::DimScalar]> + Copy + Default;packPack sub-dimension scalars into a single storage value.
fn pack(dims: Self::Unpacked) -> SelfTraitFloatLikeBackward-compatible alias: any type implementing NumberLike also implements FloatLike.
pub trait FloatLike: NumberLikeImplementors
impl<Scalar: NumberLike> FloatLike for Scalar
TraitNumberLikeTrait for types that support conversion to/from f32 with classification and constants.2
pub trait NumberLike: StorageElementProvides a unified interface for all numeric types used in NumKong, including half-precision floats, mini-floats, integers, and packed types.
Implementors
impl NumberLike for f32impl NumberLike for f64impl NumberLike for f16impl NumberLike for bf16impl NumberLike for e4m3impl NumberLike for e5m2impl NumberLike for e2m3impl NumberLike for e3m2impl NumberLike for i8impl NumberLike for u8impl NumberLike for i32impl NumberLike for u32impl NumberLike for i16impl NumberLike for u16impl NumberLike for i64impl NumberLike for u64impl NumberLike for i4x2impl NumberLike for u4x2impl NumberLike for u1x8impl<Scalar: ComplexComponent> NumberLike for complex<Scalar>
from_f32Convert from f32 to this type.
fn from_f32(v: f32) -> Selffrom_f64Convert from f64 to this type — by default via an f32 roundtrip.
fn from_f64(v: f64) -> SelfTraitStorageElementMinimal trait for types that can be stored in vectors and tensors.2
pub trait StorageElement: Sized + Copy + Clone + Default + DebugProvides identity elements (zero, one) and sub-byte packing metadata.
Does not require numeric conversion — use NumberLike for that.
Implementors
impl StorageElement for Ue4m3impl StorageElement for Ue8m0impl StorageElement for f32impl StorageElement for f64impl StorageElement for f16impl StorageElement for bf16impl StorageElement for e4m3impl StorageElement for e5m2impl StorageElement for e2m3impl StorageElement for e3m2impl StorageElement for i8impl StorageElement for u8impl StorageElement for i32impl StorageElement for u32impl StorageElement for i16impl StorageElement for u16impl StorageElement for i64impl StorageElement for u64impl StorageElement for usizeimpl StorageElement for i4x2impl StorageElement for u4x2impl StorageElement for e2m1x2impl StorageElement for u1x8impl<Scalar: ComplexComponent> StorageElement for complex<Scalar>
zeroThe additive identity.
fn zero() -> SelfoneThe multiplicative identity.
fn one() -> SelfStructUe4m3NVFP4 per-block scale byte: an unsigned E4M3 magnitude with the sign bit forced to 0.5
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 takes the absolute value.
Fields
0 | u8 |
|---|
Examples
use numkong::Ue4m3;
let scale = Ue4m3::from_f32(2.0);
assert_eq!(scale.to_f32(), 2.0);
Implements
ZEROThe all-zero byte — decodes to 0.0.
pub const ZERO: Self = _;from_f32Encodes an f32 magnitude into a UE4M3 scale byte — absolute value, round-to-nearest.
pub fn from_f32(value: f32) -> SelfUE4M3 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_f32Decodes this UE4M3 scale byte to a non-negative f32 multiplier.
pub fn to_f32(self) -> f32zeroThe additive identity.
oneThe multiplicative identity.
StructUe8m0MX-family per-block scale byte: an unsigned power-of-two exponent, UE8M0.4
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 rounds the magnitude UP to the smallest power
of two that is ≥ |value|.
Fields
0 | u8 |
|---|
Examples
use numkong::Ue8m0;
let scale = Ue8m0::from_f32(4.0);
assert_eq!(scale.to_f32(), 4.0);
Implements
from_f32Encodes an f32 magnitude into a UE8M0 scale byte.
pub fn from_f32(value: f32) -> SelfRounds 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_f32Decodes this UE8M0 scale byte to a power-of-two f32 multiplier.
zeroThe additive identity.
oneThe multiplicative identity.
TraitRootsScalar square-root and reciprocal-square-root operations backed by NumKong's exported kernels.
pub trait Roots: SizedUnlike f32::sqrt / f64::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
uses a single Newton refinement to ~1 ULP — roughly 2-4× faster than computing 1 / √x
explicitly.
Implementors
TraitCastDTypeTrait for types that can participate in cast operations.
pub trait CastDType: Sealed + StorageElementThis trait is sealed - users cannot implement it for their own types.
Implementors
impl CastDType for f64impl CastDType for f32impl CastDType for f16impl CastDType for bf16impl CastDType for e4m3impl CastDType for e5m2impl CastDType for e2m3impl CastDType for e3m2impl CastDType for f64cimpl CastDType for f32cimpl CastDType for f16cimpl CastDType for bf16cimpl CastDType for i8impl CastDType for i16impl CastDType for i32impl CastDType for i64impl CastDType for u8impl CastDType for u16impl CastDType for u32impl CastDType for u64
TraitCastOpsExtension trait: type casting for any TensorRef implementor.2
pub trait CastOps<Source: Clone + CastDType, const MAX_RANK: usize>: TensorRef<Source, MAX_RANK>Implementors
castCasts every element to Destination, returning a new tensor of the same shape.
fn cast<Destination: Clone + CastDType>(
&self,
) -> Result<Tensor<Destination, Self::Alloc, MAX_RANK>, Error>
where
Self::Alloc: Clone,cast_intoCast into a pre-allocated sink.
fn cast_into<Destination, OutputTensor>(&self, out: &mut OutputTensor) -> Result<(), Error>
where
Destination: Clone + CastDType,
OutputTensor: TensorMut<Destination, MAX_RANK> + ?Sized,The destination may be a &mut Tensor<...> or a &mut TensorSpan<...>, any TensorMut; a strided sub-span works too.
TraitDenseToScaledOpsEncode a dense f32 matrix into a ScaledTensor.1
pub trait DenseToScaledOps<const MAX_RANK: usize>: TensorRef<f32, MAX_RANK>The source must be a contiguous 2D [rows,columns] view with columns divisible by
F::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.
Blanket-implemented for every TensorRef<f32, MAX_RANK>, so Tensor<f32>, TensorView<f32>,
and TensorSpan<f32> all expose .cast_to_scaled::<F>() without an intervening .view().
Implementors
impl<const R: usize, C: TensorRef<f32, R> + ?Sized> DenseToScaledOps<R> for C
cast_to_scaledEncodes the tensor into the block-scaled format F.
fn cast_to_scaled<F: BlockScaledFormat>(&self) -> Result<ScaledTensor<F, Self::Alloc>, Error>
where
Self::Alloc: Clone,StructBlockScaledDescriptor#[repr(C)] mirror of nk_block_scaled_format_t.3
pub struct BlockScaledDescriptorField 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.
Fields
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, Eqplainnk_plain(dtype) — a non-block-scaled buffer of element_dtype.
pub fn plain(element_dtype: u32) -> Selfelements_sizeElement storage bytes for count logical elements — mirrors nk_block_scaled_elements_size: count * element_bits / 8.
pub fn elements_size(&self, count: usize) -> usizecount counts dimensions, a multiple of the values per byte.
scales_sizeScale storage bytes for count logical elements — mirrors nk_block_scaled_scales_size: 0 when plain, else round_up(count, block_size).
pub fn scales_size(&self, count: usize) -> usizeTraitBlockScaledFormatCompile-time description of a block-scaled tensor layout.5
pub trait BlockScaledFormatEach implementor is a zero-sized tag (Nvfp4, Mxfp4, …). The associated types name the
storage scalars of the two composed tensors: Element for the packed values and Scale for the
per-block scale bytes.
Implementors
impl BlockScaledFormat for Nvfp4impl BlockScaledFormat for Mxfp4impl BlockScaledFormat for Mxfp6E2m3impl BlockScaledFormat for Mxfp6E3m2impl BlockScaledFormat for Mxfp8E4m3impl BlockScaledFormat for Mxfp8E5m2impl BlockScaledFormat for Mxint8
ElementStorage scalar of the elements tensor, e.g.
ScaleStorage scalar of the block_scales tensor (Ue4m3 or Ue8m0).
type Scale: StorageElement + Clone;BLOCK_SIZELogical elements per block; quantization is on the last axis.
const BLOCK_SIZE: usize;HAS_TENSOR_SCALEWhether this format carries a per-tensor f32 multiplier (tensor_scale).
const HAS_TENSOR_SCALE: bool;*× 8The C descriptor literal for this format.
fn descriptor() -> BlockScaledDescriptorStructMxfp4OCP MXFP4: E2M1 elements, UE8M0 block scale (block=32), no tensor scale.
StructMxfp6E2m3OCP MXFP6 (E2M3 variant): E2M3 elements, UE8M0 block scale (block=32).
StructMxfp6E3m2OCP MXFP6 (E3M2 variant): E3M2 elements, UE8M0 block scale (block=32).
StructMxfp8E4m3OCP MXFP8 (E4M3 variant): E4M3 elements, UE8M0 block scale (block=32).
StructMxfp8E5m2OCP MXFP8 (E5M2 variant): E5M2 elements, UE8M0 block scale (block=32).
StructMxint8OCP MXINT8: i8 elements, UE8M0 block scale (block=32).
StructNvfp4NVIDIA NVFP4: E2M1 elements, UE4M3 block scale (block=16), per-tensor f32 scale.
StructcomplexComplex number with adjacent real and imaginary components of type Scalar.9
pub struct complex<Scalar>Layout: {re: Scalar, im: Scalar}. Supports conjugate, norm², and component access.
Concrete aliases: f16c, bf16c, f32c, f64c.
Fields
re | Scalar | Real component. |
|---|---|---|
im | Scalar | Imaginary component. |
Implements
FloatLike, Debug, Clone, Copy, StructuralPartialEq, PartialEq, Default, From<f32>, Add, Sub, Mul, Div, Neg, Display, StorageElement, NumberLike, FloatConvertiblefrom_real_imagBuilds a complex number from its real and imaginary components.
pub const fn from_real_imag(re: Scalar, im: Scalar) -> Selfto_real_imagSplits the complex number into its real and imaginary components.
pub const fn to_real_imag(self) -> (Scalar, Scalar)
where
Scalar: Copy,conjComplex conjugate.
pub fn conj(self) -> Selfnorm_sqrSquared magnitude, re² + im².
pub fn norm_sqr(self) -> Scalar::NormzeroThe additive identity.
oneThe multiplicative identity.
from_f32Convert from f32 to this type.
from_f64Convert from f64 to this type — by default via an f32 roundtrip.
packPack sub-dimension scalars into a single storage value.
Functions
castCast source slice elements to destination slice.
pub fn cast<S: CastDType, D: CastDType>(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 castdest- Destination slice to receive cast elements; must be same length as source
Errors
Error::ShapeMismatchif slices have different lengthsError::KernelFailedcarrying 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);