mxnet.util¶

general utility functions

Functions

mxnet.util.get_cuda_compute_capability(ctx)[source]¶

Returns the cuda compute capability of the input ctx.

Parameters

ctx (Context) – GPU context whose corresponding cuda compute capability is to be retrieved.

Returns

cuda_compute_capability – CUDA compute capability. For example, it returns 70 for CUDA arch equal to sm_70.

Return type

int

References

https://gist.github.com/f0k/63a664160d016a491b2cbea15913d549#file-cuda_check-py

mxnet.util.is_np_array()[source]¶

Checks whether the NumPy-array semantics is currently turned on. This is currently used in Gluon for checking whether an array of type mxnet.numpy.ndarray or mx.nd.NDArray should be created. For example, at the time when a parameter is created in a Block, an mxnet.numpy.ndarray is created if this returns true; else an mx.nd.NDArray is created.

Normally, users are not recommended to use this API directly unless you known exactly what is going on under the hood.

Please note that this is designed as an infrastructure for the incoming MXNet-NumPy operators. Legacy operators registered in the modules mx.nd and mx.sym are not guaranteed to behave like their counterparts in NumPy within this semantics.

Returns

Return type

A bool value indicating whether the NumPy-array semantics is currently on.

mxnet.util.is_np_shape()[source]¶

Checks whether the NumPy shape semantics is currently turned on. In NumPy shape semantics, () represents the shape of scalar tensors, and tuples with 0 elements, for example, (0,), (1, 0, 2), represent the shapes of zero-size tensors. This is turned off by default for keeping backward compatibility.

In the NumPy shape semantics, -1 indicates an unknown size. For example, (-1, 2, 2) means that the size of the first dimension is unknown. Its size may be inferred during shape inference.

Please note that this is designed as an infrastructure for the incoming MXNet-NumPy operators. Legacy operators registered in the modules mx.nd and mx.sym are not guaranteed to behave like their counterparts in NumPy within this semantics.

Returns

Return type

A bool value indicating whether the NumPy shape semantics is currently on.

Example

>>> import mxnet as mx
>>> prev_state = mx.set_np_shape(True)
>>> print(prev_state)
False
>>> print(mx.is_np_shape())
True

mxnet.util.np_array(active=True)[source]¶

Returns an activated/deactivated NumPy-array scope to be used in ‘with’ statement and captures code that needs the NumPy-array semantics.

Currently, this is used in Gluon to enforce array creation in Block`s as type `mxnet.numpy.ndarray, instead of mx.nd.NDArray.

It is recommended to use the decorator use_np_array to decorate the classes that need this semantics, instead of using this function in a with statement unless you know exactly what has been scoped by this semantics.

Please note that this is designed as an infrastructure for the incoming MXNet-NumPy operators. Legacy operators registered in the modules mx.nd and mx.sym are not guaranteed to behave like their counterparts in NumPy even within this scope.

Parameters

active (bool) – Indicates whether to activate NumPy-array semantics.

Returns

A scope object for wrapping the code w/ or w/o NumPy-shape semantics.

Return type

_NumpyShapeScope

mxnet.util.np_shape(active=True)[source]¶

Returns an activated/deactivated NumPy shape scope to be used in ‘with’ statement and captures code that needs the NumPy shape semantics, i.e. support of scalar and zero-size tensors.

Please note that this is designed as an infrastructure for the incoming MXNet-NumPy operators. Legacy operators registered in the modules mx.nd and mx.sym are not guaranteed to behave like their counterparts in NumPy even within this scope.

Parameters

active (bool) – Indicates whether to activate NumPy-shape semantics.

Returns

• _NumpyShapeScope – A scope object for wrapping the code w/ or w/o NumPy-shape semantics.

• Example:: –

  with mx.np_shape(active=True):

  # A scalar tensor’s shape is (), whose ndim is 0. scalar = mx.nd.ones(shape=()) assert scalar.shape == ()

  # If NumPy shape semantics is enabled, 0 in a shape means that # dimension contains zero elements. data = mx.sym.var(“data”, shape=(0, 2, 3)) ret = mx.sym.sin(data) arg_shapes, out_shapes, _ = ret.infer_shape() assert arg_shapes[0] == (0, 2, 3) assert out_shapes[0] == (0, 2, 3)

  # -1 means unknown shape dimension size in the new NumPy shape definition data = mx.sym.var(“data”, shape=(-1, 2, 3)) ret = mx.sym.sin(data) arg_shapes, out_shapes, _ = ret.infer_shape_partial() assert arg_shapes[0] == (-1, 2, 3) assert out_shapes[0] == (-1, 2, 3)

  # When a shape is completely unknown when NumPy shape semantics is on, it is # represented as None in Python. data = mx.sym.var(“data”) ret = mx.sym.sin(data) arg_shapes, out_shapes, _ = ret.infer_shape_partial() assert arg_shapes[0] is None assert out_shapes[0] is None

  with mx.np_shape(active=False):

  # 0 means unknown shape dimension size in the legacy shape definition. data = mx.sym.var(“data”, shape=(0, 2, 3)) ret = mx.sym.sin(data) arg_shapes, out_shapes, _ = ret.infer_shape_partial() assert arg_shapes[0] == (0, 2, 3) assert out_shapes[0] == (0, 2, 3)

  # When a shape is completely unknown in the legacy mode (default), its ndim is # equal to 0 and it is represented as () in Python. data = mx.sym.var(“data”) ret = mx.sym.sin(data) arg_shapes, out_shapes, _ = ret.infer_shape_partial() assert arg_shapes[0] == () assert out_shapes[0] == ()

mxnet.util.np_ufunc_legal_option(key, value)[source]¶

Checking if ufunc arguments are legal inputs

Parameters

• key (string) – the key of the ufunc argument.

• value (string) – the value of the ufunc argument.

Returns

legal – Whether or not the argument is a legal one. True when the key is one of the ufunc arguments and value is an allowed value. False when the key is not one of the ufunc arugments or the value is not an allowed value even when the key is a legal one.

Return type

boolean

mxnet.util.reset_np()[source]¶

Deactivate NumPy shape and array semantics at the same time.

mxnet.util.set_module(module)[source]¶

Decorator for overriding __module__ on a function or class.

Example usage:

@set_module('mxnet.numpy')
def example():
    pass

assert example.__module__ == 'numpy'

mxnet.util.set_np(shape=True, array=True)[source]¶

Setting NumPy shape and array semantics at the same time. It is required to keep NumPy shape semantics active while activating NumPy array semantics. Deactivating NumPy shape semantics while NumPy array semantics is still active is not allowed. It is highly recommended to set these two flags to True at the same time to fully enable NumPy-like behaviors. Please refer to the Examples section for a better understanding.

Parameters

• shape (bool) – A boolean value indicating whether the NumPy-shape semantics should be turned on or off. When this flag is set to True, zero-size and zero-dim shapes are all valid shapes in shape inference process, instead of treated as unknown shapes in legacy mode.

• array (bool) – A boolean value indicating whether the NumPy-array semantics should be turned on or off. When this flag is set to True, it enables Gluon code flow to use or generate mxnet.numpy.ndarray`s instead of `mxnet.ndarray.NDArray. For example, a Block would create parameters of type mxnet.numpy.ndarray.

Examples

>>> import mxnet as mx

Creating zero-dim ndarray in legacy mode would fail at shape inference.

>>> mx.nd.ones(shape=())
mxnet.base.MXNetError: Operator _ones inferring shapes failed.

>>> mx.nd.ones(shape=(2, 0, 3))
mxnet.base.MXNetError: Operator _ones inferring shapes failed.

In legacy mode, Gluon layers would create parameters and outputs of type mx.nd.NDArray.

>>> from mxnet.gluon import nn
>>> dense = nn.Dense(2)
>>> dense.initialize()
>>> dense(mx.nd.ones(shape=(3, 2)))
[[0.01983214 0.07832371]
 [0.01983214 0.07832371]
 [0.01983214 0.07832371]]
<NDArray 3x2 @cpu(0)>

>>> [p.data() for p in dense.collect_params().values()]
[
[[0.0068339  0.01299825]
 [0.0301265  0.04819721]]
<NDArray 2x2 @cpu(0)>,
[0. 0.]
<NDArray 2 @cpu(0)>]

When the shape flag is True, both shape inferences are successful.

>>> from mxnet import np, npx
>>> npx.set_np()  # this is required to activate NumPy-like behaviors

>>> np.ones(shape=())
array(1.)
>>> np.ones(shape=(2, 0, 3))
array([], shape=(2, 0, 3))

When the array flag is True, Gluon layers would create parameters and outputs of type mx.np.ndarray.

>>> dense = nn.Dense(2)
>>> dense.initialize()
>>> dense(np.ones(shape=(3, 2)))
array([[0.01983214, 0.07832371],
       [0.01983214, 0.07832371],
       [0.01983214, 0.07832371]])

>>> [p.data() for p in dense.collect_params().values()]
[array([[0.0068339 , 0.01299825],
       [0.0301265 , 0.04819721]]), array([0., 0.])]

mxnet.util.set_np_shape(active)[source]¶

Turns on/off NumPy shape semantics, in which () represents the shape of scalar tensors, and tuples with 0 elements, for example, (0,), (1, 0, 2), represent the shapes of zero-size tensors. This is turned off by default for keeping backward compatibility.

Please note that this is designed as an infrastructure for the incoming MXNet-NumPy operators. Legacy operators registered in the modules mx.nd and mx.sym are not guaranteed to behave like their counterparts in NumPy within this semantics.

Parameters

active (bool) – Indicates whether to turn on/off NumPy shape semantics.

Returns

Return type

A bool value indicating the previous state of NumPy shape semantics.

Example

>>> import mxnet as mx
>>> prev_state = mx.set_np_shape(True)
>>> print(prev_state)
False
>>> print(mx.is_np_shape())
True

mxnet.util.use_np(func)[source]¶

A convenience decorator for wrapping user provided functions and classes in the scope of both NumPy-shape and NumPy-array semantics, which means that (1) empty tuples () and tuples with zeros, such as (0, 1), (1, 0, 2), will be treated as scalar tensors’ shapes and zero-size tensors’ shapes in shape inference functions of operators, instead of as unknown in legacy mode; (2) ndarrays of type mxnet.numpy.ndarray should be created instead of mx.nd.NDArray.

Example::

import mxnet as mx from mxnet import gluon, np

class TestHybridBlock1(gluon.HybridBlock):

def __init__(self):

super(TestHybridBlock1, self).__init__() self.w = self.params.get(‘w’, shape=(2, 2))

def hybrid_forward(self, F, x, w):

return F.dot(x, w) + F.ones((1,))

x = mx.nd.ones((2, 2)) net1 = TestHybridBlock1() net1.initialize() out = net1.forward(x) for _, v in net1.collect_params().items():

assert type(v.data()) is mx.nd.NDArray

assert type(out) is mx.nd.NDArray

@np.use_np class TestHybridBlock2(gluon.HybridBlock):

def __init__(self):

super(TestHybridBlock2, self).__init__() self.w = self.params.get(‘w’, shape=(2, 2))

def hybrid_forward(self, F, x, w):

return F.np.dot(x, w) + F.np.ones(())

x = np.ones((2, 2)) net2 = TestHybridBlock2() net2.initialize() out = net2.forward(x) for _, v in net2.collect_params().items():

print(type(v.data())) assert type(v.data()) is np.ndarray

assert type(out) is np.ndarray

Parameters

• func (a user-provided callable function or class to be scoped by the) –

• and NumPy-array semantics. (NumPy-shape) –

Returns

A function or class wrapped in the Numpy-shape and NumPy-array scope.

Return type

Function or class

mxnet.util.use_np_array(func)[source]¶

A decorator wrapping Gluon Block`s and all its methods, properties, and static functions with the semantics of NumPy-array, which means that where ndarrays are created, `mxnet.numpy.ndarray`s should be created, instead of legacy ndarrays of type `mx.nd.NDArray. For example, at the time when a parameter is created in a Block, an mxnet.numpy.ndarray is created if it’s decorated with this decorator.

Example::

import mxnet as mx from mxnet import gluon, np

class TestHybridBlock1(gluon.HybridBlock):

def __init__(self):

super(TestHybridBlock1, self).__init__() self.w = self.params.get(‘w’, shape=(2, 2))

def hybrid_forward(self, F, x, w):

return F.dot(x, w)

x = mx.nd.ones((2, 2)) net1 = TestHybridBlock1() net1.initialize() out = net1.forward(x) for _, v in net1.collect_params().items():

assert type(v.data()) is mx.nd.NDArray

assert type(out) is mx.nd.NDArray

@np.use_np_array class TestHybridBlock2(gluon.HybridBlock):

def __init__(self):

super(TestHybridBlock2, self).__init__() self.w = self.params.get(‘w’, shape=(2, 2))

def hybrid_forward(self, F, x, w):

return F.np.dot(x, w)

x = np.ones((2, 2)) net2 = TestHybridBlock2() net2.initialize() out = net2.forward(x) for _, v in net2.collect_params().items():

print(type(v.data())) assert type(v.data()) is np.ndarray

assert type(out) is np.ndarray

Parameters

func (a user-provided callable function or class to be scoped by the NumPy-array semantics.) –

Returns

A function or class wrapped in the NumPy-array scope.

Return type

Function or class

mxnet.util.use_np_shape(func)[source]¶

A decorator wrapping a function or class with activated NumPy-shape semantics. When func is a function, this ensures that the execution of the function is scoped with NumPy shape semantics, such as the support for zero-dim and zero size tensors. When func is a class, it ensures that all the methods, static functions, and properties of the class are executed with the NumPy shape semantics.

Example::

import mxnet as mx @mx.use_np_shape def scalar_one():

return mx.nd.ones(())

print(scalar_one())

@np.use_np_shape class ScalarTensor(object):

def __init__(self, val=None):

if val is None:

val = ScalarTensor.random().value

self._scalar = mx.nd.ones(()) * val

def __repr__(self):

print(“Is __repr__ in np_shape semantics? {}!”.format(str(np.is_np_shape()))) return str(self._scalar.asnumpy())

@staticmethod def random():

val = mx.nd.random.uniform().asnumpy().item() return ScalarTensor(val)

@property def value(self):

print(“Is value property in np_shape semantics? {}!”.format(str(np.is_np_shape()))) return self._scalar.asnumpy().item()

print(“Is global scope of np_shape activated? {}!”.format(str(np.is_np_shape()))) scalar_tensor = ScalarTensor() print(scalar_tensor)

Parameters

func (a user-provided callable function or class to be scoped by the NumPy-shape semantics.) –

Returns

A function or class wrapped in the NumPy-shape scope.

Return type

Function or class

mxnet.util.wrap_np_binary_func(func)[source]¶

A convenience decorator for wrapping numpy-compatible binary ufuncs to provide uniform error handling.

Parameters

func (a numpy-compatible binary function to be wrapped for better error handling.) –

Returns

A function wrapped with proper error handling.

Return type

Function

mxnet.util.wrap_np_unary_func(func)[source]¶

A convenience decorator for wrapping numpy-compatible unary ufuncs to provide uniform error handling.

Parameters

func (a numpy-compatible unary function to be wrapped for better error handling.) –

Returns

A function wrapped with proper error handling.

Return type

Function