matx.runtime.ndarray module¶

Runtime NDArray API

class matx.runtime.ndarray.NDArray(arr: Union[int, float, list, List], shape: Union[list, List], dtype: str, device: str = 'cpu')[source]¶

Bases: Object

Lightweight NDArray implementation for matx runtime

The structure is currently just a container for a multi-dimensional array, without defining various types of transformations and arithmetic methods. The goal of the structure is to serve as a bridge tool and other machine learning frameworks (pytorch tensorflow) for the conversion of multidimensional arrays

Parameters:

arr (List) – Constructing the contents of an NDArray
shape (List) – Shape of the constructed NDArray
dtype (str) – The type of the constructed NDArray element, supporting “int32” “int64” “float32” “float64”

Construction method 1

arr is a one-dimensional List, the shape is not empty, producing NDArray with the content of arr and the shape of the given shape

Examples:

>>> import matx
>>> nd = matx.NDArray([1,2,3,4,5,6], [3,2], "int32")
>>> nd
[
 [ 1 2 ]
 [ 3 4 ]
 [ 5 6 ]
]

Construction method 2

arr is a List of arbitrary dimensions, shape is an empty List, producing NDArray with the same shape as arr and the same content as arr

Examples:

>>> import matx
>>> nd = matx.NDArray([[1, 2, 3,], [4, 5, 6]], [], "int32")
>>> nd
[
 [ 1 2 3 ]
 [ 4 5 6 ]
]

>>> nd = matx.NDArray([1, 2, 3, 4, 5, 6], [], "int32")
>>> nd
[1, 2, 3, 4, 5, 6]

Construction method 3

arr is empty, shape is not empty, return a NDArray corresponding to the random initialization content of the shape

Examples:

>>> imoprt matx
>>> nd = matx.NDArray([], [2, 3], "float32")
>>> nd
[
 [ 4.46171e-08 3.08678e-41 2.25609e-43 ]
 [ 0 8.15743e-06 4.5723e-41 ]
]

__init__(arr: Union[int, float, list, List], shape: Union[list, List], dtype: str, device: str = 'cpu')[source]¶

as_type(dtype: str)[source]¶

asnumpy()[source]¶

Construct a numpy.ndarray from the current NDArray. Note! This method cannot be compiled for use in matx.script

Returns:: numpy.ndarray

Examples

>>> import matx
>>> import numpy
>>> nd = matx.NDArray([[1,2,3],[4,5,6]], [], "int32")
>>> nd
[
 [1, 2, 3]
 [4, 5, 6]
]
>>> arr = nd.asnumpy()
>>> arr
array([[1, 2, 3],
    [4, 5, 6]], dtype=int32)

contiguous()[source]¶

Returns a copy of the ndarray with contiguous memory if the adarray is not contiguous. Otherwise, the original one is returned.

Returns:: matx.NDArray

Examples

>>> import matx
>>> x = matx.NDArray([1,2,3,4], [2,2], "int32")
>>> y = x.transpose()
>>> z = y.contiguous()
[[1, 3],
 [2, 4]]
>>> z.is_contiguous()
1

device()[source]¶: Returns the current NDArray device as a string

dim()[source]¶

Returns the number of array dimensions. Unlike numpy, this is a method and not a property.

Returns:: int

Examples

>>> import matx
>>> x = matx.NDArray([], [3,2], "int32")
>>> x.dim()
2

dtype()[source]¶

Returns the dtype of the current NDArray as a string

Returns:: “int32” “int64” “float32” “float64”
Return type:: str

Examples

>>> import matx
>>> x = matx.NDArray([], [3,2], "int32")
>>> x.dtype()
'int32'

from_numpy(source_array)[source]¶

Copy data from a numpy.ndarray to the current NDArray, requiring both to have the same size.: Note! This method cannot be compiled for use in matx.script

Parameters:: source_array (numpy.ndarray) –
Raises:: ValueError –
Returns:: self
Return type:: matx.NDArray

Examples

>>> import matx
>>> import numpy
>>> arr = numpy.random.rand(2, 3)
>>> arr
array([[0.0402096 , 0.99905783, 0.85840985],
    [0.89764146, 0.25342801, 0.566187  ]])
>>> nd = matx.NDArray([], arr.shape, str(arr.dtype))
>>> nd.from_numpy(arr)
[
 [0.0402096 , 0.99905783, 0.85840985]
 [0.89764146, 0.25342801, 0.566187  ]
]

is_contiguous()[source]¶

Returns a int indicating if the underlying data is contiguous in memory. The continuity of array changes when its stride changes.

Returns:: int

Examples

>>> import matx
>>> x = matx.NDArray([1,2,3,4], [2,2], "int32")
>>> y = x.transpose()
>>> y.is_contiguous()
0

numpy()[source]¶

Construct a numpy.ndarray from the current NDArray. Note! This method cannot be compiled for use in matx.script

Returns:: numpy.ndarray

Examples

>>> import matx
>>> import numpy
>>> nd = matx.NDArray([[1,2,3],[4,5,6]], [], "int32")
>>> nd
[
 [1, 2, 3]
 [4, 5, 6]
]
>>> arr = nd.numpy()
>>> arr
array([[1, 2, 3],
    [4, 5, 6]], dtype=int32)

release()[source]¶

reshape(newshape: Union[tuple, list])[source]¶

shape()[source]¶

Returns the current NDArray’s shape, unlike numpy, this is a method and not a property

Returns:: matx.List

Examples

>>> import matx
>>> x = matx.NDArray([], [3,2], "int32")
>>> x.shape()
[3, 2]

squeeze(axis: tuple = ())[source]¶

stride()[source]¶

Returns List of bytes to step in each dimension when traversing an array.

Returns: matx.List

Examples

>>> import matx
>>> x = matx.NDArray([1,2,3,4], [2,2], "int32")
>>> y = x.transpose()
>>> y.stride()
[1, 2]

to_dlpack()[source]¶

to_list()[source]¶

Convert a NDArray to a matx.List corresponding to the shape

Returns:: matx.List

Examples

>>> import matx
>>> nd = matx.NDArray([], [2, 3], "float32")
>>> nd
[
 [ 1.35134e-24 4.55548e-41 1.35134e-24 ]
 [ 4.55548e-41 7.41622e+14 3.06142e-41 ]
]
>>> l = nd.to_list()
>>> l
[[1.35134e-24, 4.55548e-41, 1.35134e-24], [4.55548e-41, 7.41622e+14, 3.06142e-41]]

tolist()[source]¶

Convert a NDArray to a matx.List corresponding to the shape

Returns:: matx.List

Examples

>>> import matx
>>> nd = matx.NDArray([], [2, 3], "float32")
>>> nd
[
 [ 1.35134e-24 4.55548e-41 1.35134e-24 ]
 [ 4.55548e-41 7.41622e+14 3.06142e-41 ]
]
>>> l = nd.tolist()
>>> l
[[1.35134e-24, 4.55548e-41, 1.35134e-24], [4.55548e-41, 7.41622e+14, 3.06142e-41]]

torch(copy=True)[source]¶

convert NDArray to torch.Tensor, make sure NDArray is synchronized

Returns:: torch.Tensor

transpose(axes=None)[source]¶

Reverse or permute the axes of an array

Parameters:: axes (list of ints) –

Returns :: the given with its axes permuted. A view is returned whenever possible

unsqueeze(dim: int)[source]¶

matx.runtime.ndarray.add(lhs, rhs)[source]¶

Supports addition between NDArray and NDArray: Supports addition between NDArray and numbers

Supports broadcasting(https://numpy.org/doc/stable/user/basics.broadcasting.html)

Specific use of the interface: matx.array.add

Parameters:

lhs (matx.NDArray or number) – Left operand
rhs (matx.NDArray or number) – Right operand

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd1 = matx.array.rand([2, 3]) # Analogous to numpy.random.rand(2, 3)
>>> nd1
[
 [ 0.767908 0.0856769 0.93522 ]
 [ 0.91489 0.347408 0.896765 ]
]

>>> nd2 = matx.array.rand([2, 1, 3])
>>> nd2
[
 [
  [ 0.811942 0.00867774 0.2914 ]
 ]
 [
  [ 0.186276 0.200477 0.650708 ]
 ]
]

>>> nd3 = matx.array.add(nd1, nd2)
>>> nd3
[
 [
  [ 1.57985 0.0943547 1.22662 ]
  [ 1.72683 0.356086 1.18816 ]
 ]
 [
  [ 0.954184 0.286154 1.58593 ]
  [ 1.10117 0.547885 1.54747 ]
 ]
]

>>> nd3.shape()
[2, 2, 3]
>>>
>>> nd3 = matx.array.add(nd1, 2.0)
>>> nd3
[
 [ 2.69112 2.45002 2.5514 ]
 [ 2.22683 2.73329 2.75127 ]
]

matx.runtime.ndarray.concatenate(seq, axes=0)[source]¶

Concatenates the given sequence of seq tensors in the given dimension, Similar to numpy.concatenate

Specific use of the interface: matx.array.concatenate

Parameters:

seq (List[matx.NDArray] or Tuple[matx.NDArray]) –
axes (int, optional) – dim

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd = matx.NDArray([0, 1, 2, 3, 4, 5, 6, 7], [2, 2, 2], "int32")
>>> matx.array.concatenate([nd, nd], 0)
[
 [
  [ 0 1 ]
  [ 2 3 ]
 ]
 [
  [ 4 5 ]
  [ 6 7 ]
 ]
 [
  [ 0 1 ]
  [ 2 3 ]
 ]
 [
  [ 4 5 ]
  [ 6 7 ]
 ]
]

>>> matx.array.concatenate([nd, nd], 1)
[
 [
  [ 0 1 ]
  [ 2 3 ]
  [ 0 1 ]
  [ 2 3 ]
 ]
 [
  [ 4 5 ]
  [ 6 7 ]
  [ 4 5 ]
  [ 6 7 ]
 ]
]

>>> matx.array.concatenate([nd, nd], 2)
[
 [
  [ 0 1 0 1 ]
  [ 2 3 2 3 ]
 ]
 [
  [ 4 5 4 5 ]
  [ 6 7 6 7 ]
 ]
]

matx.runtime.ndarray.div(lhs, rhs)[source]¶

Support division between NDArray and NDArray: Support division between NDArray and numbers

Supports broadcasting(https://numpy.org/doc/stable/user/basics.broadcasting.html)

Specific use of the interface: matx.array.div

Parameters:

lhs (matx.NDArray or number) – Left operand
rhs (matx.NDArray or number) – Right operand

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd1 = matx.array.rand([2, 3]) # Analogous to numpy.random.rand(2, 3)
>>> nd1
[
 [ 0.767908 0.0856769 0.93522 ]
 [ 0.91489 0.347408 0.896765 ]
]

>>> nd2 = matx.array.rand([2, 1, 3])
>>> nd2
[
 [
  [ 0.811942 0.00867774 0.2914 ]
 ]
 [
  [ 0.186276 0.200477 0.650708 ]
 ]
]

>>> nd3 = matx.array.div(nd1, nd2)
>>> nd3
[
 [
  [ 0.85119 51.8594 1.89225 ]
  [ 0.279369 84.5028 2.57815 ]
 ]
 [
  [ 3.71017 2.24476 0.847389 ]
  [ 1.21772 3.65775 1.15455 ]
 ]
]

>>> nd3.shape()
[2, 2, 3]
>>>
>>> nd3 = matx.array.div(nd1, 2)
>>> nd3
[
 [ 0.345559 0.225011 0.275701 ]
 [ 0.113416 0.366647 0.375637 ]
]

matx.runtime.ndarray.from_dlpack(dltensor)[source]¶

Produce an array from a DLPack tensor without memory copy. Retreives the underlying DLPack tensor’s pointer to create an array from the data. Removes the original DLPack tensor’s destructor as now the array is responsible for destruction.

Parameters:: dltensor (DLPack tensor) – Input DLManagedTensor, can only be consumed once.
Returns:: arr – The array view of the tensor data.
Return type:: nd.NDArray

matx.runtime.ndarray.from_numpy(arr, device='cpu')[source]¶

Construct a module method for matx.NDArray from numpy.ndarray.: Note! This method cannot be compiled for use in matx.script

Parameters:

arr (numpy.ndarray) –
(MATXScriptDevice (device) – The device context to create the array)
optional – The device context to create the array)

Returns:

matx.NDArray

Examples

>>> import numpy
>>> import matx
>>> arr = numpy.random.rand(2, 3)
>>> nd = matx.array.from_numpy(arr)
>>> nd
[
 [0.39801043, 0.5075788 , 0.58423371]
 [0.34059181, 0.90339341, 0.72762747]
]

matx.runtime.ndarray.mul(lhs, rhs)[source]¶

Support multiplication between NDArray and NDArray: Support multiplication between NDArray and numbers

support broadcasting(https://numpy.org/doc/stable/user/basics.broadcasting.html)

Specific use of the interface: matx.array.mul

Parameters:

lhs (matx.NDArray or number) – Left operand
rhs (matx.NDArray or number) – Right operand

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd1 = matx.array.rand([2, 3]) # Analogous to numpy.random.rand(2, 3)
>>> nd1
[
 [ 0.767908 0.0856769 0.93522 ]
 [ 0.91489 0.347408 0.896765 ]
]

>>> nd2 = matx.array.rand([2, 1, 3])
>>> nd2
[
 [
  [ 0.811942 0.00867774 0.2914 ]
 ]
 [
  [ 0.186276 0.200477 0.650708 ]
 ]
]

>>> nd3 = matx.array.mul(nd1, nd2)
>>> nd3
[
 [
  [ 0.561147 0.00390518 0.160679 ]
  [ 0.184174 0.00636333 0.218921 ]
 ]
 [
  [ 0.128739 0.0902191 0.358802 ]
  [ 0.0422533 0.147008 0.48886 ]
 ]
]

>>> nd3.shape()
[2, 2, 3]
>>>
>>> nd3 = matx.array.mul(nd1, 2)
>>> nd3
[
 [ 1.38223 0.900045 1.1028 ]
 [ 0.453663 1.46659 1.50255 ]
]

matx.runtime.ndarray.rand(shape)[source]¶

Returns a NDArray filled with random numbers from a uniform distribution on the interval[0, 1), similar to numpy.rando.rand

Analogous to: matx.array.rand

Parameters:: shape (List) –
Returns:: matx.NDArray

Examples

>>> import matx
>>> nd = marx.nd_rand([2, 3])
>>> nd

[
[ 0.145728 0.357696 0.574777 ] [ 0.437011 0.0172242 0.704895 ]

]
>>> nd.shape()
[2, 3]
>>> nd.dtype()
'float32'

matx.runtime.ndarray.stack(seq, axes=0)[source]¶

Concatenates a sequence of NDArray along a new dimension.

Specific use of the interface: matx.array.stack

Parameters:

seq (List[matx.NDArray] or Tuple[matx.NDArray]) –
axes (int, optional) – dim

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd = matx.NDArray([0, 1, 2, 3, 4, 5, 6, 7], [2, 2, 2], "int32")
>>> matx.array.stack([nd, nd], 0)
[
 [
  [
    [ 0 1 ]
    [ 2 3 ]
  ]
  [
    [ 4 5 ]
    [ 6 7 ]
  ]
 ]
 [
  [
    [ 0 1 ]
    [ 2 3 ]
  ]
  [
    [ 4 5 ]
    [ 6 7 ]
  ]
 ]
]

>>> matx.array.stack([nd, nd], 1)
[
 [
  [
    [ 0 1 ]
    [ 2 3 ]
  ]
  [
    [ 0 1 ]
    [ 2 3 ]
  ]
 ]
 [
  [
    [ 4 5 ]
    [ 6 7 ]
  ]
  [
    [ 4 5 ]
    [ 6 7 ]
  ]
 ]
]

>>> matx.array.stack([nd, nd], 2)
[
 [
  [
    [ 0 1 ]
    [ 0 1 ]
  ]
  [
    [ 2 3 ]
    [ 2 3 ]
  ]
 ]
 [
  [
    [ 4 5 ]
    [ 4 5 ]
  ]
  [
    [ 6 7 ]
    [ 6 7 ]
  ]
 ]
]

matx.runtime.ndarray.sub(lhs, rhs)[source]¶

Support subtraction between NDArray and NDArray: Support subtraction between NDArray and numbers

Support broadcasting(https://numpy.org/doc/stable/user/basics.broadcasting.html)

Specific use of the interface: matx.array.sub

Parameters:

lhs (matx.NDArray or number) – Left operand
rhs (matx.NDArray or number) – Right operand

Returns:

matx.NDArray

Examples

>>> import matx
>>> nd1 = matx.array.rand([2, 3]) # Analogous to numpy.random.rand(2, 3)
>>> nd1
[
 [ 0.767908 0.0856769 0.93522 ]
 [ 0.91489 0.347408 0.896765 ]
]

>>> nd2 = matx.array.rand([2, 1, 3])
>>> nd2
[
 [
  [ 0.811942 0.00867774 0.2914 ]
 ]
 [
  [ 0.186276 0.200477 0.650708 ]
 ]
]

>>> nd3 = matx.array.sub(nd1, nd2)
>>> nd3
[
 [
  [ -0.120825 0.441345 0.260003 ]
  [ -0.58511 0.724615 0.459874 ]
 ]
 [
  [ 0.504841 0.249546 -0.0993055 ]
  [ 0.0405553 0.532816 0.100566 ]
 ]
]

>>> nd3.shape()
[2, 2, 3]
>>>
>>> nd3 = matx.array.sub(nd1, 2.0)
>>> nd3
[
 [ -1.30888 -1.54998 -1.4486 ]
 [ -1.77317 -1.26671 -1.24873 ]
]