# Matrix Kernels

> NumKong for JavaScript

`import * as numkong from 'numkong';`

`import { PackedMatrix } from 'numkong';`

## PackedMatrix

Opaque packed matrix container.

```typescript
class PackedMatrix
```

Packed layout is not indexable — this is a data container for packed GEMM kernels.

- N-API path: buffer is a V8-managed ArrayBuffer, auto-freed by GC.

- WASM path: stores a heap pointer, `dispose()` calls Module._free().

## PackedMatrix

```typescript
new PackedMatrix(
    buffer: ArrayBuffer,
    columns: number,
    depth: number,
    dtype: DType,
    byteLength: number,
)
```

## dispose

```typescript
dispose(): void
```

## toString

```typescript
toString(): string
```

## columns

```typescript
readonly columns: number
```

## depth

```typescript
readonly depth: number
```

## dtype

```typescript
readonly dtype: DType
```

## byteLength

```typescript
readonly byteLength: number
```

## buffer

```typescript
readonly buffer: ArrayBuffer
```

## disposed

```typescript
readonly disposed: boolean
```

## dotsPackedSize

Queries the packed buffer's byte count for a matrix with the given __[columns,depth]__ and dtype, matching what [`dotsPack`](#dotsPack) would allocate.

```typescript
function dotsPackedSize(
    columns: number,
    depth: number,
    dtype: DType,
): number
```

- `columns`: Number of vectors being packed, the matrix rows.
- `depth`: Dimensionality per vector, the matrix columns.
- `dtype`: Element dtype of the source matrix.

## dotsPack

Packs a Matrix for use with packed GEMM-like operations, such as [`dotsPacked`](#dotsPacked).

```typescript
function dotsPack(matrix: Matrix): PackedMatrix
```

- `matrix`: The matrix to pack, __[rows,columns]__ shaped.

## dotsPacked

Computes the dot products between every row of `a` and every packed vector in `packed`.

```typescript
function dotsPacked(
    a: Matrix,
    packed: PackedMatrix,
    out?: Matrix,
): Matrix
```

- `a`: The query matrix, __[rows,columns]__ shaped, columns matching packed's depth.
- `packed`: The packed matrix produced by [`dotsPack`](#dotsPack).
- `out`: Optional output matrix to write into, __[a.rows,packed.columns]__ shaped.

## angularsPacked

Computes the angular distances between every row of `a` and every packed vector in `packed`.

```typescript
function angularsPacked(
    a: Matrix,
    packed: PackedMatrix,
    out?: Matrix,
): Matrix
```

- `a`: The query matrix, __[rows,columns]__ shaped, columns matching packed's depth.
- `packed`: The packed matrix produced by [`dotsPack`](#dotsPack).
- `out`: Optional output matrix to write into, __[a.rows,packed.columns]__ shaped.

## euclideansPacked

Computes the Euclidean distances between every row of `a` and every packed vector in `packed`.

```typescript
function euclideansPacked(
    a: Matrix,
    packed: PackedMatrix,
    out?: Matrix,
): Matrix
```

- `a`: The query matrix, __[rows,columns]__ shaped, columns matching packed's depth.
- `packed`: The packed matrix produced by [`dotsPack`](#dotsPack).
- `out`: Optional output matrix to write into, __[a.rows,packed.columns]__ shaped.

## dotsSymmetric

Computes the all-pairs dot products between every row of `vectors` and every other row.

```typescript
function dotsSymmetric(
    vectors: Matrix,
    out?: Matrix,
    options?: { rowsBegin?: number; rowsEnd?: number },
): Matrix
```

- `vectors`: The matrix of vectors, __[rows,columns]__ shaped.
- `out`: Optional output matrix to write into, __[vectors.rows,vectors.rows]__ shaped.
- `options`: Optional row range: `rowsBegin` and `rowsEnd` restrict which rows of the
symmetric matrix are computed, defaulting to all rows.

## angularsSymmetric

Computes the all-pairs angular distances between every row of `vectors` and every other row.

```typescript
function angularsSymmetric(
    vectors: Matrix,
    out?: Matrix,
    options?: { rowsBegin?: number; rowsEnd?: number },
): Matrix
```

- `vectors`: The matrix of vectors, __[rows,columns]__ shaped.
- `out`: Optional output matrix to write into, __[vectors.rows,vectors.rows]__ shaped.
- `options`: Optional row range: `rowsBegin` and `rowsEnd` restrict which rows of the
symmetric matrix are computed, defaulting to all rows.

## euclideansSymmetric

Computes the all-pairs Euclidean distances between every row of `vectors` and every other row.

```typescript
function euclideansSymmetric(
    vectors: Matrix,
    out?: Matrix,
    options?: { rowsBegin?: number; rowsEnd?: number },
): Matrix
```

- `vectors`: The matrix of vectors, __[rows,columns]__ shaped.
- `out`: Optional output matrix to write into, __[vectors.rows,vectors.rows]__ shaped.
- `options`: Optional row range: `rowsBegin` and `rowsEnd` restrict which rows of the
symmetric matrix are computed, defaulting to all rows.