05 Library functions.ipynb

{
  "cells": [
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# Introduction\n\nA feature of modern programming languages is an extensive library of standard functions. This means that we can make use of standard, well-tested and optimised functions\nfor performing common tasks rather than writing our own. This makes our programs shorter and of higher quality, and in most cases faster.\n\n\n\n## Objectives\n\n- Introduce use of standard library functions\n- Importing and using modules\n- Introduction to namespaces\n- Print formatting of floats"
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# The standard library\n\nYou have already used some standard library types and functions. In previous activities we have used built-in types like `string` and `float`, and the function `abs` for absolute value. We have made use of the standard library function `print` to display to the screen.\n\nPython has a large standard library. To organise it, most functionality is arranged into 'modules', with each module providing a range of related functions. Before you program a function, check if there is a library function that can perform the task. The Python standard library is documented at https://docs.python.org/3/library/.\nSearch engines are a good way to find library functions, e.g. entering \"Is there a Python function to compute the hyperbolic tangent of a complex number\" into a search engine will take you to the function `cmath.tanh`. Try this link: http://bfy.tw/7aMc."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# Other libraries\n\nThe standard library tools are general purpose and will be available in any Python environment.\nSpecialised tools are usually made available in other libraries (modules). There is a huge range of Python libraries available for specialised problems. We have already used some parts\nof NumPy (http://www.numpy.org/), which is a specialised library for numerical computation. \nIt provides much the same functionality as MATLAB. \n\nThe simplest way to install a non-standard library is using the command `pip`. From the command line, the library NumPy is installed using:\n\n    pip install numpy\n    \nand from inside a Jupyter notebook use:\n\n    !pip install numpy\n\nNumPy is so commonly used it is probably already installed on computers you will be using.\nYou will see `pip` being used in some later notebooks to install special-purpose tools.\n\nWhen developing programs outside of learning exercises,\nif there is a no standard library module for a problem you are trying to solve, \nsearch online for a module before implementing your own."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# Using library functions: `math` example\n\nTo use a function from a module we need to make it available in our program. \nThis is called 'importing'. We have done this in previous notebooks with the `math` module, but without explanation. The process is explained below.\n\nThe `math` module (https://docs.python.org/3/library/math.html) provides a wide range of mathematical functions. For example, to compute the square root of a number, we do:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "import math\n\nx = 2.0\nx = math.sqrt(x)\nprint(x)",
      "execution_count": 1,
      "outputs": [
        {
          "output_type": "stream",
          "text": "1.4142135623730951\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "Dissecting the above code block, the line \n```python\nimport math \n```\nmakes the math module available in our program. It is good style to put all `import` statements at the top of a file (or at the top of a cell when using a Jupyter notebook). \n\nThe function call\n```python\nx = math.sqrt(x)\n```    \nsays 'use the `sqrt` function from the `math` module to compute the square root'.\n\nBy prefixing `sqrt` with `math`, we are using a *namespace* (which in this case is `math`).\nThis makes clear precisely which `sqrt` function we want to use - there could be more than one `sqrt` function available.\n\n> *Namespaces:* The prefix '`math`' indicates which '`sqrt`' function we want to use. This\nmight seem pedantic, but in practice there are often different algorithms for performing the same or similar  operation. They might vary in speed and accuracy. In some applications we might need an accurate (but slow)  method for computing the square root, while for other applications we might need speed with a compromise on accuracy. But, if two functions have the same name and are not distinguished by a name space, we have a *name clash*.\n\n> In a large program, two developers might choose the same name for two functions that perform similar but slightly different tasks. If these functions are in different modules, there will be no name clash since the module name provides a 'namespace'  - a prefix that provides a distinction between the two functions. Namespaces are extremely helpful for multi-author programs. A weakness of older languages, like C and Fortran, is that they do not support namespaces. Most modern languages do support namespaces.  \n\nWe can import specific functions from a module, e.g. importing only the `sqrt` function:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "from math import sqrt\n\nx = 2.0\nx = sqrt(x)\nprint(x)",
      "execution_count": 2,
      "outputs": [
        {
          "output_type": "stream",
          "text": "1.4142135623730951\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "This way, we are importing (making available) only the `sqrt` function from the `math` module (the `math` module has a large number of functions).\n\nWe can even choose to re-name functions that we import:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "from math import sqrt as some_math_function \n\nx = 2.0\nx = some_math_function(x)\nprint(x)",
      "execution_count": 3,
      "outputs": [
        {
          "output_type": "stream",
          "text": "1.4142135623730951\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "Renaming functions at import can be helpful to keep code short, and we will see below it can be useful for switching between different functions.\nHowever the above choice of name is very poor practice - the name '`some_math_function`' is not descriptive.\nBelow is a more sensible example."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "Say we program a function that computes the roots of a quadratic function using the quadratic formula:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "from math import sqrt as square_root\n\ndef compute_roots(a, b, c):\n    \"Compute roots of the polynomial f(x) = ax^2 + bx + c\"\n    \n    root0 = (-b + square_root(b*b - 4*a*c))/(2*a)\n    root1 = (-b - square_root(b*b - 4*a*c))/(2*a)\n    \n    return root0, root1\n\n# Compute roots of f = 4x^2 + 10x + 1\nroot0, root1 = compute_roots(4, 10, 1)\nprint(root0, root1)",
      "execution_count": 4,
      "outputs": [
        {
          "output_type": "stream",
          "text": "-0.10435607626104004 -2.3956439237389597\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "The above is fine as long as the polynomial has real roots. However, the function `math.sqrt` \nwill give an error (technically, it will 'raise an exception') if a negative argument is passed to it. This is to stop naive programmers from making silly mistakes.\n\nWe do know about complex numbers, so we want to compute complex roots. The Python module `cmath` provides functions for complex numbers. If we were to use `cmath.sqrt` to compute the square root, our function would support complex roots. We do this by importing the `cmath.sqrt` functions as `square_root`:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "# Use the function from cmath as square_root to compute the square root\n# (this will replace the previously imported sqrt function)\nfrom cmath import sqrt as square_root\n\n# Compute roots (roots will be complex in this case)\nroot0, root1 = compute_roots(40, 10, 1)\nprint(root0, root1)\n\n# Compute roots (roots will be real in this case, but cmath.sqrt always returns a complex type)\nroot0, root1 = compute_roots(4, 10, 1)\nprint(root0, root1)",
      "execution_count": 5,
      "outputs": [
        {
          "output_type": "stream",
          "text": "(-0.125+0.09682458365518543j) (-0.125-0.09682458365518543j)\n(-0.10435607626104004+0j) (-2.3956439237389597+0j)\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "The function now works for all cases because `square_root` is now using `cmath.sqrt`. Note that `cmath.sqrt` always returns a complex number type, even when the complex part is zero."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# String functions and string formatting\n\nA standard function that we have used since the beginning is '`print`'. This function turns arguments into a string and displays the string to the screen. So far, we have only printed simple variables and relied mostly on the default conversions to a string for printing to the screen (the exception was printing the floating point representation of 0.1, where we needed to specify the number of significant digits to see the inexact representation in binary)."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "## Formatting\n\nWe can control how strings are formatted and displayed. Below is an example of inserting a string variable and a number variable into a string of characters:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "# Format a string with name and age\nname = \"Amber\"\nage = 19\ntext_string = \"My name is {} and I am {} years old.\".format(name, age)\n\n# Print to screen \nprint(text_string)\n\n# Short-cut for printing without assignment\nname = \"Ashley\"\nage = 21\nprint(\"My name is {} and I am {} years old.\".format(name, age))",
      "execution_count": 6,
      "outputs": [
        {
          "output_type": "stream",
          "text": "My name is Amber and I am 19 years old.\nMy name is Ashley and I am 21 years old.\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "For floating-point numbers, we often want to control the formatting, and in particular the number of significant figures displayed. Using the display of $\\pi$ as an example: "
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "# Import math module to get access to math.pi\nimport math\n\n# Default formatting\nprint(\"The value of π using the default formatting is: {}\".format(math.pi))\n\n# Control number of significant figures in formatting\nprint(\"The value of π to 5 significant figures is: {:.5}\".format(math.pi))\nprint(\"The value of π to 8 significant figures is: {:.8}\".format(math.pi))\nprint(\"The value of π to 20 significant figures and using scientific notation is: {:.20e}\".format(math.pi))",
      "execution_count": 7,
      "outputs": [
        {
          "output_type": "stream",
          "text": "The value of π using the default formatting is: 3.141592653589793\nThe value of π to 5 significant figures is: 3.1416\nThe value of π to 8 significant figures is: 3.1415927\nThe value of π to 20 significant figures and using scientific notation is: 3.14159265358979311600e+00\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "There are many more ways in which float formatting can be controlled - search online if you want to format a float in a particular way.  "
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# Module example: parallel processing\n\nStandard modules can make very technical problems simpler. An example is parallel processing.\n\nThe majority of CPUs - from phones to supercomputers - now have CPUs with multiple cores, with each core performing computations. To benefit from the multiple cores, we need to compute in *parallel*.\nA 'standard' program performs tasks in order, and in this case only one core will be utilised and the rest will\nremain idle. To get the best performance from the hardware, we need to compute in parallel. That is, we perform multiple tasks at the same time. \n\nParallel processing is an enormous topic on its own, but we can touch upon it here because we have standard libraries\nthat make it easy to use. Managing parallel tasks at a low-level is extremely technical, but standard libraries can make it easy. We will use the `multiprocessing` module, and use it to sort lists of numbers concurrently.\n\nWe start by looking at how to generate a list of random integers using the `random` module. The following code \ncreates a list (more on lists in the following notebook) of 10 random integers in the range 0 to 100 (not including 100):"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "import random\nx = random.sample(range(0, 100), 10)\nprint(x)",
      "execution_count": 8,
      "outputs": [
        {
          "output_type": "stream",
          "text": "[0, 55, 44, 85, 86, 94, 96, 72, 27, 43]\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "To create a sorted list, we used the built-in function `sorted`:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "y = sorted(x)\nprint(y)",
      "execution_count": 9,
      "outputs": [
        {
          "output_type": "stream",
          "text": "[0, 27, 43, 44, 55, 72, 85, 86, 94, 96]\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "Now, if we need to sort multiple different lists, we could sort the lists one after the other, or \nwe could sort several lists at the same time (in parallel). Our operating system will then manage the dispatch \nof the sorting task to different processor cores. Before seeing how to do this, we implement a function to perform the sorting:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "import multiprocessing\nimport random\n\ndef mysort(N):\n    \"Create a list of random numbers of length N, and return a sorted list\"\n\n    # Create random list \n    x = random.sample(range(0, N), N) \n\n    # Print process identifier (just out of interest)\n    print(\"Process id: {}\".format(multiprocessing.current_process()))\n    \n    # Return sorted list of numbers\n    return sorted(x)",
      "execution_count": 10,
      "outputs": []
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "To create the sorted lists, making available three processes (threads), we use:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "N = 20000\nwith multiprocessing.Pool(processes=3) as p:\n    p.map(mysort, [N, N, N])  # Call function mysort three times",
      "execution_count": 11,
      "outputs": [
        {
          "output_type": "stream",
          "text": "Process id: <ForkProcess(ForkPoolWorker-3, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-2, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-1, started daemon)>\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "We see from the output that three different processes have worked on our problem - one for each sorting task.\n\nWe use parallel processing the make computations faster. Let's time our computation using different numbers\nof processes to see how it affects performance. \nTo perform the timing, we first encapsulate our problem in a function:"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "def parallel_sort(N, num_proc):\n    \"Create three lists of random numbers (each of length N) using num_proc processes\"\n    with multiprocessing.Pool(processes=num_proc) as p:\n        p.map(mysort, [N, N, N])",
      "execution_count": 12,
      "outputs": []
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "Using the magic command '[`%time`](Notebook%20tips.ipynb#Simple-timing)', we time the sorting using just one process (the one process sorts the lists one after the other):"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "N = 500000\n%time parallel_sort(N, 1)    ",
      "execution_count": 13,
      "outputs": [
        {
          "output_type": "stream",
          "text": "Process id: <ForkProcess(ForkPoolWorker-4, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-4, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-4, started daemon)>\nCPU times: user 43.2 ms, sys: 423 ms, total: 466 ms\nWall time: 3.77 s\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "We see from '`Process id`' that the same process worked on all three lists.\n\nWe now try with up to 4 processes (there are only three lists to sort, so only three will be used):"
    },
    {
      "metadata": {
        "trusted": true
      },
      "cell_type": "code",
      "source": "%time parallel_sort(N, 4)    ",
      "execution_count": 14,
      "outputs": [
        {
          "output_type": "stream",
          "text": "Process id: <ForkProcess(ForkPoolWorker-8, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-5, started daemon)>\nProcess id: <ForkProcess(ForkPoolWorker-6, started daemon)>\nCPU times: user 122 ms, sys: 96.7 ms, total: 219 ms\nWall time: 1.84 s\n",
          "name": "stdout"
        }
      ]
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "We see from `Process id` that three different processes have worked on the lists. The parallel execution should be faster (this will depend on the hardware)."
    },
    {
      "metadata": {},
      "cell_type": "markdown",
      "source": "# Exercises\n\nComplete now the [05 Exercises](Exercises/05%20Exercises.ipynb) notebook."
    }
  ],
  "metadata": {
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3",
      "language": "python"
    },
    "language_info": {
      "mimetype": "text/x-python",
      "nbconvert_exporter": "python",
      "name": "python",
      "pygments_lexer": "ipython3",
      "version": "3.5.4",
      "file_extension": ".py",
      "codemirror_mode": {
        "version": 3,
        "name": "ipython"
      }
    }
  },
  "nbformat": 4,
  "nbformat_minor": 1
}