Module `C.Mat`

type t = mat

Matrix operations

Creation of matrices

val random : 
  ?rnd_state:Random.State.t ->
  ?re_from:float ->
  ?re_range:float ->
  ?im_from:float ->
  ?im_range:float ->
  int ->
  int ->
  mat

random ?rnd_state ?re_from ?re_range ?im_from ?im_range m n

returns
an mxn matrix initialized with random elements sampled uniformly from re_range and im_range starting at re_from and im_from for real and imaginary numbers respectively. A random state rnd_state can be passed.

parameter rnd_state
default = Random.get_state ()

parameter re_from
default = -1.0

parameter re_range
default = 2.0

parameter im_from
default = -1.0

parameter im_range
default = 2.0

type unop =
  ?m:int ->
  ?n:int ->
  ?br:int ->
  ?bc:int ->
  ?b:mat ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  mat

type binop =
  ?m:int ->
  ?n:int ->
  ?cr:int ->
  ?cc:int ->
  ?c:mat ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?br:int ->
  ?bc:int ->
  mat ->
  mat

Creation of matrices and accessors

val create : int -> int -> mat

create m n

returns
a matrix containing m rows and n columns.

val make : int -> int -> Complex.t -> mat

make m n x

returns
a matrix containing m rows and n columns initialized with value x.

val make0 : int -> int -> mat

make0 m n x

returns
a matrix containing m rows and n columns initialized with the zero element.

val of_array : Complex.t array array -> mat

of_array ar

returns
a matrix initialized from the array of arrays ar. It is assumed that the OCaml matrix is in row major order (standard).

val to_array : mat -> Complex.t array array

to_array mat

returns
an array of arrays initialized from matrix mat.

val of_list : Complex.t list list -> mat

of_list ls

returns
a matrix initialized from the list of lists ls. Each sublist of ls represents a row of the desired matrix, and must be of the same length.

val to_list : mat -> Complex.t list list

to_array mat

returns
mat in row major order as lists.

val of_col_vecs : vec array -> mat

of_col_vecs ar

returns
a matrix whose columns are initialized from the array of vectors ar. The vectors must be of same length.

val to_col_vecs : mat -> vec array

to_col_vecs mat

returns
an array of column vectors initialized from matrix mat.

val of_col_vecs_list : vec list -> mat

of_col_vecs_list ar

returns
a matrix whose columns are initialized from the list of vectors ar. The vectors must be of same length.

val to_col_vecs_list : mat -> vec list

to_col_vecs_list mat

returns
a list of column vectors initialized from matrix mat.

val as_vec : mat -> vec

as_vec mat

returns
a vector containing all elements of the matrix in column-major order. The data is shared.

val init_rows : int -> int -> (int -> int -> Complex.t) -> mat

init_cols m n f

returns
a matrix containing m rows and n columns, where each element at row and col is initialized by the result of calling f row col. The elements are passed row-wise.

val init_cols : int -> int -> (int -> int -> Complex.t) -> mat

init_cols m n f

returns
a matrix containing m rows and n columns, where each element at row and col is initialized by the result of calling f row col. The elements are passed column-wise.

val create_mvec : int -> mat

create_mvec m

returns
a matrix with one column containing m rows.

val make_mvec : int -> Complex.t -> mat

make_mvec m x

returns
a matrix with one column containing m rows initialized with value x.

val mvec_of_array : Complex.t array -> mat

mvec_of_array ar

returns
a matrix with one column initialized with values from array ar.

val mvec_to_array : mat -> Complex.t array

mvec_to_array mat

returns
an array initialized with values from the first (not necessarily only) column vector of matrix mat.

val from_col_vec : vec -> mat

from_col_vec v

returns
a matrix with one column representing vector v. The data is shared.

val from_row_vec : vec -> mat

from_row_vec v

returns
a matrix with one row representing vector v. The data is shared.

val empty : mat

empty, the empty matrix.

val identity : int -> mat

identity n

returns
the nxn identity matrix.

val of_diag : 
  ?n:int ->
  ?br:int ->
  ?bc:int ->
  ?b:mat ->
  ?ofsx:int ->
  ?incx:int ->
  vec ->
  mat

of_diag ?n ?br ?bc ?b ?ofsx ?incx x

returns
matrix b with diagonal elements in the designated sub-matrix coming from the designated sub-vector in x.

parameter n
default = greater n s.t. ofsx+(n-1)(abs incx) <= dim x

parameter br
default = 1

parameter bc
default = 1

parameter b
default = minimal fresh matrix consistent with n, br, and bc

parameter ofsx
default = 1

parameter incx
default = 1

val dim1 : mat -> int

dim1 m

returns
the first dimension of matrix m (number of rows).

val dim2 : mat -> int

dim2 m

returns
the second dimension of matrix m (number of columns).

val has_zero_dim : mat -> bool

has_zero_dim mat checks whether matrix mat has a dimension of size zero. In this case it cannot contain data.

val col : mat -> int -> vec

col m n

returns
the nth column of matrix m as a vector. The data is shared.

val copy_row : ?vec:vec -> mat -> int -> vec

copy_row ?vec mat int

returns
a copy of the nth row of matrix m in vector vec.

parameter vec
default = fresh vector of length dim2 mat

Matrix transformations

val swap : 
  ?uplo:[ `U | `L ] ->
  ?m:int ->
  ?n:int ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?br:int ->
  ?bc:int ->
  mat ->
  unit

swap ?m ?n ?ar ?ac a ?br ?bc b swaps the contents of (sub-matrices) a and b.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter ar
default = 1

parameter ac
default = 1

parameter br
default = 1

parameter bc
default = 1

val transpose_copy : unop

transpose_copy ?m ?n ?br ?bc ?b ?ar ?ac a

returns
the transpose of (sub-)matrix a. If b is given, the result will be stored in there using offsets br and bc, otherwise a fresh matrix will be used. NOTE: this operations does _not_ support in-place transposes!

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter br
default = 1

parameter bc
default = 1

parameter b
default = fresh matrix with br + m - 1 rows and bc + n - 1 columns

parameter ar
default = 1

parameter ac
default = 1

val detri : ?up:bool -> ?n:int -> ?ar:int -> ?ac:int -> mat -> unit

detri ?up ?n ?ar ?ac a takes a triangular (sub-)matrix a, i.e. one where only the upper (iff up is true) or lower triangle is defined, and makes it a symmetric matrix by mirroring the defined triangle along the diagonal.

parameter up
default = true

parameter n
default = Mat.dim1 a

parameter ar
default = 1

parameter ac
default = 1

val packed : ?up:bool -> ?n:int -> ?ar:int -> ?ac:int -> mat -> vec

packed ?up ?n ?ar ?ac a

returns
(sub-)matrix a in packed storage format.

parameter up
default = true

parameter n
default = Mat.dim2 a

parameter ar
default = 1

parameter ac
default = 1

val unpacked : ?up:bool -> ?n:int -> vec -> mat

unpacked ?up x

returns
an upper or lower (depending on up) triangular matrix from packed representation vec. The other triangle of the matrix will be filled with zeros.

parameter up
default = true

parameter n
default = Vec.dim x

Operations on one matrix

val fill : ?m:int -> ?n:int -> ?ar:int -> ?ac:int -> mat -> Complex.t -> unit

fill ?m ?n ?ar ?ac a x fills the specified sub-matrix in a with value x.

val sum : ?m:int -> ?n:int -> ?ar:int -> ?ac:int -> mat -> Complex.t

sum ?m ?n ?ar ?ac a computes the sum of all elements in the m-by-n submatrix starting at row ar and column ac.

val add_const : Complex.t -> unop

add_const c ?m ?n ?br ?bc ?b ?ar ?ac a adds constant c to the designated m by n submatrix in a and stores the result in the designated submatrix in b.

parameter m
default = Mat.dim1 a

parameter n
default = Mat.dim2 a

parameter ar
default = 1

parameter ac
default = 1

parameter br
default = 1

parameter bc
default = 1

parameter b
default = fresh matrix of size m by n

val neg : unop

neg ?m ?n ?br ?bc ?b ?ar ?ac a computes the negative of the elements in the m by n (sub-)matrix of the matrix a starting in row ar and column ac. If b is given, the result will be stored in there using offsets br and bc, otherwise a fresh matrix will be used. The resulting matrix is returned.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter br
default = 1

parameter bc
default = 1

parameter b
default = fresh matrix with br + m - 1 rows and bc + n - 1 columns

parameter ar
default = 1

parameter ac
default = 1

val reci : unop

reci ?m ?n ?br ?bc ?b ?ar ?ac a computes the reciprocal of the elements in the m by n (sub-)matrix of the matrix a starting in row ar and column ac. If b is given, the result will be stored in there using offsets br and bc, otherwise a fresh matrix will be used. The resulting matrix is returned.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter br
default = 1

parameter bc
default = 1

parameter b
default = fresh matrix with br + m - 1 rows and bc + n - 1 columns

parameter ar
default = 1

parameter ac
default = 1

val copy_diag : 
  ?n:int ->
  ?ofsy:int ->
  ?incy:int ->
  ?y:vec ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  vec

copy_diag ?n ?ofsy ?incy ?y ?ar ?ac a

returns
the diagonal of the (sub-)matrix a in a (sub-)vector.

parameter n
default = greatest n that does not exceed matrix dimensions

parameter ofsy
default = 1

parameter incy
default = 1

parameter y
default = fresh vector of length n

parameter ar
default = 1

parameter ac
default = 1

val trace : mat -> Complex.t

trace m

returns
the trace of matrix m. If m is not a square matrix, the sum of the longest possible sequence of diagonal elements will be returned.

val scal : ?m:int -> ?n:int -> Complex.t -> ?ar:int -> ?ac:int -> mat -> unit

scal ?m ?n alpha ?ar ?ac a BLAS scal function for (sub-)matrices.

val scal_cols : 
  ?m:int ->
  ?n:int ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?ofs:int ->
  vec ->
  unit

scal_cols ?m ?n ?ar ?ac a ?ofs alphas column-wise scal function for matrices.

val scal_rows : 
  ?m:int ->
  ?n:int ->
  ?ofs:int ->
  vec ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  unit

scal_rows ?m ?n ?ofs alphas ?ar ?ac a row-wise scal function for matrices.

val syrk_trace : ?n:int -> ?k:int -> ?ar:int -> ?ac:int -> mat -> Complex.t

syrk_trace ?n ?k ?ar ?ac a computes the trace of either a' * a or a * a', whichever is more efficient (results are identical), of the (sub-)matrix a multiplied by its own transpose. This is the same as the square of the Frobenius norm of a matrix. n is the number of rows to consider in a, and k the number of columns to consider.

parameter n
default = number of rows of a

parameter k
default = number of columns of a

parameter ar
default = 1

parameter ac
default = 1

val syrk_diag : 
  ?n:int ->
  ?k:int ->
  ?beta:Complex.t ->
  ?ofsy:int ->
  ?y:vec ->
  ?trans:[ `N | `T ] ->
  ?alpha:Complex.t ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  vec

syrk_diag ?n ?k ?beta ?ofsy ?y ?trans ?alpha ?ar ?ac a computes the diagonal of the symmetric rank-k product of the (sub-)matrix a, multiplying it with alpha and adding beta times y, storing the result in y starting at the specified offset. n elements of the diagonal will be computed, and k elements of the matrix will be part of the dot product associated with each diagonal element.

parameter n
default = number of rows of a (or tra)

parameter k
default = number of columns of a (or tra)

parameter beta
default = 0

parameter ofsy
default = 1

parameter y
default = fresh vector of size n + ofsy - 1

parameter trans
default = `N

parameter alpha
default = 1

parameter ar
default = 1

parameter ac
default = 1

Operations on two matrices

val add : binop

add ?m ?n ?cr ?cc ?c ?ar ?ac a ?br ?bc b computes the sum of the m by n sub-matrix of the matrix a starting in row ar and column ac with the corresponding sub-matrix of the matrix b starting in row br and column bc. If c is given, the result will be stored in there starting in row cr and column cc, otherwise a fresh matrix will be used. The resulting matrix is returned.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter cr
default = 1

parameter cc
default = 1

parameter c
default = fresh matrix with cr + m - 1 rows and cc + n - 1 columns

parameter br
default = 1

parameter bc
default = 1

parameter ar
default = 1

parameter ac
default = 1

val sub : binop

sub ?m ?n ?cr ?cc ?c ?ar ?ac a ?br ?bc b computes the difference of the m by n sub-matrix of the matrix a starting in row ar and column ac with the corresponding sub-matrix of the matrix b starting in row br and column bc. If c is given, the result will be stored in there starting in row cr and column cc, otherwise a fresh matrix will be used. The resulting matrix is returned.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter cr
default = 1

parameter cc
default = 1

parameter c
default = fresh matrix with cr + m - 1 rows and cc + n - 1 columns

parameter br
default = 1

parameter bc
default = 1

parameter ar
default = 1

parameter ac
default = 1

val mul : binop

mul ?m ?n ?cr ?cc ?c ?ar ?ac a ?br ?bc b computes the element-wise product of the m by n sub-matrix of the matrix a starting in row ar and column ac with the corresponding sub-matrix of the matrix b starting in row br and column bc. If c is given, the result will be stored in there starting in row cr and column cc, otherwise a fresh matrix will be used. The resulting matrix is returned.

NOTE: please do not confuse this function with matrix multiplication! The LAPACK-function for matrix multiplication is called gemm, e.g. Lacaml.D.gemm.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter cr
default = 1

parameter cc
default = 1

parameter c
default = fresh matrix with cr + m - 1 rows and cc + n - 1 columns

parameter br
default = 1

parameter bc
default = 1

parameter ar
default = 1

parameter ac
default = 1

val div : binop

div ?m ?n ?cr ?cc ?c ?ar ?ac a ?br ?bc b computes the division of the m by n sub-matrix of the matrix a starting in row ar and column ac with the corresponding sub-matrix of the matrix b starting in row br and column bc. If c is given, the result will be stored in there starting in row cr and column cc, otherwise a fresh matrix will be used. The resulting matrix is returned.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter cr
default = 1

parameter cc
default = 1

parameter c
default = fresh matrix with cr + m - 1 rows and cc + n - 1 columns

parameter br
default = 1

parameter bc
default = 1

parameter ar
default = 1

parameter ac
default = 1

val axpy : 
  ?alpha:Complex.t ->
  ?m:int ->
  ?n:int ->
  ?xr:int ->
  ?xc:int ->
  mat ->
  ?yr:int ->
  ?yc:int ->
  mat ->
  unit

axpy ?alpha ?m ?n ?xr ?xc x ?yr ?yc y BLAS axpy function for matrices.

val gemm_diag : 
  ?n:int ->
  ?k:int ->
  ?beta:Complex.t ->
  ?ofsy:int ->
  ?y:vec ->
  ?transa:trans3 ->
  ?alpha:Complex.t ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?transb:trans3 ->
  ?br:int ->
  ?bc:int ->
  mat ->
  vec

gemm_diag ?n ?k ?beta ?ofsy ?y ?transa ?transb ?alpha ?ar ?ac a ?br ?bc b computes the diagonal of the product of the (sub-)matrices a and b (taking into account potential transposing), multiplying it with alpha and adding beta times y, storing the result in y starting at the specified offset. n elements of the diagonal will be computed, and k elements of the matrices will be part of the dot product associated with each diagonal element.

parameter n
default = number of rows of a (or tr a) and number of columns of b (or tr b)

parameter k
default = number of columns of a (or tr a) and number of rows of b (or tr b)

parameter beta
default = 0

parameter ofsy
default = 1

parameter y
default = fresh vector of size n + ofsy - 1

parameter transa
default = `N

parameter alpha
default = 1

parameter ar
default = 1

parameter ac
default = 1

parameter transb
default = `N

parameter br
default = 1

parameter bc
default = 1

val gemm_trace : 
  ?n:int ->
  ?k:int ->
  ?transa:trans3 ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?transb:trans3 ->
  ?br:int ->
  ?bc:int ->
  mat ->
  Complex.t

gemm_trace ?n ?k ?transa ?ar ?ac a ?transb ?br ?bc b computes the trace of the product of the (sub-)matrices a and b (taking into account potential transposing). When transposing a, this yields the so-called Frobenius product of a and b. n is the number of rows (columns) to consider in a and the number of columns (rows) in b. k is the inner dimension to use for the product.

parameter n
default = number of rows of a (or tr a) and number of columns of b (or tr b)

parameter k
default = number of columns of a (or tr a) and number of rows of b (or tr b)

parameter transa
default = `N

parameter ar
default = 1

parameter ac
default = 1

parameter transb
default = `N

parameter br
default = 1

parameter bc
default = 1

val symm2_trace : 
  ?n:int ->
  ?upa:bool ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?upb:bool ->
  ?br:int ->
  ?bc:int ->
  mat ->
  Complex.t

symm2_trace ?n ?upa ?ar ?ac a ?upb ?br ?bc b computes the trace of the product of the symmetric (sub-)matrices a and b. n is the number of rows and columns to consider in a and b.

parameter n
default = dimensions of a and b

parameter upa
default = true (upper triangular portion of a is accessed)

parameter ar
default = 1

parameter ac
default = 1

parameter upb
default = true (upper triangular portion of b is accessed)

parameter br
default = 1

parameter bc
default = 1

val ssqr_diff : 
  ?m:int ->
  ?n:int ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  ?br:int ->
  ?bc:int ->
  mat ->
  Complex.t

ssqr_diff ?m ?n ?ar ?ac a ?br ?bc b

returns
the sum of squared differences between the m by n sub-matrix of the matrix a starting in row ar and column ac with the corresponding sub-matrix of the matrix b starting in row br and column bc.

parameter m
default = greater n s.t. ar + m - 1 <= dim1 a

parameter n
default = greater n s.t. ac + n - 1 <= dim2 a

parameter ar
default = 1

parameter ac
default = 1

parameter br
default = 1

parameter bc
default = 1

Iterators over matrices

val map : 
  (Complex.t -> Complex.t) ->
  ?m:int ->
  ?n:int ->
  ?br:int ->
  ?bc:int ->
  ?b:mat ->
  ?ar:int ->
  ?ac:int ->
  mat ->
  mat

map f ?m ?n ?br ?bc ?b ?ar ?ac a

returns
matrix with f applied to each element of a.

parameter m
default = number of rows of a

parameter n
default = number of columns of a

parameter b
default = fresh matrix of size m by n

val fold_cols : ('a -> vec -> 'a) -> ?n:int -> ?ac:int -> 'a -> mat -> 'a

fold_cols f ?n ?ac acc a

returns
accumulator resulting from folding over each column vector.

parameter ac
default = 1

parameter n
default = number of columns of a

package lacaml

Module C.Mat