koblas

SparseMatrix

@Serializable
@SerialName(value = "SparseMatrix")
class SparseMatrix : MatrixStorage(source)

Compressed-sparse-column form: column j occupies colPointers(j) until colPointers(j + 1) of rowIndices and values, rows strictly ascending. A stored zero is preserved, and a 64-bit-index host library needs a widening copy.

Use copyColumnPointers, copyRowIndices, or forEachInColumn for safe structural access. colPointers and rowIndices are live zero-copy escape hatches for specialized kernels and require UnsafeKoblasApi; mutating them can invalidate the CSC structure. values remains live so coefficients can be updated without rebuilding the pattern; do not use the matrix as a hash-map key while mutating it. Inserting an entry through set or changing the pattern through Matrix.copyFrom replaces the buffers; obtain current arrays from the accessors after structural writes.

Types

Link copied to clipboard
object Companion

Factories for sparse matrices.

Properties

colPointers

Live column pointers; structural writes may replace this buffer. Do not mutate it.

cols

open override val cols: Int(source)

nnz

val nnz: Int(source)

Number of stored nonzeros.

rowIndices

Live row positions; structural writes may replace this buffer. Do not mutate it.

rows

open override val rows: Int(source)

values

Live coefficients; structural writes may replace this buffer.

Functions

columnView

A writable view of column, indexed from zero within this matrix. Changes through the vector update the matrix. The view borrows storage; use Vector.copy for an independent result. The vector follows this column after structural changes, including writes through other views.

copyColumnPointers

A copy of the CSC column start offsets, of length cols + 1.

copyRowIndices

A copy of the stored row indices, parallel to values.

equals

open operator override fun equals(other: Any?): Boolean(source)

Structural equality over the shape and the CSC arrays, so two matrices differing only in which explicit zeros they store are not equal.

forEachColumns

inline fun forEachColumns(block: (column: SparseVector) -> Unit)(source)

Visits writable column views in column order, including empty columns. Returns no new matrix.

forEachInColumn

inline fun forEachInColumn(j: Int, action: (row: Int, value: Double) -> Unit)(source)

Visits the stored entries of column j as (row, value), rows ascending.

get

open operator override fun get(i: Int, j: Int): Double(source)

Reads entry (i, j), or 0.0 where nothing is stored. A binary search over the column, so O(log nnzⱼ) and fine for a probe; sweep with forEachInColumn instead.

hashCode

open override fun hashCode(): Int(source)

set

open operator override fun set(i: Int, j: Int, v: Double)(source)

Writes an entry, inserting its position when absent. Explicitly written zeros remain stored.

toArray

open override fun toArray(): Array<DoubleArray>(source)

Materialises into a fresh rows × cols array of rows; unstored entries stay zero.

toString

open override fun toString(): String(source)
Link copied to clipboard
fun Matrix.columnView(column: Int): Vector

A writable vector view of column. Mutations update this matrix; the vector's indices are local rows. Built-in containers return DenseVector or SparseVector; other implementations use Matrix.get and Matrix.set. Use Vector.copy for independent storage.

Link copied to clipboard

An independent copy of the logical entries. Sparse storage keeps its pattern, including stored zeros; dense views and custom matrices produce owning dense storage. No backing arrays are shared.

Link copied to clipboard
fun Matrix.copyFrom(source: Matrix)

Copies source into this matrix, requiring equal shapes before writing. Inputs may share storage; overlapping or opaque sources are snapshotted first. Entries outside a destination view are untouched.

Link copied to clipboard
inline fun Matrix.forEachColumns(block: (column: Vector) -> Unit)

Visits writable column views in column order, including empty columns. Mutations through a callback's vector update this matrix. Concrete containers retain their dense or sparse callback type for calls to KoblasEngine; through Matrix, callbacks use the generic Vector contract. Returns no new matrix.

Link copied to clipboard
inline fun Matrix.forEachStored(block: (row: Int, col: Int, value: Double) -> Unit)

Visits stored entries as (row, column, value), columns first and rows ascending within each column. SparseMatrix visits only stored positions, including stored zeros; other implementations visit every entry. Dense views report local indices and exclude padding. Empty matrices invoke no callbacks.

Link copied to clipboard
fun Matrix.norm(type: Norm = Norm.Frobenius): Double

Matrix norm of type: Norm.Frobenius is the rescaled square root of the sum of squared entries, Norm.One is the largest absolute column sum, Norm.Infinity is the largest absolute row sum, and Norm.MaxAbs is the maximum absolute entry. A matrix with either dimension empty has norm zero.

Link copied to clipboard

Plain sum of all entries. Dense storage uses KoblasEngine.sum through the default koblas engine, sparse storage sums only its stored values, and custom matrices are read through Matrix.get. An empty matrix sums to zero. Summation order and rounding depend on the storage and engine.

Sums along axis into a fresh dense vector: axis = 0 reduces rows and returns Matrix.cols column sums; axis = 1 reduces columns and returns Matrix.rows row sums. A zero-length reduced dimension contributes zero to each result. The result owns its storage.

Link copied to clipboard

Fresh transposed matrix. Sparse storage remains CSC and preserves stored zeros; other implementations produce dense storage. Views transpose only their logical entries. For products, prefer the transpose flags on KoblasEngine.gemv and KoblasEngine.gemm to avoid materializing the transpose.