# Quickstart

> NumKong for Rust

```rust
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:

```rust
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.

`use numkong::Status;`

`use numkong::Error;`

## Status

What a NumKong call reports, C's `nk_status_t`, each variant holding the header's value.

```rust
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`](#Unrecognized).

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

Implements: `Clone`, `Copy`, `Debug`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Hash`, `Display`

## Error

Every failure a NumKong call reports, from shape checks in this crate to a kernel's status.

```rust
pub enum Error
```

- `AllocationFailed`: Memory 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.
- `NonContiguousRows`: Operation 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`](https://www.unum.cloud/docs/numkong/rust/maxsim.md#reserve) first.
- `SubByteUnsupported`: Operation 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`](#Status), like a matrix packed under other
capabilities than the current [`crate::Capabilities::cpu_enabled`](https://www.unum.cloud/docs/numkong/rust/runtime-dispatch.md#cpu_enabled).

Implements: `Debug`, `Clone`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Display`