Legend:
Library
Module
Module type
Parameter
Class
Class type
Matrix module: including creation, manipulation, and various vectorised mathematical operations.
About the comparison of two complex numbers x and y, Owl uses the following conventions: 1) x and y are equal iff both real and imaginary parts are equal; 2) x is less than y if the magnitude of x is less than the magnitude of x; in case both x and y have the same magnitudes, x is less than x if the phase of x is less than the phase of y; 3) less or equal, greater, greater or equal relation can be further defined atop of the aforementioned conventions.
empty m n creates an m by n matrix without initialising the values of elements in x.
val create : ('a, 'b)kind->int ->int ->'a->('a, 'b)t
create m n a creates an m by n matrix and all the elements of x are initialised with the value a.
val init : ('a, 'b)kind->int ->int ->(int ->'a)->('a, 'b)t
init m n f creates a matrix x of shape m x n, then using f to initialise the elements in x. The input of f is 1-dimensional index of the matrix. You need to explicitly convert it if you need 2D index. The function Owl_utils._index_1d_nd can help you.
val init_nd : ('a, 'b)kind->int ->int ->(int ->int ->'a)->('a, 'b)t
init_nd m n f s almost the same as init but f receives 2D index as input. It is more convenient since you don't have to convert the index by yourself, but this also means init_nd is slower than init.
val complex :
('a, 'b)kind->('c, 'd)kind->('a, 'b)t->('a, 'b)t->('c, 'd)t
complex re im constructs a complex ndarray/matrix from re and im. re and im contain the real and imaginary part of x respectively.
Note that both re and im can be complex but must have same type. The real part of re will be the real part of x and the imaginary part of im will be the imaginary part of x.
val polar :
('a, 'b)kind->('c, 'd)kind->('a, 'b)t->('a, 'b)t->('c, 'd)t
complex rho theta constructs a complex ndarray/matrix from polar coordinates rho and theta. rho contains the magnitudes and theta contains phase angles. Note that the behaviour is undefined if rho has negative elelments or theta has infinity elelments.
val sequential : ('a, 'b)kind->?a:'a->?step:'a->int ->int ->('a, 'b)t
sequential ~a ~step m n creates an m by n matrix. The elements in x are initialised sequentiallly from ~a and is increased by ~step.
The default value of ~a is zero whilst the default value of ~step is one.
val uniform : ?scale:float ->('a, 'b)kind->int ->int ->('a, 'b)t
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 ->('a, 'b)kind->int ->int ->('a, 'b)t
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.
semidef n returns an random n by n positive semi-definite matrix.
val linspace : ('a, 'b)kind->'a->'a->int ->('a, 'b)t
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 logspace : ('a, 'b)kind->?base:float ->'a->'a->int ->('a, 'b)t
logspace base a b n ... the default value of base is e.
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 : ('a, 'b)t->('a, 'b)t->('a, 'b)t * ('a, 'b)t
meshup x y creates mesh grids by using two row vectors x and y.
val bernoulli :
('a, 'b)kind->?p:float ->?seed:int ->int ->int ->('a, 'b)t
diagm k v creates a diagonal matrix using the elements in v as diagonal values. k specifies the main diagonal index. If k > 0 then it is above the main diagonal, if k < 0 then it is below the main diagonal. This function is the same as the diag function in Matlab.
triu k x returns the element on and above the kth diagonal of x. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is below the main diagonal.
tril k x returns the element on and below the kth diagonal of x. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is below the main diagonal.
val symmetric : ?upper:bool ->('a, 'b)t->('a, 'b)t
symmetric ~upper x creates a symmetric matrix using either upper or lower triangular part of x. If upper is true then it uses the upper part, if upper is false, then symmetric uses the lower part. By default upper is true.
hermitian ~upper x creates a hermitian matrix based on x. By default, the upper triangular part is used for creating the hermitian matrix, but you use the lower part by setting upper=false
val bidiagonal : ?upper:bool ->('a, 'b)t->('a, 'b)t->('a, 'b)t
bidiagonal upper dv ev creates a bidiagonal matrix using dv and ev. Both dv and ev are row vectors. dv is the main diagonal. If upper is true then ev is superdiagonal; if upper is false then ev is subdiagonal. By default, upper is true.
NOTE: because the diagonal elements in a hermitian matrix must be real, the function set the imaginary part of the diagonal elements to zero by default. In other words, if the diagonal elements of x have non-zero imaginary parts, the imaginary parts will be dropped without a warning.
toeplitz ~c r generates a toeplitz matrix using r and c. Both r and c are row vectors of the same length. If the first elements of c is different from that of r, r's first element will be used.
Note: 1) If c is not passed in, then c = r will be used. 2) If c is not passed in and r is complex, the c = conj r will be used. 3) If r and c have different length, then the result is a rectangular matrix.
hankel ~r c generates a hankel matrix using r and c. c will be the first column and r will be the last row of the returned matrix.
Note: 1) If only c is passed in, the elelments below the anti-diagnoal are zero. 2) If the last element of c is different from the first element of r then the first element of c prevails. 3) c and r can have different length, the return will be an rectangular matrix.
hadamard k n constructs a hadamard matrix of order n. For a hadamard H, we have H'*H = n*I. Currrently, this function handles only the cases where n, n/12, or n/20 is a power of 2.
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 get_index : ('a, 'b)t->int array array->'a array
get_index i x returns an array of element values specified by the indices i. The length of array i equals the number of dimensions of x. The arrays in i must have the same length, and each represents the indices in that dimension.
E.g., [| [|1;2|]; [|3;4|] |] returns the value of elements at position (1,3) and (2,4) respectively.
val set_index : ('a, 'b)t->int array array->'a array-> unit
set_index sets the value of elements in x according to the indices specified by i. The length of array i equals the number of dimensions of x. The arrays in i must have the same length, and each represents the indices in that dimension.
slice s x returns a copy of the slice in x. The slice is defined by a which is an int array. Please refer to the same function in the Owl_dense_ndarray_generic documentation for more details.
set_slice axis x y set the slice defined by axis in x according to the values in y. y must have the same shape as the one defined by axis.
About the slice definition of axis, please refer to slice function.
val get_slice_simple : int list list->('a, 'b)t->('a, 'b)t
get_slice_simple axis x aims to provide a simpler version of get_slice. This function assumes that every list element in the passed in in list list represents a range, i.e., R constructor.
E.g., [[];[0;3];[0]] is equivalent to [R []; R [0;3]; R [0]] .
val set_slice_simple : int list list->('a, 'b)t->('a, 'b)t-> unit
set_slice_simple axis x y aims to provide a simpler version of set_slice. This function assumes that every list element in the passed in in list list represents a range, i.e., R constructor.
E.g., [[];[0;3];[0]] is equivalent to [R []; R [0;3]; R [0]] .
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.
reshape m n x returns a new m by n matrix from the m' by n' matrix x. Note that (m * n) must be equal to (m' * n'), and the returned matrix shares the same memory with the original x.
rotate x d rotates x clockwise d degrees. d must be multiple times of 90, otherwise the function will fail. If x is an n-dimensional array, then the function rotates the plane formed by the first and second dimensions.
copy_to x y copies the elements of x to y. x and y must have the same demensions.
val copy_row_to : ('a, 'b)t->('a, 'b)t->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 : ('a, 'b)t->('a, 'b)t->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 : ('a, 'b)t->('a, 'b)t->('a, 'b)t
concat_vertical x y concats two matrices x and y vertically, therefore their column numbers must be the same.
val concat_horizontal : ('a, 'b)t->('a, 'b)t->('a, 'b)t
concat_horizontal x y concats two matrices x and y horizontally, therefore their row numbers must be the same.
val concatenate : ?axis:int ->('a, 'b)t array->('a, 'b)t
concatenate ~axis:1 x concatenates an array of matrices along the second dimension. For the matrices in x, they must have the same shape except the dimension specified by axis. The default value of axis is 0, i.e., the lowest dimension on a marix, i.e., rows.
val split : ?axis:int ->int array->('a, 'b)t->('a, 'b)t array
top x n returns the indices of n greatest values of x. The indices are arranged according to the corresponding elelment values, from the greatest one to the smallest one.
bottom x n returns the indices of n smallest values of x. The indices are arranged according to the corresponding elelment values, from the smallest one to the greatest one.
sort x performs in-place quicksort of the elelments in x.
Iterate elements, columns, and rows.
val iteri : (int ->int ->'a-> unit)->('a, 'b)t-> 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.
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 ->'a->'a)->('a, 'b)t->('a, 'b)t
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.
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.
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 : ('a-> bool)->('a, 'b)t->(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 ->('a, 'b)t-> unit)->('a, 'b)t-> unit
iteri_rows f x iterates every row in x and applies function f : int -> mat -> unit to each of them.
val iter_rows : (('a, 'b)t-> unit)->('a, 'b)t-> unit
Similar to iteri_rows except row number is not passed to f.
val iter2i_rows :
(int ->('a, 'b)t->('a, 'b)t-> unit)->('a, 'b)t->('a, 'b)t->
unit
val iter2_rows :
(('a, 'b)t->('a, 'b)t-> unit)->('a, 'b)t->('a, 'b)t->
unit
val iteri_cols : (int ->('a, 'b)t-> unit)->('a, 'b)t-> 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 : (('a, 'b)t-> unit)->('a, 'b)t-> unit
Similar to iteri_cols except col number is not passed to f.
val filteri_rows : (int ->('a, 'b)t-> bool)->('a, 'b)t->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 : (('a, 'b)t-> bool)->('a, 'b)t->int array
Similar to filteri_rows except that the row indices are not passed to f.
val filteri_cols : (int ->('a, 'b)t-> bool)->('a, 'b)t->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 : (('a, 'b)t-> bool)->('a, 'b)t->int array
Similar to filteri_cols except that the column indices are not passed to f.
val fold_rows : ('c->('a, 'b)t->'c)->'c->('a, 'b)t->'c
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 : ('c->('a, 'b)t->'c)->'c->('a, 'b)t->'c
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 ->('a, 'b)t->'c)->('a, 'b)t->'c 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 : (('a, 'b)t->'c)->('a, 'b)t->'c array
Similar to mapi_rows except row number is not passed to f.
val mapi_cols : (int ->('a, 'b)t->'c)->('a, 'b)t->'c 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 : (('a, 'b)t->'c)->('a, 'b)t->'c array
Similar to mapi_cols except column number is not passed to f.
val mapi_by_row :
int ->(int ->('a, 'b)t->('a, 'b)t)->('a, 'b)t->('a, 'b)t
mapi_by_row d f x applies f to each row of a m by n matrix x, then uses the returned d dimensional row vectors to assemble a new m by d matrix.
val map_by_row : int ->(('a, 'b)t->('a, 'b)t)->('a, 'b)t->('a, 'b)t
map_by_row d f x is similar to mapi_by_row except that the row indices are not passed to f.
val mapi_by_col :
int ->(int ->('a, 'b)t->('a, 'b)t)->('a, 'b)t->('a, 'b)t
mapi_by_col d f x applies f to each column of a m by n matrix x, then uses the returned d dimensional column vectors to assemble a new d by n matrix.
val map_by_col : int ->(('a, 'b)t->('a, 'b)t)->('a, 'b)t->('a, 'b)t
map_by_col d f x is similar to mapi_by_col except that the column indices are not passed to f.
val mapi_at_row : (int ->int ->'a->'a)->('a, 'b)t->int ->('a, 'b)t
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 : ('a->'a)->('a, 'b)t->int ->('a, 'b)t
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 ->'a->'a)->('a, 'b)t->int ->('a, 'b)t
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 : ('a->'a)->('a, 'b)t->int ->('a, 'b)t
map_at_col f x i is similar to mapi_at_col except that the coordinates of an element is not passed to f.
elt_equal x y performs element-wise = comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a = b.
val elt_not_equal : ('a, 'b)t->('a, 'b)t->('a, 'b)t
elt_not_equal x y performs element-wise != comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a <> b.
elt_less x y performs element-wise < comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a < b.
elt_greater x y performs element-wise > comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a > b.
val elt_less_equal : ('a, 'b)t->('a, 'b)t->('a, 'b)t
elt_less_equal x y performs element-wise <= comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a <= b.
val elt_greater_equal : ('a, 'b)t->('a, 'b)t->('a, 'b)t
elt_greater_equal x y performs element-wise >= comparison of x and y. Assume that a is from x and b is the corresponding element of a from y of the same position. The function returns another binary (0 and 1) ndarray/matrix wherein 1 indicates a >= b.
elt_equal_scalar x a performs element-wise = comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a = b, otherwise 0.
val elt_not_equal_scalar : ('a, 'b)t->'a->('a, 'b)t
elt_not_equal_scalar x a performs element-wise != comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a <> b, otherwise 0.
elt_less_scalar x a performs element-wise < comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a < b, otherwise 0.
elt_greater_scalar x a performs element-wise > comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a > b, otherwise 0.
val elt_less_equal_scalar : ('a, 'b)t->'a->('a, 'b)t
elt_less_equal_scalar x a performs element-wise <= comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a <= b, otherwise 0.
val elt_greater_equal_scalar : ('a, 'b)t->'a->('a, 'b)t
elt_greater_equal_scalar x a performs element-wise >= comparison of x and a. Assume that b is one element from x The function returns another binary (0 and 1) ndarray/matrix wherein 1 of the corresponding position indicates a >= b, otherwise 0.
val approx_equal : ?eps:float ->('a, 'b)t->('a, 'b)t-> bool
approx_equal ~eps x y returns true if x and y are approximately equal, i.e., for any two elements a from x and b from y, we have abs (a - b) < eps.
Note: the threshold check is exclusive for passed in eps.
val approx_equal_scalar : ?eps:float ->('a, 'b)t->'a-> bool
approx_equal_scalar ~eps x a returns true all the elements in x are approximately equal to a, i.e., abs (x - a) < eps. For complex numbers, the eps applies to both real and imaginary part.
Note: the threshold check is exclusive for the passed in eps.
val approx_elt_equal : ?eps:float ->('a, 'b)t->('a, 'b)t->('a, 'b)t
approx_elt_equal ~eps x y compares the element-wise equality of x and y, then returns another binary (i.e., 0 and 1) ndarray/matrix wherein 1 indicates that two corresponding elements a from x and b from y are considered as approximately equal, namely abs (a - b) < eps.
val approx_elt_equal_scalar : ?eps:float ->('a, 'b)t->'a->('a, 'b)t
approx_elt_equal_scalar ~eps x a compares all the elements of x to a scalar value a, then returns another binary (i.e., 0 and 1) ndarray/matrix wherein 1 indicates that the element b from x is considered as approximately equal to a, namely abs (a - b) < eps.
Randomisation functions
val draw_rows :
?replacement:bool ->('a, 'b)t->int ->('a, 'b)t * 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 ->('a, 'b)t->int ->('a, 'b)t * 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 draw_rows2 :
?replacement:bool ->('a, 'b)t->('a, 'b)t->int ->('a, 'b)t * ('a, 'b)t * int array
draw_rows2 x y c is similar to draw_rows but applies to two matrices.
val draw_cols2 :
?replacement:bool ->('a, 'b)t->('a, 'b)t->int ->('a, 'b)t * ('a, 'b)t * int array
draw_col2 x y c is similar to draw_cols but applies to two matrices.
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).
min x returns the minimum of all elements in x. For two complex numbers, the one with the smaller magnitude will be selected. If two magnitudes are the same, the one with the smaller phase will be selected.
max x returns the maximum of all elements in x. For two complex numbers, the one with the greater magnitude will be selected. If two magnitudes are the same, the one with the greater phase will be selected.
max_i x returns the maximum of all elements in x as well as its index.
val minmax_i : ('a, 'b)t->('a * int * int) * ('a * int * int)
minmax_i x returns ((min_v,min_i), (max_v,max_i)) where (min_v,min_i) is the minimum value in x along with its index while (max_v,max_i) is the maximum value along its index.
conj x computes the conjugate of the elements in x and returns the result in a new matrix. If the passed in x is a real matrix, the function simply returns a copy of the original x.
reci_tol ~tol x computes the reciprocal of every element in x. Different from reci, reci_tol sets the elements whose abs value smaller than tol to zeros. If tol is not specified, the defautl Owl_utils.eps Float32 will be used. For complex numbers, refer to Owl's doc to see how to compare.
fix x rounds each element of x to the nearest integer toward zero. For positive elements, the behavior is the same as floor. For negative ones, the behavior is the same as ceil.
modf x performs modf over all the elements in x, the fractal part is saved in the first element of the returned tuple whereas the integer part is saved in the second element.
l2norm_sqr x calculates the square of l2-norm (or l2norm, Euclidean norm) of all elements in x. The function uses conjugate transpose in the product, hence it always returns a float number.
val max_pool :
?padding:Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t
val avg_pool :
?padding:Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t
std x computes the standard deviation of x along the axis dimension. By default, axis is set to the lowest dimension.
val mat2gray : ?amin:'a->?amax:'a->('a, 'b)t->('a, 'b)t
mat2gray ~amin ~amax x converts the matrix x to the intensity image. The elements in x are clipped by amin and amax, and they will be between 0. and 1. after conversion to represents the intensity.
ssqr x a computes the sum of squared differences of all the elements in x from constant a. This function only computes the square of each element rather than the conjugate transpose as sqr_nrm2 does.
ssqr_diff x y computes the sum of squared differences of every elements in x and its corresponding element in y.
val cross_entropy : (float, 'a)t->(float, 'a)t-> float
cross_entropy x y calculates the cross entropy between x and y using base e.
val clip_by_value : ?amin:'a->?amax:'a->('a, 'b)t->('a, 'b)t
clip_by_value ~amin ~amax x clips the elements in x based on amin and amax. The elements smaller than amin will be set to amin, and the elements greater than amax will be set to amax.
val clip_by_l2norm : float ->(float, 'a)t->(float, 'a)t
clip_by_l2norm t x clips the x according to the threshold set by t.
cov ~a calculates the covariance matrix of a wherein each row represents one observation and each column represents one random variable. a is normalised by the number of observations-1. If there is only one observation, it is normalised by 1.
cov ~a ~b takes two matrices as inputs. The functions flatten a and b first then returns a 2 x 2 matrix, so two must have the same number of elements.
kron a b calculates the Kronecker product between the matrices a and b. If a is an m x n matrix and b is a p x q matrix, then kron(a,b) is an m*p x n*q matrix formed by taking all possible products between the elements of a and the matrix b.