# NDArray API¶

NDArray package (mxnet.ndarray) contains tensor operations similar to numpy.ndarray. The syntax is similar except for some additional calls to deal with I/O and multi-devices.

## Create NDArray¶

Like numpy, you could create mxnet.ndarray like followings:

>>> import mxnet as mx
>>> # all-zero array of dimension 100x50
>>> a = mx.nd.zeros((100, 50))
>>> # all-one array of dimension 256x32x128x1
>>> b = mx.nd.ones((256, 32, 128, 1))
>>> # initialize array with contents
>>> c = mx.nd.array([[1, 2, 3], [4, 5, 6]])


## NDArray operations¶

We provide some basic ndarray operations like arithmetic and slice operations. More operations are coming in handy!

### Arithmetic operations¶

>>> import mxnet as mx
>>> a = mx.nd.zeros((100, 50))
>>> a.shape
(100L, 50L)
>>> b = mx.nd.ones((100, 50))
>>> # c and d will be calculated in parallel here!
>>> c = a + b
>>> d = a - b
>>> # inplace operation, b's contents will be modified, but c and d won't be affected.
>>> b += d


### Slice operations¶

>>> import mxnet as mx
>>> a = mx.nd.zeros((100, 50))
>>> a[0:10] = 1   # first 10 rows will become 1


## Conversion from/to numpy.ndarray¶

MXNet NDArray supports pretty nature way to convert from/to mxnet.ndarray to/from numpy.ndarray:

>>> import mxnet as mx
>>> import numpy as np
>>> a = np.array([1,2,3])
>>> b = mx.nd.array(a)                  # convert from numpy array
>>> b
<mxnet.ndarray.NDArray object at ...>
>>> b.asnumpy()                         # convert to numpy array
array([ 1., 2., 3.], dtype=float32)


You can always use pickle to save and load NDArrays. We also provide functions to help save and load list or dictionary of NDArrays from file systems.

>>> import mxnet as mx
>>> a = mx.nd.zeros((100, 200))
>>> b = mx.nd.zeros((100, 200))
>>> # save list of NDArrays
>>> mx.nd.save("/path/to/array/file", [a, b])
>>> # save dictionary of NDArrays to AWS S3
>>> mx.nd.save("s3://path/to/s3/array", {'A' : a, 'B' : b})
>>> # save list of NDArrays to hdfs.
>>> mx.nd.save("hdfs://path/to/hdfs/array", [a, b])


The good thing about using the above save and load interface is that:

• You could use the format across all mxnet language bindings.
• Already support S3 and HDFS.

## Multi-device Support¶

The device information is stored in mxnet.Context structure. When creating ndarray in mxnet, user could either use the context argument (default is CPU context) to create arrays on specific device or use the with statement as follows:

>>> import mxnet as mx
>>> cpu_a = mx.nd.zeros((100, 200))
>>> cpu_a.context
cpu(0)
>>> with mx.Context(mx.gpu(0)):
>>>   gpu_a = mx.nd.ones((100, 200))
>>> gpu_a.context
gpu(0)
>>> ctx = mx.Context(mx.gpu(0))
>>> gpu_b = mx.nd.zeros((100, 200), ctx)
>>> gpu_b.context
gpu(0)


Currently, we DO NOT allow operations among arrays from different contexts. To allow this, use copyto member function to copy the content to different devices and continue computation:

>>> import mxnet as mx
>>> x = mx.nd.zeros((100, 200))
>>> with mx.Context(mx.gpu(0)):
>>>   y = mx.nd.zeros((100, 200))
>>> z = x + y
mxnet.base.MXNetError: [13:29:12] src/ndarray/ndarray.cc:33: Check failed: lhs.ctx() == rhs.ctx() operands context mismatch
>>> cpu_y = mx.nd.zeros((100, 200))
>>> y.copyto(cpu_y)
>>> z = x + cpu_y


## NDArray API Reference¶

NDArray API of mxnet.

mxnet.ndarray.waitall()

Wait all async operation to finish in MXNet

This function is used for benchmark only

class mxnet.ndarray.NDArray(handle, writable=True)

NDArray object in mxnet.

NDArray is basic ndarray/Tensor like data structure in mxnet.

__setitem__(in_slice, value)

Set ndarray value

__getitem__(in_slice)

Get ndarray

reshape(new_shape)

Return a reshaped NDArray that shares memory with current one.

Parameters: new_shape (iterable of int) – new shape of NDArray
broadcast_to(shape)

Broadcasting the current NDArray into the given shape. The semantics is the same with numpy‘s broadcasting

wait_to_read()

Block until all pending writes operations on current NDArray are finished.

This function will return when all the pending writes to the current NDArray finishes. There can still be pending read going on when the function returns.

shape

Get shape of current NDArray.

Returns: a tuple representing shape of current ndarray
size

Get size of current NDArray.

Returns: an int representing size of current ndarray
context

Get context of current NDArray.

Returns: context – The context of current NDArray. mxnet.Context
dtype

Get data type of current NDArray.

Returns: an numpy.dtype object representing type of current ndarray
T

Get transpose of current NDArray

asnumpy()

Return a copied numpy array of current array.

Returns: array – A copy of array content. numpy.ndarray
asscalar()

Return a CPU scalar(float) of current ndarray.

This ndarray must have shape (1,)

Returns: scalar – The scalar representation of the ndarray. np.float
astype(dtype)

Return a copied numpy array of current array with specified type.

Parameters: dtype (numpy.dtype or string) – Desired type of result array. array – A copy of array content. numpy.ndarray
copyto(other)

Copy the content of current array to other.

When other is NDArray, the content is copied over. When other is a Context, a new NDArray in the context will be created as target

Parameters: other (NDArray or Context) – Target NDArray or context we want to copy data to. dst – The copy target NDArray NDArray
copy()

Make a copy of the current ndarray on the same context

Returns: cpy – The copy NDArray
as_in_context(context)

Return an NDArray that lives in the target context. If the array is already in that context, self is returned. Otherwise, a copy is made.

Parameters: context (Context) – The target context we want the return value to live in. A copy or self as an NDArray that lives in the target context.
mxnet.ndarray.onehot_encode(indices, out)

One hot encoding indices into matrix out.

Parameters: indices (NDArray) – An NDArray containing indices of the categorical features. out (NDArray) – The result holder of the encoding. out – Same as out. Array
mxnet.ndarray.empty(shape, ctx=None, dtype=<Mock name='mock.float32' id='47926572494224'>)

Create an empty uninitialized new NDArray, with specified shape.

Parameters: shape (tuple) – shape of the NDArray. ctx (Context, optional) – The context of the NDArray, default to current default context. out – The created NDArray. Array
mxnet.ndarray.add(lhs, rhs)

Parameters: lhs (Array or float value) – left hand side operand rhs (Array of float value) – right hand side operand out – result array Array
mxnet.ndarray.subtract(lhs, rhs)

Perform element-wise subtract

Parameters: lhs (Array or float value) – left hand side operand rhs (Array of float value) – right hand side operand out – result array Array
mxnet.ndarray.multiply(lhs, rhs)

Perform element-wise multiplication

Parameters: lhs (Array or float value) – left hand side operand rhs (Array of float value) – right hand side operand out – result array Array
mxnet.ndarray.divide(lhs, rhs)

Perform element-wise divide

Parameters: lhs (Array or float value) – left hand side operand rhs (Array of float value) – right hand side operand out – result array Array
mxnet.ndarray.true_divide(lhs, rhs)

Same as numpy’s true_divide. It adjusts the output type to present the best answer, regardless of input types.

mxnet.ndarray.negative(arr)

Return the negation of array values

mxnet.ndarray.zeros(shape, ctx=None, dtype=<Mock name='mock.float32' id='47926572494224'>)

Create a new NDArray filled with 0, with specified shape.

Parameters: shape (tuple) – shape of the NDArray. ctx (Context, optional.) – The context of the NDArray, default to current default context. out – The created NDArray. Array
mxnet.ndarray.ones(shape, ctx=None, dtype=<Mock name='mock.float32' id='47926572494224'>)

Create a new NDArray filled with 1, with specified shape.

Parameters: shape (tuple) – shape of the NDArray. ctx (Context, optional) – The context of the NDArray, default to current default context. out – The created NDArray. Array
mxnet.ndarray.sum(arr, axis=None, keepdims=False)

Sum the array along given axises. The semantic strictly follows numpy’s document.

Parameters: arr (Array) – the array to be reduced axis (int or list(int), optional) – along which axis to do reduction keepdims (bool) – whether the reduced axis should be kept in the final shape out – The reduced NDArray. Array
mxnet.ndarray.max(arr, axis=None, keepdims=False)

Take the maximum of the array along given axises. The semantic strictly follows numpy’s document.

Parameters: arr (Array) – the array to be reduced axis (int or list(int), optional) – along which axis to do reduction keepdims (bool) – whether the reduced axis should be kept in the final shape out – The reduced NDArray. Array
mxnet.ndarray.min(arr, axis=None, keepdims=False)

Take the minimum of the array along given axises. The semantic strictly follows numpy’s document.

Parameters: arr (Array) – the array to be reduced axis (int or list(int), optional) – along which axis to do reduction keepdims (bool) – whether the reduced axis should be kept in the final shape out – The reduced NDArray. Array
mxnet.ndarray.full(shape, val, ctx=None)

Create a new NDArray filled with given value, with specified shape.

Parameters: shape (tuple) – shape of the NDArray. val (float) – value to be filled with. ctx (Context, optional) – The context of the NDArray, default to current default context. out – The created NDArray. Array
mxnet.ndarray.array(source_array, ctx=None, dtype=<Mock name='mock.float32' id='47926572494224'>)

Create a new NDArray that copies content from source_array.

Parameters: source_array (array_like) – Source data to create NDArray from. ctx (Context, optional) – The context of the NDArray, default to current default context. out – The created NDArray. Array
mxnet.ndarray.concatenate(arrays, always_copy=True)

Concatenate a list of NDArrays along the first dimension.

Parameters: arrays (list of NDArray) – Arrays to be concatenate. They must have identical shape except the first dimension. They also must have the same data type. always_copy (bool) – Default True. When not True, if the arrays only contain one NDArray, that element will be returned directly, avoid copying. An NDArray that lives on the same context as arrays[0].context.
mxnet.ndarray.load(fname)

You can also use pickle to do the job if you only work on python. The advantage of load/save is the file is language agnostic. This means the file saved using save can be loaded by other language binding of mxnet. You also get the benefit being able to directly load/save from cloud storage(S3, HDFS)

Parameters: fname (str) – The name of the file.Can be S3 or HDFS address (remember built with S3 support). Example of fname: s3://my-bucket/path/my-s3-ndarray hdfs://my-bucket/path/my-hdfs-ndarray /path-to/my-local-ndarray out – List of NDArray or dict of str->NDArray, depending on what was saved. list of NDArray or dict of str to NDArray
mxnet.ndarray.save(fname, data)

Save list of NDArray or dict of str->NDArray to binary file.

You can also use pickle to do the job if you only work on python. The advantage of load/save is the file is language agnostic. This means the file saved using save can be loaded by other language binding of mxnet. You also get the benefit being able to directly load/save from cloud storage(S3, HDFS)

Parameters: fname (str) – The name of the file.Can be S3 or HDFS address (remember built with S3 support). Example of fname: s3://my-bucket/path/my-s3-ndarray hdfs://my-bucket/path/my-hdfs-ndarray /path-to/my-local-ndarray data (list of NDArray or dict of str to NDArray) – The data to be saved.
mxnet.ndarray.imdecode(str_img, clip_rect=(0, 0, 0, 0), out=None, index=0, channels=3, mean=None)

Decode an image from string. Requires OpenCV to work.

Parameters: str_img (str) – binary image data clip_rect (iterable of 4 int) – clip decoded image to rectangle (x0, y0, x1, y1) out (NDArray) – output buffer. can be 3 dimensional (c, h, w) or 4 dimensional (n, c, h, w) index (int) – output decoded image to i-th slice of 4 dimensional buffer channels (int) – number of channels to output. Decode to grey scale when channels = 1. mean (NDArray) – substract mean from decode image before outputing.
mxnet.ndarray.abs(src, out=None, *args, **kwargs)

Take absolute value of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.argmax_channel(src, out=None, *args, **kwargs)

Take argmax indices of each channel of the src.The result will be ndarray of shape (num_channel,) on the same device.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.broadcast_axis(src, out=None, *args, **kwargs)

Broadcast data in the given axis to the given size. The original size of the broadcasting axis must be 1.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.broadcast_div(lhs, rhs, out=None, **kwargs)

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.broadcast_minus(lhs, rhs, out=None, **kwargs)

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.broadcast_mul(lhs, rhs, out=None, **kwargs)

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.broadcast_plus(lhs, rhs, out=None, **kwargs)

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.ceil(src, out=None, *args, **kwargs)

Take ceil value of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.choose_element_0index(lhs, rhs, out=None, **kwargs)

Choose one element from each line(row for python, column for R/Julia) in lhs according to index indicated by rhs. This function assume rhs uses 0-based index.

Parameters: lhs (NDArray) – Left operand to the function. rhs (NDArray) – Right operand to the function. out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.clip(*args, **kwargs)

Clip ndarray elements to range (a_min, a_max)

Parameters: src (NDArray) – Source input a_min (real_t) – Minimum value a_max (real_t) – Maximum value out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.cos(src, out=None, *args, **kwargs)

Take cos of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.crop(src, out=None, *args, **kwargs)

Crop the input matrix and return a new one

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.dot(lhs, rhs, out=None, **kwargs)

Calculate dot product of two matrices or two vectors

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.exp(src, out=None, *args, **kwargs)

Take exp of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.fill_element_0index(*args, **kwargs)

Fill one element of each line(row for python, column for R/Julia) in lhs according to index indicated by rhs and values indicated by mhs. This function assume rhs uses 0-based index.

Parameters: lhs (NDArray) – Left operand to the function. mhs (NDArray) – Middle operand to the function. rhs (NDArray) – Right operand to the function. out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.flip(src, out=None, *args, **kwargs)

Flip the input matrix along axis and return a new one

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.floor(src, out=None, *args, **kwargs)

Take floor value of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.log(src, out=None, *args, **kwargs)

Take log of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.max_axis(src, out=None, *args, **kwargs)

Take max of the src in the given axis. axis=-1 means to reduce all the dimensions.The keepdims option has the same meaning as Numpy.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.max_internal(src, out=None, *args, **kwargs)

(Deprecated! Use max_axis instead.) Take max of the src.The result will be ndarray of shape (1,) on the same device.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.min_axis(src, out=None, *args, **kwargs)

Take min of the src in the given axis. axis=-1 means to reduce all the dimensions.The keepdims option has the same meaning as Numpy.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.min_internal(src, out=None, *args, **kwargs)

(Deprecated! Use min_axis instead.) Take min of the src.The result will be ndarray of shape (1,) on the same device.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.norm(src, out=None, *args, **kwargs)

Take L2 norm of the src.The result will be ndarray of shape (1,) on the same device.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.round(src, out=None, *args, **kwargs)

Take round value of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.rsqrt(src, out=None, *args, **kwargs)

Take rsqrt of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.sign(src, out=None, *args, **kwargs)

Take sign value of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.sin(src, out=None, *args, **kwargs)

Take sin of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.smooth_l1(src, out=None, *args, **kwargs)

Calculate Smooth L1 Loss(lhs, scalar)

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.softmax_cross_entropy(lhs, rhs, out=None, **kwargs)

Calculate cross_entropy(lhs, one_hot(rhs))

Parameters: lhs (NDArray) – Left operand to the function rhs (NDArray) – Right operand to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.sqrt(src, out=None, *args, **kwargs)

Take sqrt of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.square(src, out=None, *args, **kwargs)

Take square of the src

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.sum_axis(src, out=None, *args, **kwargs)

Take sum of the src in the given axis. axis=-1 means to reduce all the dimensions.The keepdims option has the same meaning as Numpy.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.sum_internal(src, out=None, *args, **kwargs)

(Deprecated! Use sum_axis instead.) Take sum of the src.The result will be ndarray of shape (1,) on the same device.

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray
mxnet.ndarray.transpose(src, out=None, *args, **kwargs)

Transpose the input matrix and return a new one

Parameters: src (NDArray) – Source input to the function out (NDArray, optional) – The output NDArray to hold the result. out – The output of binary function. NDArray

## NDArray Random API Reference¶

Random Number interface of mxnet.

mxnet.random.uniform(low, high, shape=None, ctx=None, out=None)

Generate uniform distribution in [low, high) with shape.

Parameters: low (float) – The lower bound of distribution. high (float) – The upper bound of distribution. shape (tuple, optional) – Output shape of the NDArray generated. ctx (Context, optional) – Context of output NDArray, will use default context if not specified. out (NDArray, optional) – Output place holder out – The result NDArray with generated result. NDArray
mxnet.random.normal(mean, stdvar, shape=None, ctx=None, out=None)

Generate normal(Gaussian) distribution N(mean, stdvar^2) with shape.

Parameters: mean (float) – The mean of the normal distribution. stdvar (float) – The standard deviation of normal distribution. shape (tuple, optional) – Output shape of the NDArray generated. ctx (Context, optional) – Context of output NDArray, will use default context if not specified. out (NDArray, optional) – Output place holder out – The result NDArray with generated result. NDArray
mxnet.random.seed(seed_state)

Seed the random number generators in mxnet.

This seed will affect behavior of functions in this module, as well as results from executors that contains Random number such as Dropout operators.

Parameters: seed_state (int) – The random number seed to set to all devices.

Notes

The random number generator of mxnet is by default device specific. This means if you set the same seed, the random number sequence generated from GPU0 can be different from CPU.

## Context API Reference¶

Context management API of mxnet.

class mxnet.context.Context(device_type, device_id=0)

Constructing a context.

Parameters: device_type ({'cpu', 'gpu'} or Context.) – String representing the device type device_id (int (default=0)) – The device id of the device, needed for GPU

Note

Context can also be used a way to change default context.

Examples

>>> # array on cpu
>>> cpu_array = mx.md.ones((2, 3))
>>> # switch default context to GPU(2)
>>> with mx.Context(mx.gpu(2)):
>>>     gpu_array = mx.md.ones((2, 3))
>>> gpu_array.context
gpu(2)

device_type

Return device type of current context.

Returns: device_type str
__eq__(other)

Compare two contexts. Two contexts are equal if they have the same device type and device id.

mxnet.context.cpu(device_id=0)

Return a CPU context.

This function is a short cut for Context(‘cpu’, device_id)

Parameters: device_id (int, optional) – The device id of the device. device_id is not needed for CPU. This is included to make interface compatible with GPU. context – The corresponding CPU context. Context
mxnet.context.gpu(device_id=0)

Return a GPU context.

This function is a short cut for Context(‘gpu’, device_id)

Parameters: device_id (int, optional) – The device id of the device, needed for GPU context – The corresponding GPU context. Context
mxnet.context.current_context()

Return the current context.

Returns: default_ctx Context