Legend:
Library
Module
Module type
Parameter
Class
Class type
N-dimensional array 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 Bigarray.Float64 [|3;4;5|] creates a three diemensional array of type Bigarray.Float64. Each dimension has the following size: 3, 4, and 5. The elements in the array are not initialised, they can be any value. empty is faster than zeros to create a ndarray.
The module only supports the following four types of ndarray: Bigarray.Float32, Bigarray.Float64, Bigarray.Complex32, and Bigarray.Complex64.
val create : ('a, 'b)kind->int array->'a->('a, 'b)t
create Bigarray.Float64 [|3;4;5|] 2. creates a three-diemensional array of type Bigarray.Float64. Each dimension has the following size: 3, 4, and 5. The elements in the array are initialised to 2.
val init : ('a, 'b)kind->int array->(int ->'a)->('a, 'b)t
init Bigarray.Float64 d f creates a ndarray x of shape d, then using f to initialise the elements in x. The input of f is 1-dimensional index of the ndarray. You need to explicitly convert it if you need N-dimensional index. The function index_1d_nd can help you.
val init_nd : ('a, 'b)kind->int array->(int array->'a)->('a, 'b)t
init_nd is almost the same as init but f receives n-dimensional 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.
zeros Bigarray.Complex32 [|3;4;5|] creates a three-diemensional array of type Bigarray.Complex32. Each dimension has the following size: 3, 4, and 5. The elements in the array are initialised to "zero". Depending on the kind, zero can be 0. or Complex.zero.
ones Bigarray.Complex32 [|3;4;5|] creates a three-diemensional array of type Bigarray.Complex32. Each dimension has the following size: 3, 4, and 5. The elements in the array are initialised to "one". Depending on the kind, one can be 1. or Complex.one.
val uniform : ?scale:float ->('a, 'b)kind->int array->('a, 'b)t
uniform Bigarray.Float64 [|3;4;5|] creates a three-diemensional array of type Bigarray.Float64. Each dimension has the following size: 3, 4, and 5. The elements in the array follow a uniform distribution 0,1.
val gaussian : ?sigma:float ->('a, 'b)kind->int array->('a, 'b)t
gaussian Float64 [|3;4;5|] ...
val sequential : ('a, 'b)kind->?a:'a->?step:'a->int array->('a, 'b)t
sequential Bigarray.Float64 [|3;4;5|] 2. creates a three-diemensional array of type Bigarray.Float64. Each dimension has the following size: 3, 4, and 5. The elements in the array are assigned sequential values.
?a specifies the starting value and the default value is zero; whilst ?step specifies the step size with default value one.
val linspace : ('a, 'b)kind->'a->'a->int ->('a, 'b)t
linspace k 0. 9. 10 ...
val logspace : ('a, 'b)kind->?base:float ->'a->'a->int ->('a, 'b)t
logspace k 0. 9. 10 ...
val bernoulli :
('a, 'b)kind->?p:float ->?seed:int ->int array->('a, 'b)t
bernoulli k ~p:0.3 [|2;3;4|]
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.
kind x returns the type of ndarray x. It is one of the four possible values: Bigarray.Float32, Bigarray.Float64, Bigarray.Complex32, and Bigarray.Complex64.
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 i x a 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.
If the length of a equals to the length of i, then each element will be assigned by the value in the corresponding position in x. If the length of a equals to one, then all the elements will be assigned the same value.
slice s x returns a copy of the slice in x. The slice is defined by a which is an int option array. E.g., for a ndarray x of dimension [|2; 2; 3|], slice [0] x takes the following slices of index \(0,*,*\), i.e., [|0;0;0|], [|0;0;1|], [|0;0;2|] ... Also note that if the length of s is less than the number of dimensions of x, slice function will append slice definition to higher diemensions by assuming all the elements in missing dimensions will be taken.
Basically, slice function offers very much the same semantic as that in numpy, i.e., start:stop:step grammar, so if you how to index and slice ndarray in numpy, you should not find it difficult to use this function. Please just refer to numpy documentation or my tutorial.
There are two differences between slice_left and slice: slice_left does not make a copy but simply moving the pointer; slice_left can only make a slice from left-most axis whereas slice is much more flexible and can work on arbitrary axis which need not start from left-most side.
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]] .
val resize : ?head:bool ->('a, 'b)t->int array->('a, 'b)t
resize ~head x d resizes the ndarray x. If there are less number of elelments in the new shape than the old one, the new ndarray shares part of the memeory with the old x. head indicates the alignment between the new and old data, either from head or from tail. Note the data is flattened before the operation.
If there are more elements in the new shape d. Then new memeory space will be allocated and the content of x will be copied to the new memory. The rest of the allocated space will be filled with zeros.
reshape x d transforms x into a new shape definted by d. Note the reshape function will not make a copy of x, the returned ndarray 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.
val transpose : ?axis:int array->('a, 'b)t->('a, 'b)t
transpose ~axis x makes a copy of x, then transpose it according to ~axis. ~axis must be a valid permutation of x dimension indices. E.g., for a three-dimensional ndarray, it can be 2;1;0, 0;2;1, 1;2;0, and etc.
tile x a tiles the data in x according the repitition specified by a. This function provides the exact behaviour as numpy.tile, please refer to the numpy's online documentation for details.
val repeat : ?axis:int ->('a, 'b)t->int ->('a, 'b)t
repeat ~axis x a repeats the elements along axis for a times. The default value of ?axis is the highest dimension of x. This function is similar to numpy.repeat except that a is an integer instead of an array.
val concatenate : ?axis:int ->('a, 'b)t array->('a, 'b)t
concatenate ~axis:2 x concatenates an array of ndarrays along the third dimension. For the ndarrays 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 of a matrix/ndarray.
val split : ?axis:int ->int array->('a, 'b)t->('a, 'b)t array
split ~axis parts x
val squeeze : ?axis:int array->('a, 'b)t->('a, 'b)t
squeeze ~axis x removes single-dimensional entries from the shape of x.
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.
val mmap :
Unix.file_descr->?pos:int64 ->('a, 'b)kind->bool ->int array->('a, 'b)t
mmap fd kind layout shared dims ...
Iterate array elements
val iteri :
?axis:int option array->(int array->'a-> unit)->('a, 'b)t->
unit
iteri ~axis f x applies function f to each element in a slice defined by ~axis. If ~axis is not passed in, then iteri simply iterates all the elements in x.
val iter : ?axis:int option array->('a-> unit)->('a, 'b)t-> unit
iter ~axis f x is similar to iteri ~axis f x, excpet the index i of an element is not passed in f. Note that iter is much faster than iteri.
val mapi :
?axis:int option array->(int array->'a->'a)->('a, 'b)t->('a, 'b)t
mapi ~axis f x makes a copy of x, then applies f to each element in a slice defined by ~axis. If ~axis is not passed in, then mapi simply iterates all the elements in x.
val map : ?axis:int option array->('a->'a)->('a, 'b)t->('a, 'b)t
map ~axis f x is similar to mapi ~axis f x except the index of the current element is not passed to the function f. Note that map is much faster than mapi.
val map2i :
?axis:int option array->(int array->'a->'a->'a)->('a, 'b)t->('a, 'b)t->('a, 'b)t
map2i ~axis f x y applies f to two elements of the same position in a slice defined by ~axis in both x and y. If ~axis is not passed in, then map2i simply iterates all the elements in x and y. The two matrices mush have the same shape.
val map2 :
?axis:int option array->('a->'a->'a)->('a, 'b)t->('a, 'b)t->('a, 'b)t
map2 ~axis f x y is similar to map2i ~axis f x y except the index of the index of the current element is not passed to the function f.
filteri ~axis f x uses f to filter out certain elements in a slice defined by ~axis. An element will be included if f returns true. The returned result is a list of indices of the selected elements.
val filter :
?axis:int option array->('a-> bool)->('a, 'b)t->int array array
Similar to filteri, but the indices of the elements are not passed to f.
val foldi :
?axis:int option array->(int array->'c->'a->'c)->'c->('a, 'b)t->'c
foldi ~axis f a x folds all the elements in a slice defined by ~axis with the function f. If ~axis is not passed in, then foldi simply folds all the elements in x.
val fold : ?axis:int option array->('c->'a->'c)->'c->('a, 'b)t->'c
Similar to foldi, except that the index of an element is not passed to f.
val iteri_slice :
int array->(int array array->('a, 'b)t-> unit)->('a, 'b)t->
unit
iteri_slice s f x iterates the slices along the passed in axis indices s, and applies the function f to each of them. The order of iterating slices is based on the order of axis in s.
E.g., for a three-dimensional ndarray of shape [|2;2;2|], iteri_slice [|1;0|] f x will access the slices in the following order: [ [0]; [0]; [] ], [ [1]; [0]; [] ], [ [1]; [1]; [] ]. Also note the slice passed in f is a copy of the original data.
val iter_slice : int array->(('a, 'b)t-> unit)->('a, 'b)t-> unit
Similar to iteri_slice, except that the index of a slice is not passed to f.
val iter2i :
(int array->'a->'b-> unit)->('a, 'c)t->('b, 'd)t->
unit
Similar to iteri but applies to two N-dimensional arrays x and y. Both x and y must have the same shape.
val iter2 : ('a->'b-> unit)->('a, 'c)t->('b, 'd)t-> unit
Similar to iter2i, except that the index of a slice 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. For complex numbers, the eps applies to both real and imaginary part.
Note: the threshold check is exclusive for passed in eps, i.e., the threshold interval is (a-eps, a+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.
Input/Output functions
val of_array : ('a, 'b)kind->'a array->int array->('a, 'b)t
of_array k x d takes an array x and converts it into an ndarray of type k and shape d.
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 array) * ('a * int array)
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.
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.
relu x computes the rectified linear unit function max(x, 0) of the elements in x and returns the result in a new ndarray.
val elu : ?alpha:float ->(float, 'a)t->(float, 'a)t
elu alpha x computes the exponential linear unit function x >= 0. ? x : (alpha * (exp(x) - 1)) of the elements in x and returns the result in a new ndarray.
val leaky_relu : ?alpha:float ->(float, 'a)t->(float, 'a)t
leaky_relu alpha x computes the leaky rectified linear unit function x >= 0. ? x : (alpha * x) of the elements in x and returns the result in a new ndarray.
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.
cumsum ~axis x : performs cumulative sum of the elements along the given axis ~axis. If ~axis is None, then the cumsum is performed along the lowest dimension. The returned result however always remains the same shape.
add x y adds all the elements in x and y elementwise, and returns the result in a new ndarray.
General broadcast operation is automatically applied to add/sub/mul/div, etc. The function compares the dimension element-wise from the highest to the lowest with the following broadcast rules (same as numpy): 1. equal; 2. either is 1.
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 l2norm_sqr 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.
val conv1d_backward_input :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val conv1d_backward_kernel :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val conv2d_backward_input :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val conv2d_backward_kernel :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val conv3d_backward_input :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val conv3d_backward_kernel :
(float, 'a)t->(float, 'a)t->int array->(float, 'a)t->(float, 'a)t
val max_pool1d_backward :
Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t->(float, 'a)t
val max_pool2d_backward :
Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t->(float, 'a)t
val avg_pool1d_backward :
Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t->(float, 'a)t
val avg_pool2d_backward :
Owl_types.padding->(float, 'a)t->int array->int array->(float, 'a)t->(float, 'a)t
Some helper and experimental functions
The following functions are helper functions for some other functions in both Ndarray and Ndview modules. In general, you are not supposed to use these functions directly.