The output type is intentionally wider than the storage type for most operations. The table below documents the promotion for scalar collection extensions.
| Input type | .dot() | .angular() | .euclidean() | .sqeuclidean() | .hamming() | .jaccard() |
|---|---|---|---|---|---|---|
Float64 | Float64 | Float64 | Float64 | Float64 | … | … |
Float32 | Float64 | Float64 | Float64 | Float64 | … | … |
BFloat16 | Float32 | Float32 | Float32 | Float32 | … | … |
Float16 | Float32 | Float32 | Float32 | Float32 | … | … |
Int8 | Int32 | Float32 | Float32 | UInt32 | … | … |
I4x2 | Int32 | Float32 | Float32 | UInt32 | … | … |
UInt8 | UInt32 | Float32 | Float32 | UInt32 | … | … |
U4x2 | UInt32 | Float32 | Float32 | UInt32 | … | … |
U1x8 | … | … | … | … | UInt32 | Float32 |
The matrix kernel output types follow a similar pattern but vary for the mini-float formats:
| Input type | Dots output | Spatial output | Hamming output | Jaccard output |
|---|---|---|---|---|
Float64 | Float64 | Float64 | … | … |
Float32 | Float64 | Float64 | … | … |
BFloat16 | Float32 | Float32 | … | … |
Float16 | Float32 | Float32 | … | … |
E5M2 | Float32 | Float32 | … | … |
E4M3 | Float32 | Float32 | … | … |
E3M2 | Float32 | Float32 | … | … |
E2M3 | Float32 | Float32 | … | … |
Int8 | Int32 | Float32 | … | … |
I4x2 | Int32 | Float32 | … | … |
UInt8 | UInt32 | Float32 | … | … |
U4x2 | UInt32 | Float32 | … | … |
U1x8 | UInt32 | … | UInt32 | Float32 |
Swift has no built-in bf16, mini-float, or packed-bit scalar types. NumKong ships storage wrappers instead.
BFloat16 — 1+8+7 bit layout (sign + exponent + mantissa), 2 bytes.
Same dynamic range as Float32 with reduced precision.
Supports NaN and Inf.E5M2 — 1+5+2 bit layout, 1 byte.
Range ±57344.
Supports Inf and NaN.E4M3 — 1+4+3 bit layout, 1 byte.
Range ±448.
No Inf representation; NaN is encoded only as 0x7F or 0xFF.E3M2 — 1+3+2 bit layout, 1 byte (6 bits used).
Range ±28.
No Inf, no NaN.E2M3 — 1+2+3 bit layout, 1 byte (6 bits used).
Range ±7.5.
No Inf, no NaN.I4x2 and U4x2 — two 4-bit lanes per byte, high nibble first.
Signed lanes span -8…7, unsigned 0…15; first and second unpack them and init(first:second:) packs them, with first in the high nibble.
Supports dot, angular, and Euclidean scalar and matrix kernels.U1x8 — 8 packed bits per byte.
Used for binary embeddings and semantic hashing.
Supports Hamming and Jaccard scalar and matrix kernels.Every floating-point wrapper provides init(bitPattern:), init(float:), and var float: Float32.
All are @frozen, Equatable, Hashable, Sendable. U1x8, I4x2, and U4x2 provide init(bitPattern:) and expose their underlying UInt8 value.
These wrappers are exact-storage types first.
They are there to preserve bits and make the native kernels callable from Swift.
They are not pretending to be standard-library numeric types.
BFloat16Brain floating-point: 16-bit storage with 8-bit exponent, used in ML inference.12@frozen struct BFloat16NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongMaxSimElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, ExpressibleByFloatLiteral, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32MaxSimOutputtypealias MaxSimOutput = Float32bitPatternvar bitPattern: UInt16initfloatvar float: Float32 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Float32*× 51static func dot<A, B>(
_ a: A,
_ b: B
) -> Float32? where A : Sequence, B : Sequence, A.Element == BFloat16, B.Element == BFloat16| Symbol |
|---|
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
hamming |
jaccard |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
dot |
angular |
euclidean |
sqeuclidean |
AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32E5M2FP8 E5M2 format with 5-bit exponent and 2-bit mantissa, used in gradient storage.10@frozen struct E5M2NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, ExpressibleByFloatLiteral, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initfloatvar float: Float32 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Float32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32E4M3FP8 E4M3 format with 4-bit exponent and 3-bit mantissa, used in transformer inference.10@frozen struct E4M3NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, ExpressibleByFloatLiteral, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initfloatvar float: Float32 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Float32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32E3M2MX E3M2 format with 3-bit exponent and 2-bit mantissa.10@frozen struct E3M2NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, ExpressibleByFloatLiteral, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initfloatvar float: Float32 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Float32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32E2M3MX E2M3 format with 2-bit exponent and 3-bit mantissa.10@frozen struct E2M3NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, ExpressibleByFloatLiteral, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initfloatvar float: Float32 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Float32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32I4x2Packed pair of 4-bit signed integers, [high nibble : low nibble], each in -8...7.11@frozen struct I4x2NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Int32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initPacks two lanes, first into the high nibble, keeping the low four bits of each.init(_ bits: UInt8)init(bitPattern: UInt8)init(first: Int8, second: Int8)Packs two lanes, first into the high nibble, keeping the low four bits of each.
firstThe first lane, in the high nibble, sign-extended.var first: Int8 { get }secondThe second lane, in the low nibble, sign-extended.var second: Int8 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = Int32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = UInt32U4x2Packed pair of 4-bit unsigned integers, [high nibble : low nibble], each in 0...15.11@frozen struct U4x2NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = UInt32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initPacks two lanes, first into the high nibble, keeping the low four bits of each.init(_ bits: UInt8)init(bitPattern: UInt8)init(first: UInt8, second: UInt8)Packs two lanes, first into the high nibble, keeping the low four bits of each.
firstThe first lane, in the high nibble.var first: UInt8 { get }secondThe second lane, in the low nibble.var second: UInt8 { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = UInt32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = UInt32E2M1x2Packed pair of 4-bit E2M1 floats, [high nibble : low nibble], each of 1 sign, 2 exponent and 1 mantissa bits.7@frozen struct E2M1x2NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertibleDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32bitPatternvar bitPattern: UInt8initPacks two lane codes, first into the high nibble, keeping the low four bits of each.init(_ bits: UInt8)init(bitPattern: UInt8)init(first: UInt8, second: UInt8)Packs two lane codes, first into the high nibble, keeping the low four bits of each.
firstThe first lane code, in the high nibble.var first: UInt8 { get }secondThe second lane code, in the low nibble.var second: UInt8 { get }descriptionvar description: String { get }U1x8Packed 8-bit binary vector element for Hamming and Jaccard distance computations.8@frozen struct U1x8NumKongDotsMatrixElement, NumKongSetsMatrixElement, Equatable, Hashable, Sendable, BitwiseCopyable, CustomStringConvertible, NumKongDot, NumKongHamming, NumKongJaccardDotsOutputtypealias DotsOutput = UInt32HammingOutputtypealias HammingOutput = UInt32JaccardOutputtypealias JaccardOutput = Float32bitPatternvar bitPattern: UInt8initpopcountvar popcount: Int { get }descriptionvar description: String { get }DotOutputtypealias DotOutput = UInt32Double8extension Double : NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongHaversines, NumKongVincentys, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanhaversinesstatic func haversines(
aLatitudes: UnsafeBufferPointer<Float64>,
aLongitudes: UnsafeBufferPointer<Float64>,
bLatitudes: UnsafeBufferPointer<Float64>,
bLongitudes: UnsafeBufferPointer<Float64>,
results: UnsafeMutableBufferPointer<Float64>
) -> Boolstatic func haversines<A, B, C, D>(
aLatitudes: A,
aLongitudes: B,
bLatitudes: C,
bLongitudes: D
) -> [Float64]? where A : Sequence, B : Sequence, C : Sequence, D : Sequence, A.Element == Double, B.Element == Double, C.Element == Double, D.Element == Doublevincentysstatic func vincentys(
aLatitudes: UnsafeBufferPointer<Float64>,
aLongitudes: UnsafeBufferPointer<Float64>,
bLatitudes: UnsafeBufferPointer<Float64>,
bLongitudes: UnsafeBufferPointer<Float64>,
results: UnsafeMutableBufferPointer<Float64>
) -> Boolstatic func vincentys<A, B, C, D>(
aLatitudes: A,
aLongitudes: B,
bLatitudes: C,
bLongitudes: D
) -> [Float64]? where A : Sequence, B : Sequence, C : Sequence, D : Sequence, A.Element == Double, B.Element == Double, C.Element == Double, D.Element == DoubleDotsOutputtypealias DotsOutput = Float64SpatialOutputtypealias SpatialOutput = Float64DotOutputtypealias DotOutput = Float64AngularOutputtypealias AngularOutput = Float64EuclideanOutputtypealias EuclideanOutput = Float64SqEuclideanOutputtypealias SqEuclideanOutput = Float64Float7extension Float : NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongMaxSimElement, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float64SpatialOutputtypealias SpatialOutput = Float64MaxSimOutputtypealias MaxSimOutput = Float64DotOutputtypealias DotOutput = Float64AngularOutputtypealias AngularOutput = Float64EuclideanOutputtypealias EuclideanOutput = Float64SqEuclideanOutputtypealias SqEuclideanOutput = Float64Float167extension Float16 : NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongMaxSimElement, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Float32SpatialOutputtypealias SpatialOutput = Float32MaxSimOutputtypealias MaxSimOutput = Float32DotOutputtypealias DotOutput = Float32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = Float32Int86extension Int8 : NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = Int32SpatialOutputtypealias SpatialOutput = Float32DotOutputtypealias DotOutput = Int32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = UInt32UInt86extension UInt8 : NumKongDotsMatrixElement, NumKongSpatialsMatrixElement, NumKongDot, NumKongAngular, NumKongEuclidean, NumKongSqEuclideanDotsOutputtypealias DotsOutput = UInt32SpatialOutputtypealias SpatialOutput = Float32DotOutputtypealias DotOutput = UInt32AngularOutputtypealias AngularOutput = Float32EuclideanOutputtypealias EuclideanOutput = Float32SqEuclideanOutputtypealias SqEuclideanOutput = UInt32