# Dense Distances

> NumKong for Swift

The collection extensions are the lightest entry point.
They are a good fit for per-vector retrieval and ranking work.

```swift
import NumKong

let a: [Float16] = [1, 2, 3, 4]
let b: [Float16] = [4, 3, 2, 1]

let sqeuclidean = a.sqeuclidean(b) // widens to Float32
let euclidean = a.euclidean(b)
let angular = a.angular(b)

print(sqeuclidean as Any, euclidean as Any, angular as Any)
```

The widening is deliberate.
That is the main difference from a naive same-storage implementation.

`import NumKong`

## NumKongSpatial

Convenience alias for types supporting all four spatial distance metrics.

```swift
typealias NumKongSpatial = NumKongDot & NumKongAngular & NumKongEuclidean & NumKongSqEuclidean
```

## NumKongAngular

A type that can compute SIMD-accelerated angular distances, also known as cosine distances.

```swift
protocol NumKongAngular
```

Conforming types: `[BFloat16](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#BFloat16)`, `[E5M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E5M2)`, `[E4M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E4M3)`, `[E3M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E3M2)`, `[E2M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E2M3)`, `[I4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#I4x2)`, `[U4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U4x2)`, [`Double`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Double), [`Float`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float), [`Float16`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float16), [`Int8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Int8), [`UInt8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#UInt8)

## AngularOutput

The type the angular distance is returned in.

```swift
associatedtype AngularOutput
```

## angular

Computes the angular distance between two vectors.

```swift
static func angular<A, B>(
    _ a: A,
    _ b: B
) -> AngularOutput? where Self == A.Element, A : Sequence, B : Sequence, A.Element == B.Element
```

- `a`: The first vector.
- `b`: The second vector, as long as `a`.

## NumKongSqEuclidean

A type that can compute SIMD-accelerated squared Euclidean distances.

```swift
protocol NumKongSqEuclidean
```

Conforming types: `[BFloat16](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#BFloat16)`, `[E5M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E5M2)`, `[E4M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E4M3)`, `[E3M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E3M2)`, `[E2M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E2M3)`, `[I4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#I4x2)`, `[U4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U4x2)`, [`Double`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Double), [`Float`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float), [`Float16`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float16), [`Int8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Int8), [`UInt8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#UInt8)

## SqEuclideanOutput

The type the squared Euclidean distance is returned in.

```swift
associatedtype SqEuclideanOutput
```

## sqeuclidean

Computes the squared Euclidean distance between two vectors.

```swift
static func sqeuclidean<A, B>(
    _ a: A,
    _ b: B
) -> SqEuclideanOutput? where Self == A.Element, A : Sequence, B : Sequence, A.Element == B.Element
```

- `a`: The first vector.
- `b`: The second vector, as long as `a`.

## NumKongEuclidean

A type that can compute SIMD-accelerated Euclidean distances.

```swift
protocol NumKongEuclidean
```

Conforming types: `[BFloat16](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#BFloat16)`, `[E5M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E5M2)`, `[E4M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E4M3)`, `[E3M2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E3M2)`, `[E2M3](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E2M3)`, `[I4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#I4x2)`, `[U4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U4x2)`, [`Double`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Double), [`Float`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float), [`Float16`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Float16), [`Int8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#Int8), [`UInt8`](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#UInt8)

## EuclideanOutput

The type the Euclidean distance is returned in.

```swift
associatedtype EuclideanOutput
```

## euclidean

Computes the Euclidean distance between two vectors.

```swift
static func euclidean<A, B>(
    _ a: A,
    _ b: B
) -> EuclideanOutput? where Self == A.Element, A : Sequence, B : Sequence, A.Element == B.Element
```

- `a`: The first vector.
- `b`: The second vector, as long as `a`.