koblas

KoblasEngine

interface KoblasEngine(source)

Dense and sparse BLAS through one immutable engine.

BLAS routines are typed members. The portable engine runs the shared schedule over its own kernels; a built-in engine such as koblas uses one optional host library above its cutoffs and otherwise runs the same schedule over its owned kernels; a vendor engine from KoblasEngine.vendor calls its library for the routines it exports and fails for the rest. The companion names exact engines, while koblas selects its platform default unless startup configuration overrides it.

Operands are typed containers; dense views retain their offsets and strides. Routines validate logical dimensions and preserve BLAS no-read rules. Copies, AXPY and matrix operations stage destructive aliases, borrowing from a Scratch when one is given. Rotations and swaps have their own overlap requirements. Primitive array windows stay internal. Rounding, reduction order and unspecified exceptional results belong to the selected arithmetic.

Types

Link copied to clipboard
object Companion

Exact engines for tests and comparisons, also assignable to koblas during startup.

Properties

id

open val id: String(source)

Stable provider identifier for diagnostics and internal routing.

implementations

Callbacks supplied by this provider. Shared matrix schedules select arithmetic directly from leaf providers.

libraryPath

Resolved host library, when applicable.

name

abstract val name: String(source)

Implementation identifier for diagnostics.

providers

Kernel providers and the selected host library, including capabilities and host provenance.

threadEvidence

Evidence for the host library's compute thread count.

vendor

open val vendor: Vendor?(source)

Library provenance, when applicable.

version

open val version: String(source)

Host library version, when applicable.

Functions

asum

open fun asum(v: DenseVector): Double(source)

Sum of absolute values of stored entries, or zero for an empty vector.

axpy

open fun axpy(alpha: Double, x: DenseVector, y: DenseVector)(source)
open fun axpy(alpha: Double, x: DenseVector, y: SparseVector)(source)
open fun axpy(alpha: Double, x: SparseVector, y: DenseVector)(source)
open fun axpy(alpha: Double, x: SparseVector, y: SparseVector)(source)

Adds alpha * x into equally sized y; zero alpha reads no entries and aliases are staged.

copy

Copies a into equally sized b, preserving sparse source structure and staging destructive aliases.

dot

Dot product of equally sized vectors; sparse operands evaluate only stored positions.

dotColumn

open fun dotColumn(matrix: SparseMatrix, column: Int, dense: DenseVector): Double(source)

Dot product of column with equally sized dense. Only stored matrix entries participate, including stored zeros.

gather

open fun gather(source: DenseVector, destination: SparseVector)(source)

Reads source at destination's stored indices. The vectors must have equal sizes and distinct coefficient buffers.

gatherZero

open fun gatherZero(source: DenseVector, destination: SparseVector)(source)

Reads and zeroes source at destination's stored indices, with the size and buffer requirements of gather.

gemm

open fun gemm(alpha: Double, a: DenseMatrix, transposeA: Boolean, b: DenseMatrix, transposeB: Boolean, beta: Double, c: DenseMatrix, scratch: Scratch? = null)(source)

C = alpha · op(A) · op(B) + beta · C (BLAS dgemm), with shapes op(A): m×k, op(B): k×n, C: m×n.

An input that shares c's storage is snapshotted first. A zero alpha or an empty shared dimension scales c and reads no operand; a zero beta overwrites c without reading it.

Scaling placement and accumulation order depend on the selected implementation, including whether alpha scales operand entries or partial sums, so rounding, overflow and non-finite results may differ between implementations and transpose modes.


open fun gemm(alpha: Double, a: SparseMatrix, transposeA: Boolean, b: DenseMatrix, transposeB: Boolean, beta: Double, c: DenseMatrix, right: Boolean = false, scratch: Scratch? = null)(source)

C = alpha · op(A) · op(B) + beta · C (Sparse BLAS usmm) for a sparse a against a dense b, or C = alpha · op(B) · op(A) + beta · C when right. A zero beta overwrites c without reading it.

right exists because a is distinguished by being the sparse operand and cannot be swapped, so without a side the product of a dense matrix by a sparse one would only be reachable by transposing the result.

gemmt

open fun gemmt(alpha: Double, a: DenseMatrix, transposeA: Boolean, b: DenseMatrix, transposeB: Boolean, beta: Double, c: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

C = alpha · op(A) · op(B) + beta · C in only the selected triangle (Netlib GEMMTR, commonly exposed as gemmt). op(A) is n×k, op(B) is k×n, and c is n×n. The opposite triangle is neither read nor written. Overlap and multipliers follow gemm.

gemv

open fun gemv(alpha: Double, a: DenseMatrix, x: DenseVector, beta: Double, y: DenseVector, transpose: Boolean = false, scratch: Scratch? = null)(source)
open fun gemv(alpha: Double, a: SparseMatrix, x: DenseVector, beta: Double, y: DenseVector, transpose: Boolean = false, scratch: Scratch? = null)(source)

y = alpha * op(A) * x + beta * y. Views retain their offsets and strides; aliases are staged. A zero alpha reads neither matrix nor input vector, and a zero beta overwrites y without reading it. transpose selects the transposed matrix.

ger

open fun ger(alpha: Double, x: DenseVector, y: DenseVector, a: DenseMatrix, scratch: Scratch? = null)(source)

Adds alpha * x * yᵀ to a, requiring matching logical dimensions and staging aliased inputs.

iamax

open fun iamax(v: DenseVector): Int(source)

Logical index of a maximum-magnitude entry, or minus one when empty. Ties and NaNs follow the selected kernel.

nrm2

open fun nrm2(v: DenseVector): Double(source)

Rescaled Euclidean norm; sparse storage reduces only its stored values. An empty vector has norm zero.

rot

open fun rot(x: DenseVector, y: DenseVector, c: Double, s: Double)(source)

Plane rotation of equally sized vectors. Equal mappings are safe; callers must stage other destructive overlaps.

scale

open fun scale(v: DenseVector, alpha: Double)(source)
open fun scale(v: SparseVector, alpha: Double)(source)

Scales stored entries in place, preserving views and sparse structure. Non-finite behavior follows the selected kernel.

scatter

open fun scatter(source: SparseVector, destination: DenseVector)(source)

Writes stored source entries into destination, leaving absent positions untouched. Aliased sources are staged.

sum

open fun sum(v: DenseVector): Double(source)
open fun sum(v: SparseVector): Double(source)

Plain sum of stored entries. Reduction order and rounding follow the selected kernel.

swap

Exchanges equally sized vectors. Callers must stage destructive overlaps, as for rot.

symm

open fun symm(alpha: Double, a: DenseMatrix, b: DenseMatrix, beta: Double, c: DenseMatrix, lower: Boolean = true, right: Boolean = false, scratch: Scratch? = null)(source)

C = alpha · A · B + beta · C, or C = alpha · B · A + beta · C when right (BLAS dsymm). Only the lower or upper triangle of the symmetric a is read. Overlap and multipliers follow gemm.


open fun symm(alpha: Double, a: SparseMatrix, b: DenseMatrix, beta: Double, c: DenseMatrix, lower: Boolean = true, right: Boolean = false, scratch: Scratch? = null)(source)

C = alpha · A · B + beta · C, or C = alpha · B · A + beta · C when right, interpreting the square sparse a as symmetric from exactly its selected lower or upper triangle. A zero alpha reads neither input and a zero beta does not read c. Shared input and destination storage is staged.

symv

open fun symv(alpha: Double, a: DenseMatrix, x: DenseVector, beta: Double, y: DenseVector, lower: Boolean = true, scratch: Scratch? = null)(source)
open fun symv(alpha: Double, a: SparseMatrix, x: DenseVector, beta: Double, y: DenseVector, lower: Boolean = true, scratch: Scratch? = null)(source)

y = alpha * A * x + beta * y. Views retain their offsets and strides; aliases are staged. A zero alpha reads neither matrix nor input vector, and a zero beta overwrites y without reading it. lower selects the stored triangle of the symmetric matrix.

syr

open fun syr(alpha: Double, x: DenseVector, a: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

Adds alpha * x * xᵀ to the selected triangle of square a. Aliased inputs are staged.

syr2

open fun syr2(alpha: Double, x: DenseVector, y: DenseVector, a: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

Adds alpha * (x * yᵀ + y * xᵀ) to the selected triangle of square a. Aliased inputs are staged.

syr2k

open fun syr2k(alpha: Double, a: DenseMatrix, b: DenseMatrix, transpose: Boolean, beta: Double, c: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

C = alpha · (op(A) · op(B)ᵀ + op(B) · op(A)ᵀ) + beta · C (BLAS dsyr2k), where op transposes when transpose. Only the lower or upper triangle is written. The implementation may accumulate the two products separately or in one traversal, with the rounding differences gemm describes.

syrk

open fun syrk(alpha: Double, a: DenseMatrix, transpose: Boolean, beta: Double, c: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

C = alpha · A·Aᵀ + beta · C, or alpha · Aᵀ·A + beta · C when transpose (BLAS dsyrk). Only the lower or upper triangle is written. One product, so alpha and the accumulation order carry the latitude gemm describes.


open fun syrk(alpha: Double, a: SparseMatrix, transpose: Boolean, beta: Double, c: DenseMatrix, lower: Boolean = true, scratch: Scratch? = null)(source)

Dense selected-triangle C = alpha · op(A) · op(A)ᵀ + beta · C for a sparse a. Only the lower or upper triangle of c is read or written, and products involving implicit zeros are not evaluated.

trmm

open fun trmm(a: DenseMatrix, b: DenseMatrix, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, right: Boolean = false, alpha: Double = 1.0, scratch: Scratch? = null)(source)

B = alpha · op(T) · B, or B = alpha · B · op(T) when right (BLAS dtrmm), the counterpart of trsm.


open fun trmm(a: SparseMatrix, b: DenseMatrix, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, right: Boolean = false, alpha: Double = 1.0, scratch: Scratch? = null)(source)

B = alpha · op(T) · B in place, or B = alpha · B · op(T) when right. Zero or missing diagonal entries participate normally. From the right a stored zero off the diagonal is skipped, as reference dtrmm skips a zero coefficient.

trmv

open fun trmv(a: DenseMatrix, x: DenseVector, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, scratch: Scratch? = null)(source)
open fun trmv(a: SparseMatrix, x: DenseVector, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, scratch: Scratch? = null)(source)

Multiplies x = op(A) * x in place using the selected triangle. transpose transposes it and unitDiag assumes a unit diagonal. Views preserve their addressing and aliased matrix entries are staged. No singularity check is performed.

trsm

open fun trsm(a: DenseMatrix, b: DenseMatrix, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, right: Boolean = false, alpha: Double = 1.0, scratch: Scratch? = null)(source)

B = alpha · op(T)⁻¹ · B in place, or B = alpha · B · op(T)⁻¹ when right (BLAS dtrsm). Flags follow trsv; the right-hand sides are the columns of b from the left and its rows from the right.


open fun trsm(a: SparseMatrix, b: DenseMatrix, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, right: Boolean = false, alpha: Double = 1.0, scratch: Scratch? = null)(source)

B = alpha · op(T)⁻¹ · B in place, or B = alpha · B · op(T)⁻¹ when right (Sparse BLAS ussm), with the flags of the sparse trsv. A missing diagonal entry behaves as zero and singularity is not reported. From the right a stored zero off the diagonal is skipped, as reference dtrsm skips a zero coefficient.

trsv

open fun trsv(a: DenseMatrix, x: DenseVector, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, scratch: Scratch? = null)(source)
open fun trsv(a: SparseMatrix, x: DenseVector, lower: Boolean, transpose: Boolean = false, unitDiag: Boolean = false, scratch: Scratch? = null)(source)

Solves op(A) * x = b in place using the selected triangle. transpose transposes it and unitDiag assumes a unit diagonal. Views preserve their addressing and aliased matrix entries are staged. No singularity check is performed.