FLENS-BLAS Interface

FLENS provides a very convenient interface for BLAS. If no native BLAS implementation is available then CXXBLAS (which comes with FLENS) gets used as a default implementation. However, for high performance we recommend to install an optimized native BLAS implementation. Some implementations like like ATLAS, GotoBLAS or OpenBLAS are free available and do an amazing job.

Also have a look at the tutorial for getting an impression on how using FLENS-BLAS.

Purpose

Simplified naming convention

Consider BLAS functions like dgemv, sgemv, ssbmv, dgbmv, ... all of them implement some kind of matrix-vector product. That's what the mv stands for. However, the names also encapsulate further information about the involved matrix/vector types:
- The first leter indicates the element type
  - s for single precision,
  - d for double precision,
  - c for complex single precision,
  - z for complex double precision.
- The next two letter indicate the involved matrix type
  - ge for a general matrix with full storage
  - gb for a general matrix with band storage
  - sy for a symmetric matrix with full storage
  - sb for a symmetric matrix with banded storage
  - ...
Because FLENS provides actual matrix/vector types this information can be retrieved from the argument types. Hence, FLENS merely provides one function mv and overloads it for different matrix/vector types.

Analogously in FLENS function mm is overloaded for various matrix/vector types such that it unifies gemm, symm, trmm, ...
Simplified function arguments

Compared to calling BLAS functions directly or through the CBLAS interface the number of arguments required by FLENS-BLAS functions is significantly smaller. In BLAS/CBLAS you always have to pass
- matrix/vector dimensions
- leading dimensions/strides and
- a data pointer
for each matrix/vector argument. In FLENS-BLAS you simply pass a single matrix/vector object to the corresponding function.

As an example: dgemv from CBLAS requires 12 arguments while its FLENS-BLAS counterpart mv only requires 6 arguments. Besides convenient usage this also provides increased safety and improves correctness.

Level 1 BLAS

This BLAS level originally deals with vector-vector operations only. For convenience we added in some cases matrix-matrix variants that for instance allow copying or adding matrices.

FLENS-BLAS	DESCRIPTION	CXXBLAS
asum	Takes the sum of the absolute values, i.e. computes \(\sum\limits_{i} \|x_i\|\).	asum
axpy	Constant times a vector plus a vector, i.e. computes \(y \leftarrow \alpha x + y\).	axpy
copy	Copies a vector \(x\) to a vector \(y\) or a matrix \(A\) to a matrix \(B\).	copy
dot, dotu	Forms the dot product of two vectors, i.e. computes \(\sum\limits_{i} \bar{x}_i y_i\) or \(\sum\limits_{i} x_i y_i\).	dot, udot
nrm2	Computes the euclidean norm of a vector, i.e. \(\sqrt{\sum\limits_{i} \|x_i\|^2}\).	nrm2
rot	Applies a plane rotation.	rot
scal	Scales a vector by a constant, i.e. computes \(x \leftarrow \alpha x\).	scal
swap	Interchanges two vectors.	swap

Level 2 BLAS

This BLAS level deals with matrix-vector operations.

FLENS-BLAS	DESCRIPTION	CXXBLAS
mv	Computes a matrix-vector product. The form of the product depends on the matrix type: For general matrices it is \(y \leftarrow \beta y + \alpha \text{op}(A) x\). For symmetric matrices it is \(y \leftarrow \beta y + \alpha A x\). For hermitian matrices it is \(y \leftarrow \beta y + \alpha A x\). For triangular matrices it is \(x \leftarrow \text{op}(A) x\). Hereby \(\text{op}(A)\) denotes \(A\), \(A^T\) or \(A^H\).	gemv symv hemv trmv
r	Computes a rank `1` operation. The type of operation depends on type of the matrix that gets updated: For general matrices it is \(A \leftarrow A + \alpha x y^T\). For symmetric matrices it is \(A \leftarrow A + \alpha x x^T\).	geru gerc syr her
r2	Computes a symmetrix rank `2` operation. The type of operation depends on type of the matrix that gets updated: For symmetric matrices it is \(A \leftarrow A + \alpha x y^T + \alpha y x^T\). For hermitian matrices it is \(A \leftarrow A + \alpha x y^H + \overline{\alpha} y x^H\).	syr2 her2
sv	Solves one of the systems of equations \(Ax = b\) or \(A^T x = b\) where \(A\) is an unit or non-unit or upper or lower triangular matrix.	trsv

Level 3 BLAS

FLENS-BLAS	DESCRIPTION	CXXBLAS
mm	Computes a matrix-matrix product. The form of the product depends on the matrix types. If one matrix is a general matrix and the other matrix is general then it is \(C \leftarrow \beta C + \alpha \, \text{op}(A) \, \text{op}(B)\) symmetric then it is \(C \leftarrow \beta C + \alpha \, A \, \text{op}(B)\) hermitian then it is \(C \leftarrow \beta C + \alpha \, A \, \text{op}(B)\) triangular then it is \(B \leftarrow \alpha \, \text{op}(A) \, B\)	gemm symm hemm trmm
r2k	Compute a symmetric rank-`2k` update, i.e. \(C \leftarrow \beta C + \alpha\,A\, B^T + \alpha\,B\,A^T\) or \(C \leftarrow \beta C + \alpha\,A^T \, B + \alpha\,B^T\,A\).	syr2k
rk	Compute a symmetric rank-`k` update, i.e. \(C \leftarrow \beta C + \alpha A \, A^T\) or \(C \leftarrow \beta C + \alpha A^T \, A\)	syrk
sm	Solves one of the matrix equations \(\text{op}(A)\,X = B\) or \(X\,\text{op}(A) = B\) for \(X\) where \(A\) is an unit or non-unit or upper or lower triangular matrix and \(\text{op}(A)\) denotes \(A\), \(A^T\) or \(A^H\).	trsm