Functions and the Stopwatch

5.1A function is a named piece of work

Up to now, changing n meant editing the code and running it again. A function lets you say "do that job, with this input" as many times as you like.

def sum_to(n):
    total = 0
    for number in range(1, n + 1):
        total = total + number
    return total

print(sum_to(10))
print(sum_to(1000))

Three parts, and each has a job:

• def sum_to(n): — the name and the parameter it expects.
• the indented block — the work, which can use n as if it were a variable.
• return total — hand the answer back. Without it, the function gives back None, which is the most common cause of "why is my result empty?"

A useful picture: a function is a recipe card. Writing the card teaches the kitchen a dish; it does not cook anything. You only get food when someone reads the card and follows it — that is a call. The parameter n is the blank on the card that says "however many portions you asked for", filled in fresh each time the card is used.

5.2The stopwatch

Python's time module has a high-resolution clock. Read it before, read it after, subtract.

import time

start = time.perf_counter()
result = sum_to(1000000)
elapsed = time.perf_counter() - start

print(f"result {result}, took {elapsed:.4f} seconds")

Your number will differ from mine, and from your own number thirty seconds from now. That is not a flaw in the method — it is the first thing you have to learn to handle.

5.3One measurement is not a measurement

Your computer is doing dozens of other things while it runs your loop. Time the same call five times and you will get five different answers:

import time

def time_it(func, n, repeats=5):
    """Run func(n) several times, return the fastest time in seconds."""
    best = None
    for _ in range(repeats):
        start = time.perf_counter()
        func(n)
        elapsed = time.perf_counter() - start
        if best is None or elapsed < best:
            best = elapsed
    return best

print(f"{time_it(sum_to, 1000000):.4f} s")

This little time_it is the harness the whole course leans on. Every week from here on hands it a function and a size and reads back a trustworthy number, so it is worth understanding line by line now.

Why the fastest run and not the average? Because interference only ever makes code slower. The quickest run is the one that got the least interrupted — the closest thing to the true cost. (Averages are fine too, as long as you say which you used.)

5.4Your first benchmark table

Now the pattern that every remaining week of this course uses. Same function, several sizes, one table:

sizes = [100000, 200000, 400000, 800000]

print(f"{'n':>10} {'seconds':>12} {'ratio':>8}")
previous = None
for n in sizes:
    t = time_it(sum_to, n)
    ratio = t / previous if previous else 1.0
    print(f"{n:>10} {t:>12.5f} {ratio:>8.2f}")
    previous = t

Read the ratio column, not the seconds column. The seconds depend on your laptop; the ratio is a property of the algorithm. Double the input, double the time: this function's cost grows in a straight line. Next week you will use that column to identify every growth pattern in the course.

5.5Two functions, one job

There is a closed-form formula for the same sum: n(n+1)/2. Same answer, different method:

def sum_formula(n):
    return n * (n + 1) // 2

for n in [1000, 100000, 10000000]:
    a = time_it(sum_to, n)
    b = time_it(sum_formula, n)
    print(f"n={n:>9}  loop {a:.6f}s   formula {b:.9f}s   x{a/b:,.0f} faster")

Look at the formula column: it barely moves. The loop's time grows with n; the formula's does not grow at all. And notice the last column growing too — the gap between the two methods widens with the data. That is the thing this course teaches you to see coming, before you write the slow one.

5.6Going deeper: warm-up, resolution and timeit

You have a working stopwatch. Three refinements separate a rough timing from one you would stake a grade — or a production decision — on.

The first run is a little lie

Time the same call five times in a row and watch the very first number:

import time

data = list(range(1000000))          # built once, before timing

for run in range(5):
    start = time.perf_counter()
    total = sum(data)
    print(f"run {run}: {time.perf_counter() - start:.5f} s")

The first run is reliably slower. It pays one-off costs the others do not: the CPU's cache is cold, memory is allocated fresh, and Python may still be settling. That first run is called a warm-up, and serious benchmarks throw it away.

How fine is the ruler?

A stopwatch that ticks in whole seconds cannot measure a 3-millisecond event. Every clock has a smallest step it can see, its resolution. Ask Python what yours is:

import time

info = time.get_clock_info("perf_counter")
print("resolution:", info.resolution, "seconds")
print("monotonic:", info.monotonic)

A nanosecond sounds plenty fine, and the raw clock is. But the practical floor is much higher: the overhead of calling a Python function and reading the clock twice is itself hundreds of nanoseconds, and that is your real smallest trustworthy interval. This is the arithmetic behind the rule from §5.3 — if a run lasts only a few times the smallest step you can measure, the trailing digits are decoration. Grow n until the time is a comfortable multiple of the resolution. (monotonic: True confirms the clock only ever moves forwards, which is why a difference can never come out negative.)

Let the standard library do it: timeit

For a very fast snippet — a single arithmetic expression, a one-line call — perf_counter around one call measures mostly its own overhead. The timeit module exists for exactly this: it runs the snippet many times, reports the total, and turns off the garbage collector during timing to remove one source of noise.

import timeit

# run sum_to(1000) ten thousand times, get the total, divide back
total = timeit.timeit("sum_to(1000)", globals=globals(), number=10000)
per_call = total / 10000
print(f"{per_call * 1e6:.2f} microseconds per call")

Use the right tool for the scale. For the tiny, use timeit; for the doubling experiments in the rest of the course — where each input size takes tens of milliseconds and you want its own number and a ratio — the time_it harness is the better fit. Both read the same underlying perf_counter; they just package it differently.

Why noise is a percentage, not an amount

When the operating system steals the CPU to service the network card, it takes a roughly fixed slice of time — say a quarter of a millisecond. On a 0.5 ms run that is a 50% error; on a 2-second run it is 0.0000125%. The interruption is the same size; what changes is its share of your measurement. That is the deep reason we grow n: not to make the algorithm slower for its own sake, but to make every fixed disturbance shrink to a rounding error relative to the signal.

5.7Try it yourself

def contains(data, target):
    for item in data:
        if item == target:
            return True      # return leaves the function immediately
    return False

print(contains([3, 9, 4], 9), contains([3, 9, 4], 5))

5.8Self-check

5.9Homework

5.10Words from this week