# Dense Distances

> NumKong for Rust

The dense spatial family covers `sqeuclidean`, `euclidean`, and `angular`.
The main value over naive loops is the combination of SIMD and safer accumulation policy.

```rust
use numkong::Euclidean;

let a = [1_i8, 2, 3, 4];
let b = [4_i8, 3, 2, 1];

let distance = i8::euclidean(&a, &b).unwrap(); // widened output, not int8
println!("{distance}");
```

`use numkong::Angular;`

`use numkong::Euclidean;`

`use numkong::SpatialSimilarity;`

## Angular

Computes the __angular distance__, also called cosine distance, between two vectors.

```rust
pub trait Angular: StorageElement
```

d = 1 − (a · b) / (‖a‖ × ‖b‖)

Range: [0, 2]. Fails with [`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch) if lengths differ, or
[`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status.

Implemented for: `f64`, `f32`, [`f16`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#f16), [`bf16`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#bf16), `i8`, `u8`, [`e4m3`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e4m3), [`e5m2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e5m2), [`e2m3`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e2m3), [`e3m2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e3m2),
[`i4x2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#i4x2), and [`u4x2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#u4x2).

Implementors: - `impl [Angular](#Angular) for f64`
- `impl [Angular](#Angular) for f32`
- `impl [Angular](#Angular) for [f16](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#f16)`
- `impl [Angular](#Angular) for [bf16](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#bf16)`
- `impl [Angular](#Angular) for i8`
- `impl [Angular](#Angular) for u8`
- `impl [Angular](#Angular) for [e4m3](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e4m3)`
- `impl [Angular](#Angular) for [e5m2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e5m2)`
- `impl [Angular](#Angular) for [e2m3](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e2m3)`
- `impl [Angular](#Angular) for [e3m2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e3m2)`
- `impl [Angular](#Angular) for [i4x2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#i4x2)`
- `impl [Angular](#Angular) for [u4x2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#u4x2)`

## Output

Result type of the angular distance.

```rust
type Output;
```

## angular

Computes the angular distance between two equally long slices.

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

## cosine

Alias for [`angular`](#angular).

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

## Euclidean

Computes the __Euclidean distance__, the L2 norm of the difference, between two vectors.

```rust
pub trait Euclidean: StorageElement
```

d = √(∑ᵢ (aᵢ − bᵢ)²)

Range: [0, ∞). Fails with [[`Error::ShapeMismatch`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#ShapeMismatch)] if lengths differ, or
[`Error::KernelFailed`](https://www.unum.cloud/docs/numkong/rust/quickstart.md#KernelFailed) carrying the kernel's status.

Implemented for: `f64`, `f32`, [`f16`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#f16), [`bf16`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#bf16), `i8`, `u8`, [`e4m3`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e4m3), [`e5m2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e5m2), [`e2m3`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e2m3), [`e3m2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e3m2),
[`i4x2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#i4x2), and [`u4x2`](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#u4x2).

Implementors: - `impl [Euclidean](#Euclidean) for f64`
- `impl [Euclidean](#Euclidean) for f32`
- `impl [Euclidean](#Euclidean) for [f16](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#f16)`
- `impl [Euclidean](#Euclidean) for [bf16](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#bf16)`
- `impl [Euclidean](#Euclidean) for i8`
- `impl [Euclidean](#Euclidean) for u8`
- `impl [Euclidean](#Euclidean) for [e4m3](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e4m3)`
- `impl [Euclidean](#Euclidean) for [e5m2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e5m2)`
- `impl [Euclidean](#Euclidean) for [e2m3](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e2m3)`
- `impl [Euclidean](#Euclidean) for [e3m2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#e3m2)`
- `impl [Euclidean](#Euclidean) for [i4x2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#i4x2)`
- `impl [Euclidean](#Euclidean) for [u4x2](https://www.unum.cloud/docs/numkong/rust/scalar-types.md#u4x2)`

## SqEuclideanOutput

Result type of the squared Euclidean distance.

```rust
type SqEuclideanOutput;
```

## EuclideanOutput

Result type of the Euclidean distance.

```rust
type EuclideanOutput;
```

## sqeuclidean

Squared Euclidean distance, i.e.

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

L2². Faster than [`euclidean`](#euclidean) for comparisons.

## euclidean

Euclidean distance, i.e.

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

L2. True metric distance.

## SpatialSimilarity

[`SpatialSimilarity`](#SpatialSimilarity) bundles spatial distance metrics: Dot, Angular, and Euclidean.

```rust
pub trait SpatialSimilarity: Dot + Angular + Euclidean
```

Implementors: - `impl<Scalar: [Dot](https://www.unum.cloud/docs/numkong/rust/dot-products.md#Dot) + [Angular](#Angular) + [Euclidean](#Euclidean)> [SpatialSimilarity](#SpatialSimilarity) for Scalar`