struct MatrixView<Element>Tensor<T> is the owning two-dimensional type.
It allocates its own buffer, handles deallocation on deinit, and produces non-owning views and spans without nesting withUnsafeBufferPointer closures.
import NumKong
// From an existing array:
let t = try Tensor<Float32>.fromArray([1, 2, 3, 4, 5, 6], rows: 2, columns: 3)
// Zero-initialized:
let z = try Tensor<Float32>.zeros(rows: 4, columns: 768)
// Constant fill:
let c = try Tensor<Float32>.full(rows: 4, columns: 768, value: 1.0)
// Subscript access:
let v = t[0, 2] // row 0, col 2
// Row buffer access:
let row1 = t.row(1) // UnsafeBufferPointer<Float32>
// Non-owning views:
let view: MatrixView<Float32> = t.view() // immutable
let span: MatrixSpan<Float32> = t.span() // mutableTensor<T> is fixed-capacity resizable. capacity reports the allocated element ceiling. tryResize(rows:columns:) reshapes within capacity without moving storage, so an existing view(), span(), or row() stays valid. reserve(_:) may reallocate to grow, which invalidates any view, span, or row pointer obtained earlier. clear() empties the tensor while keeping capacity.
The view/span split is the same aliasing discipline used throughout the binding. MatrixView is non-owning and immutable. MatrixSpan is non-owning and mutable.
Neither allocates.
The ownership model is explicit:
MatrixView<Element>is a non-owning immutable view.MatrixSpan<Element>is a non-owning mutable view.PackedMatrix<Element>owns one internal packed buffer and deallocates it ondeinit.Tensor<Element>owns its element storage and deallocates it ondeinit.
PackedMatrix allocates its internal payload with UnsafeMutableRawPointer.allocate(byteCount:alignment:).
The alignment is 64 bytes for the owned packed buffer.
That does not mean your source matrix must be aligned.
Packing accepts ordinary Swift-managed buffers and handles the internal layout itself.
The Tensor API eliminates the nested closure structure required when working directly with Swift’s withUnsafeBufferPointer.
The difference in call-site verbosity is significant for anything more than a single kernel call:
// Without Tensor — three nested closures just to call one kernel
try a.withUnsafeBufferPointer { aPtr in
try b.withUnsafeBufferPointer { bPtr in
try out.withUnsafeMutableBufferPointer { outPtr in
let aView = MatrixView(baseAddress: aPtr.baseAddress!, rows: 2, columns: 3)
let bView = MatrixView(baseAddress: bPtr.baseAddress!, rows: 2, columns: 3)
var cSpan = MatrixSpan(baseAddress: outPtr.baseAddress!, rows: 2, columns: 2)
let packed = try PackedMatrix<Float32>(packing: bView)
try dotsPacked(aView, packed, &cSpan)
}
}
}
// With Tensor — no closures at the call site
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()
let c = try a.dotsPacked(packed) // returns Tensor<Float64>API
StructMatrixViewNon-owning, immutable view over a row-major matrix stored in contiguous memory.5
baseAddress
let baseAddress: UnsafePointer<Element>rows
let rows: Intcolumns
let columns: IntrowStrideBytes
let rowStrideBytes: Intinit
init(baseAddress: UnsafePointer<Element>, rows: Int, columns: Int, rowStrideBytes: Int? = nil)StructMatrixSpanNon-owning, mutable view over a row-major matrix stored in contiguous memory.5
struct MatrixSpan<Element>baseAddress
let baseAddress: UnsafeMutablePointer<Element>rows
let rows: Intcolumns
let columns: IntrowStrideBytes
let rowStrideBytes: Intinit
init(baseAddress: UnsafeMutablePointer<Element>, rows: Int, columns: Int, rowStrideBytes: Int? = nil)ClassTensorOwning, row-major dense matrix that deallocates its memory on deinit.24
rows
var rows: Int { get }columns
var columns: Int { get }capacityAllocated element capacity (>= count) — the ceiling tryResize honors.
var capacity: Int { get }count
var count: Int { get }shape
var shape: (rows: Int, columns: Int) { get }fromArrayCreates a tensor by copying elements from a flat array into owned memory.
static func fromArray(_ data: [Element], rows: Int, columns: Int) throws -> TensorfullCreates a tensor filled with a repeating value.
static func full(rows: Int, columns: Int, value: Element) throws -> Tensor*× 4
tryResizeResizes within the allocated capacity without moving storage, so existing view(), span(), and row() results stay valid.
@discardableResult func tryResize(rows newRows: Int, columns newColumns: Int) -> BoolReturns
false, leaving the tensor unchanged, if either extent is negative or rows * columns exceeds capacity; call reserve(_:) first to grow.reserveGrows capacity to at least minimumCapacity, reallocating and copying the live elements.
func reserve(_ minimumCapacity: Int)A no-op when already large enough.
Warning
This may move storage, invalidating any outstanding view(), span(), or row() pointers obtained before the call.
clearResets to an empty 0×0 tensor while keeping the allocated capacity.
func clear()zerosCreates a zero-filled tensor.
static func zeros(
rows: Int,
columns: Int
) throws -> Tensor where Element : ExpressibleByIntegerLiteralpackForDotsPacks this tensor into a kernel-optimized layout for batch dot products.
func packForDots() throws -> PackedMatrix<Element> where Element : NumKongDotsMatrixElementdotsPackedComputes dot products between this tensor's rows and a packed matrix, owning the result.
func dotsPacked(
_ packed: PackedMatrix<Element>
) throws -> Tensor<Element.DotsOutput> where Element : NumKongDotsMatrixElementdotsSymmetricComputes the symmetric dot-product matrix for all row pairs, returning an owned result.
func dotsSymmetric(
rowsBegin: Int = 0,
rowsEnd: Int? = nil
) throws -> Tensor<Element.DotsOutput> where Element : NumKongDotsMatrixElementangularsPackedComputes angular distances between this tensor's rows and a packed matrix.
func angularsPacked(
_ packed: PackedMatrix<Element>
) throws -> Tensor<Element.SpatialOutput> where Element : NumKongSpatialsMatrixElementeuclideansPackedComputes Euclidean distances between this tensor's rows and a packed matrix.
func euclideansPacked(
_ packed: PackedMatrix<Element>
) throws -> Tensor<Element.SpatialOutput> where Element : NumKongSpatialsMatrixElementangularsSymmetricComputes the symmetric angular-distance matrix for all row pairs.
func angularsSymmetric(
rowsBegin: Int = 0,
rowsEnd: Int? = nil
) throws -> Tensor<Element.SpatialOutput> where Element : NumKongSpatialsMatrixElementeuclideansSymmetricComputes the symmetric Euclidean-distance matrix for all row pairs.
func euclideansSymmetric(
rowsBegin: Int = 0,
rowsEnd: Int? = nil
) throws -> Tensor<Element.SpatialOutput> where Element : NumKongSpatialsMatrixElementhammingsPackedComputes Hamming distances between this tensor's rows and a packed matrix.
func hammingsPacked(
_ packed: PackedMatrix<Element>
) throws -> Tensor<Element.HammingOutput> where Element : NumKongSetsMatrixElementhammingsSymmetricComputes the symmetric Hamming-distance matrix for all row pairs.
func hammingsSymmetric(
rowsBegin: Int = 0,
rowsEnd: Int? = nil
) throws -> Tensor<Element.HammingOutput> where Element : NumKongSetsMatrixElementjaccardsPackedComputes Jaccard distances between this tensor's rows and a packed matrix.
func jaccardsPacked(
_ packed: PackedMatrix<Element>
) throws -> Tensor<Element.JaccardOutput> where Element : NumKongSetsMatrixElementjaccardsSymmetricComputes the symmetric Jaccard-distance matrix for all row pairs.
func jaccardsSymmetric(
rowsBegin: Int = 0,
rowsEnd: Int? = nil
) throws -> Tensor<Element.JaccardOutput> where Element : NumKongSetsMatrixElementmaxSimPackPacks this tensor into a MaxSim-optimized layout for late-interaction scoring.
func maxSimPack() throws -> MaxSimPackedMatrix<Element> where Element : NumKongMaxSimElementProtocolRandomAccessCollection6
extension RandomAccessCollectiondotComputes the SIMD-accelerated dot product with another sequence.
func dot<B>(
_ b: B
) -> Element.DotOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongDotangularComputes the SIMD-accelerated angular, or cosine, distance to another sequence.
func angular<B>(
_ b: B
) -> Element.AngularOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongAngulareuclideanComputes the SIMD-accelerated Euclidean distance to another sequence.
func euclidean<B>(
_ b: B
) -> Element.EuclideanOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongEuclideansqeuclideanComputes the SIMD-accelerated squared Euclidean distance to another sequence.
func sqeuclidean<B>(
_ b: B
) -> Element.SqEuclideanOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongSqEuclideanhammingComputes the SIMD-accelerated Hamming distance to another sequence.
func hamming<B>(
_ b: B
) -> Element.HammingOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongHammingjaccardComputes the SIMD-accelerated Jaccard distance to another sequence.
func jaccard<B>(
_ b: B
) -> Element.JaccardOutput? where B : Sequence, Self.Element == B.Element, Self.Element : NumKongJaccard