# Matrix Kernels

> NumKong for Swift

Packed kernels are the GEMM-like throughput path.
They are useful when the right-hand side is reused across many query batches.

```swift
import NumKong

let a = try Tensor<Float32>.fromArray([1, 2, 3, 4, 5, 6], rows: 2, columns: 3)
let b = try Tensor<Float32>.fromArray([7, 8, 9, 1, 0, 1], rows: 2, columns: 3)

let packed = try b.packForDots()           // PackedMatrix<Float32>, owned
let dots   = try a.dotsPacked(packed)      // Tensor<Float64>, 2x2
let angs   = try a.angularsPacked(packed)  // Tensor<Float64>, 2x2
let eucs   = try a.euclideansPacked(packed)// Tensor<Float64>, 2x2

assert(dots.rows == 2 && dots.columns == 2)
```

The free-function API (`dotsPacked`, `angularsPacked`, etc.) accepts `MatrixView`, `PackedMatrix`, and `MatrixSpan` directly for cases where you need manual buffer management — see the verbosity comparison in the Tensors section above.

### Symmetric Matrix Kernels

Symmetric kernels compute self-similarity or self-distance matrices.
They are the right shape for `SYRK`-like workloads and row-window partitioning.

```swift
import NumKong

let vectors = try Tensor<Float32>.fromArray([
    1, 0, 0,
    0, 1, 0,
    0, 0, 1,
], rows: 3, columns: 3)

let gram = try vectors.dotsSymmetric()       // Tensor<Float64>, 3x3
let dists = try vectors.euclideansSymmetric()// Tensor<Float64>, 3x3
let angs  = try vectors.angularsSymmetric()  // Tensor<Float64>, 3x3

assert(gram.rows == 3 && gram.columns == 3)
```

The free-function form (`dotsSymmetric`, `angularsSymmetric`, etc.) exposes `rowsBegin` and `rowsEnd` parameters for external partitioning.

`import NumKong`

## PackedMatrix

Owns a kernel-optimized packed copy of a matrix for batch distance computations.

```swift
final class PackedMatrix<Element>
```

Conforms to: `Sendable`

## rows

```swift
let rows: Int
```

## columns

```swift
let columns: Int
```

## byteCount

```swift
let byteCount: Int
```

## rawBuffer

Provides read-only access to the underlying packed bytes.

```swift
var rawBuffer: UnsafeRawBufferPointer { get }
```

## init

Packs the given matrix view into a kernel-optimized layout for batch dot products.

```swift
convenience init(packing matrix: MatrixView<Element>) throws where Element : NumKongDotsMatrixElement
```

```swift
convenience init(packing tensor: Tensor<Element>) throws where Element : NumKongDotsMatrixElement
```

Packs a tensor's storage into a kernel-optimized layout for batch dot products.

## shape

Reads the packed matrix shape, __[rows,columns]__, from the buffer's self-describing header.

```swift
var shape: (rows: Int, columns: Int) { get throws } where Element : NumKongDotsMatrixElement
```

## NumKongDotsMatrixElement

Element type that supports batch dot-product matrix operations.

```swift
protocol NumKongDotsMatrixElement
```

Conforming types: `[NumKongSpatialsMatrixElement](#NumKongSpatialsMatrixElement)`, `[NumKongSetsMatrixElement](#NumKongSetsMatrixElement)`, `[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)`, `[E2M1x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E2M1x2)`, `[I4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#I4x2)`, `[U4x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U4x2)`, `[U1x8](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U1x8)`, [`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)

## DotsOutput

The element type of the result matrices that [`dotsPacked`](#dotsPacked) and [`dotsSymmetric`](#dotsSymmetric) write.

```swift
associatedtype DotsOutput
```

## NumKongSpatialsMatrixElement

Element type that supports batch angular and Euclidean matrix operations.

```swift
protocol NumKongSpatialsMatrixElement : NumKongDotsMatrixElement
```

Conforms to: `[NumKongDotsMatrixElement](#NumKongDotsMatrixElement)`

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)`, `[E2M1x2](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#E2M1x2)`, `[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)

## SpatialOutput

The element type of the result matrices of the angular and Euclidean batch functions.

```swift
associatedtype SpatialOutput
```

## NumKongSetsMatrixElement

Element type that supports batch Hamming and Jaccard matrix operations.

```swift
protocol NumKongSetsMatrixElement : NumKongDotsMatrixElement
```

Conforms to: `[NumKongDotsMatrixElement](#NumKongDotsMatrixElement)`

Conforming types: `[U1x8](https://www.unum.cloud/docs/numkong/swift/scalar-types.md#U1x8)`

## HammingOutput

The element type of the result matrices that [`hammingsPacked`](#hammingsPacked) and [`hammingsSymmetric`](#hammingsSymmetric) write.

```swift
associatedtype HammingOutput
```

## JaccardOutput

The element type of the result matrices that [`jaccardsPacked`](#jaccardsPacked) and [`jaccardsSymmetric`](#jaccardsSymmetric) write.

```swift
associatedtype JaccardOutput
```

## dotsPacked

Computes dot products between each row of `a` and every row packed in `bPacked`.

```swift
func dotsPacked<Element>(
    _ a: MatrixView<Element>,
    _ bPacked: PackedMatrix<Element>,
    _ result: inout MatrixSpan<Element.DotsOutput>
) throws where Element : NumKongDotsMatrixElement
```

## dotsSymmetric

Computes the symmetric dot-product matrix for all row pairs in [`vectors`](https://www.unum.cloud/docs/numkong/swift/maxsim.md#vectors).

```swift
func dotsSymmetric<Element>(
    _ vectors: MatrixView<Element>,
    _ result: inout MatrixSpan<Element.DotsOutput>,
    rowsBegin: Int = 0,
    rowsEnd: Int? = nil
) throws where Element : NumKongDotsMatrixElement
```

## angularsPacked

Computes angular distances between each row of `a` and every row packed in `bPacked`.

```swift
func angularsPacked<Element>(
    _ a: MatrixView<Element>,
    _ bPacked: PackedMatrix<Element>,
    _ result: inout MatrixSpan<Element.SpatialOutput>
) throws where Element : NumKongSpatialsMatrixElement
```

## euclideansPacked

Computes Euclidean distances between each row of `a` and every row packed in `bPacked`.

```swift
func euclideansPacked<Element>(
    _ a: MatrixView<Element>,
    _ bPacked: PackedMatrix<Element>,
    _ result: inout MatrixSpan<Element.SpatialOutput>
) throws where Element : NumKongSpatialsMatrixElement
```

## angularsSymmetric

Computes the symmetric angular-distance matrix for all row pairs in [`vectors`](https://www.unum.cloud/docs/numkong/swift/maxsim.md#vectors).

```swift
func angularsSymmetric<Element>(
    _ vectors: MatrixView<Element>,
    _ result: inout MatrixSpan<Element.SpatialOutput>,
    rowsBegin: Int = 0,
    rowsEnd: Int? = nil
) throws where Element : NumKongSpatialsMatrixElement
```

## euclideansSymmetric

Computes the symmetric Euclidean-distance matrix for all row pairs in [`vectors`](https://www.unum.cloud/docs/numkong/swift/maxsim.md#vectors).

```swift
func euclideansSymmetric<Element>(
    _ vectors: MatrixView<Element>,
    _ result: inout MatrixSpan<Element.SpatialOutput>,
    rowsBegin: Int = 0,
    rowsEnd: Int? = nil
) throws where Element : NumKongSpatialsMatrixElement
```

## hammingsPacked

Computes Hamming distances between each row of `a` and every row packed in `bPacked`.

```swift
func hammingsPacked<Element>(
    _ a: MatrixView<Element>,
    _ bPacked: PackedMatrix<Element>,
    _ result: inout MatrixSpan<Element.HammingOutput>
) throws where Element : NumKongSetsMatrixElement
```

## hammingsSymmetric

Computes the symmetric Hamming-distance matrix for all row pairs in [`vectors`](https://www.unum.cloud/docs/numkong/swift/maxsim.md#vectors).

```swift
func hammingsSymmetric<Element>(
    _ vectors: MatrixView<Element>,
    _ result: inout MatrixSpan<Element.HammingOutput>,
    rowsBegin: Int = 0,
    rowsEnd: Int? = nil
) throws where Element : NumKongSetsMatrixElement
```

## jaccardsPacked

Computes Jaccard distances between each row of `a` and every row packed in `bPacked`.

```swift
func jaccardsPacked<Element>(
    _ a: MatrixView<Element>,
    _ bPacked: PackedMatrix<Element>,
    _ result: inout MatrixSpan<Element.JaccardOutput>
) throws where Element : NumKongSetsMatrixElement
```

## jaccardsSymmetric

Computes the symmetric Jaccard-distance matrix for all row pairs in [`vectors`](https://www.unum.cloud/docs/numkong/swift/maxsim.md#vectors).

```swift
func jaccardsSymmetric<Element>(
    _ vectors: MatrixView<Element>,
    _ result: inout MatrixSpan<Element.JaccardOutput>,
    rowsBegin: Int = 0,
    rowsEnd: Int? = nil
) throws where Element : NumKongSetsMatrixElement
```