Functions in mathematics

Two examples
1. `f(x) = x^2 - x + 1`
2. `f(-2) = 7`
3. `g(x, y) = x^3 - y^2`
4. `g(-2, 1) = -9`
Line 1 defines the function f; line 3 defines the function g.
In line 2, f is applied to -2; in line 4, g is applied to -2 and 1.
f takes one argument, which must be a number, and returns a number.
g takes two arguments, both of which must be numbers, and returns a number.
In the function definitions, x and y are variables called parameters.
We can compose functions.
`f(g(-2, -1)) = 91`
`f(f(f(2))) = 43`
`g(f(-1), f(-2)) = -22`
`fg(x, y) = f(g(x, y))`
`fg(-2, -1) = 91`

Function definitions in Python

Function definitions look like this:

def f(x):
    return x**2 - x + 1

def g(x, y):
    return x**3 - y**2

The list of parameters must be followed by a colon, and the body of the definition must be indented with respect to the first line (the header).
Evaluating a function definition makes the value of the function name (a variable) the function.
```
>>> def f(x):
	return x**2 - x + 1
>>> f
<function f at 0x114c14f30>
```
These two functions have a return statement, specifying the return value of the function.
We normally save a set of function definitions that we want to use in a file (a module). Running that module evaluates the function definitions so that we can then call them.
Practice
- Define a function that calculates the sigmoid of a number x: `1 / (1 + e^(-x))` Note that `e` is a fundamental constant of mathematics, and raising `e` to the power `x` is also known as the exponential of `x`. This function is found in the math module.
- Define a function that takes a person's name (a string) and a social security number (an integer) and returns a string consisting of the name, followed by ", SS#: ", followed by the number.
- Define a function that takes an integer and returns a random integer between 0 and that number. For this function, you will need to convert a float to an integer. You can do this with the function int, which takes some object and returns the equivalent integer, if this is possible.
- Using the last function, write a function that takes a string s and returns a string consisting of s followed by a random integer between 0 and 99.

Function calls

Calling functions

>>> def f(x):
       return x**2 - x + 1
>>> def g(x, y):
       return x**3 - y**2
>>> f(-2)
7
>>> g(-2, 1)
-9

Evaluating a function call means finding the value that function returns when it is applied to its arguments.
When the function is called, the arguments are first evaluated; then function is applied to those values, according to what is in the body of the function definition.
The arguments in a function call can be any expressions that evaluate to the right type.
```
>>> f(f(f(2)))
43
>>> g(f(-1), f(-2))
-22
```
When we call a function, the function parameters take on the values of the arguments in the function call.
- In the last example, the first argument of g, that is, f(-1), evaluates to 3, and the parameter x in the definition of g gets bound to this value.
- Note that both f and g have parameters called x. This is not a problem because the parameter only has a value during the function call; once the function returns a value the parameters of the function are no longer bound to anything.
Note that in IDLE, you can get the value of the last expression returned with _.

Variations

Functions don't have to return anything. They may be useful instead for their side effects.

def print_name_ss(name, ss):
    print('Name:', name, 'SS#:', ss)
    
>>> print_name_ss('John Brown', 555609843)
Name: John Brown SS#: 555609843

Functions (in Python) can return multiple values.

Separate the things to be returned with commas.

def names2ways(first, middle, last):
    return first + ' ' + middle + ' ' + last, last + ', ' + first + ' ' + middle

>>> names2ways('John', 'Q.', 'Jones')
('John Q. Jones', 'Jones, John Q.')

The values are returned in a tuple, which we'll learn about later. You can access the values in a tuple using brackets and the index of the item you want, starting at 0.
```
>>> jqj = names2ways('John', 'Q.', 'Jones')
>>> jqj[0]
'John Q. Jones'
>>> jqj[1]
'Jones, John Q.'
```

Functions don't have to take any arguments. But we still need the parentheses so Python knows this is a function call.

>>> import random
>>> random.random()
0.62219559535873636
>>> random.random
<built-in method random of Random object at 0x92ae10>

Practice
- Define a function that prints out, rather than returning, a name and SS# as in the function on page 2.
- Define a function that returns a random number between -1 and 0.

Built-in functions

A number of functions are built into Python. You can find them described in the documentation.
We have already seen the function type, which returns the type of its single argument.

Each type (what gets returned by type applied to some object) is also a function. These functions convert their single argument to that type, if this is possible.

>>> int('421')
421
>>> str(421)
'421'
>>> float(421)
421.0
>>> float('spam')

Traceback (most recent call last):
  File "<pyshell#3>", line 1, in 
    float('spam')
ValueError: invalid literal for float(): spam

help (like print) is an example of a function that can take different numbers of arguments.
- With no arguments, help starts up the interactive help system.
- With one string argument, help prints out information about the function, module, etc. that has that name if something does.
input is a function with no arguments that waits for user input and then returns this as a string, once it is entered. (It can also take a string argument, which behaves like a prompt for the user.)
len takes a string (or another kind of sequence) and returns its length.
Practice
- Write a function that returns a name and SS# string but gets both from the user rather than taking them as arguments to the function.
- Write a function that takes first, middle, and last names and prints out the full name and the number of characters in it.
- Write a function that takes a number and a type (int, float, or str) and returns the number converted to that type.

Local variables

When you call a function, the function parameters are bound to the values of the arguments, but these bindings go away once the call is complete.

You may also make variable assignments within the body of a function.

def print_name_info(first, middle, last):
    name = first + ' ' + middle + ' ' + last
    print('Full name:', name, '# characters:', len(name))

Any variable assignment made within a function no longer holds once the function has been called.

>>> print_name_info('John', 'Q.', 'Smith')
Full name: John Q. Smith # characters: 13
>>> name
...
NameError: name 'name' is not defined

Parameters and variables created within the body of a function are local variables.

Practice: functions for agent movement

The agent has x, y coordinates and a current heading. It moves a constant distance in the direction of its heading.
Write a function that takes the x coordinate, step size, and heading and calculates the new x coordinate (as an integer) after a move. (The heading is expressed in degrees. You will have to subtract it from 360 and convert it to radians before doing the trigonometry.)
```
	
>>> move_x(100, 50, 45)
135
>>> move_x(100, 50, 180)
50
>>> move_x(100, 50, 300)
125
```

Miscellany: lines, statements, documentation

Lines and statements

A statement normally takes up a physical line, that is, a string of characters followed by a newline.

But if you have a very long expression, you can split it onto multiple physical lines with one ore more backslashes.

>>> 'Expecting the world to treat you fairly because you are good ' + \
      'is like expecting the bull not to charge because you are a vegetarian.'
'Expecting the world to treat you fairly because you are good is like expecting the bull not to charge because you are a vegetarian.'

And if you have a series of very short statements, you can combine them on a single line, separated by semicolons.
```
>>> input('A number? '); input('Try again? ')
A number? 11
'11'
Try again? no
'no'
```

Documentation
- As you know, you should put comments in your code to remind yourself and others what it is supposed to do. A special form of comment is used as documentation for function definitions.
- A string surrounded by triple quotes can include newlines (without the escape character). The documentation for a function, called its docstring, appears in a triple-quoted string between the header and the body of the function definition.
```
import math

def sigmoid(x):
    """Squash x to a value between 0 and 1."""
    return 1 / (1 + math.exp(-x))

def func_twice(func, arg1, arg2):
    """Print out the result of applying func to arg1 and then arg2."""
    print(func(arg1))
    print(func(arg2))
    
>>> func_twice(sigmoid, 1, 2)
0.73105857863
0.880797077978
```
- Unlike for a comment with "#", Python stores a documentation string so that you can use it in various ways.
  - You are prompted with it in IDLE when you type the open parenthesis for the function.
  - And you can retrieve it with the help function.
```
>>> help(sigmoid)
Help on function sigmoid in module __main__:

sigmoid(x)
    Squash x to a value between 0 and 1.

>>> help(func_twice)
Help on function func_twice in module __main__:

func_twice(func, arg1, arg2)
    Print out the result of applying func to arg1 and then arg2.
```