.. _crash_course_ndarray:

Step 1: Manipulate data with NP on MXNet
========================================


This getting started exercise introduces the ``np`` package, which is
the primary tool for storing and transforming data on MXNet. If you’ve
worked with NumPy before, you’ll notice ``np`` is, by design, similar to
NumPy.

Import packages and create an array
-----------------------------------

To get started, run the following commands to import the ``np`` package
together with the NumPy extensions package ``npx``. Together, ``np``
with ``npx`` make up the NP on MXNet front end.

.. code:: python

    from mxnet import np, npx
    npx.set_np()  # Activate NumPy-like mode.

In this step, create a 2D array (also called a matrix). The following
code example creates a matrix with values from two sets of numbers: 1,
2, 3 and 4, 5, 6. This might also be referred to as a tuple of a tuple
of integers.

.. code:: python

    np.array(((1,2,3),(5,6,7)))




.. parsed-literal::
    :class: output

    array([[1., 2., 3.],
           [5., 6., 7.]])



You can also create a very simple matrix with the same shape (2 rows by
3 columns), but fill it with 1s.

.. code:: python

    x = np.ones((2,3))
    x




.. parsed-literal::
    :class: output

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



You can create arrays whose values are sampled randomly. For example,
sampling values uniformly between -1 and 1. The following code example
creates the same shape, but with random sampling.

.. code:: python

    y = np.random.uniform(-1,1, (2,3))
    y




.. parsed-literal::
    :class: output

    array([[0.09762704, 0.18568921, 0.43037868],
           [0.6885315 , 0.20552671, 0.71589124]])



As with NumPy, the dimensions of each ndarray are shown by accessing the
``.shape`` attribute. As the following code example shows, you can also
query for ``size``, which is equal to the product of the components of
the shape. In addition, ``.dtype`` tells the data type of the stored
values.

.. code:: python

    (x.shape, x.size, x.dtype)




.. parsed-literal::
    :class: output

    ((2, 3), 6, dtype('float32'))



Performing operations on an array
---------------------------------

An ndarray supports a large number of standard mathematical operations.
Here are three examples. You can perform element-wise multiplication by
using the following code example.

.. code:: python

    x * y




.. parsed-literal::
    :class: output

    array([[0.09762704, 0.18568921, 0.43037868],
           [0.6885315 , 0.20552671, 0.71589124]])



You can perform exponentiation by using the following code example.

.. code:: python

    np.exp(y)




.. parsed-literal::
    :class: output

    array([[1.1025515, 1.204048 , 1.5378398],
           [1.9907899, 1.2281718, 2.0460093]])



You can also find a matrix’s transpose to compute a proper matrix-matrix
product by using the following code example.

.. code:: python

    np.dot(x, y.T)




.. parsed-literal::
    :class: output

    array([[0.71369493, 1.6099495 ],
           [0.71369493, 1.6099495 ]])



Indexing an array
-----------------

The ndarrays support slicing in many ways you might want to access your
data. The following code example shows how to read a particular element,
which returns a 1D array with shape ``(1,)``.

.. code:: python

    y[1,2]




.. parsed-literal::
    :class: output

    array(0.71589124)



This example shows how to read the second and third columns from ``y``.

.. code:: python

    y[:,1:3]




.. parsed-literal::
    :class: output

    array([[0.18568921, 0.43037868],
           [0.20552671, 0.71589124]])



This example shows how to write to a specific element.

.. code:: python

    y[:,1:3] = 2
    y




.. parsed-literal::
    :class: output

    array([[0.09762704, 2.        , 2.        ],
           [0.6885315 , 2.        , 2.        ]])



You can perform multi-dimensional slicing, which is shown in the
following code example.

.. code:: python

    y[1:2,0:2] = 4
    y




.. parsed-literal::
    :class: output

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



Converting between MXNet ndarrays and NumPy ndarrays
----------------------------------------------------

You can convert MXNet ndarrays to and from NumPy ndarrays, as shown in
the following example. The converted arrays do not share memory.

.. code:: python

    a = x.asnumpy()
    (type(a), a)




.. parsed-literal::
    :class: output

    (numpy.ndarray, array([[1., 1., 1.],
            [1., 1., 1.]], dtype=float32))



.. code:: python

    np.array(a)




.. parsed-literal::
    :class: output

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



Next steps
----------

Learn how to construct a neural network with the Gluon module:
:ref:`crash_course_nn`.