Rust · Quickstart

Quickstart

use numkong::Status;use numkong::Error; 8.0.0-rc.1 · b1f866ab

use numkong::{Capabilities, Dot};

fn main() {
    Capabilities::cpu_enabled().configure_thread().unwrap();
    let a = [1.0_f32, 2.0, 3.0];
    let b = [4.0_f32, 5.0, 6.0];
    let dot = f32::dot(&a, &b).unwrap();
    println!("dot={dot}");
}

§ Core Traits

The crate root re-exports the main metric families:

  • Dot, VDot, Angular, Euclidean
  • Hamming, Jaccard
  • KullbackLeibler, JensenShannon
  • SqEuclideans3D
  • Bilinear, Mahalanobis
  • ReduceMoments, ReduceMinMax
  • EachScale, EachSum, EachBlend, EachFma

The standard call shape is:

use numkong::{Dot, JensenShannon, Jaccard, u1x8};

let a = [1.0_f32, 2.0, 3.0];
let b = [4.0_f32, 5.0, 6.0];
let dot = f32::dot(&a, &b).unwrap();

let bits_a = [u1x8(0b11110000), u1x8(0b00001111)];
let bits_b = [u1x8(0b11110000), u1x8(0b11110000)];
let jaccard = u1x8::jaccard(&bits_a, &bits_b).unwrap();

let p = [0.2_f32, 0.3, 0.5];
let q = [0.1_f32, 0.3, 0.6];
let jsd = f32::jensenshannon(&p, &q).unwrap();

println!("{dot} {jaccard} {jsd}");

Every slice kernel returns a Result, failing with Error::ShapeMismatch when operand lengths differ and with Error::KernelFailed carrying the kernel’s Status when it refuses its operands. ReduceMinMax returns Ok(None) for an all-NaN input, which is an empty result rather than a failure.

API

EnumStatusWhat a NumKong call reports, C's nk_status_t, each variant holding the header's value.
capabilities.rs:100 ↗
pub enum Status

Zero is success, and a negative value means the call wrote nothing. A code the header this crate was built from does not list, like the positive values C reserves for results written with a caveat, reads as Status::Unrecognized.

Values

Success0nk_success_k: scheduled, or finished, without error.
BadAlloc-10nk_bad_alloc_k: the queue could not take more memory, or record another block.
UnexpectedDimensions-15nk_unexpected_dimensions_k: operand shapes contradict each other.
MissingGpu-16nk_missing_gpu_k: no GPU of the vendor this build targets answers.
DeviceCodeMismatch-17nk_device_code_mismatch_k: the device code lacks the kernel, or it failed to run.
DeviceMemoryMismatch-18nk_device_memory_mismatch_k: an operand lies in memory the device cannot address.
MissingKernel-19nk_missing_kernel_k: no capability in the capability mask has this kernel.
Misaligned-20nk_misaligned_k: an operand or stride breaks the alignment contract.
PackMismatch-21nk_pack_mismatch_k: the buffer was packed by another capability or layout.
MissingLibrary-22nk_missing_library_k: a dispatch point called from a build that links no library.
Unrecognizedi32::MINA code outside this list, which only a library built from another header returns.

Implements

Clone, Copy, Debug, StructuralPartialEq, PartialEq, Eq, Hash, Display
EnumErrorEvery failure a NumKong call reports, from shape checks in this crate to a kernel's status.
tensor.rs:431 ↗
pub enum Error

Values

AllocationFailedMemory allocation failed.
ShapeMismatch{ axis: usize, expected: usize, got: usize }Shape mismatch: axis axis has size expected on one side and got on the other.
InvalidShape{ axis: usize, size: usize, reason: &'static str }Invalid shape specification.
NonContiguousRowsOperation requires contiguous rows but array has non-contiguous rows.
DimensionMismatch{ expected: usize, got: usize }Expected a specific number of dimensions.
IndexOutOfBounds{ index: usize, size: usize }Index out of bounds.
TooManyRanks{ got: usize }Too many dimensions — exceeds MAX_RANK.
CapacityExceeded{ requested: usize, capacity: usize }A resize would exceed the fixed allocated capacity; grow the buffer via reserve first.
SubByteUnsupportedOperation not supported for sub-byte types: i4x2, u4x2, u1x8.
KernelFailed{ status: <a data-ref="Status">Status</a> }A kernel refused its operands with this Status, like a matrix packed under other capabilities than the current crate::Capabilities::cpu_enabled.

Implements

Debug, Clone, StructuralPartialEq, PartialEq, Eq, Display