## Defining Functions in Python

YOU HAVE BEEN COMPOSING CODE THAT calls Python functions since the beginning of this book, from writing strings with stdio.writeln() to using type conversion functions such as str() and int() to computing mathematical functions such as math.sqrt() to using all of the functions in stdio,stddraw, and stdaudio. In this section, you will learn how to define and call your own functions.In mathematics, a function maps an input value of one type (the domain) to an output value of another type (the range). For example, the square function f(x) = x2 maps 2 to 4, 3 to 9, 4 to 16, and so forth. At first, we work with Python functions that implement mathematical functions, because they are so familiar. Many standard mathematical functions are implemented in Python’s math module, but scientists and engineers work with a broad variety of mathematical functions, which cannot all be included in the module. At the beginning of this section, you will learn how to implement and use such functions on your own.Later, you will learn that we can do more with Python functions than implement mathematical functions: Python functions can have strings and other types as their domain or range, and they can have side effects such as writing output. We also consider in this section how to use Python functions to organize programs and thereby simplify complicated programming tasks.From this point forward, we use the generic term function to mean either Python function ormathematical function depending on the context. We use the more specific terminology only when the context requires that we do so.Functions support a key concept that will pervade your approach to programming from this point forward: Whenever you can clearly separate tasks within a computation, you should do so. We will be overemphasizing this point throughout this section and reinforcing it throughout the rest of the chapter (and the rest of the book). When you write an essay, you break it up into paragraphs; when you compose a program, you break it up into functions. Separating a larger task into smaller ones is much more important when programming than when writing an essay, because it greatly facilitates debugging, maintenance, and reuse, which are all critical in developing good software.

## Using and defining functions

As you know from the functions you have been using, the effect of calling a Python function is easy to understand. For example, when you place math.sqrt(a-b) in a program, the effect is as if you had replaced that code with the return value that is produced by Python’s math.sqrt() function when passed the expression a-b as an argument. This usage is so intuitive that we have hardly needed to comment on it. If you think about what the system has to do to create this effect, however, you will see that it involves changing a program’s control flow. The implications of being able to change the control flow in this way are as profound as doing so for conditionals and loops.You can define functions in any Python program, using the def statement that specifies the function signature, followed by a sequence of statements that constitute the function. We will consider the details shortly, but begin with a simple example that illustrates how functions affect control flow. Our first example, PROGRAM 2.1.1 (harmonicf.py), includes a function named harmonic() that takes an argument n and computes the nth harmonic number (see PROGRAM 1.3.5). It also illustrates the typical structure of a Python program, having three components:
• A sequence of import statements
• A sequence of function definitions
• Arbitrary global code, or the body of the program
PROGRAM 2.1.1 has two import statements, one function definition, and four lines of arbitrary global code. Python executes the global code when we invoke the program by typing python harmonicf.pyon the command line; that global code calls the harmonic() function defined earlier.The implementation in harmonicf.py is preferable to our original implementation for computing harmonic numbers (PROGRAM 1.3.5) because it clearly separates the two primary tasks performed by the program: calculating harmonic numbers and interacting with the user. (For purposes of illustration, we have made the user-interaction part of the program a bit more complicated than in PROGRAM 1.3.5.)Whenever you can clearly separate tasks within a computation, you should do so. Next, we carefully examine precisely how harmonicf.py achieves this goal.

### Control flow

The diagram on the next page illustrates the flow of control for the command python harmonicf.py 1 2 3. First, Python processes the import statements, thus making all of the features defined in the sysand stdio modules available to the program. Next, Python processes the definition of the harmonic()function at lines 4 through 8, but does not execute the function—Python executes a function only when it is called. Then, Python executes the first statement in the global code after the function definition, the for statement, which proceeds normally until Python begins to execute the statement value = harmonic(arg), starting by evaluating the expression harmonic(arg) when arg is 1. To do so it transfers control to the harmonic() function—the flow of control passes to the code in the function definition. Python initializes the “parameter” variable n to 1 and the “local” variable total to 0.0 and then executes the for loop within harmonic(), which terminates after one iteration with total equal to 1.0. Then, Python executes the return statement at the end of the definition of harmonic(), causing the flow of control to jump back to the calling statement value = harmonic(arg), continuing from where it left off, but now with the expression harmonic(arg) replaced by 1.0. Thus, Python assigns 1.0 to value and writes it to standard output. Then, Python iterates the loop once more, and calls the harmonic() function a second time with n initialized to 2, which results in 1.5 being written. The process is then repeated a third time with arg (and then n) equal to 4, which results in2.083333333333333 being written. Finally, the for loop terminates and the whole process is complete. As the diagram indicates, the simple code masks a rather intricate flow of control.

#### Program 2.1.1 Harmonic numbers (revisited) (harmonicf.py)

Abbreviation alertWe continue to use the abbreviations that we introduced in SECTION 1.2 for functions and function calls. For example, we might say, “The function call harmonic(2) returns the value 1.5,” instead of the more accurate but verbose “When we pass to harmonic() a reference to an object of typeint whose value is 2, it returns a reference to an object of type float whose value is 1.5.” We strive to use language that is succinct and only as precise as necessary in a given context.

### Informal function call/return trace

One simple approach to following the control flow through function calls is to imagine that each function writes its name and argument(s) when it is called and its return value just before returning, with indentation added on calls and subtracted on returns. The result enhances the process of tracing a program by writing the values of its variables, which we have been using since SECTION 1.2. An informal trace for our example is shown at right. The added indentation exposes the flow of the control, and helps us check that each function has the effect that we expect. Generally, adding calls onstdio.writef() to trace any program’s control flow in this way is a fine approach to begin to understand what it is doing. If the return values match our expectations, we need not trace the function code in detail, saving us a substantial amount of work.FOR THE REST OF THIS CHAPTER, your programming will be centered on creating and using functions, so it is worthwhile to consider in more detail their basic properties and, in particular, the terminology surrounding functions. Following that, we will study several examples of function implementations and applications.

### Basic terminology

As we have been doing throughout, it is useful to draw a distinction between abstract concepts and Python mechanisms to implement them (the Python if statement implements the conditional, thewhile statement implements the loop, and so forth). There are several concepts rolled up in the idea of a mathematical function and there are Python constructs corresponding to each, as summarized in the table at the top of the following page. While you can rest assured that these formalisms have served mathematicians well for centuries (and have served programmers well for decades), we will refrain from considering in detail all of the implications of this correspondence and focus on those that will help you learn to program.When we use a symbolic name in a formula that defines a mathematical function (such as f(x) = 1  x  x2), the symbol x is a placeholder for some input value that will be substituted into the formula to determine the output value. In Python, we use a parameter variable as a symbolic placeholder and we refer to a particular input value where the function is to be evaluated as an argument.conceptPython constructdescriptionfunctionfunctionmappinginput valueargumentinput to functionoutput valuereturn valueoutput of functionformulafunction bodyfunction definitionindependent variableparameter variablesymbolic placeholder for input value

### Function definition

The first line of a function definition, known as its signature, gives a name to the function and to each parameter variable. The signature consists of the keyword def; the function name; a sequence of zero or more parameter variable names separated by commas and enclosed in parentheses; and a colon. The indented statements following the signature define the function body. The function body can consist of the kinds of statements that we discussed in CHAPTER 1. It also can contain a return statement, which transfers control back to the point where the function was called and returns the result of the computation or return value. The body may also define local variables, which are variables that are available only inside the function in which they are defined.

### Function calls

As we have seen throughout, a Python function call is nothing more than the function name followed by its arguments, separated by commas and enclosed in parentheses, in precisely the same form as is customary for mathematical functions. As noted in SECTION 1.2, each argument can be an expression, which is evaluated and the resulting value passed as input to the function. When the function finishes, the return value takes the place of the function call as if it were the value of a variable (perhaps within an expression).

### Multiple arguments

Like a mathematical function, a Python function can have more than one parameter variable, so it can be called with more than one argument. The function signature lists the name of each parameter variable, separated by commas. For example, the following function computes the length of the hypotenuse of a right triangle with sides of length a and b:
```def hypot(a, b)
return math.sqrt(a*a   b*b)```

### Multiple functions

You can define as many functions as you want in a .py file. The functions are independent, except that they may refer to each other through calls. They can appear in any order in the file:
```def square(x):
return x*x

def hypot(a, b):
return math.sqrt(square(a)   square(b))```
However, the definition of a function must appear before any global code that calls it. That is the reason that a typical Python program contains (1) import statements, (2) function definitions, and (3) arbitrary global code, in that order.

### Multiple return statements

You can put return statements in a function wherever you need them: control goes back to the calling program as soon as the first return statement is reached. This primality-testing function is an example of a function that is natural to define using multiple return statements:
```def isPrime(n):
if n < 2: return False
i = 2
while i*i <= n:
if n % i == 0: return False
i  = 1
return True```

### Single return value

A Python function provides only one return value to the caller (or, more precisely, it returns a reference to one object). This policy is not as restrictive as it might seem, because Python data types can contain more information than a single number, boolean, or string. For example, you will see later in this section that you can use arrays as return values.

### Scope

The scope of a variable is the set of statements that can refer to that variable directly. The scope of a function’s local and parameter variables is limited to that function; the scope of a variable defined in global code—known as a global variable—is limited to the .py file containing that variable. Therefore, global code cannot refer to either a function’s local or parameter variables. Nor can one function refer to either the local or parameter variables that are defined in another function. When a function defines a local (or parameter) variable with the same name as a global variable (such as i in PROGRAM 2.1.1), the variable name in the function refers to the local (or parameter) variable, not the global variable.A guiding principle when designing software is to define each variable so that its scope is as small as possible. One of the important reasons that we use functions is so that changes made to one part of a program will not affect an unrelated part of the program. So, while code in a function can refer to global variables, it should not do so: all communication from a caller to a function should take place via the function’s parameter variables, and all communication from a function to its caller should take place via the function’s return value. In SECTION 2.2, we consider a technique for removing most global code, thereby limiting scope and the potential for unexpected interactions.

### Default arguments

A Python function may designate an argument to be optional by specifying a default value for that argument. If you omit an optional argument in a function call, then Python substitutes the default value for that argument. We have already encountered a few examples of this feature. For example,math.log(x, b) returns the base-b logarithm of x. If you omit the second argument, then b defaults tomath.e—that is, math.log(x) returns the natural logarithm of x. It might appear that the mathmodule has two different logarithm functions, but it actually has just one, with an optional argument and a default value.You can specify an optional argument with a default value in a user-defined function by putting an equals sign followed by the default value after the parameter variable in the function signature. You can specify more than one optional argument in a function signature, but all of the optional arguments must follow all of the mandatory arguments.For example, consider the problem of computing the nth generalized harmonic number of order r: Hn, r= 1 1/2r  1/3r  ... 1/nr. For example, H1, 2 = 1, H2, 2 = 5/4, and H2, 2 = 49/36. The generalized harmonic numbers are closely related to the Riemann zeta function from number theory. Note that thenth generalized harmonic number of order r = 1 is equal to the nth harmonic number. Therefore it is appropriate to use 1 as the default value for r if the caller omits the second argument. We specify by writing r=1 in the signature:
```def harmonic(n, r=1):
total = 0.0
for i in range(1, n 1):
total  = 1.0 / (i ** r)
With this definition, harmonic(2, 2) returns 1.25, while both harmonic(2, 1) and harmonic(2)return 1.5. To the client, it appears that we have two different functions, one with a single argument and one with two arguments, but we achieve this effect with a single implementation.

### Side effects

In mathematics, a function maps one or more input values to some output value. In computer programming, many functions fit that same model: they accept one or more arguments, and their only purpose is to return a value. A pure function is a function that, given the same arguments, always return the same value, without producing any observable side effects, such as consuming input, producing output, or otherwise changing the state of the system. So far, in this section we have considered only pure functions.However, in computer programming it is also useful to define functions that do produce side effects. In fact, we often define functions whose only purpose is to produce side effects. An explicit returnstatement is optional in such a function: control returns to the caller after Python executes the function’s last statement. Functions with no specified return value actually return the special valueNone, which is usually ignored.For example, the stdio.write() function has the side effect of writing the given argument to standard output (and has no specified return value). Similarly, the following function has the side effect of drawing a triangle to standard drawing (and has no specified return value):
```def drawTriangle(x0, y0, x1, y1, x2, y2):
stddraw.line(x0, y0, x1, y1)
stddraw.line(x1, y1, x2, y2)
stddraw.line(x2, y2, x0, y0)```
It is generally poor style to compose a function that both produces side effects and returns a value. One notable exception arises in functions that read input. For example, the stdio.readInt() function both returns a value (an integer) and produces a side effect (consuming one integer from standard input).

### Type checking

In mathematics, the definition of a function specifies both the domain and the range. For example, for the harmonic numbers, the domain is the positive integers and the range is the positive real numbers. In Python, we do not specify the types of the parameter variables or the type of the return value. As long as Python can apply all of the operations within a function, Python executes the function and returns a value.If Python cannot apply an operation to a given object because it is of the wrong type, it raises a run-time error to indicate the invalid type. For example, if you call the square() function defined earlier with an int argument, the result is an int; if you call it with a float argument, the result is a float. However, if you call it with a string argument, then Python raises a TypeError at run time.This flexibility is a popular feature of Python (known as polymorphism) because it allows us to define a single function for use with objects of different types. It can also lead to unexpected errors when we call a function with arguments of unanticipated types. In principle, we could include code to check for such errors, and we could carefully specify which types of data each function is supposed to work with. Like most Python programmers, we refrain from doing so. However, in this book, our message is that you should always be aware of the type of your data, and the functions that we consider in this book are built in line with this philosophy, which admittedly clashes with Python’s tendency toward polymorphism. We will discuss this issue in some detail in SECTION 3.3.THE TABLE BELOW SUMMARIZES OUR DISCUSSION by collecting together the function definitions that we have examined so far. To check your understanding, take the time to reread these examples carefully.primality test
```def isPrime(n):
if n < 2: return False
i = 2
while i*i <= n:
if n % i == 0: return False
i  = 1
return True```
hypotenuse of a right triangle
```def hypot(a, b)
return math.sqrt(a*a   b*b)```
generalized harmonic number
```def harmonic(n, r=1):
total = 0.0
for i in range(1, n 1):
total  = 1.0 / (i ** r)
draw a triangle
```def drawTriangle(x0, y0, x1, y1, x2, y2):
stddraw.line(x0, y0, x1, y1)
stddraw.line(x1, y1, x2, y2)
stddraw.line(x2, y2, x0, y0)```
Typical code for implementing functions

## Implementing mathematical functions

Why not just use the Python built-in functions and those that are defined in the standard or extension Python modules? For example, why not use the math.hypot() function instead of defining our ownhypot() function? The answer to this question is that we do use such functions when they are present (because they are likely to be faster and more accurate). However, there is an unlimited number of functions that we may wish to use and only a finite number of functions is defined in the Python standard and extension modules. When you need a function that is not defined in the Python standard or extension modules, you need to define the function yourself.As an example, we consider the kind of code required for a familiar and important application that is of interest to many potential college students in the United States. In a recent year, over 1 million students took the Scholastic Aptitude Test (SAT). The test consists of two major sections: critical reading and mathematics. Scores range from 200 (lowest) to 800 (highest) on each section, so overall test scores range from 400 to 1600. Many universities consider these scores when making important decisions. For example, student athletes are required by the National Collegiate Athletic Association (NCAA), and thus by many universities, to have a combined score of at least 820 (out of 1600), and the minimum eligibility requirement for certain academic scholarships is 1500 (out of 1600). What percentage of test takers is ineligible for athletics? What percentage is eligible for the scholarships?Two functions from statistics enable us to compute accurate answers to these questions. The standard normal (Gaussian) probability density function is characterized by the familiar bell-shaped curve and defined by the formula . The standard normal (Gaussian) cumulative distribution function Φ(z) is defined to be the area under the curve defined by ϕ(x) above the x-axis and to the left of the vertical line x = z. These functions play an important role in science, engineering, and finance because they arise as accurate models throughout the natural world and because they are essential in understanding experimental error. In particular, these functions are known to accurately describe the distribution of test scores in our example, as a function of the mean (average value of the scores) and the standard deviation (square root of the average of the squares of the differences between each score and the mean), which are published each year. Given the mean μ and the standard deviation σ of the test scores, the percentage of students with scores less than a given value z is closely approximated by the function Φ(z, μ, σ) = Φ((z—μ)/σ). Functions to calculate ϕ and Φ are not available in Python’s math module, so we develop our own implementations.

### Closed form

In the simplest situation, we have a closed-form mathematical formula defining our function in terms of functions that are implemented in Python’s math module. This situation is the case for ϕ—the mathmodule includes functions to compute the exponential and the square root functions (and a constant value for π), so a function pdf() corresponding to the mathematical definition is easy to implement. For convenience, gauss.py (PROGRAM 2.1.2) uses the default arguments μ = 0 and σ = 1 and actually computes Φ(x, μ, σ) = Φ((x — μ) / σ) / σ.

### No closed form

If no formula is known, we may need a more complicated algorithm to compute function values. This situation is the case for Φ—no closed-form expression exists for this function. Algorithms to compute function values sometimes follow immediately from Taylor series approximations, but developing reliably accurate implementations of mathematical functions is an art and a science that needs to be addressed carefully, taking advantage of the knowledge built up in mathematics over the past several centuries. Many different approaches have been studied for evaluating Φ. For example, a Taylor series approximation to the ratio of Φ and ϕturns out to be an effective basis for evaluating the function:
• Φ(z) 1/2 ϕ(z) ( z   z3/3  z5/ (3·5)  z7 / (3·5·7) ... ).
This formula readily translates to the Python code for the function cdf() in PROGRAM 2.1.2. For small (respectively large) z, the value is extremely close to 0 (respectively 1), so the code directly returns 0 (respectively 1); otherwise, it uses the Taylor series to add terms until the sum converges. Again, for convenience, PROGRAM 2.1.2 actually computes Φ(z, μ, σ) = Φ((z—μ) / σ), using the defaults μ = 0 and σ = 1.Running gauss.py with the appropriate arguments on the command line tells us that about 17% of the test takers were ineligible for athletics in a year when the mean was 1019 and the standard deviation was 209. In the same year, about 1% percent qualified for academic scholarships.COMPUTING WITH MATHEMATICAL FUNCTIONS OF ALL sorts plays a central role in science and engineering. In a great many applications, the functions that you need are expressed in terms of the functions in Python’s math module, as we have just seen with pdf(), or in terms of a Taylor series approximation or some other formulation that is easy to compute, as we have just seen with cdf(). Indeed, support for such computations has played a central role throughout the evolution of computing systems and programming languages.

## Using functions to organize code

Beyond evaluating mathematical functions, the process of calculating an output value as a function of input values is important as a general technique for organizing control flow in any computation. Doing so is a simple example of an extremely important principle that is a prime guiding force for any good programmer: Whenever you can clearly separate tasks within a computation, you should do so.Functions are natural and universal mechanism for expressing computational tasks. Indeed, the “bird’s-eye view” of a Python program that we began with in SECTION 1.1 was equivalent to a function: we began by thinking of a Python program as a function that transforms command-line arguments into an output string. This view expresses itself at many different levels of computation. In particular, it is generally the case that you can express a long program more naturally in terms of functions instead of as a sequence of Python assignment, conditional, and loop statements. With the ability to define functions, you can better organize your programs by defining functions within them when appropriate.For example, coupon.py (PROGRAM 2.1.3) on the facing page is an improved version ofcouponcollector.py (PROGRAM 1.4.2) that better separates the individual components of the computation. If you study PROGRAM 1.4.2, you will identify three separate tasks:
• Given the number of coupon values n, compute a random coupon value.
• Given n, do the coupon collection experiment.
• Get n from the command line, then compute and write the result.
PROGRAM 2.1.3 rearranges the code to reflect the reality that these three activities underlie the computation. The first two are implemented as functions, the third as global code.With this organization, we could change getCoupon() (for example, we might want to draw the random numbers from a different distribution) or the global code (for example, we might want to take multiple inputs or run multiple experiments) without worrying about the effect of any of these changes oncollect().Using functions isolates the implementation of each component of the collection experiment from others, or encapsulates them. Typically, programs have many independent components, which magnifies the benefits of separating them into different functions. We will discuss these benefits in further detail after we have seen several other examples, but you certainly can appreciate that it is better to express a computation in a program by breaking it up into functions, just as it is better to express an idea in an essay by breaking it up into paragraphs. Whenever you can clearly separate tasks within a computation, you should do so.

## Passing arguments and returning values

Next, we examine the specifics of Python’s mechanisms for passing arguments to and returning values from functions. These mechanisms are conceptually very simple, but it is worthwhile to take the time to understand them fully, as the effects are actually profound. Understanding argument-passing and return-value mechanisms is key to learning any new programming language. In the case of Python, the concepts of immutability and aliasing play a central role.

### Call by object reference

You can use parameter variables anywhere in the body of the function in the same way as you use local variables. The only difference between a parameter variable and a local variable is that Python initializes the parameter variable with the corresponding argument provided by the calling code. We refer to this approach as call by object reference. (It is more commonly known as call by value, where the value is always an object reference—not the object’s value.) One consequence of this approach is that if a parameter variable refers to a mutable object and you change that object’s value within a function, then this also changes the object’s value in the calling code (because it is the same object). Next, we explore the ramifications of this approach.

### Immutability and aliasing

As discussed in SECTION 1.4, arrays are mutable data types, because we can change array elements. By contrast, a data type is immutable if it is not possible to change the value of an object of that type. The other data types that we have been using (int, float, str, and bool) are all immutable. In an immutable data type, operations that might seem to change a value actually result in the creation of a new object, as illustrated in the simple example at right. First, the statement i = 99 creates an integer99, and assigns to i a reference to that integer. Then j = i assigns i (an object reference) to j, so both i and j reference the same object—the integer 99. Two variables that reference the same objects are said to be aliases. Next, j = 1 results in j referencing an object with value 100, but it does not do so by changing the value of the existing integer from 99 to 100! Indeed, since int objects are immutable, no statement can change the value of that existing integer. Instead, that statement creates a new integer 1, adds it to the integer 99 to create another new integer 100, and assigns to j a reference to that integer. But i still references the original 99. Note that the new integer 1 has no reference to it in the end—that is the system’s concern, not ours. The immutability of integers, floats, strings, and booleans is a fundamental aspect of Python. We will consider the advantages and disadvantages of this approach in more detail in SECTION 3.3.

### Integers, floats, booleans, and strings as arguments

The key point to remember about passing arguments to functions in Python is that whenever you pass arguments to a function, the arguments and the function’s parameter variables become aliases. In practice, this is the predominant use of aliasing in Python, and it is important to understand its effects. For purposes of illustration, suppose that we need a function that increments an integer (our discussion applies to any more complicated function as well). A programmer new to Python might try this definition:
```def inc(j):
j  = 1```
and then expect to increment an integer i with the call inc(i). Code like this would work in some programming languages, but it has no effect in Python, as shown in the figure at right. First, the statement i = 99 assigns to global variable i a reference to the integer 99. Then, the statementinc(i) passes i, an object reference, to the inc() function. That object reference is assigned to the parameter variable j. At this point i and j are aliases. As before, the inc() function’s j = 1statement does not change the integer 99, but rather creates a new integer 100 and assigns a reference to that integer to j. But when the inc() function returns to its caller, its parameter variable jgoes out of scope, and the variable i still references the integer 99.
This example illustrates that, in Python, a function cannot produce the side effect of changing the value of an integer object (nothing can do so). To increment variable i, we could use the definition
```def inc(j):
j  = 1
return j```
and call the function with the assignment statement i = inc(i).The same holds true for any immutable type. A function cannot change the value of an integer, a float, a boolean, or a string.

### Arrays as arguments

When a function takes an array as an argument, it implements a function that operates on an arbitrary number of objects. For example, the following function computes the mean (average) of an array of floats or integers:
```def mean(a):
total = 0.0
for v in a:
total  = v
We have been using arrays as arguments from the beginning of the book. For example, by convention, Python collects the strings that you type after the program name in the python command into an arraysys.argv[] and implicitly calls your global code with that array of strings as the argument.

### Side effects with arrays

Since arrays are mutable, it is often the case that the purpose of a function that takes an array as argument is to produce a side effect (such as changing the order of array elements). A prototypical example of such a function is one that exchanges the elements at two given indices in a given array. We can adapt the code that we examined at the beginning of SECTION 1.4:
```def exchange(a, i, j):
temp = a[i]
a[i] = a[j]
a[j] = temp```
This implementation stems naturally from the Python array representation. The first parameter variable in exchange() is a reference to the array, not to all of the array’s elements: when you pass an array as an argument to a function, you are giving it the opportunity to operate on that array (not a copy of it). A formal trace of a call on this function is shown on the facing page. This diagram is worthy of careful study to check your understanding of Python’s function-call mechanism.A second prototypical example of a function that takes an array argument and produces side effects is one that randomly shuffles the elements in the array, using this version of the algorithm that we examined in SECTION 1.4 (and the exchange() function just defined):
```def shuffle(a):
n = len(a)
for i in range(n):
r = random.randrange(i, n)
exchange(a, i, r)```
Incidentally, Python’s standard function random.shuffle() does the same task. As another example, we will consider in SECTION 4.2 functions that sort an array (rearrange its elements so that they are in order).

### Arrays as return values

A function that sorts, shuffles, or otherwise modifies an array taken as argument does not have to return a reference to that array, because it is changing the contents of a client array, not a copy. But there are many situations where it is useful for a function to provide an array as a return value. Chief among these are functions that create arrays for the purpose of returning multiple objects of the same type to a client.As an example, consider the following function, which returns an array of random floats:
```def randomarray(n):
a = stdarray.create1D(n)
for i in range(n):
a[i] = random.random()
return a```
Later in this chapter, we will be developing numerous functions that return huge amounts of data in this way.THE TABLE BELOW CONCLUDES OUR DISCUSSION of arrays as function arguments by highlighting some typical array-procession functions.mean of an array
```def mean(a):
total = 0.0
for v in a:
total  = v
dot product of two vectors of the same length
```def dot(a, b):
total = 0
for i in range(len(a)):
total  = a[i] * b[i]
exchange two elements in an array
```def exchange(a, i, j):
temp = a[i]
a[i] = a[j]
a[j] = temp```
write a one-dimensional array (and its length)
```def write1D(a):
stdio.writeln(len(a))
for v in a:
stdio.writeln(v)```
read a two-dimensional array of floats (with dimensions)
```def readFloat2D():
a = stdarray.create2D(m, n, 0.0)
for i in range(m):
for j in range(n):
return a```
Typical code for implementing functions with arrays

## Example: superposition of sound waves

As discussed in SECTION 1.5, the simple audio model that we studied there needs to be embellished to create sound that resembles the sound produced by a musical instrument. Many different embellishments are possible; with functions, we can systematically apply them to produce sound waves that are far more complicated than the simple sine waves that we produced in SECTION 1.5. As an illustration of the effective use of functions to solve an interesting computational problem, we consider a program that has essentially the same functionality as playthattune.py (PROGRAM 1.5.8), but adds harmonic tones one octave above and one octave below each note to produce a more realistic sound.

### Chords and harmonics

Notes like concert A have a pure sound that is not very musical, because the sounds that you are accustomed to hearing have many other components. The sound from a guitar string echoes off the wooden part of the instrument, the walls of the room that you are in, and so forth. You may think of such effects as modifying the basic sine wave. For example, most musical instruments produceharmonics (the same note in different octaves and not as loud), or you might play chords (multiple notes at the same time). To combine multiple sounds, we use superposition: simply add their waves together and rescale to make sure that all values stay between −1 and 1. As it turns out, when we superpose sine waves of different frequencies in this way, we can get arbitrarily complicated waves. Indeed, one of the triumphs of 19th-century mathematics was the development of the idea that any smooth periodic function can be expressed as a sum of sine and cosine waves, known as a Fourier series. This mathematical idea corresponds to the notion that we can create a large range of sounds with musical instruments or our vocal cords and that all sound consists of a composition of various oscillating curves. Any sound corresponds to a curve and any curve corresponds to a sound, so we can create arbitrarily complex curves with superposition.

### Computing with sound waves

In SECTION 1.5, we saw how to represent sound waves by arrays of numbers that represent their values at the same sample points. Now, we will use such arrays as return values and arguments to functions to process such data. For example, the following function takes a frequency (in hertz) and a duration (in seconds) as arguments and returns a representation of a sound wave (more precisely, an array that contains values sampled from the specified wave at the standard 44,100 samples per second).
```def tone(hz, duration, sps=44100):
n = int(sps * duration)
a = stdarray.create1D(n 1, 0.0)
for i in range(n 1):
a[i] = math.sin(2.0 * math.pi * i * hz / sps)
return a```
The size of the array returned depends on the duration: it contains about sps*duration floats (nearly half a million floats for 10 seconds). But we can now treat that array (the value returned from tone) as a single entity and compose code that processes sound waves, as we will soon see in PROGRAM 2.1.4.

### Weighted superposition

Since we represent sound waves by arrays of numbers that represent their values at the same sample points, superposition is simple to implement: we add together their sample values at each sample point to produce the combined result. For greater control, we also specify a relative weight for each of the two waves to be superposed, with the following function:
```def superpose(a, b, aWeight, bWeight):
c = stdarray.create1D(len(a), 0.0)
for i in range(len(a)):
c[i] = aWeight*a[i]   bWeight*b[i]
return c```
(This code assumes that a[] and b[] are of the same length.) For example, if we have a sound represented by an array a[] that we want to have three times the effect of the sound represented by an array b[], we would call superpose(a, b, 0.75, 0.25). The figure at the top of the next page shows the use of two calls on this function to add harmonics to a tone (we superpose the harmonics, then superpose the result with the original tone, which has the effect of giving the original tone twice the weight of each harmonic). As long as the weights are positive and sum to 1, superpose()preserves our convention of keeping the values of all waves between −1 and 1.PROGRAM 2.1.4 (playthattunedeluxe.py) is an implementation that applies these concepts to produce a more realistic sound than that produced by PROGRAM 1.5.8. To do so, it makes use of functions to divide the computation into four parts:
• Given a frequency and duration, create a pure tone.
• Given two sound waves and relative weights, superpose them.
• Given a pitch and duration, create a note with harmonics.
• Read and play a sequence of pitch/duration pairs from standard input.

#### Program 2.1.4 Play that tune (revisited) (playthattunedeluxe.py)

These tasks are all amenable to implementation as functions, which depend on one another. Each function is well defined and straightforward to implement. All of them (and stdaudio) represent sound as a series of discrete values kept in an array, corresponding to sampling a sound wave at 44,100 samples per second.Up to this point, our use of functions has been somewhat of a notational convenience. For example, the control flow in PROGRAM 2.1.1, PROGRAM 2.1.2, and PROGRAM 2.1.3 is simple—each function is called in just one place in the code. By contrast, PROGRAM 2.1.4 is a convincing example of the effectiveness of defining functions to organize a computation because each function is called multiple times. For example, as illustrated in the figure below, the function note() calls the function tone() three times and the function superpose() twice. Without functions, we would need multiple copies of the code intone() and superpose(); with functions, we can deal directly with concepts close to the application. Like loops, functions have a simple but profound effect: one sequence of statements (those in the function definition) is executed multiple times during the execution of our program—once for each time the function is called in the control flow in the global code.FUNCTIONS ARE IMPORTANT BECAUSE THEY GIVE us the ability to extend the Python language within a program. Having implemented and debugged functions such as harmonic(), pdf(), cdf(), mean(),exchange(), shuffle(), isPrime(), superpose(), tone(), and note(), we can use them almost as if they were built into Python. The flexibility to do so opens up a whole new world of programming. Before, you were safe in thinking about a Python program as a sequence of statements. Now you need to think of a Python program as a set of functions that can call one another. The statement-to-statement control flow to which you have been accustomed is still present within functions, but programs have a higher-level control flow defined by function calls and returns. This ability enables you to think in terms of operations called for by the application, not just the operations that are built into Python.Whenever you can clearly separate tasks within a computation, you should do so. The examples in this section (and the programs throughout the rest of the book) clearly illustrate the benefits of adhering to this maxim. With functions, we can
• Divide a long sequence of statements into independent parts.
• Reuse code without having to copy it.
• Work with higher-level concepts (such as sound waves).
This point of view leads to code that is easier to understand, maintain, and debug compared to a long program composed solely of Python assignment, conditional, and loop statements. In the next section, we discuss the idea of using functions defined in other files, which again takes us to another level of programming.