Merge branch 'bepi' into 'master'

New files added

See merge request QIM/websitetutorials!1

IntroductionToPython/01_Debugging and more.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Debugging and more\n",
+    "\n",
+    "\n",
+    "This is a quick introduction to Jupyter notebooks and Python. It combines key elements from several open source introductory courses on Jupyter and Python for scienfitic computing. Previous experience with programming is assumed (Elementary experience with MATLAB, R, etc. or C, C++, etc. is fine).\n",
+    "\n",
+    "Author: Nicolai Riis, DTU Compute, July 2017.\n",
+    "\n",
+    "Each notebook takes roughly 1 hour to go through (reading + exercises).\n",
+    "\n",
+    "Consider skipping segments that are familiar to you and using the notebooks as refence during the course.\n",
+    "\n",
+    "## List of notebooks:\n",
+    "1) [Introduction to Jupyter notebooks and Python](1 - Introduction to Jupyter notebooks and Python.ipynb)\n",
+    "\n",
+    "2) [Introduction to NumPy](2 - Introduction to NumPy.ipynb)\n",
+    "\n",
+    "3) [Introduction to Matplotlib](3 - Introduction to Matplotlib.ipynb)\n",
+    "\n",
+    "4) [Debugging and more](4 - Debugging and more.ipynb) - (Current)\n",
+    "\n",
+    "### Licence:\n",
+    "These notebooks are released under the Attribution 3.0 Unported Licence (https://creativecommons.org/licenses/by/3.0/). This means you are free to share and adapt the content as you please as long as you give appropriate credit, link the licence and indicate if changes are made to the material.\n",
+    "\n",
+    "\n",
+    "For the original content that these notebooks are based upon please see:\n",
+    "\n",
+    "* https://github.com/jhamrick/nbgrader-demo/tree/master/instructor/source/ps1\n",
+    "* https://github.com/jrjohansson/scientific-python-lectures\n",
+    "\n",
+    "\n",
+    "### Contact for errors:\n",
+    "\n",
+    "[nabr@dtu.dk](nabr@dtu.dk)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "A significant portion of the time you spend on the problem sets will be spent debugging. In this notebook we discuss simple strategies to minimize hair loss and maximize coding pleasure. This problem is not worth any points, but we **strongly** encourage you to still go through it -- it will save you a ton of time in the future!\n",
+    "\n",
+    "## Writing Readable Code\n",
+    ">Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.\n",
+    ">\n",
+    ">**Brian Kernighan**\n",
+    "\n",
+    "The number one key to easy debugging is writing readable code. A few helpful tips:\n",
+    "1. Write short notes to yourself in the comments. These will help you to quickly orient yourself.\n",
+    "2. Use descriptive variable names. Avoid naming variables things like `a` or `foo`, as you will easily forget what they were used for. \n",
+    "   1. An exception to this rule is when using temporary variables (e.g., counts), which can be as short as a single character.\n",
+    "3. Try to write your code in a consistent style to ensure that it is predictable across problem sets. You'll thank yourself for this later!\n",
+    "4. Don't reinvent the wheel. Check the docs to see if a particular function exists before you spend hours trying to implement it on your own. You'd be surprised at how often this happens.\n",
+    "\n",
+    "Although these tips won't save you from having to debug your code, they _will_ make the time you spend debugging much more productive. \n",
+    "\n",
+    "## Debugging in the IPython Notebook\n",
+    "\n",
+    "Imagine that a friend wrote you a function `plot_log` for plotting the function $\\log(x)$ over the interval $[1,2]$. How sweet! Their code is below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# for inline plotting in the notebook\n",
+    "%matplotlib inline \n",
+    "\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "def plot_log():\n",
+    "    figure, axis = plt.subplots(2, 1)\n",
+    "    x = np.linspace(1, 2, 10)\n",
+    "    axis.plot(x, np.log(x))\n",
+    "    plt.show()\n",
+    "\n",
+    "plot_log()  # Call the function, generate plot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "Unfortunately, when you go to execute the code block, Python throws an error. Some friend! How can we fix the code so that it runs correctly?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "### Check the traceback\n",
+    "\n",
+    "The presence of a **traceback** (the multicolored text that appears when we try to run the preceding code block) is the first indication that your code isn't behaving correctly. In the current example the traceback suggests that an error is occurring at the method call `axis.plot(x, np.log(x))` on line 10. This is helpful, although somewhat baffling -- we used the same `axis.plot()` syntax in Notebook 4, and it ran fine! What's going on?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "### Inspect the local variables\n",
+    "\n",
+    "Inspecting the traceback gives us a general idea of where our issue is, but its output can often be fairly cryptic. A good next step is to inspect the local variables and objects defined during the execution of your code: if there's a mismatch between what the code _should_ be generating on each line and what it actually generates, you can trace it back until you've found the line containing the bug.\n",
+    "\n",
+    "In the current example, we might first try inspecting the variables and objects present on the line where the traceback indicates our error is occurring. These include the `axis` object, the local variable `x`, and the method call `np.log(x)`. We can do this with IPython's `debug` magic function, or by using `print` statements. Both methods are outlined below."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "**Using the Interactive Debugger** \n",
+    "\n",
+    "The IPython magic function `%debug` pauses code execution upon encountering an error and drops us into an interactive debugging console. In the current example, this means that the code execution will pause just before running line 7. Once the debugger opens, we can inspect the local variables in the interactive debugger to see whether they match what we'd expect.\n",
+    "\n",
+    "To invoke the debugger, just type the magic command `%debug` in a new code cell immediately after encountering the error. When you run this new cell, it will drop you into a debugger where you can investigate what went wrong:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# Uncomment the following line and run the cell to debug the previous function:\n",
+    "#%debug"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "<div class=\"alert alert-danger\">\n",
+    "Warning: make sure you remove or comment out any <code>%debug</code> statements from your code before turning in your problem set. If you do not, then they will cause the grading scripts to break and you may not receive full credit. Always make sure you run the <code>nbgrader validate</code> commands in <a href=\"Submit.ipynb\">Submit.ipynb</a> and ensure that they complete properly before submitting your assignment!\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "If you run the above code block, you should see something like this:\n",
+    "\n",
+    "```\n",
+    "> <ipython-input-4-cf8c844b7e23>(5)plot_log()\n",
+    "      4     x = np.linspace(1, 2, 10)\n",
+    "----> 5     axis.plot(x, np.log(x))\n",
+    "      6     plt.show()\n",
+    "ipdb>\n",
+    "```\n",
+    "The presence of the `ipdb>` prompt at the bottom indicates that we have entered the IPython debugger. Any command you enter here will be evaluated and its output will be returned in the console. To see the stock commands available within the debugger, type `h` (short for \"help\") at the prompt.   \n",
+    "```\n",
+    "ipdb> h\n",
+    "Documented commands (type help <topic>):\n",
+    "========================================\n",
+    "EOF    bt         cont      enable  jump  pdef   r        tbreak   w\n",
+    "a      c          continue  exit    l     pdoc   restart  u        whatis\n",
+    "alias  cl         d         h       list  pinfo  return   unalias  where\n",
+    "args   clear      debug     help    n     pp     run      unt\n",
+    "b      commands   disable   ignore  next  q      s        until\n",
+    "break  condition  down      j       p     quit   step     up\n",
+    "\n",
+    "Miscellaneous help topics:\n",
+    "==========================\n",
+    "exec  pdb\n",
+    "\n",
+    "Undocumented commands:\n",
+    "======================\n",
+    "retval  rv\n",
+    "```\n",
+    "For information on a particular command, you can type `h` followed by the command. For example, to see what the `c` command does, type\n",
+    "```\n",
+    "ipdb> h c\n",
+    "c(ont(inue))\n",
+    "Continue execution, only stop when a breakpoint is encountered.\n",
+    "```\n",
+    "We can use the debugger to inspect the contents of the variables and objects defined so far in our code. For example, we can inspect the contents of our `axis` object by typing `axis` at the `ipdb>` prompt:\n",
+    "\n",
+    "```\n",
+    "ipdb> axis\n",
+    "array([<matplotlib.axes._subplots.AxesSubplot object at 0x10a5e8950>,\n",
+    "       <matplotlib.axes._subplots.AxesSubplot object at 0x108dcf790>], dtype=object)\n",
+    "```\n",
+    "\n",
+    "Aha! Instead of a single instance of the `matplotlib.axes` class (as we might expect), it appears that `axis` is actually an _array_ containing two separate `matplotlib.axes` instances. Why might this be? Tracing the `axis` object back to its definition on line 3, we  see that the `subplots` method is the culprit. Looking up [`subplots`](http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.subplots) in the matplotlib documentation, we see that this method returns as many axis objects as there are cells in a subplot grid. In our case, since we specified a grid of size $2 \\times 1$, it returned two separate axis objects inside a single array. When we asked Python to access the `plot` method of our array on line 7, it understandably got confused -- arrays don't have a `plot` method! With this in mind, we can adjust our code to resolve the issue. One solution would be ignore the second subplot entirely:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "def plot_log():\n",
+    "    figure, axis = plt.subplots()\n",
+    "    x = np.linspace(1, 2, 10)\n",
+    "    axis.plot(x, np.log(x))\n",
+    "    plt.show()\n",
+    "plot_log()  # Call the function, generate plot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "**Using `print` Statements**\n",
+    "\n",
+    "An alternative technique for inspecting the behavior of your code is to check the values of local variables using `print` statements. The [`print`](https://docs.python.org/3/library/functions.html?highlight=print#print) command evaluates its argument and writes the result to the standard output. We could use a `print` statement to inspect the `ax` object in our `plot_log` function as follows:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "This runs the code to completion, resulting in the same error we saw earlier. However, because we placed the `print` statement in our code immediately before the error occurred, we see that IPython also printed the contents of the `axis` object above the traceback. Thus, `print` statements are an alternative means of checking the values of local variables without using the IPython debugger. Just remember to remove the `print` statements before validating your code!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "## Getting Help\n",
+    "\n",
+    "### Check the Docs\n",
+    "\n",
+    "Although we will try to make this course as self-contained as possible, you may still need to refer to external sources while solving the homework problems. You can look up the documentation for a particular function within the IPython notebook by creating a new code block and typing the name of the function either preceded or succeeded by a `?`. For example, if you wanted to see the documentation for the matplotlib method `subplots`, you could write `?plt.subplots` (or `plt.sublots?`), which will open a pager displaying the docstring for `plt.subplots`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "?plt.subplots"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "If you'd prefer to look at the available functions in your web browser, links to the NumPy, Matplotlib, Python, and IPython Notebook online docs are below:\n",
+    "* Python 3: https://docs.python.org/3/genindex.html\n",
+    "* NumPy: http://docs.scipy.org/doc/numpy/genindex.html\n",
+    "* pyplot (matplotlib): http://matplotlib.org/api/pyplot_summary.html\n",
+    "* IPython Notebook: http://ipython.org/ipython-doc/2/notebook/index.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbgrader": {
+     "grade": false,
+     "locked": false,
+     "schema_version": 1,
+     "solution": false
+    }
+   },
+   "source": [
+    "### Hail Mary\n",
+    "\n",
+    "If these techniques fail and you're still having trouble, the following suggestions may be of use:\n",
+    "1. Copy and paste your error message into Google to see if anyone else has experienced similar problems. You'd be surprised how often this works!\n",
+    "2. Search [StackOverflow](https://stackoverflow.com/questions/tagged/python)\n",
+    "3. Consult fellow classmates\n",
+    "4. Consult the GSIs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}