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? Interruptions often add delay, so the minimum can estimate a lightly interrupted run. It is not a guaranteed true cost: cache state, CPU frequency, measurement overhead and the chosen input also matter. Report the individual samples and say whether you used a minimum, median or mean.

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 both the ratio and seconds columns. Ratios can reveal a growth pattern when machine effects approximately cancel, but they still depend on the measured conditions. Near-doubling times support the linear model here; the loop count explains it for all n. Next week you will use ratios as evidence when distinguishing growth patterns.

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 performs a fixed number of arithmetic operations when each arithmetic operation counts as one step. Python's arbitrarily large integers make individual arithmetic costs grow with bit length. 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 may be slower because of one-off setup, cold caches or runtime warm-up. This is not guaranteed. A deliberately untimed first call is a warm-up; use and report it when the intended measurement is steady-state performance.

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.0125% (0.25 ms / 2 000 ms × 100). 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.

Reading the timing examples: displayed seconds and fitted slopes are illustrative output, not measurements from your machine. Run the experiment, retain the actual samples, and report the input and measurement conditions. Exact operation-count formulas are separate mathematical claims.

5.9Optional Studio Extension

5.10Words from this week