owl 0.1.0 · OCaml Package

Real dense matrix module

type mat = Gsl.Matrix.matrix

Type of dense matrices. It is defined as Gsl.Matrix.matrix which is essentially a two dimensional array in Bigarray module.

Create dense matrices

val empty : int -> int -> mat

empty m n creates an m by n matrix without initialising the values of elements in x.

val create : int -> int -> float -> mat

create m n a creates an m by n matrix and all the elements of x are initialised with the value a.

val zeros : int -> int -> mat

zeros m n creates an m by n matrix where all the elements are initialised to zeros.

val ones : int -> int -> mat

ones m n creates an m by n matrix where all the elements are ones.

val eye : int -> mat

eye m creates an m by m identity matrix.

val sequential : int -> int -> mat

sequential m n creates an m by n matrix. The elements in x are initialised sequentiallly from 0 to (m * n - 1).

val uniform_int : ?a:int -> ?b:int -> int -> int -> mat

uniform ~a ~b m n creates an m by n matrix where all the elements follow a uniform distribution in [a, b] interval. By default, a = 0 and b = 100.

val uniform : ?scale:float -> int -> int -> mat

uniform m n creates an m by n matrix where all the elements follow a uniform distribution in (0,1) interval. uniform ~scale:a m n adjusts the interval to (0,a).

val gaussian : ?sigma:float -> int -> int -> mat

gaussian m n creates an m by n matrix where all the elements in x follow a Gaussian distribution with specified sigma. By default sigma = 1.

val semidef : int -> mat

semidef n returns an random n by n positive semi-definite matrix.

Dense vectors and meshgrids

val vector : int -> mat

vector m returns an 1 by m row vector x without initialising the values in x.

val vector_zeros : int -> mat

vector_zeros m returns an 1 by m row vector x by initialising the all values in x to zeros.

val vector_ones : int -> mat

vector_ones m returns an 1 by m row vector x by initialising the all values in x to ones.

val vector_uniform : int -> mat

vector_zeros m returns an 1 by m row vector x and the values are drawn from the interval (0,1) with a uniform distribution.

val linspace : float -> float -> int -> mat

linspace a b n linearly divides the interval [a,b] into n pieces by creating an m by 1 row vector. E.g., linspace 0. 5. 5 will create a row vector [0;1;2;3;4;5].

val meshgrid : float -> float -> float -> float -> int -> int -> mat * mat

meshgrid a1 b1 a2 b2 n1 n2 is similar to the meshgrid function in Matlab. It returns two matrices x and y where the row vectors in x are linearly spaced between [a1,b1] by n1 whilst the column vectors in y are linearly spaced between (a2,b2) by n2.

val meshup : mat -> mat -> mat * mat

meshup x y creates mesh grids by using two row vectors x and y.

Obtain the basic properties of a matrix

val shape : mat -> int * int

If x is an m by n matrix, shape x returns (m,n), i.e., the size of two dimensions of x.

val row_num : mat -> int

row_num x returns the number of rows in matrix x.

val col_num : mat -> int

col_num x returns the number of columns in matrix x.

val numel : mat -> int

numel x returns the number of elements in matrix x. It is equivalent to (row_num x) * (col_num x).

val same_shape : mat -> mat -> bool

same_shape x y returns true if two matrics have the same shape.

val reshape : int -> int -> mat -> mat

reshape m n x creates a new m by n matrix from the m' by n' matrix x. Note that (m * n) must be equal to (m' * n').

Manipulate a matrix

val get : mat -> int -> int -> float

get x i j returns the value of element (i,j) of x. The shorthand for get x i j is x.{i,j}

val set : mat -> int -> int -> float -> unit

set x i j a sets the element (i,j) of x to value a. The shorthand for set x i j a is x.{i,j} <- a

val row : mat -> int -> mat

row x i returns the row i of x.

val col : mat -> int -> mat

col x j returns the column j of x.

val rows : mat -> int array -> mat

rows x a returns the rows (defined in an int array a) of x. The returned rows will be combined into a new dense matrix. The order of rows in the new matrix is the same as that in the array a.

val cols : mat -> int array -> mat

Similar to rows, cols x a returns the columns (specified in array a) of x in a new dense matrix.

val clone : mat -> mat

clone x returns a copy of matrix x.

val copy_to : mat -> mat -> unit

copy_to x y copies the elements of x to y. x and y must have the same demensions.

val copy_row_to : mat -> mat -> int -> unit

copy_row_to v x i copies an 1 by n row vector v to the ith row in an m by n matrix x.

val copy_col_to : mat -> mat -> int -> unit

copy_col_to v x j copies an 1 by n column vector v to the jth column in an m by n matrix x.

val concat_vertical : mat -> mat -> mat

concat_vertical x y concats two matrices x and y vertically, therefore their column numbers must be the same.

val concat_horizontal : mat -> mat -> mat

concat_horizontal x y concats two matrices x and y horizontally, therefore their row numbers must be the same.

val transpose : mat -> mat

transpose x transposes an m by n matrix to n by m one.

val diag : mat -> mat

diag x returns the diagonal elements of x.

val trace : mat -> float

trace x returns the sum of diagonal elements in x.

val add_diag : mat -> float -> mat

add_diag x a adds a constant a to all the diagonal elements in x.

val replace_row : mat -> mat -> int -> mat

replace_row v x i uses the row vector v to replace the ith row in the matrix x.

val replace_col : mat -> mat -> int -> mat

replace_col v x j uses the column vector v to replace the jth column in the matrix x.

val swap_rows : mat -> int -> int -> mat

swap_rows x i i' swaps the row i with row i' of x.

val swap_cols : mat -> int -> int -> mat

swap_cols x j j' swaps the column j with column j' of x.

Iterate elements, columns, and rows.

val iteri : (int -> int -> float -> unit) -> mat -> unit

iteri f x iterates all the elements in x and applies the user defined function f : int -> int -> float -> 'a. f i j v takes three parameters, i and j are the coordinates of current element, and v is its value.

val iter : (float -> unit) -> mat -> unit

iter f x is the same as as iteri f x except the coordinates of the current element is not passed to the function f : float -> 'a

val mapi : (int -> int -> float -> float) -> mat -> mat

mapi f x maps each element in x to a new value by applying f : int -> int -> float -> float. The first two parameters are the coordinates of the element, and the third parameter is the value.

val map : (float -> float) -> mat -> mat

map f x is similar to mapi f x except the coordinates of the current element is not passed to the function f : float -> float

val fold : ('a -> float -> 'a) -> 'a -> mat -> 'a

fold f a x folds all the elements in x with the function f : 'a -> float -> 'a. For an m by n matrix x, the order of folding is from (0,0) to (m-1,n-1), row by row.

val filteri : (int -> int -> float -> bool) -> mat -> (int * int) array

filteri f x uses f : int -> int -> float -> bool to filter out certain elements in x. An element will be included if f returns true. The returned result is a list of coordinates of the selected elements.

val filter : (float -> bool) -> mat -> (int * int) array

Similar to filteri, but the coordinates of the elements are not passed to the function f : float -> bool.

val iteri_rows : (int -> mat -> unit) -> mat -> unit

iteri_rows f x iterates every row in x and applies function f : int -> mat -> unit to each of them.

val iter_rows : (mat -> unit) -> mat -> unit

Similar to iteri_rows except row number is not passed to f.

val iteri_cols : (int -> mat -> unit) -> mat -> unit

iteri_cols f x iterates every column in x and applies function f : int -> mat -> unit to each of them. Column number is passed to f as the first parameter.

val iter_cols : (mat -> unit) -> mat -> unit

Similar to iteri_cols except col number is not passed to f.

val filteri_rows : (int -> mat -> bool) -> mat -> int array

filteri_rows f x uses function f : int -> mat -> bool to check each row in x, then returns an int array containing the indices of those rows which satisfy the function f.

val filter_rows : (mat -> bool) -> mat -> int array

Similar to filteri_rows except that the row indices are not passed to f.

val filteri_cols : (int -> mat -> bool) -> mat -> int array

filteri_cols f x uses function f : int -> mat -> bool to check each column in x, then returns an int array containing the indices of those columns which satisfy the function f.

val filter_cols : (mat -> bool) -> mat -> int array

Similar to filteri_cols except that the column indices are not passed to f.

val fold_rows : ('a -> mat -> 'a) -> 'a -> mat -> 'a

fold_rows f a x folds all the rows in x using function f. The order of folding is from the first row to the last one.

val fold_cols : ('a -> mat -> 'a) -> 'a -> mat -> 'a

fold_cols f a x folds all the columns in x using function f. The order of folding is from the first column to the last one.

val mapi_rows : (int -> mat -> 'a) -> mat -> 'a array

mapi_rows f x maps every row in x to a type 'a value by applying function f : int -> mat -> 'a to each of them. The results is an array of all the returned values.

val map_rows : (mat -> 'a) -> mat -> 'a array

Similar to mapi_rows except row number is not passed to f.

val mapi_cols : (int -> mat -> 'a) -> mat -> 'a array

mapi_cols f x maps every column in x to a type 'a value by applying function f : int -> mat -> 'a.

val map_cols : (mat -> 'a) -> mat -> 'a array

Similar to mapi_cols except column number is not passed to f.

val mapi_by_row : ?d:int -> (int -> mat -> mat) -> mat -> mat

mapi_by_row f x applies f to each row of x, then uses the returned row vectors to assemble a new matrix.

val map_by_row : ?d:int -> (mat -> mat) -> mat -> mat

map_by_row f x i is similar to mapi_by_row except that the row indices are not passed to f.

val mapi_by_col : ?d:int -> (int -> mat -> mat) -> mat -> mat

mapi_by_col f x applies f to each column of x, then uses the returned column vectors to assemble a new matrix.

val map_by_col : ?d:int -> (mat -> mat) -> mat -> mat

map_by_col f x i is similar to mapi_by_col except that the column indices are not passed to f.

val mapi_at_row : (int -> int -> float -> float) -> mat -> int -> mat

mapi_at_row f x i creates a new matrix by applying function f only to the ith row in matrix x.

val map_at_row : (float -> float) -> mat -> int -> mat

map_at_row f x i is similar to mapi_at_row except that the coordinates of an element is not passed to f.

val mapi_at_col : (int -> int -> float -> float) -> mat -> int -> mat

mapi_at_col f x j creates a new matrix by applying function f only to the jth column in matrix x.

val map_at_col : (float -> float) -> mat -> int -> mat

map_at_col f x i is similar to mapi_at_col except that the coordinates of an element is not passed to f.

Examine the elements in a matrix

val exists : (float -> bool) -> mat -> bool

exists f x checks all the elements in x using f. If at least one element satisfies f then the function returns true otherwise false.

val not_exists : (float -> bool) -> mat -> bool

not_exists f x checks all the elements in x, the function returns true only if all the elements fail to satisfy f : float -> bool.

val for_all : (float -> bool) -> mat -> bool

for_all f x checks all the elements in x, the function returns true if and only if all the elements pass the check of function f.

Compare two matrices

val is_equal : mat -> mat -> bool

is_equal x y returns true if two matrices x and y are equal.

val is_unequal : mat -> mat -> bool

is_unequal x y returns true if there is at least one element in x is not equal to that in y.

val is_greater : mat -> mat -> bool

is_greater x y returns true if all the elements in x are greater than the corresponding elements in y.

val is_smaller : mat -> mat -> bool

is_smaller x y returns true if all the elements in x are smaller than the corresponding elements in y.

val equal_or_greater : mat -> mat -> bool

equal_or_greater x y returns true if all the elements in x are not smaller than the corresponding elements in y.

val equal_or_smaller : mat -> mat -> bool

equal_or_smaller x y returns true if all the elements in x are not greater than the corresponding elements in y.

Basic mathematical operations of matrices

val add : mat -> mat -> mat

add x y adds two matrices x and y. Both must have the same dimensions.

val sub : mat -> mat -> mat

sub x y subtracts the matrix x from y. Both must have the same dimensions.

val mul : mat -> mat -> mat

mul x y performs an element-wise multiplication, so both x and y must have the same dimensions.

val div : mat -> mat -> mat

div x y performs an element-wise division, so both x and y must have the same dimensions.

val dot : mat -> mat -> mat

dot x y calculates the dot product of an m by n matrix x and another n by p matrix y.

val abs : mat -> mat

abs x returns a new matrix where each element has the absolute value of that in the original matrix x.

val neg : mat -> mat

neg x returns a new matrix where each element has the negative value of that in the original matrix x.

val power : mat -> float -> mat

power x a calculates the power of a of each element in x.

val add_scalar : mat -> float -> mat

add_scalar x a adds every element in x by a constant factor a.

val sub_scalar : mat -> float -> mat

sub_scalar x a subtracts every element in x by a constant factor a.

val mul_scalar : mat -> float -> mat

mul_scalar x a multiplies every element in x by a constant factor a.

val div_scalar : mat -> float -> mat

div_scalar x a divides every element in x by a constant factor a.

val sum : mat -> float

sum x returns the summation of all the elements in x.

val average : mat -> float

average x returns the average value of all the elements in x. It is equivalent to calculate sum x divided by numel x

val min : mat -> float * int * int

min x returns the minimum value of all elements in x.

val max : mat -> float * int * int

max x returns the maximum value of all elements in x.

val minmax : mat -> float * float * int * int * int * int

minmax x returns both the minimum and minimum values in x.

val is_zero : mat -> bool

is_zero x returns true if all the elements in x are zeros.

val is_positive : mat -> bool

is_positive x returns true if all the elements in x are positive.

val is_negative : mat -> bool

is_negative x returns true if all the elements in x are negative.

val is_nonnegative : mat -> bool

is_nonnegative returns true if all the elements in x are non-negative.

val log : mat -> mat

log x applies log function to each element in matrix x.

val log10 : mat -> mat

log10 x applies log10 function to each element in matrix x.

val exp : mat -> mat

exp x applies exp function to each element in matrix x.

val sigmoid : mat -> mat

sigmoid x applies sigmoid function to each element in matrix x.

val sum_rows : mat -> mat

sum_rows x returns the summation of all the row vectors in x.

val sum_cols : mat -> mat

sum_cols returns the summation of all the column vectors in x.

val average_rows : mat -> mat

average_rows x returns the average value of all row vectors in x. It is equivalent to div_scalar (sum_rows x) (float_of_int (row_num x)).

val average_cols : mat -> mat

average_cols x returns the average value of all column vectors in x. It is equivalent to div_scalar (sum_cols x) (float_of_int (col_num x)).

val min_rows : mat -> (float * int * int) array

min_rows x returns the minimum value in each row along with their coordinates.

val min_cols : mat -> (float * int * int) array

min_cols x returns the minimum value in each column along with their coordinates.

val max_rows : mat -> (float * int * int) array

max_rows x returns the maximum value in each row along with their coordinates.

val max_cols : mat -> (float * int * int) array

min_cols x returns the minimum value in each column along with their coordinates.

Randomisation functions

val draw_rows : ?replacement:bool -> mat -> int -> mat * int array

draw_rows x m draws m rows randomly from x. The row indices are also returned in an int array along with the selected rows. The parameter replacement indicates whether the drawing is by replacement or not.

val draw_cols : ?replacement:bool -> mat -> int -> mat * int array

draw_cols x m draws m cols randomly from x. The column indices are also returned in an int array along with the selected columns. The parameter replacement indicates whether the drawing is by replacement or not.

val shuffle_rows : mat -> mat

shuffle_rows x shuffles all the rows in matrix x.

val shuffle_cols : mat -> mat

shuffle_cols x shuffles all the columns in matrix x.

val shuffle : mat -> mat

shuffle x shuffles all the elements in x by first shuffling along the rows then shuffling along columns. It is equivalent to shuffle_cols (shuffle_rows x).

Input/Output and helper functions

val to_array : mat -> float array

to_array x flattens an m by n matrix x then returns x as an float array of length (numel x).

val to_arrays : mat -> float array array

to arrays x returns an array of float arrays, wherein each row in x becomes an array in the result.

val of_array : float array -> int -> int -> mat

of_array x m n converts a float array x into an m by n matrix. Note the length of x must be equal to (m * n).

val of_arrays : float array array -> mat

of_arrays x converts an array of m float arrays (of length n) in to an m by n matrix.

val print : mat -> unit

print x pretty prints matrix x without headings.

val pp_dsmat : mat -> unit

pp_spmat x pretty prints matrix x with headings. Toplevel uses this function to print out the matrices.

val save : mat -> string -> unit

save x f saves the matrix x to a file with the name f. The format is binary by using Marshal module to serialise the matrix.

val load : string -> mat

load f loads a sparse matrix from file f. The file must be previously saved by using save function.

val save_txt : mat -> string -> unit

save_txt x f save the matrix x into a text file f. The operation can be very time consuming.

val load_txt : string -> mat

load_txt f load a text file f into a matrix.

Shorhand infix operators

val (>>) : mat -> mat -> unit

Shorthand for copy_to x y, i.e., x >> y

val (<<) : mat -> mat -> unit

Shorthand for copy_to y x, i.e., x << y

val (@=) : mat -> mat -> mat

Shorthand for concat_vertical x y, i.e., x @= y

val (@||) : mat -> mat -> mat

Shorthand for concat_horizontal x y, i.e., x @|| y

val (+@) : mat -> mat -> mat

Shorthand for add x y, i.e., x +@ y

val (-@) : mat -> mat -> mat

Shorthand for sub x y, i.e., x -@ y

val (*@) : mat -> mat -> mat

Shorthand for mul x y, i.e., x *@ y

val (/@) : mat -> mat -> mat

Shorthand for div x y, i.e., x /@ y

val ($@) : mat -> mat -> mat

Shorthand for dot x y, i.e., x $@ y

val (**@) : mat -> float -> mat

Shorthand for power x a, i.e., x **@ a

val (+$) : mat -> float -> mat

Shorthand for add_scalar x a, i.e., x +$ a

val (-$) : mat -> float -> mat

Shorthand for sub_scalar x a, i.e., x -$ a

val (*$) : mat -> float -> mat

Shorthand for mul_scalar x a, i.e., x *$ a

val (/$) : mat -> float -> mat

Shorthand for div_scalar x a, i.e., x /$ a

val ($+) : float -> mat -> mat

Shorthand for add_scalar x a, i.e., a $+ x

val ($-) : float -> mat -> mat

Shorthand for sub_scalar x a, i.e., a -$ x

val ($*) : float -> mat -> mat

Shorthand for mul_scalar x a, i.e., x $* a

val ($/) : float -> mat -> mat

Shorthand for div_scalar x a, i.e., x $/ a

val (=@) : mat -> mat -> bool

Shorthand for is_equal x y, i.e., x =@ y

val (>@) : mat -> mat -> bool

Shorthand for is_greater x y, i.e., x >@ y

val (<@) : mat -> mat -> bool

Shorthand for is_smaller x y, i.e., x <@ y

val (<>@) : mat -> mat -> bool

Shorthand for is_unequal x y, i.e., x <>@ y

val (>=@) : mat -> mat -> bool

Shorthand for equal_or_greater x y, i.e., x >=@ y

val (<=@) : mat -> mat -> bool

Shorthand for equal_or_smaller x y, i.e., x <=@ y

val (@@) : (float -> float) -> mat -> mat

Shorthand for map f x, i.e., f @@ x

package owl