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"
   ]
  },
  {
   "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": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "8\n",
      "21\n"
     ]
    }
   ],
   "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": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Case A: 3 values\n",
      "0\n",
      "1\n",
      "8\n",
      "Case B: 12 values\n",
      "0\n",
      "1\n",
      "8\n",
      "27\n",
      "64\n",
      "125\n",
      "36\n",
      "49\n",
      "64\n",
      "81\n",
      "100\n",
      "0\n"
     ]
    }
   ],
   "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": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-1\n",
      "3\n"
     ]
    }
   ],
   "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": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-1\n",
      "-1\n"
     ]
    }
   ],
   "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": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n"
     ]
    }
   ],
   "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 coordinates in 2D and 3D if the default value for the third coordinate 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": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.8038\n"
     ]
    }
   ],
   "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": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.8044\n"
     ]
    }
   ],
   "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": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.8044\n"
     ]
    }
   ],
   "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": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "-20 0.5 -6.466666666666666\n"
     ]
    }
   ],
   "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": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "10.0\n"
     ]
    }
   ],
   "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": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "e0a9b2e8a53ee557285f579debe9e5cc",
     "grade": false,
     "grade_id": "cell-0dc6eedbed930025",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "## Exercise 04.1 (simple function)\n",
    "\n",
    "Write a function called `is_odd` which takes an integer as an argument and returns `True` if the argument is odd, and otherwise returns `False`. Test your function for several values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "a02ca20847904f8b06f9f4e363f7793f",
     "grade": false,
     "grade_id": "cell-f07e8ac1f9838913",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def is_odd(x):\n",
    "    \"\"\"Retruns True if the argument is oddd\"\"\"\n",
    "    \n",
    "    if x%2 != 0:       #odd numbers are not divisable by 2\n",
    "        a =  True\n",
    "    else: \n",
    "        a = False      #even number are divisable by 2\n",
    "    \n",
    "    return a\n",
    "        \n",
    "        \n",
    "is_odd(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "1c1d897bf819677735ebbabd84478b5a",
     "grade": true,
     "grade_id": "cell-8a4ca795d9fa96dd",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "assert is_odd(0) == False\n",
    "assert is_odd(101) == True\n",
    "assert is_odd(982) == False \n",
    "assert is_odd(-5) == True\n",
    "assert is_odd(-8) == False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "34d59ab6e239d09f5de616f9f8d7a54d",
     "grade": false,
     "grade_id": "cell-5ff5517961853849",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "## Exercise 04.2 (functions and default arguments)\n",
    "\n",
    "Write a single function named `magnitude`. This should return the length of a straight line that starts at the origin, and ends at a coordinate described by 2 arguments (a line in 2D) or 3 arguments (a line in 3D). Use default arguments to handle lines in 2D or 3D _with the same code_. Test your function for correctness against hand calculations for a selection of values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "eb3b0a0798740195ebc614523189be95",
     "grade": false,
     "grade_id": "cell-693a09b45c6bb532",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "import math\n",
    "# YOUR CODE HERE\n",
    "\n",
    "def magnitude(a, b, c=0):\n",
    "    \"Calculates magnitude\"\n",
    "    \n",
    "    return math.sqrt(a**2 + b**2 + c**2)   #uses Pythagoras theorem\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "53cdb70056d8af7e0a1d29feffbe9ccc",
     "grade": true,
     "grade_id": "cell-384a85ba97b226d7",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "assert round(magnitude(3, 4) - 5.0, 10) == 0.0\n",
    "assert round(magnitude(4, 3) - 5.0, 10) == 0.0\n",
    "assert round(magnitude(4, 3, 0.0)- 5.0, 10) == 0.0\n",
    "assert round(magnitude(4, 0.0, 3.0) - 5.0, 10) == 0.0\n",
    "assert round(magnitude(3, 4, 4) - 6.403124237, 8) == 0.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "markdown",
     "checksum": "41dbb0a818ccdedb37806cea8a5e4866",
     "grade": false,
     "grade_id": "cell-668d765c259431ca",
     "locked": true,
     "schema_version": 3,
     "solution": false
    }
   },
   "source": [
    "## Exercise 04.3 (functions)\n",
    "\n",
    "Given the coordinates of the vertices of a triangle, $(x_0, y_0)$, $(x_1, y_1)$ and $(x_2, y_2)$, the area $A$ of the triangle is given by:\n",
    "$$\n",
    "A = \\left| \\frac{x_0(y_1  - y_2) + x_1(y_2 - y_0) + x_2(y_0 - y_1)}{2} \\right|\n",
    "$$\n",
    "Write a function named `area` that computes the area of a triangle given the coordinates of the vertices.\n",
    "The order of the function arguments must be (`x0, y0, x1, y1, x2, y2)`.\n",
    "\n",
    "Test the output of your function against some known solutions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "deletable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "57a01efe35b4f958c2cfea74b0f11088",
     "grade": false,
     "grade_id": "cell-ed02439d4509b2c1",
     "locked": false,
     "schema_version": 3,
     "solution": true
    }
   },
   "outputs": [],
   "source": [
    "# YOUR CODE HERE\n",
    "def area (x0, y0, x1, y1, x2, y2):\n",
    "    'calculate are of a triangle based on its vertices cooridnates'\n",
    "    \n",
    "    a = (x0*(y1 - y2) + x1*(y2 - y0) + x2*(y0 - y1))/2\n",
    "    \n",
    "    return abs(a)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "deletable": false,
    "editable": false,
    "nbgrader": {
     "cell_type": "code",
     "checksum": "940773ef0980f1e545e0b29f04d732a9",
     "grade": true,
     "grade_id": "cell-64f8b6708595aed3",
     "locked": true,
     "points": 0,
     "schema_version": 3,
     "solution": false
    }
   },
   "outputs": [],
   "source": [
    "x0, y0 = 0.0, 0.0\n",
    "x1, y1 = 0.0, 2.0\n",
    "x2, y2 = 3.0, 0.0\n",
    "A = area(x0, y0, x1, y1, x2, y2)\n",
    "assert round(A - 3.0, 10) == 0.0"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "default:Python",
   "language": "python",
   "name": "conda-env-default-py"
  },
  "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}