# Sparse Operations

> NumKong for Rust

Sparse helpers cover both sorted-index intersection and weighted sparse dot products.

```rust
use numkong::{SparseIntersect, SparseDot};

let a_idx = [1_u32, 3, 5, 7];
let b_idx = [3_u32, 4, 5, 8];
let count = u32::sparse_intersection_size(&a_idx, &b_idx).unwrap();
assert_eq!(count, 2); // indices 3 and 5

let a_weights = [1.0_f32, 2.0, 3.0, 4.0];
let b_weights = [5.0_f32, 6.0, 7.0, 8.0];
let dot = u32::sparse_dot(&a_idx, &b_idx, &a_weights, &b_weights).unwrap();
assert!(dot > 0.0); // weighted dot over shared indices
```

`use numkong::SparseDot;`

`use numkong::SparseIntersect;`

## SparseDot

Computes sparse dot product between two sorted sparse vectors with weights.

```rust
pub trait SparseDot: Sized
```

Each vector consists of sorted indices and corresponding weights. The dot product is computed
over the intersection of indices, summing the products of weights.

Errors: [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) when no capability of the current
[`Capabilities`](https://www.unum.cloud/docs/numkong/rust/runtime-dispatch.md#Capabilities) has the kernel.

Implementors: - `impl [SparseDot](#SparseDot) for u16`
- `impl [SparseDot](#SparseDot) for u32`

## Weight

Weight type for this sparse dot product.

```rust
type Weight;
```

## Output

Output type for this sparse dot product.

```rust
type Output;
```

## sparse_dot

Computes sparse dot product.

```rust
fn sparse_dot(
    a_indices: &[Self],
    b_indices: &[Self],
    a_weights: &[Self::Weight],
    b_weights: &[Self::Weight],
) -> Result<Self::Output, Error>
```

Returns the sum of `a_weights[i] × b_weights[j]` for all pairs where `a_indices[i] == b_indices[j]`. A sparse vector carries one weight per index, so a weights slice shorter than
its index slice describes no vector at all and yields the default rather than reading past
its end.

## SparseIntersect

Computes set operations on sorted sparse vectors.

```rust
pub trait SparseIntersect: Sized
```

Errors: [`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) when no capability of the current
[`Capabilities`](https://www.unum.cloud/docs/numkong/rust/runtime-dispatch.md#Capabilities) has the kernel.

Implementors: - `impl [SparseIntersect](#SparseIntersect) for u16`
- `impl [SparseIntersect](#SparseIntersect) for u32`
- `impl [SparseIntersect](#SparseIntersect) for u64`

## sparse_intersection_size

Returns the intersection size between two sorted sparse vectors.

```rust
fn sparse_intersection_size(a: &[Self], b: &[Self]) -> Result<usize, Error>
```

## sparse_intersect_into

Computes intersection and writes matching elements to output buffer.

```rust
fn sparse_intersect_into(a: &[Self], b: &[Self], result: &mut [Self]) -> Result<usize, Error>
```

Buffer must be at least `min(a.len(), b.len())` in size.
Returns the number of elements written, or [`Error::CapacityExceeded`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#CapacityExceeded) if the buffer
is too small.