04 Functions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "Functions are one of the most important concepts in computing.  Similar to mathematical functions, they take input data and return an output(s). Functions are ideal for repetitive tasks that perform a particular operation\n",
    "on different input data and return a result. A simple function might take the coordinates of the vertices of a triangle and return the area. Any non-trivial program will use functions, and in many cases will have many functions.\n",
    "\n",
    "\n",
    "## Objectives\n",
    "\n",
    "- Introduce construction and use of user functions\n",
    "- Returning from functions\n",
    "- Default arguments\n",
    "- Recursion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What is a function?\n",
    "\n",
    "Below is a Python function that takes two arguments (`a` and `b`), and returns `a + b + 1`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def sum_and_increment(a, b):\n",
    "    \"\"\"\"Return the sum of a and b, plus 1\"\"\"\n",
    "    return a + b + 1\n",
    "\n",
    "# Call the function\n",
    "m = sum_and_increment(3, 4)\n",
    "print(m)  # Expect 8\n",
    "\n",
    "# Call the function\n",
    "m = 10\n",
    "n = sum_and_increment(m, m)\n",
    "print(n)  # Expect 21"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the above example as a model, we can examine the anatomy of a Python function.\n",
    "\n",
    "- A function is declared using `def`, followed by the function name, `sum_and_increment`, followed by the list \n",
    "  of arguments to be passed to the function between brackets, `(a, b)`, and ended with a colon:\n",
    "  ```python\n",
    "  def sum_and_increment(a, b):\n",
    "  ```\n",
    "\n",
    "- Next comes the body of the function. The first part of the body is indented four spaces. \n",
    "  Everything that makes \n",
    "  up  the body of the function is indented at least four spaces relative to `def`. \n",
    "  In Python, the first part of the body is an optional documentation string that describes in words what the   \n",
    "  function does \n",
    "  ```python  \n",
    "      \"Return the sum of a and b, plus 1\"\n",
    "  ```\n",
    "\n",
    "- It is good practice to include a 'docstring'.  What comes after the documentation string \n",
    "  is the code that the function executes. At the end of a function is usually a `return` statement; this defines   what\n",
    "  result the function should return:\n",
    "  ```python\n",
    "      return a + b + 1\n",
    "  ```\n",
    "Anything indented to the same level (or less) as `def` falls outside of the function body.\n",
    "\n",
    "Most functions will take arguments and return something, but this is not strictly required.\n",
    "Below is an example of a function that does not take any arguments or return any variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_message():\n",
    "    print(\"The function 'print_message' has been called.\")\n",
    "\n",
    "print_message()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Purpose\n",
    "\n",
    "Functions allow blocks of computer code to be re-used multiple times with different input data. It is good to re-use code as much as possible because we then focus testing and debugging efforts, and maybe also performance optimisations, on small blocks of code that are then re-used. The more code that is written, the less frequently sections of code are used, and as a consequence the greater the likelihood of errors.\n",
    "\n",
    "Functions can also enhance the readability of a program, and make it easier to collaborate with others. Functions allow us to focus on *what* a program does at a high level \n",
    "rather than the details of *how* it does it. Low-level implementation details are *encapsulated* in functions. To understand at a high level what a program does, we usually just need to know what data is passed into a function and what the function returns. It is not necessary to know the precise details of how a function is implemented to grasp the structure of a program and how it works. For example, we might need to know that a function computes and returns $\\sin(x)$; we don't usually need to know *how* it computes sine.\n",
    "\n",
    "Below is a simple example of a function being 'called' numerous times from inside a `for` loop."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def process_value(x):\n",
    "    \"Return a value that depends on the input value x \"\n",
    "    if x > 10:\n",
    "        return 0\n",
    "    elif x > 5:\n",
    "        return x*x\n",
    "    elif x > 0:\n",
    "        return x**3\n",
    "    else:\n",
    "        return x\n",
    "\n",
    "    \n",
    "print(\"Case A: 3 values\")    \n",
    "for y in range(3):\n",
    "    print(process_value(y))\n",
    "\n",
    "print(\"Case B: 12 values\")    \n",
    "for y in range(12):\n",
    "    print(process_value(y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using a function, we did not have to duplicate the `if-elif-else` statement inside each loop\n",
    "we re-used it.\n",
    "With a function we only have to change the way in which we process the number `x` in one place."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Function arguments\n",
    "\n",
    "The order in which function arguments are listed in the function declaration is in general the order in which arguments should be passed to a function. \n",
    "\n",
    "For the function `sum_and_increment` that was declared above, we could switch the order of the arguments and the result would not change because we are simply summing the input arguments. But, if we were to subtract one argument from the other, the result would depend on the input order:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def subtract_and_increment(a, b):\n",
    "    \"Return a minus b, plus 1\"\n",
    "    return a - b + 1\n",
    "\n",
    "alpha, beta = 3, 5  # This is short hand notation for alpha = 3\n",
    "                    #                                 beta = 5\n",
    "\n",
    "# Call the function and print the return value\n",
    "print(subtract_and_increment(alpha, beta))  # Expect -1\n",
    "print(subtract_and_increment(beta, alpha))  # Expect 3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more complicated functions we might have numerous arguments. Consequently, it becomes easier to get the wrong order by accident when calling the function (which results in a bug). In Python, we can reduce the likelihood of an error by using *named* arguments, in which case order will not matter, e.g.:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(subtract_and_increment(a=alpha, b=beta))  # Expect -1\n",
    "print(subtract_and_increment(b=beta, a=alpha))  # Expect -1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using named arguments can often enhance program readability and reduce errors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What can be passed as a function argument?\n",
    "\n",
    "Many object types can be passed as arguments to functions, including other functions. Below\n",
    "is a function, `is_positive`, that checks if the value of a function $f$ evaluated at $x$ is positive:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def f0(x):\n",
    "    \"Compute x^2 - 1\"\n",
    "    return x*x - 1\n",
    "\n",
    "\n",
    "def f1(x):\n",
    "    \"Compute -x^2 + 2x + 1\"\n",
    "    return -x*x + 2*x + 1\n",
    "\n",
    "\n",
    "def is_positive(f, x):\n",
    "    \"Check if the function value f(x) is positive\"\n",
    "\n",
    "    # Evaluate the function passed into the function for the value of x \n",
    "    # passed into the function\n",
    "    if f(x) > 0:\n",
    "        return True\n",
    "    else:\n",
    "        return False\n",
    "\n",
    "    \n",
    "# Value of x for which we want to test a function sign\n",
    "x = 4.5\n",
    "\n",
    "# Test function f0\n",
    "print(is_positive(f0, x))\n",
    "\n",
    "# Test function f1\n",
    "print(is_positive(f1, x))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Default arguments\n",
    "\n",
    "It can sometimes be helpful for functions to have 'default' argument values which can be overridden. In some cases it just saves the programmer effort - they can write less code. In other cases it can allow us to use a function for a wider range of problems. For example, we could use the same function for vectors of length 2 and 3 if the default value for the third component is zero.\n",
    "\n",
    "As an example we consider the position $r$ of a particle with initial position $r_{0}$ and initial velocity $v_{0}$, and subject to an acceleration $a$. The position $r$ is given by:  \n",
    "\n",
    "$$\n",
    "r = r_0 + v_0 t + \\frac{1}{2} a t^{2}\n",
    "$$\n",
    "\n",
    "Say for a particular application the acceleration is almost always due to gravity ($g$), and $g = 9.81$ m s$^{-1}$ is sufficiently accurate in most cases. Moreover, the initial velocity is usually zero. We might therefore implement a function as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def position(t, r0, v0=0.0, a=-9.81):\n",
    "    \"Compute position of an accelerating particle.\"\n",
    "    return r0 + v0*t + 0.5*a*t*t\n",
    "\n",
    "# Position after 0.2 s (t) when dropped from a height of 1 m (r0) \n",
    "# with v0=0.0 and a=-9.81\n",
    "p = position(0.2, 1.0)\n",
    "print(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the equator, the acceleration due to gravity is slightly less, and for a case where this difference is important we can call the function with the acceleration due to gravity at the equator:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Position after 0.2 s (t) when dropped from a height of  1 m (r0)\n",
    "p = position(0.2, 1, 0.0, -9.78)\n",
    "print(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we have also passed the initial velocity - otherwise the program might assume that our acceleration was in fact the velocity. We can use the default velocity and specify the acceleration by using named arguments: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Position after 0.2 s (t) when dropped from a height of  1 m (r0)\n",
    "p = position(0.2, 1, a=-9.78)\n",
    "print(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Return arguments\n",
    "\n",
    "Most functions, but not all, return data. Above are examples that return a single value (object), and one case where there is no return value. Python functions can have more than one return value. For example, we could have a function that takes three values and returns the maximum, the minimum and the mean, e.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def compute_max_min_mean(x0, x1, x2):\n",
    "    \"Return maximum, minimum and mean values\"\n",
    "    \n",
    "    x_min = x0\n",
    "    if x1 < x_min:\n",
    "        x_min = x1\n",
    "    if x2 < x_min:\n",
    "        x_min = x2\n",
    "\n",
    "    x_max = x0\n",
    "    if x1 > x_max:\n",
    "        x_max = x1\n",
    "    if x2 > x_max:\n",
    "        x_max = x2\n",
    "\n",
    "    x_mean = (x0 + x1 + x2)/3    \n",
    "        \n",
    "    return x_min, x_max, x_mean\n",
    "\n",
    "\n",
    "xmin, xmax, xmean = compute_max_min_mean(0.5, 0.1, -20)\n",
    "print(xmin, xmax, xmean)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This function works, but we will see better ways to implement the functionality using lists or tuples \n",
    "in a later notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Scope\n",
    "\n",
    "Functions have local scope, which means that variables that are declared inside a function are not visible outside the function. This is a very good thing - it means that we do not have to worry about variables declared inside a function unexpectedly affecting other parts of a program. Here is a simple example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Assign 10.0 to the varibale a\n",
    "a = 10.0\n",
    "\n",
    "# A simple function that creates a variable 'a' and returns the value\n",
    "def dummy():\n",
    "    c = 5\n",
    "    a = \"A simple function\"\n",
    "    return a\n",
    "\n",
    "# Call the function\n",
    "b = dummy()\n",
    "\n",
    "# Check that the function declaration of 'a' has not affected \n",
    "# the variable 'a' outside of the function\n",
    "print(a)\n",
    "\n",
    "# This would throw an error - the variable c is not visible outside of the function\n",
    "# print(c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The variable `a` that is declared outside of the function is unaffected by what is done inside the function.\n",
    "Similarly, the variable `c` in the function is not 'visible' outside of the function. \n",
    "\n",
    "There is more to scoping rules that we can skip over for now."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Recursion with functions\n",
    "\n",
    "A classic construction with functions is recursion, which is when a function makes calls to itself. \n",
    "Recursion can be very powerful, and rather quite confusing at first. We demonstrate with a well-known example, the Fibonacci series of numbers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fibonacci number\n",
    "\n",
    "The Fibonacci series is defined recursively, i.e. the $n$th term $f_{n}$ is computed from the preceding terms $f_{n-1}$ and $f_{n-2}$:\n",
    "\n",
    "$$\n",
    "f_n = f_{n-1} + f_{n-2}\n",
    "$$\n",
    "\n",
    "for $n > 1$, and with $f_0 = 0$ and $f_1 = 1$. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a non-recursive function that computes the $n$th number in the Fibonacci sequence using a `for` loop inside the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "55\n"
     ]
    }
   ],
   "source": [
    "def fib(n):\n",
    "    \"Compute the nth Fibonacci number\"\n",
    "    # Starting values for f0 and f1\n",
    "    f0, f1 = 0, 1\n",
    "\n",
    "    # Handle cases n==0 and n==1\n",
    "    if n == 0:\n",
    "        return 0\n",
    "    elif n == 1:\n",
    "        return 1\n",
    "    \n",
    "    # Start loop (from n = 2)    \n",
    "    for i in range(2, n + 1):\n",
    "        # Compute next term in sequence\n",
    "        f = f1 + f0\n",
    "\n",
    "        # Update f0 and f1    \n",
    "        f0 = f1\n",
    "        f1 = f\n",
    "\n",
    "    # Return Fibonacci number\n",
    "    return f\n",
    "\n",
    "print(fib(10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the Fibonacci sequence has a recursive structure, with the $n$th term computed from the $n-1$ and $n-2$ terms, we could write a function that uses this recursive structure:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "55\n"
     ]
    }
   ],
   "source": [
    "def f(n): \n",
    "    \"Compute the nth Fibonacci number using recursion\"\n",
    "    if n == 0:\n",
    "        return 0  # This doesn't call f, so it breaks out of the recursion loop\n",
    "    elif n == 1:\n",
    "        return 1  # This doesn't call f, so it breaks out of the recursion loop\n",
    "    else:\n",
    "        return f(n - 1) + f(n - 2)  # This calls f for n-1 and n-2 (recursion), and returns the sum \n",
    "\n",
    "print(f(10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As expected (if the implementations are correct) the two implementations return the same result.\n",
    "The recursive version is simple and has a more 'mathematical' structure. It is good that a program which performs a mathematical task closely reflects the mathematical problem. It makes it easier to comprehend at a high level what the program does.\n",
    "\n",
    "Care needs to be taken when using recursion that a program does not enter an infinite recursion loop. There must be a mechanism to 'break out' of the recursion cycle. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pass by  value, reference or object\n",
    "\n",
    "*This section is for reference and should be skipped if you are new to programming. It is not necessary for this course but may be of interest \n",
    "to those with more experience.*\n",
    "\n",
    "When passing something to a function, it is *passed by value*, *passed by reference*, or *passed by object*.\n",
    "The model depends on the language.\n",
    "\n",
    "Pass by value means that the version available inside the function is a copy of the value outside. \n",
    "A simple example is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value of variable 'a' inside function: 10\n",
      "Value of variable 'a' post-function: 5\n"
     ]
    }
   ],
   "source": [
    "def mult_by_two(a):\n",
    "    a *= 2\n",
    "    print(\"Value of variable \\'a\\' inside function:\", a)\n",
    "    \n",
    "a = 5\n",
    "mult_by_two(a)\n",
    "print(\"Value of variable \\'a\\' post-function:\", a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The value of the variable outside of the function remains unchanged.\n",
    "\n",
    "Pass by reference means that the 'version' passed into the function is that same as that outside the function, rather than a copy being made, and changes made inside the function will be seen outside of the function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value of variable 'a' inside function: [2, 3, 2, 3]\n",
      "Value of variable 'a' post-function:   [2, 3, 2, 3]\n"
     ]
    }
   ],
   "source": [
    "a = [2, 3]\n",
    "mult_by_two(a)\n",
    "print(\"Value of variable \\'a\\' post-function:  \", a)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python uses the *pass-by-object model*. The apparent behaviours depends on the details of the object being passed.\n",
    "In many cases it is clearer to return objects. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercises\n",
    "\n",
    "Complete now the [04 Exercises](Exercises/04%20Exercises.ipynb) notebook."
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}