# Highlights

> NumKong for Swift

__Collection-first scalar API.__
Plain `[Float32]`, `[Float16]`, `[Int8]`, `[U1x8]`, and other wrapper arrays work directly.
__Owning tensors.__
`Tensor<T>` owns its storage, produces views and spans without nested pointer closures, and drives the matrix kernel API.
__Explicit matrix views.__
`MatrixView` and `MatrixSpan` make strides and ownership visible.
__Reusable packed matrices.__
`PackedMatrix` owns its internal packed buffer and can be reused across repeated queries.
__Binary metrics.__
`U1x8` packs 8 bits per byte; Hamming and Jaccard kernels operate directly on those packed words.
__MaxSim and ColBERT-style late interaction.__
`MaxSimPackedMatrix` and `.maxSimPack()` cover token-level late-interaction scoring.
__No hidden output allocation.__
You own the result buffers for matrix kernels.
__Low-precision wrappers.__
Storage wrappers preserve exact bits for bf16 and mini-float formats.
__Unaligned caller buffers are fine.__
Packing handles internal layout itself.

### Ecosystem Comparison

| Feature                      | NumKong                                                                                                                | Accelerate/vDSP                                                   | [MLX][mlx]                                                         |
| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------- |
| Operation families           | dots, distances, binary, geospatial, MaxSim                                                                            | dots, distances, FFT, some BLAS                                   | matmul, elementwise, reductions, FFT                               |
| Precision                    | BFloat16 through sub-byte — Float8, Float6, packed bits; automatic widening; Kahan summation; 0 ULP in Float32/Float64 | Float32/Float64, limited Float16; no auto-widening; IEEE defaults | Float16/BFloat16/Float32; no Float8 or sub-byte; backend-dependent |
| Runtime SIMD dispatch        | per call, the highest capability the CPU runs and the build holds, across x86, Arm, RISC-V                             | Apple-only, no runtime ISA selection                              | GPU dispatch only, no CPU ISA selection                            |
| Packed matrix, GEMM-like     | `PackedMatrix` packs once, reused across query batches                                                                 | BLAS GEMM available                                               | GEMM via graph, implicit caching                                   |
| Symmetric kernels, SYRK-like | `dotsSymmetric`, `angularsSymmetric`, etc. skip duplicate pairs, up to 2x speedup                                      | `cblas_ssyrk` available for rank-k updates                        | no duplicate-pair skipping                                         |
| Collection-based API         | works with any `RandomAccessCollection` conforming type                                                                | pointer-based vDSP functions                                      | `MLXArray`-based                                                   |
| Memory model                 | caller-owned buffers; `Tensor`/`PackedMatrix` own their storage                                                        | caller-managed via `UnsafePointer`                                | graph-managed; implicit allocation and caching                     |

[mlx]: https://github.com/ml-explore/mlx