{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Calling Functions\n",
    "\n",
    "Python is capable of more than just simple arithmetic, of course. It provides many **functions** for performing other operations, like finding the absolute value of a number to computing the cosine of an angle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function Call Expressions\n",
    "\n",
    "A **function** is a named piece of code that takes in zero or more inputs called **arguments** and (usually) returns something as output. One of Python's simplest functions is called `abs`. Unsurprisingly, it computes the absolute value of the number it is given as input. We can evaluate a function by writing its name, followed by the arguments inside parenthesis, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "abs(-42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function call is an expression, meaning that it it evaluates to a value. Since it is an expression, we can store the result in a variable, as usual:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_lucky_number = abs(-7)\n",
    "my_lucky_number"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The arguments can be expressions themselves, meaning that things like this work:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 4\n",
    "abs(2*x - 12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And since function calls are expressions, they can be combined with other function calls:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "abs(-4) + abs(-2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multiple Arguments\n",
    "\n",
    "Some functions take more than one argument. `round`, for instance, takes in a (decimal) number as well as the number of decimal places to round to. When we call a function with more than one argument, we separate the arguments with a comma:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "round(3.14159, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "round(3.14159, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose we want to round a number like 721 to then tens' place, so that it becomes 720. How do we do this with `round`? To get a hint, we can ask Python for help:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(round)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```{margin}\n",
    "\n",
    "You might have noticed that `help` is itself a function. It accepts as its argument *another function*, and prints a help message.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This helpful message tells us that the second argument (which is here called `ndigits`) may be negative. What happens if we try that?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "round(721, -1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "round(721, -2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Tip**\n",
    "\n",
    "A big part of learning to program is experimenting with code to see what does (and doesn't) work. Luckily, Jupyter notebooks make this easy!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Jupyter Tip**\n",
    "\n",
    "Another way to see a function's help message in a Jupyter notebook is to write the function name, followed by `?`. For instance, to see the documentation for the `round` function, write\n",
    "\n",
    "    round?\n",
    "    \n",
    "by itself in a code cell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing\n",
    "\n",
    "Suppose we need to calculate the base-2 logarithm of a number. Since `abs` finds the absolute value, and `round` rounds, we might expect `log` to find the logarithm. Let's try:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [],
   "source": [
    "log(1024)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Uh oh, we get a `NameError`. This is Python's way of saying that the name we are referring to -- in this case, `log` -- isn't defined, meaning that the kernel doesn't know of such a name.\n",
    "\n",
    "It turns out that finding the logarithm isn't popular enough to necessitate a **built-in** function. A built-in function is a function that is available by default in Python. But Python provides many more functions in what are called **modules**. Python comes with plenty of modules, but they are not loaded by default. Instead, we must **import** them.\n",
    "\n",
    "For example, Python provides a whole variety of mathematical functions in the `math` module (you can see all of them in the [Python documentation](https://docs.python.org/3/library/math.html)). To import the math module, we write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can use the various functions within the module. From looking at the Python documentation, we see that there is a function named `log2` that supposedly calculates the base-2 logarithm of a number. Let's try it out. To call a function in a module, we must preface the function's name with the module name followed by a dot, like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "math.log2(1024)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The math module has many other useful functions, like `math.sin` for computing the sine of an angle, and `math.comb` which will \"Return the number of ways to choose k items from n items without repetition and without order.\" The math module also contains variables, like `math.pi`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "math.pi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example\n",
    "\n",
    "We saw in the previous section that the number of seconds in a year is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "seconds_in_a_year = 60 * 60 * 24 * 365\n",
    "seconds_in_a_year"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It turns out that an easy approximation to the number of seconds in a year is $\\pi \\times 10^7$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "approximation = math.pi * 10**7\n",
    "approximation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How far away is the approximation from the true answer?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "abs(approximation - seconds_in_a_year)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It appears to be about 120,000 seconds off."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Question**:\n",
    " How many days is 120,073 seconds? Write some code to calculate the answer and round it to two decimal places.\n",
    "\n",
    "<details><summary><b>Answer</b>:</summary>`round(120_073 / (60 * 60 * 24), 2)`, which evaluates to 1.39 days.</details>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}