week02.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Week 2 worksheet: Lists, loops, and functions\n",
    "\n",
    "So far, we have seen object types consisting of essentially a single item of data. It is useful to have data types that can represent more than a single value -- for instance, in mathematics, we might want to represent a matrix or a vector. Python offers a number of different built-in object types to do this, called **containers** -- because they can contain other objects with different types. This week, we introduce **lists** as our first type of container.\n",
    "\n",
    "We have also seen that Python executes a set of commands from top to bottom, in the order in which you have scripted them. *Control flow* lets you decide *when*, *how many times*, or *under what condition(s)* to execute certain parts of your code, allowing you more control over the structure (or *flow*) of the code. This week, we also introduce our first control flow tools: **`for` loops** and **functions**.\n",
    "\n",
    "The best way to learn programming is to write code. Don't hesitate to edit the code in the example cells, or add your own code, to test your understanding. You will find practice exercises throughout the notebook, denoted by 🚩 ***Exercise $x$:***.\n",
    "\n",
    "#### Displaying solutions\n",
    "\n",
    "Solutions will be released one week after the worksheets are released, as a new `.txt` file in the same GitHub repository. After pulling the file to your workspace (either your computer or your Noteable server), run the following cell to create clickable buttons under each exercise, which will allow you to reveal the solutions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%run scripts/create_widgets.py 'week02'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Type-casting, duck-typing\n",
    "\n",
    "Before moving on to lists, let's wrap up our discussion of basic object types from the Week 1 tutorial. In Python, the type of an object can be changed, either manually or automatically.\n",
    "\n",
    "Take a look at this example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(type(39))\n",
    "print(type(5))\n",
    "\n",
    "print(39 / 5)\n",
    "print(type(39 / 5))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Type-casting** is the technical name for changing the type of an object. In this example, although we operate with two `int` objects, the result is **cast** (i.e. its type is automatically set) to a `float` object. Here, type-casting happened automatically -- the result of `39 / 5` could not be represented as an `int`. However, this doesn't always happen.\n",
    "\n",
    "If we want to *explicitly* change the type of an object, in some cases it is possible to use functions like `int()`, `float()`, or `str()`. Python will then attempt to interpret the content of the object and come up with a new representation in the desired type. Some examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "i = 2566\n",
    "print(type(i))\n",
    "print(float(i))\n",
    "print(str(i))\n",
    "\n",
    "string_number = '273'\n",
    "print(float(string_number))\n",
    "print(int(string_number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, for instance, the following will not work, as Python does not know how to interpret the string `'twenty'` as a number. The error message gives a hint: Python can only convert strings whose characters are decimal numbers, and doesn't know how to read letters or words."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "string_number = 'twenty'\n",
    "print(int(string_number))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, note that, in all examples so far, Python has *assumed* the type of an object by the way you have created it, and the way you use it. We call this behaviour **duck-typing**, because\n",
    "> If it looks like a duck, walks like a duck, and quacks like a duck, then it's a duck.\n",
    "\n",
    "Python uses duck-typing, and therefore doesn't require you to specify the type of an object before you are allowed to create or assign it. (This is not the case in some programming languages, e.g. C/C++, Java...).\n",
    "\n",
    "---\n",
    "🚩 ***Exercise 1:*** The `bool()` function casts an object to the Boolean type. Run the code cell below; from the results, can you infer what happens when different object types are cast to a Boolean? Don't hesitate to write more tests to complete your understanding."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "i = 2566\n",
    "print(bool(i))\n",
    "\n",
    "i = 0.0\n",
    "print(bool(i))\n",
    "\n",
    "i = -3.4\n",
    "print(bool(i))\n",
    "\n",
    "i = '273'\n",
    "print(bool(i))\n",
    "\n",
    "i = '0'\n",
    "print(bool(i))\n",
    "\n",
    "i = ''\n",
    "print(bool(i))\n",
    "\n",
    "i = 'False'\n",
    "print(bool(i))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex1'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Lists\n",
    "\n",
    "Lists are what they sound like -- a list is an object which can contain a number of other objects, in a certain order.\n",
    "\n",
    "A list can be defined by listing its elements inside square brackets `[...]`, separated by commas. For example, let us create a few lists, and assign them to variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = [1, 2, 3, 10, 6]\n",
    "b = ['Hi', 'how', 'are', 'you?']\n",
    "c = ['my', 1, 4.5, ['you', 'they'], 432, -2.3, 33]\n",
    "d = []\n",
    "\n",
    "print(a)\n",
    "print(b[0])\n",
    "print(c[-3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A few important things to note here:\n",
    "* An **empty list** is created by typing square brackets with nothing in between `[]`.\n",
    "* A list can contain **mixed data** -- its elements need not have the same type.\n",
    "* A list can contain other lists -- in fact, in general, containers may be **nested** in other containers.\n",
    "* The individual elements of a list are **indexed** -- they can be accessed in a similar way to the characters in a string, by referring to their position in square brackets. Remember that indexing in Python starts from `0`.\n",
    "\n",
    "We can go back to the drawer analogy to try and visualise how lists are stored in memory. For instance, consider the list `a` here:\n",
    "\n",
    "<div style=\"width:70%;margin:auto;\">\n",
    "\n",
    "| `a = [1, 2, 3, 10, 6]` |\n",
    "|:--:|\n",
    "| ![The list a in memory](graphics/lists.png) |\n",
    "\n",
    "</div>\n",
    "\n",
    "The objects are created and stored in memory as before, but now they are put in a list container labelled `a` (the yellow box/drawer), in a specific order. To access any one particular object, we use its *index* in the list (the yellow label), which indicates its position.\n",
    "\n",
    "The following examples demonstrate some of the ways to manipulate lists -- make sure to run the previous code cell first to define `a`, `b`, and `c`. Don't hesitate to try more examples to test your understanding."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Join two lists together\n",
    "print(a + b)\n",
    "\n",
    "# Find the length of a list\n",
    "print(len(b))\n",
    "\n",
    "# Append (add) an item to the end of a list\n",
    "c.append('extra')\n",
    "print(c)\n",
    "\n",
    "# Print the 2nd element of the 4th element of c\n",
    "print(c[3][1])\n",
    "\n",
    "# Sort a list\n",
    "print(sorted(a))\n",
    "\n",
    "# Create a list with 12 repetitions of the same sequence\n",
    "print(12 * [3, 0, 'y'])\n",
    "\n",
    "# Check if something is in a list\n",
    "print('my' in c)\n",
    "print('you' in c)\n",
    "print('you' in c[3])\n",
    "print(7 in a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "🚩 ***Exercise 2:*** A list of numbers can be used to represent, for example, a vector. Create a list `my_mat` to represent the $2 \\times 2$ identity matrix, that is\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "1 & 0 \\\\\n",
    "0 & 1\n",
    "\\end{bmatrix}.\n",
    "$$\n",
    "\n",
    "Then, modify `my_mat` to represent the $3\\times 3$ identity matrix, using the `.append()` method.\n",
    "\n",
    "*Hint:* you can think of a matrix as a collection of row vectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex2'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "### Slicing\n",
    "\n",
    "So far, we have seen how to create and manipulate lists, and how to operate on any single element of a list. It is often convenient to access several list elements at a time. **Index slicing** allows us to extract a new list from any subsequence of an existing list. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = [2, 5, 4, 8, 8]\n",
    "print(a[1:3])\n",
    "print(a[2:])\n",
    "print(a[:-2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Index slicing uses the colon `:` character. For instance, the command `print(a[2:])` displayed all elements of `a`, starting from the third element (with index `2`). The general syntax to access a subsequence of a list `l` is as follows:\n",
    "```python\n",
    "l[start:stop]        # from start to stop-1\n",
    "l[start:]            # from start to len(l)-1\n",
    "l[:stop]             # from 0 to stop-1\n",
    "l[start:stop:step]   # from start to stop-1, with increment step\n",
    "l[::step]            # from 0 to len(l)-1, with increment step\n",
    "l[::], l[:]          # all the elements\n",
    "```\n",
    "\n",
    "A couple of things to note:\n",
    "* As was the case for indexing single elements, we can use negative indices when slicing to indicate positions starting from the end of the list.\n",
    "* The second index `stop` indicates the **first element of `l` which is not accessed**. In other words, `l[i:j]` returns `[l[i], l[i+1], ..., l[j-2], l[j-1]]`, and **excludes** `l[j]`. You can see this in the first example above: `a[1:3]` returned `[a[1], a[2]]`.\n",
    "* If `j` $=$ `i`, then `a[i:j]` and `a[i:j:k]` are empty lists, for any value of `k`.\n",
    "* If `j` $<$ `i`, then `a[i:j]` and `a[i:j:k]` are empty lists, for *positive* values of `k`.\n",
    "\n",
    "*Note:* index slicing works on any type of *sequence*, not just lists. For instance, a string is another type of sequence in Python.\n",
    "\n",
    "---\n",
    "**📚 Learn more:**\n",
    "* [Lists - An informal introduction to Python - Python 3.7 documentation](https://docs.python.org/3/tutorial/introduction.html#lists)\n",
    "* [More on lists - Python 3.7 documentation](https://docs.python.org/3/tutorial/datastructures.html#more-on-lists) - more examples of list methods, to perform different operations on lists.\n",
    "\n",
    "---\n",
    "\n",
    "🚩 ***Exercise 3:*** Consider the list `m` below. What is the most concise way to create a new list `m_back`, which takes as value the list `m`, backwards? In other words, `print(m_back)` should display\n",
    "```\n",
    "['e', 'd', 'c', 'b', 'a']\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "m = ['a', 'b', 'c', 'd', 'e']\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex3'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "🚩 ***Exercise 4:*** Create a variable `n`, with value $n \\in \\mathbb{N}$ such that $5 \\leq n \\leq 20$. Create a list `my_list` of $n - 1$ ones. Then, append $\\pi$ to the list -- its length should now be $n$. Finally, change the value of the $3$rd element of `my_list` to be the sum of its last $n - 4$ elements.\n",
    "\n",
    "For example, for $n=6$, `print(my_list)` should display\n",
    "```\n",
    "[1, 1, 4.141592653589793, 1, 1, 3.141592653589793]\n",
    "```\n",
    "\n",
    "*Hint:* You may wish to use the [sum()](https://docs.python.org/3/library/functions.html#sum) function (a list is a type of *iterable*)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex4'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Loops\n",
    "\n",
    "More often than not, an important motivation for using programming to solve problems is the computer's ability (relative to the human brain's struggle) to perform a given set of computations *many* times over, very quickly. Loops allow us to do just that: give the computer a set of instructions and a stopping point, and it will execute these instructions over and over until that point is reached.\n",
    "\n",
    "As a simple first example, take Exercise 5 from the Week 1 worksheet: create a string variable `my_string`, holding some text characters of your choice. Create an integer variable `m` with some value $m$, and use it to print **every $m$th character** of `my_string`.\n",
    "\n",
    "To do this without loops, we need to type the `print()` command repeatedly, and change the index every time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_string = 'Some text characters of my choice.'\n",
    "m = 4\n",
    "\n",
    "# Find out how many times we can print the mth character\n",
    "# before exceeding the string length\n",
    "N = len(my_string)\n",
    "print(N // m)\n",
    "\n",
    "print(my_string[m - 1])\n",
    "print(my_string[2 * m - 1])\n",
    "print(my_string[3 * m - 1])\n",
    "print(my_string[4 * m - 1])\n",
    "print(my_string[5 * m - 1])\n",
    "print(my_string[6 * m - 1])\n",
    "print(my_string[7 * m - 1])\n",
    "print(my_string[8 * m - 1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By now, you know about *slicing*, and you could think of doing it this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_string = 'Some text characters of my choice.'\n",
    "m = 4\n",
    "\n",
    "print(my_string[m-1::m])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Not bad! But we could also do this with a **`for` loop** --- don't worry, we'll explain how it works in the next section:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_string = 'Some text characters of my choice.'\n",
    "m = 4\n",
    "\n",
    "N = len(my_string)\n",
    "\n",
    "# Loop over the characters\n",
    "for i in range(m-1, N, m):\n",
    "    print(my_string[i])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two types of loop available in Python:\n",
    "* **`for`** loops allow us to perform a set of instructions *for* a pre-determined number of *iterations*;\n",
    "* **`while`** loops allow us to perform a set of instructions *while* a given condition is true. The number of iterations need not be known in advance.\n",
    "\n",
    "This week, we focus on `for` loops; next week, we will introduce `while` loops.\n",
    "\n",
    "---\n",
    "## `for` loops\n",
    "\n",
    "`for` loops iterate over the elements of a **sequence** (e.g. a list or a string), in the order in which they appear in that sequence. The syntax is as follows:\n",
    "```python\n",
    "for i in my_seq:\n",
    "    [some instructions]\n",
    "```\n",
    "The `for` loop uses a *placeholder variable* (`i` in the example above), which is assigned with each element of `my_seq`, in turn.\n",
    "\n",
    "For example, we can loop over a list to print each of its elements separately:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = [1, 2, 3, 10, 6]\n",
    "\n",
    "for element in a:\n",
    "    print(element)\n",
    "    \n",
    "print('These are all the elements of a.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the loop starts, `element` is assigned the value `a[0]`, and the instructions in the loop are performed. Here, we just have one instruction, `print(element)`: the value `a[0]` is printed.\n",
    "\n",
    "When all instructions have been executed, we go back to the start of the loop, and `element` is assigned the next value `a[1]`. The instructions are executed, and we start again. The loop **terminates** when we run out of elements in `a` -- here, after 5 iterations. The rest of the code is then executed as usual.\n",
    "\n",
    "<div style=\"width:60%;margin:auto;\">\n",
    "\n",
    "![Looping over the elements of a](graphics/forloop.png)\n",
    "\n",
    "</div>\n",
    "\n",
    "Note that after the loop terminates, the variable `element` is not deleted; it remains assigned with the last value it was assigned by the loop --- here, `a[4]`. (You can see this by printing its value once *after* the loop.)\n",
    "\n",
    "#### Delimiting code blocks\n",
    "\n",
    "A very important thing to note here is **indentation**. The way Python knows where the loop instructions start and end is by looking at the indentation level of the commands following the `for` statement. As soon as the indentation level is brought back to the same level as the `for` statement, we are back in the main part of the code; any commands from then on are not part of the loop.\n",
    "\n",
    "---\n",
    "**Note:** Briefly going back to code style, it is standard in most style guides to count 4 spaces as 1 indentation level. Most of the time, Jupyter indents and de-dents code automatically, by adding or removing 4 spaces at the start of lines when it deems it relevant.\n",
    "\n",
    "You can select one or more lines in any code cell, and press <kbd>Tab</kbd> to indent by 1 level.\n",
    "\n",
    "---\n",
    "🚩 ***Exercise 5:*** Indent the last line in the code cell above, by adding 4 spaces (either manually, or by inserting a <kbd>Tab</kbd> character, which will automatically be converted to 4 spaces) at the start of the line. Run the cell again -- what happens?\n",
    "\n",
    "---\n",
    "\n",
    "### Ranges\n",
    "\n",
    "There is another *sequence type* which we haven't mentioned so far, but is often useful in conjunction with `for` loops: the `range` type. A range is a sequence of increasing or decreasing integers, and can be created using the `range()` function, as follows:\n",
    "```python\n",
    "range(j)             # 0, 1, 2, ..., j-1\n",
    "range(i, j)          # i, i+1, i+2, ..., j-1\n",
    "range(i, j, k)       # i, i+k, i+2k, ..., i+m\n",
    "```\n",
    "where `m` is the largest multiple of `k` such that `i + m` $\\leq$ `j - 1`. Note that, as was the case for index slicing, **the stopping index `j` is the first value which is *not* included in the range**. A few examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(range(5))\n",
    "print(list(range(5)))\n",
    "print(list(range(10, -10, -3)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that, to print all elements of a range object, we first **cast** it to a list (i.e. manually change its *type* to `list`, by using the function `list()`).\n",
    "\n",
    "Now, let us see how ranges can be helpful with `for` loops. For example, consider the sum\n",
    "$$\n",
    "S = \\sum_{i=0}^{10} i.\n",
    "$$\n",
    "One way to compute this sum would be as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "S = 0\n",
    "\n",
    "# Loop over indices 0 to 10, inclusive\n",
    "for i in range(11):\n",
    "    S += i    # this is a shortcut for S = S + i\n",
    "\n",
    "print(S)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "***Note:*** when looping over a **sequence** (e.g. a list or a string --- anything with elements indexed by number), you can either loop over the elements or over the indices. The two loops here produce the same result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = [2, 5, 7, 2, 1]\n",
    "\n",
    "# Looping over the list by element\n",
    "for element in a:\n",
    "    print(element)\n",
    "    \n",
    "# Looping over the list by index\n",
    "for idx in range(len(a)):\n",
    "    print(a[idx])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- At the $n$th iteration in the first loop, `element` is assigned the value of the $n$th element of `a`. For instance, at iteration 2 (starting from 0 for convenience), `element` is `7`.\n",
    "- At the $n$th iteration in the second loop, `idx` is assigned the value $n$. For instance, at iteration 2, `idx` is `2`. (Here, strictly speaking, we don't actually loop over `a`, but over a `range` of numbers from 0 to 4, which we use to index the elements of `a` from inside the loop.)\n",
    "\n",
    "The choice of either looping by element or by index usually depends on the problem --- in general, if the index (the position) of each element is not needed for the computations inside the loop, the first form is preferred.\n",
    "\n",
    "---\n",
    "**📚 Learn more:**\n",
    "* [The `for` statement - Python 3.7 documentation](https://docs.python.org/3/tutorial/controlflow.html#for-statements)\n",
    "* [Ranges - Python 3.7 documentation](https://docs.python.org/3/library/stdtypes.html#typesseq-range)\n",
    "* [Looping techniques - Python 3.7 documentation](https://docs.python.org/3/tutorial/datastructures.html#looping-techniques) -- some useful tricks to loop over sequences, including the `enumerate()` and `zip()` functions.\n",
    "\n",
    "---\n",
    "🚩 ***Exercise 6:*** Using a `for` loop, compute and print the product\n",
    "$$\n",
    "P = \\prod_{j=2}^{n} \\left(j^3 + 5j^2 - 3\\right),\n",
    "$$\n",
    "where $n \\geq 2$ is an integer value of your choice. To check your code, the result for $n=20$ is\n",
    "```\n",
    "102608796359678464673256924713629769626423839617879814815625.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex6'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Defining functions\n",
    "\n",
    "So far, we have used some of the built-in Python functions (e.g. `print()`, `sorted()`), and functions like `numpy.sin()` or `numpy.sqrt()` which come with the `numpy` module.\n",
    "\n",
    "You can also define your own custom functions to encapsulate specific subtasks and structure your programs. A **function** is essentially a block of code which only *executes* when the function is *called*. A Python function can be defined using\n",
    "```python\n",
    "def my_func(inputs):\n",
    "    [function body]\n",
    "    return outputs\n",
    "```\n",
    "where\n",
    "* `my_func` is the *name* of your function,\n",
    "* `inputs` are the (zero or more) **input arguments**,\n",
    "* `[function body]` are the commands to execute upon *calling* the function,\n",
    "* `outputs` are the (zero or more) **return values** or **output values**.\n",
    "\n",
    "For example, we can define Python functions to represent mathematical functions. Consider the function\n",
    "\n",
    "$$\n",
    "f(x) = \\frac{3x - 2}{\\sqrt{2x + 1}}.\n",
    "$$\n",
    "\n",
    "We can write a function `f()`, which takes a variable `x` as an input argument, with some value $x$, and returns the value of $f(x)$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "def f(x):\n",
    "    y = (3*x - 2) / math.sqrt(2*x + 1)\n",
    "    return y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function `f()` is now defined, but note that nothing seems to happen when running the above cell. The function hasn't been **called** (i.e. used), so the instructions in the function body are not executed. Simply speaking, we are merely providing the *Python interpreter* with a set of instructions, so that it knows what to do in case we ask it, for instance, to compute `f(5)`. Functions, like everything else in Python, are also **objects** --- it may be helpful to visualise them as recipes or blueprints.\n",
    "\n",
    "Now, we can *call* our function if we want to compute $f(x)$ for different values of $x$, instead of having to write the formula several times:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "a = 3\n",
    "b = -0.2\n",
    "c = math.pi\n",
    "\n",
    "# Display return values on the screen\n",
    "print(f(a), f(b), f(c))\n",
    "\n",
    "# Assign return values to variables\n",
    "f_pi = f(c)\n",
    "print('f(x) evaluated at x = pi is', f_pi)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The statement `f(a)` *calls* the function `f()`, with the input value `a`. The instructions in the body of the function are then executed; the result is computed using the value of `a`, and is then assigned to a variable `y`. The *value* of `y` is finally *returned* by the function, and can be assigned to variables and manipulated as usual.\n",
    "\n",
    "| <code>def f(x):<br/>&nbsp;&nbsp;&nbsp;&nbsp;y = (3\\*x - 2) / math.sqrt(2\\*x + 1)<br/>&nbsp;&nbsp;&nbsp;&nbsp;return y</code> | <code>a = 3<br/>b = -0.2<br/>c = math.pi<br/></code>  | `f_pi = f(c)` |\n",
    "|:---|:---|:---:|\n",
    "| ![Defining the function f](graphics/def.png) | ![Assigning a, b, c](graphics/abc.png) | ![Assigning f(c) to f_pi](graphics/func_store.png) |\n",
    "| **1.** A function object is created as a set of instructions, and named `f`. | **2.** Three number objects are created and respectively named `a, b, c`. | **3.** The function `f` is *called* with input value `c`; the instructions are executed. `f` *returns* a new number object, which we store in memory with the name `f_pi`. |\n",
    "\n",
    "#### Return values\n",
    "\n",
    "When the `return` statement is reached, we **exit** the function -- we *return* to the main program with some output value(s).\n",
    "\n",
    "Recall that *code blocks* in Python are delimited with indentation levels -- the body of the function is everything under the definition `def my_func(inputs):`, indented by one level. However, when the `return` statement is reached, the function exits immediately, and any code written after it is simply *not executed* -- even if it is still indented, and part of the function body. This is somewhat analogous to how the `break` statement works in loops.\n",
    "\n",
    "The `return` statement is optional -- a function can perform a set of instructions without returning any value. For instance, the `print()` function itself doesn't *return* any value -- it simply prints the value of its input argument(s) on the screen.\n",
    "\n",
    "---\n",
    "**Note:** strictly speaking, all functions return a value. If you omit the `return` statement when writing your function, or if you don't specify any output values, then by default the return value will be `None`. In Python, `None` is the object that represents the absence of a value (although it is, itself, a value).\n",
    "\n",
    "For example, if we try to assign the output value of `print()` to a variable, we get"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = print('Hello World!')\n",
    "print(a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the `print()` function is called the first time, it does its job -- it displays its input argument on the screen. However, it doesn't return anything -- strictly speaking, it returns `None`. The value `None` is therefore assigned to the variable `a`.\n",
    "\n",
    "<div style=\"width:50%;margin:auto;\">\n",
    "\n",
    "| `a = print('Hello World!')` |\n",
    "|:--:|\n",
    "| ![print displays on screen, but returns None](graphics/print.png) |\n",
    "| Here, the red card represents a string object with value `Hello World!`. Note that it is never assigned to a variable, and therefore not kept in memory.|\n",
    "\n",
    "</div>\n",
    "\n",
    "---\n",
    "### Returning multiple values\n",
    "\n",
    "To return multiple values from a function, we can list them after the `return` statement, one after another, separated by commas. For instance, let us define a function `sum_diff_prod()` which computes and returns the sum, difference, and product of two given numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sum_diff_prod(a, b):\n",
    "    '''\n",
    "    Computes and returns the sum, difference,\n",
    "    and product of a and b.\n",
    "    '''\n",
    "    return a+b, a-b, a*b\n",
    "\n",
    "# Print the output of the function as a tuple\n",
    "print(sum_diff_prod(12, 4))\n",
    "print(sum_diff_prod(0, -1.2))\n",
    "\n",
    "# Unpack the output into different variables\n",
    "s, d, p = sum_diff_prod(-4, -3)\n",
    "print(s)\n",
    "print(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two things to note:\n",
    "* Just below the `def` statement, the red string between a pair of triple quotes is called the **docstring** of the function. It describes what the function does -- think of it as a short version of the function's documentation. It is *always* a good idea to write docstrings when defining functions. When the input arguments and output values are not trivially defined, the docstring should list them and give a short description for each.\n",
    "* If a function returns several output values, they can be **unpacked** to assign the different return values to different variables. For instance, here,\n",
    "```python\n",
    "s, d, p = sum_diff_prod(-4, -3)\n",
    "```\n",
    "assigns the 3 values returned by `sum_diff_prod()` to the 3 variables `s`, `d`, and `p` respectively.\n",
    "\n",
    "---\n",
    "**📚 Learn more:**\n",
    "* [Defining Functions - Python 3 documentation](https://docs.python.org/3/tutorial/controlflow.html#defining-functions)\n",
    "* [More on Defining Functions - Python 3 documentation](https://docs.python.org/3/tutorial/controlflow.html#more-on-defining-functions)\n",
    "* [PEP 257 - Docstring Conventions](https://www.python.org/dev/peps/pep-0257/)\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "🚩 ***Exercise 7:*** Write a function `compute_P()`, which takes 1 input argument `n`, representing an integer $n \\geq 2$, and returns the product $P$ defined earlier for that particular value of $n$:\n",
    "$$\n",
    "P = \\prod_{j=2}^{n} \\left(j^3 + 5j^2 - 3\\right).\n",
    "$$\n",
    "\n",
    "For example, `print(compute_P(7))` should display `13811904975375`.\n",
    "\n",
    "You can reuse your code from Exercise 5 inside your function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "solution_cell"
    ]
   },
   "outputs": [],
   "source": [
    "%run scripts/show_solutions.py 'week02_ex7'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Coderunner\n",
    "\n",
    "Now that you know how to write functions, we can make use of a tool called Coderunner, which hosts your weekly quizzes. The quizzes consist of a number of programming questions, which are automatically graded.\n",
    "\n",
    "For each question, you will be asked to write functions to perform specific tasks. The question will always state\n",
    "* the name of the function,\n",
    "* the number and the type of input arguments it should take (if any), and\n",
    "* the number and the type of output arguments it should return (if any).\n",
    "\n",
    "Your function will be tested against a number of test input values, and the output will be compared to the expected output values, to determine whether your function is correct.\n",
    "\n",
    "Each week, you will have a practice quiz on Coderunner, which will **not** count for credit. This will contain some programming questions for you to practice what you learned during the week.\n",
    "\n",
    "On weeks 2, 4, 5, 7, 8, and 10, you will **also** have an **assessed quiz**, which will count for credit.\n",
    "\n",
    "More detailed information on the quizzes is given on the \"Weekly assessments\" page (where all your quizzes and code review assessments will be), and in the \"Assessment\" page on Learn."
   ]
  }
 ],
 "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}