``````blas
=====

This project is a NIF based wrapper of the Basic Linear Algebra Subprograms, which provides algorithms fine-tuned for a large variety of hardware.

This implementation uses [openblas](https://github.com/xianyi/OpenBLAS). Other cblas implementations can be used, but will need modifictations of c_src/Makefile linking options and c_src/eblas.h include options.

API
----
The following sites provide a clear BLAS API:
- [netlib's](https://netlib.org/blas/) concise reference.
- [intel's](https://www.intel.com/content/www/us/en/content-details/671183/developer-reference-for-intel-math-kernel-library-intel-mkl-11-3-c.html?wapkw=BLAS%20mlk) complete reference.
- [IBM's](https://www.ibm.com/docs/en) reference, with clear examples.

Usage
-----
```erlang
blas:run(Tuple);        % Execute on dirty scheduler
blas:run(Tuple, dirty); % Execute on dirty scheduler.
blas:run(Tuple, clean); % Execute on usual scheduler.
```
Tuple contains, in sequence, a BLAS function name (represented as an atom), followed by its arguments in Erlang representation.

Examples
-----

[caxpy](https://www.ibm.com/docs/en/essl/6.1?topic=vss-saxpy-daxpy-caxpy-zaxpy-multiply-vector-by-scalar-add-vector-store-in-vector): single Complex numbers, Alpha*x Plus Y:

```erlang
Alpha = blas:ltb(c, [1,0]),
X     = blas:ltb(c, [1,2,  2,3,  3,1]),
Y     = blas:new(c, [1,1,  0,0,  1,2]),
ok    = blas:run({caxpy, 3, Alpha, X, 1, Y, 1}),

io:format("Result: ~p~n", [blas:to_list(c, Y)]).
```

[stpmv](https://www.ibm.com/docs/en/essl/6.1?topic=mvs-strmv-dtrmv-ctrmv-ztrmv-stpmv-dtpmv-ctpmv-ztpmv-matrix-vector-product-triangular-matrix-its-transpose-its-conjugate-transpose): Single real numbers, Triangular Packed Matrix, Matrix*Vector operation.

```erlang
N  = 3,
A  = blas:new(s, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]),
X  = blas:new(s, [-0.25,-0.125,0.5]),
ok = blas:run(
{stpmv, blasRowMajor, blasUpper, blasNoTrans, blasNonUnit, N, A, X, 1},
clean
),
[1.0,2.0,3.0] = blas:to_list(s, X).
```

Datatype conversion tables
-----

```
enums       cblas[value]           blas[value]

numbers
(const)int             int
void*                  c_binary
const float            double; binary; c_binary
const double           double; binary; c_binary
const void*            binary; c_binary

```

For example, taking stpmv's cblas signature:

```c
void cblas_stpmv(OPENBLAS_CONST enum CBLAS_ORDER order, OPENBLAS_CONST enum CBLAS_UPLO Uplo, OPENBLAS_CONST enum CBLAS_TRANSPOSE TransA, OPENBLAS_CONST enum CBLAS_DIAG Diag,
OPENBLAS_CONST blasint N, OPENBLAS_CONST float *Ap, float *X, OPENBLAS_CONST blasint incX);
```
The arguments can be represented as such:
```erlang
% enums
Order  = blasRowMajor  || blasColMajor
Uplo   = blasUpper     || blasLower
Transa = blasNoTrans   || blasTrans
Diag   = blasNonUnit   || blasUnit

% int
N      = 3
incX   = 1

% const float*
A      = blas:new(s, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]); % c_binary, a mutable binary
A_2    = blas:ltb(s, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]); % binary

% float*
X      = blas:new(s, [-0.25,-0.125,0.5]);             % c_binary
```

Creating c_binaries
-----
Since BLAS functions operate in place, c_binaries representing mutable arrays are needed. They can be created as such:
```erlang
C_binary = blas:new(Binary).
% Binary is an erlang binary.
C_binary = blas:new(Type, List).
% List is a list of numbers.
% Type is used to encode the binary, and is one of:
% s -> single precision
% d -> double precision
% c -> single complex numbers: List is of even size
% Z -> double complex numbers: List is of even size
```

-----
The content of c_binaries can be retrieved as either a list of elements, or a constant binary.
Retrieving a list is done as such:
```erlang
C_binary = blas:to_list(Type, C_binary).
% Binary is a c_binary created using blas:new.
% Type is used to decode the binary, and is one of:
% s -> single precision
% d -> double precision
% c -> single complex numbers (equivalent to s)
% Z -> double complex numbers (equivqlent to d)
```
Retrieving a binary is done as such:
```erlang
Binary = blas:to_bin(C_binary).
% Binary is a c_binary created using blas:new.
```
``````