.. _deepnumpy_cheat_sheet:

The NP on MXNet cheat sheet
===========================


To begin, import the ``np`` and ``npx`` module and update MXNet to run
in NumPy-like mode.

.. code:: python

    from mxnet import np, npx
    npx.set_np()  # Change MXNet to the numpy-like mode.

NDArray figure (TODO)

Creating arrays
---------------

.. code:: python

    np.array([1, 2, 3])  # default datatype is float32




.. parsed-literal::
    :class: output

    array([1., 2., 3.])



.. code:: python

    np.array([(1.5, 2, 3), (4, 5, 6)], dtype='float16')




.. parsed-literal::
    :class: output

    array([[1.5, 2. , 3. ],
           [4. , 5. , 6. ]], dtype=float16)



.. code:: python

    np.array([[(15,2,3), (4,5,6)], [(3,2,1), (4,5,6)]], dtype='int32')




.. parsed-literal::
    :class: output

    array([[[15,  2,  3],
            [ 4,  5,  6]],
    
           [[ 3,  2,  1],
            [ 4,  5,  6]]], dtype=int32)



Initial placeholders
~~~~~~~~~~~~~~~~~~~~

.. code:: python

    np.zeros((3, 4))  # Create an array of zeros




.. parsed-literal::
    :class: output

    array([[0., 0., 0., 0.],
           [0., 0., 0., 0.],
           [0., 0., 0., 0.]])



.. code:: python

    np.ones((2, 3, 4), dtype='int8')  # Create an array of ones




.. parsed-literal::
    :class: output

    array([[[1, 1, 1, 1],
            [1, 1, 1, 1],
            [1, 1, 1, 1]],
    
           [[1, 1, 1, 1],
            [1, 1, 1, 1],
            [1, 1, 1, 1]]], dtype=int8)



.. code:: python

    np.arange(10, 25, 5)  # Create an array of evenly spaced values (step value)




.. parsed-literal::
    :class: output

    array([10., 15., 20.])



.. code:: python

    # Create an array of evenly spaced values (number of samples)
    # np.linspace(0, 2, 9)

.. code:: python

    # np.full((2, 2), 7)  # Create a constant array

.. code:: python

    # np.eye(2)  # Create a 2X2 identity matrix

.. code:: python

    # np.random.random((2, 2))  # Create an array with random values

.. code:: python

    np.empty((3,2))  # Create an empty array




.. parsed-literal::
    :class: output

    array([[1.05535857e-22, 4.56627118e-41],
           [1.70921326e+01, 3.07220675e-41],
           [4.48415509e-44, 0.00000000e+00]])



I/O
---

Saving and loading on disk
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    # Save one array
    a = np.array([1, 2, 3])
    npx.save('my_array', a)
    npx.load('my_array')




.. parsed-literal::
    :class: output

    [array([1., 2., 3.])]



.. code:: python

    # Save a list of arrays
    b = np.array([4, 6, 8])
    npx.save('my_arrays', [a, b])  # FIXME, cannot be a tuple
    npx.load('my_arrays')




.. parsed-literal::
    :class: output

    [array([1., 2., 3.]), array([4., 6., 8.])]



Saving and loading text files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    # np.loadtxt("myfile.txt")
    # np.genfromtxt("my_file.csv", delimiter=',')
    # np.savetxt("myarray.txt", a, delimiter=" ")

Data types
----------

.. code:: python

    # np.int64    # Signed 64-bit integer types
    # np.float32  # Standard double-precision floating point
    # np.complex  # Complex numbers represented by 128 floats
    # np.bool     # Boolean type storing TRUE and FALSE values
    # np.object   # Python object type
    # np.string_  # Fixed-length string type
    # np.unicode_ # Fixed-length unicode type

Inspecting your array
---------------------

.. code:: python

    a.shape # Array dimensions




.. parsed-literal::
    :class: output

    (3,)



.. code:: python

    len(a) # Length of array




.. parsed-literal::
    :class: output

    3



.. code:: python

    b.ndim # Number of array dimensions




.. parsed-literal::
    :class: output

    1



.. code:: python

    b.size # Number of array elements




.. parsed-literal::
    :class: output

    3



.. code:: python

    b.dtype # Data type of array elements




.. parsed-literal::
    :class: output

    dtype('float32')



.. code:: python

    # b.dtype.name # Name of data type

.. code:: python

    b.astype('int') # Convert an array to a different type




.. parsed-literal::
    :class: output

    array([4, 6, 8], dtype=int64)



Asking For Help
---------------

.. code:: python

    # np.info(np.ndarray.dtype)

Array mathematics
-----------------

Arithmetic operations
~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    a - b # Subtraction




.. parsed-literal::
    :class: output

    array([-3., -4., -5.])



.. code:: python

    np.subtract(a, b) # Subtraction




.. parsed-literal::
    :class: output

    array([-3., -4., -5.])



.. code:: python

    b + a # Addition




.. parsed-literal::
    :class: output

    array([ 5.,  8., 11.])



.. code:: python

    np.add(b, a) # Addition




.. parsed-literal::
    :class: output

    array([ 5.,  8., 11.])



.. code:: python

    a / b # Division




.. parsed-literal::
    :class: output

    array([0.25      , 0.33333334, 0.375     ])



.. code:: python

    np.divide(a,b) # Division




.. parsed-literal::
    :class: output

    array([0.25      , 0.33333334, 0.375     ])



.. code:: python

    a * b # Multiplication




.. parsed-literal::
    :class: output

    array([ 4., 12., 24.])



.. code:: python

    np.multiply(a, b) # Multiplication




.. parsed-literal::
    :class: output

    array([ 4., 12., 24.])



.. code:: python

    np.exp(b) # Exponentiation




.. parsed-literal::
    :class: output

    array([  54.59815,  403.4288 , 2980.958  ])



.. code:: python

    np.sqrt(b) # Square root




.. parsed-literal::
    :class: output

    array([2.       , 2.4494898, 2.828427 ])



.. code:: python

    np.sin(a) # Sines of an array




.. parsed-literal::
    :class: output

    array([0.84147096, 0.9092974 , 0.14112   ])



.. code:: python

    np.cos(b) # Element-wise cosine




.. parsed-literal::
    :class: output

    array([-0.6536436 ,  0.96017027, -0.14550003])



.. code:: python

    np.log(a) # Element-wise natural logarithm




.. parsed-literal::
    :class: output

    array([0.       , 0.6931472, 1.0986123])



.. code:: python

    a.dot(b) # Dot product




.. parsed-literal::
    :class: output

    array(40.)



Comparison
~~~~~~~~~~

Aggregate functions
~~~~~~~~~~~~~~~~~~~

.. code:: python

    a.sum() # Array-wise sum




.. parsed-literal::
    :class: output

    array(6.)



.. code:: python

    # a.min() # Array-wise minimum value

.. code:: python

    c = np.array(([[1,2,3], [2,3,4]]))
    # c.max(axis=0) # Maximum value of an array row

.. code:: python

    # c.cumsum(axis=1) # Cumulative sum of the elements

.. code:: python

    a.mean() # Mean




.. parsed-literal::
    :class: output

    array(2.)



.. code:: python

    # b.median() # Median

.. code:: python

    # a.corrcoef() # Correlation coefficient

.. code:: python

    # np.std(b) # Standard deviation

Copying arrays
--------------

.. code:: python

    # a.view() # Create a view of the array with the same data

.. code:: python

    np.copy(a) # Create a copy of the array




.. parsed-literal::
    :class: output

    array([1., 2., 3.])



.. code:: python

    a.copy() # Create a deep copy of the array




.. parsed-literal::
    :class: output

    array([1., 2., 3.])



Sorting Arrays
--------------

.. code:: python

    # a.sort() # Sort an array

.. code:: python

    # c.sort(axis=0) # Sort the elements of an array's axis

Subsetting, slicing, indexing
-----------------------------

Subsetting
~~~~~~~~~~

.. code:: python

    a[2] # Select the element at the 2nd index 3




.. parsed-literal::
    :class: output

    array(3.)



.. code:: python

    c[0,1] # Select the element at row 1 column 2




.. parsed-literal::
    :class: output

    array(2.)



Slicing
~~~~~~~

.. code:: python

    a[0:2] # Select items at index 0 and 1




.. parsed-literal::
    :class: output

    array([1., 2.])



.. code:: python

    c[0:2,1] # Select items at rows 0 and 1 in column 1




.. parsed-literal::
    :class: output

    array([2., 3.])



.. code:: python

    c[:1] # Select all items at row 0




.. parsed-literal::
    :class: output

    array([[1., 2., 3.]])



.. code:: python

    # c[1,...] # Same as [1,:,:]

.. code:: python

    a[ : :-1] #Reversed array a array([3, 2, 1])




.. parsed-literal::
    :class: output

    array([3., 2., 1.])



Boolean Indexing
~~~~~~~~~~~~~~~~

.. code:: python

    # a[a<2] # Select elements from a less than 2

Fancy indexing
~~~~~~~~~~~~~~

.. code:: python

    c[[1,0,1,0], [0,1,2,0]] # Select elements (1,0),(0,1),(1,2) and (0,0)




.. parsed-literal::
    :class: output

    array([2., 2., 4., 1.])



.. code:: python

    c[[1,0,1,0]][:,[0,1,2,0]] # Select a subset of the matrix’s rows




.. parsed-literal::
    :class: output

    array([[2., 3., 4., 2.],
           [1., 2., 3., 1.],
           [2., 3., 4., 2.],
           [1., 2., 3., 1.]])



Array manipulation
------------------

Transposing array
~~~~~~~~~~~~~~~~~

.. code:: python

    np.transpose(c) # Permute array dimensions




.. parsed-literal::
    :class: output

    array([[1., 2.],
           [2., 3.],
           [3., 4.]])



.. code:: python

    c.T # Permute array dimensions




.. parsed-literal::
    :class: output

    array([[1., 2.],
           [2., 3.],
           [3., 4.]])



Changing array shape
~~~~~~~~~~~~~~~~~~~~

.. code:: python

    # b.ravel() # Flatten the array

.. code:: python

    # c.reshape(3,-2) # Reshape, but don’t change data

Adding and removing elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    # c.resize((6,2)) # Return a new array with shape (6, 2)

.. code:: python

    # np.append(h,g) # Append items to an array

.. code:: python

    # np.insert(a, 1, 5) # Insert items in an array

.. code:: python

    # np.delete(a, [1]) # Delete items from an array

Combining arrays
~~~~~~~~~~~~~~~~

.. code:: python

    np.concatenate((a,b),axis=0) # Concatenate arrays




.. parsed-literal::
    :class: output

    array([1., 2., 3., 4., 6., 8.])



.. code:: python

    # np.vstack((a,b)) # Stack arrays vertically (row-wise)

.. code:: python

    # np.r_[e,f] # Stack arrays vertically (row-wise)

.. code:: python

    # np.hstack((e,f)) # Stack arrays horizontally (column-wise)

.. code:: python

    # np.column_stack((a,d)) # Create stacked column-wise arrays

.. code:: python

    # np.c_[a,d] # Create stacked column-wise arrays

Splitting arrays
~~~~~~~~~~~~~~~~

.. code:: python

    # np.hsplit(a,3) # Split the array horizontally at the 3rd index

.. code:: python

    # np.vsplit(c,2) # Split the array vertically at the 2nd index

Use GPUs
--------

Prerequisites: A GPU exists and GPU-enabled MXNet is installed.

.. code:: python

    npx.num_gpus()  # Query number of GPUs




.. parsed-literal::
    :class: output

    4



.. code:: python

    npx.gpu(0), npx.gpu(1)  # Context for the first and second GPUs




.. parsed-literal::
    :class: output

    (gpu(0), gpu(1))



.. code:: python

    gpu_0 = npx.gpu(0) if npx.num_gpus() > 1 else npx.cpu()
    g0 = np.zeros((2,3), ctx=gpu_0)  # Create array on GPU 0
    g0




.. parsed-literal::
    :class: output

    array([[0., 0., 0.],
           [0., 0., 0.]], ctx=gpu(0))



.. code:: python

    gpu_1 = npx.gpu(1) if npx.num_gpus() > 2 else npx.cpu()
    g1 = np.random.uniform(size=(2,3), ctx=gpu_1)  # Create array on GPU 1
    g1




.. parsed-literal::
    :class: output

    array([[0.67478997, 0.07540122, 0.9956977 ],
           [0.09488854, 0.415456  , 0.11231736]], ctx=gpu(1))



.. code:: python

    # Copy to another GPU
    g1.copyto(gpu_0)




.. parsed-literal::
    :class: output

    array([[0.67478997, 0.07540122, 0.9956977 ],
           [0.09488854, 0.415456  , 0.11231736]], ctx=gpu(0))



.. code:: python

    # Return itself if matching the context, otherwise copy
    g1.copyto(gpu_0), g1.copyto(gpu_0)




.. parsed-literal::
    :class: output

    (array([[0.67478997, 0.07540122, 0.9956977 ],
            [0.09488854, 0.415456  , 0.11231736]], ctx=gpu(0)),
     array([[0.67478997, 0.07540122, 0.9956977 ],
            [0.09488854, 0.415456  , 0.11231736]], ctx=gpu(0)))



.. code:: python

    g1.context  # Query the device an array is on




.. parsed-literal::
    :class: output

    gpu(1)



.. code:: python

    ## The computation is performed by the devices on which the input arrays are
    g0 + g1.copyto(gpu_0)




.. parsed-literal::
    :class: output

    array([[0.67478997, 0.07540122, 0.9956977 ],
           [0.09488854, 0.415456  , 0.11231736]], ctx=gpu(0))



Auto differentiation
--------------------

.. code:: python

    a.attach_grad() # Allocate gradient for a variable
    a.grad # access the gradient




.. parsed-literal::
    :class: output

    array([0., 0., 0.])



Compute the :math:`\nabla_a b=\exp(2a)^T a`

.. code:: python

    from mxnet import autograd
    
    with autograd.record():
        b = np.exp(2*a).dot(a)
    b.backward()
    a.grad




.. parsed-literal::
    :class: output

    array([  22.167168,  272.99075 , 2824.0015  ])



**Acknowledgement**

Adapted from www.datacamp.com.