versions/1.9.1/api/python/docs/_sources/tutorials/packages/ndarray/01-ndarray-intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "eb78cb41",
   "metadata": {},
   "source": [
    "<!--- Licensed to the Apache Software Foundation (ASF) under one -->\n",
    "<!--- or more contributor license agreements.  See the NOTICE file -->\n",
    "<!--- distributed with this work for additional information -->\n",
    "<!--- regarding copyright ownership.  The ASF licenses this file -->\n",
    "<!--- to you under the Apache License, Version 2.0 (the -->\n",
    "<!--- \"License\"); you may not use this file except in compliance -->\n",
    "<!--- with the License.  You may obtain a copy of the License at -->\n",
    "\n",
    "<!---   http://www.apache.org/licenses/LICENSE-2.0 -->\n",
    "\n",
    "<!--- Unless required by applicable law or agreed to in writing, -->\n",
    "<!--- software distributed under the License is distributed on an -->\n",
    "<!--- \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->\n",
    "<!--- KIND, either express or implied.  See the License for the -->\n",
    "<!--- specific language governing permissions and limitations -->\n",
    "<!--- under the License. -->\n",
    "\n",
    "# An Intro: Manipulate Data the MXNet Way with NDArray\n",
    "\n",
    "## Overview\n",
    "This guide\n",
    "will introduce you to how data is handled with MXNet. You will learn the basics\n",
    "about MXNet's multi-dimensional array format, `ndarray`.\n",
    "\n",
    "This content was extracted and simplified from the gluon tutorials in\n",
    "[Dive Into Deep Learning](https://d2l.ai/).\n",
    "\n",
    "## Prerequisites\n",
    "* [MXNet installed in a Python environment](/get_started?version=master&platform=linux&language=python&environ=pip&processor=cpu).\n",
    "* Python 2.7.x or Python 3.x\n",
    "\n",
    "\n",
    "## Getting started\n",
    "\n",
    "In this chapter, we'll get\n",
    "you going with the basic functionality. Don't worry if you don't understand any\n",
    "of the basic math, like element-wise operations or normal distributions. In the\n",
    "next two chapters we'll take another pass at `NDArray`, teaching you both the math\n",
    "you'll need and how to realize it in code.\n",
    "\n",
    "To get started, let's import\n",
    "`mxnet`. We'll also import `ndarray` from `mxnet` for convenience. We’ll make a\n",
    "habit of setting a random seed so that you always get the same results that we\n",
    "do."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d2fae10",
   "metadata": {},
   "source": [
    "```python\n",
    "import mxnet as mx\n",
    "from mxnet import nd\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9932625f",
   "metadata": {},
   "source": [
    "Let's start with a very simple 1-dimensional array with a python list."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9fff6fc2",
   "metadata": {},
   "source": [
    "```python\n",
    "x = nd.array([1,2,3])\n",
    "print(x)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a4bb5e8",
   "metadata": {},
   "source": [
    "Now a 2-dimensional array."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f96022a",
   "metadata": {},
   "source": [
    "```python\n",
    "y = nd.array([[1,2,3,4], [1,2,3,4], [1,2,3,4]])\n",
    "print(y)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e858344",
   "metadata": {},
   "source": [
    "Next, let's see how to create an `NDArray`, without any values initialized.\n",
    "Specifically, we'll create a 2D array (also called a *matrix*) with 3 rows and 4\n",
    "columns using the `.empty` function. We'll also try out `.full` which takes an\n",
    "additional parameter for what value you want to fill in the array."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb688fe7",
   "metadata": {},
   "source": [
    "```python\n",
    "x = nd.empty((3, 3))\n",
    "print(x)\n",
    "x = nd.full((3,3), 7)\n",
    "print(x)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b13abf8",
   "metadata": {},
   "source": [
    "`empty` just grabs some memory and hands us back a matrix without setting the\n",
    "values of any of its entries. This means that the entries can have any form of\n",
    "values, including very big ones! Typically, we'll want our matrices initialized\n",
    "and very often we want a matrix of all zeros, so we can use the `.zeros`\n",
    "function.\n",
    "\n",
    "<!-- showing something\n",
    "different here (3,10) since the zeros may not produce anything different from\n",
    "empty... or use the two demonstrations to show something interesting or\n",
    "unique... when would I use one over the other?-->"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68be0023",
   "metadata": {},
   "source": [
    "```python\n",
    "x = nd.zeros((3, 10))\n",
    "print(x)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "892b3ace",
   "metadata": {},
   "source": [
    "Similarly, `ndarray` has a function to create a matrix of all ones aptly named\n",
    "[ones](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.ones)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce66bc96",
   "metadata": {},
   "source": [
    "```python\n",
    "x = nd.ones((3, 4))\n",
    "print(x)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1dbf699b",
   "metadata": {},
   "source": [
    "Often, we'll want to create arrays whose values are sampled randomly. This is\n",
    "especially common when we intend to use the array as a parameter in a neural\n",
    "network. In this snippet, we initialize with values drawn from a standard normal\n",
    "distribution with zero mean and unit variance using\n",
    "[random_normal](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.random_normal).\n",
    "\n",
    "<!--\n",
    "Is it that important to introduce zero mean and unit variance right now?\n",
    "Describe more? Or how about explain which is which for the 0 and the 1 and what\n",
    "they're going to do... if it actually matters at this point. -->"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d16b140b",
   "metadata": {},
   "source": [
    "```python\n",
    "y = nd.random_normal(0, 1, shape=(3, 4))\n",
    "print(y)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15cfe4f3",
   "metadata": {},
   "source": [
    "Sometimes you will want to copy an array by its shape but not its contents. You\n",
    "can do this with `.zeros_like`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c622ad4",
   "metadata": {},
   "source": [
    "```python\n",
    "z = nd.zeros_like(y)\n",
    "print(z)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a894840",
   "metadata": {},
   "source": [
    "As in NumPy, the dimensions of each `NDArray` are accessible via the `.shape`\n",
    "attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6baeafad",
   "metadata": {},
   "source": [
    "```python\n",
    "y.shape\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c2829b0",
   "metadata": {},
   "source": [
    "We can also query its `.size`, which is equal to the product of the components\n",
    "of the shape. Together with the precision of the stored values, this tells us\n",
    "how much memory the array occupies.\n",
    "<!-- is there a function for that or do you\n",
    "just do it manually? Should we show that? -->"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f215c5e0",
   "metadata": {},
   "source": [
    "```python\n",
    "y.size\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e4cd32c",
   "metadata": {},
   "source": [
    "We can query the data type using `.dtype`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41bd4151",
   "metadata": {},
   "source": [
    "```python\n",
    "y.dtype\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7619bc96",
   "metadata": {},
   "source": [
    "`float32` is the default data type. Performance can be improved with less\n",
    "precision, or you might want to use a different data type. You can force the\n",
    "data type when you create the array using a numpy type. This requires you to\n",
    "import numpy first."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6802dd38",
   "metadata": {},
   "source": [
    "```python\n",
    "import numpy as np\n",
    "a = nd.array([1,2,3])\n",
    "b = nd.array([1,2,3], dtype=np.int32)\n",
    "c = nd.array([1.2, 2.3], dtype=np.float16)\n",
    "(a.dtype, b.dtype, c.dtype)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4107b3ef",
   "metadata": {},
   "source": [
    "As you will come to learn in detail later, operations and memory storage will\n",
    "happen on specific devices that you can set. You can compute on CPU(s), GPU(s), a\n",
    "specific GPU, or all of the above depending on your situation and preference.\n",
    "Using `.context` reveals the location of the variable."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a7b2f77f",
   "metadata": {},
   "source": [
    "```python\n",
    "y.context\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e41b73ba",
   "metadata": {},
   "source": [
    "## Next Up\n",
    "\n",
    "[NDArray Operations](02-ndarray-operations.md)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}