Measuring and improving speed

time.ticks_us() on a Pico counts up to 1,073,741,823 and then starts again at 0, so end - start comes out wrong, by about a billion, whenever a timing straddles the wrap, which comes round every 17.9 minutes. Timing on a board goes wrong in quieter ways too: one run instead of several, a run that includes a collection, or a number measured on a computer.

Below, code is timed the way that holds up on a board, with ticks_diff() and the best of several runs, and the changes that make a hot loop faster are named: const(), local names, integer maths and less work per sample.

Ticks wrap, so never subtract them

The ticks functions return a counter that wraps: ticks_us() in microseconds, ticks_ms() in milliseconds. The time module’s documentation promises only that the period is a power of two; on 32-bit ports such as rp2 and esp32 it is 2³⁰, every positive small integersmall integer: An integer that MicroPython keeps inside the object word itself, with no heap allocation: on most 32-bit ports one from -2**30 to just below 2**30. Larger integers stay exact but are stored on the heap. More in “Numbers, bytes and text on small chips”, so a reading never needs the heap. This program does the arithmetic the way extmod/modtime.c does it:

"""MicroPython's ticks arithmetic on a 32-bit port, written as extmod/modtime.c does it."""
PERIOD = 2 ** 30  # MICROPY_PY_TIME_TICKS_PERIOD: every positive small integer
HALF = PERIOD // 2


def ticks_add(ticks, delta):
    if not -HALF < delta < HALF:
        raise OverflowError("ticks interval overflow")
    return (ticks + delta) & (PERIOD - 1)


def ticks_diff(end, start):
    return ((end - start + HALF) & (PERIOD - 1)) - HALF


start = ticks_add(0, -200)  # 200 us before ticks_us() wraps to 0
end = ticks_add(start, 711)  # 711 us later, after the wrap
print("start %d, end %d" % (start, end))
print("end - start            %d" % (end - start))
print("ticks_diff(end, start) %d" % ticks_diff(end, start))
print()
for gap in (HALF - 1, HALF):
    later = (start + gap) & (PERIOD - 1)
    print("%d ticks later: ticks_diff gives %d" % (gap, ticks_diff(later, start)))
try:
    ticks_add(start, HALF)
except OverflowError as e:
    print("ticks_add(start, %d): OverflowError: %s" % (HALF, e))
print()
print("ticks_us() wraps every %d us, %.1f minutes" % (PERIOD, PERIOD / 60e6))
print("ticks_ms() wraps every %d ms, %.1f days" % (PERIOD, PERIOD / 86400e3))

start 1073741624, end 511
end - start            -1073741113
ticks_diff(end, start) 711

536870911 ticks later: ticks_diff gives 536870911
536870912 ticks later: ticks_diff gives -536870912
ticks_add(start, 536870912): OverflowError: ticks interval overflow

ticks_us() wraps every 1073741824 us, 17.9 minutes
ticks_ms() wraps every 1073741824 ms, 12.4 days

The timing started 200 µs before the wrap and lasted 711 µs. Plain subtraction gives −1,073,741,113, while ticks_diff() gives 711, because it works modulo the period of the ticksticks: The counts that time.ticks_ms(), ticks_us() and ticks_cpu() return: they wrap to 0 at a power of two, 2**30 on 32-bit ports, so two readings are compared only with time.ticks_diff(). More in “Pins: outputs, inputs, pull-ups and Signal”. It stays right while the two readings are less than half a period apart: 8.9 minutes for ticks_us(), 6.2 days for ticks_ms(). At half a period its answer turns negative, and ticks_add() refuses such an interval with OverflowError.

Time the best of several runs, on the board

Measuring speed starts with distrust of a single run: a collection, an interrupt or a slow first call can land in it. MicroPython’s speed guide times functions with ticks_us() and ticks_diff(); repeat the call, call gc.collect() before each run so that no garbage from earlier is collected inside it, and keep the best run as the code’s own cost and the slowest as a warning. timing.py does that, and bench.py prints what ran it beside the numbers:

"""Time a checksum the way you would on a board, and print what ran it beside the numbers."""
import sys

from timing import best_of


def checksum(data):
    total = 0
    for b in data:
        total = (total + b) & 0xFFFF
    return total


impl = sys.implementation
print("%s %d.%d.%d on %s" % ((impl.name,) + tuple(impl.version[:3]) + (sys.platform,)))
fast, slow = best_of(checksum, bytes(range(256)) * 8)
print("checksum of 2,048 bytes: best %d us, slowest %d us of 7 runs" % (fast, slow))

cpython 3.14.8 on darwin
checksum of 2,048 bytes: best 67 us, slowest 76 us of 7 runs

"""best_of(): time a function as you would on a board, the best of several runs.

On MicroPython it uses ticks_us() and ticks_diff(). On CPython, which has no ticks, a
microsecond counter made from perf_counter_ns() stands in; it never wraps.
"""
import gc

try:
    from time import ticks_diff, ticks_us
except ImportError:
    from time import perf_counter_ns

    def ticks_us():
        return perf_counter_ns() // 1000

    def ticks_diff(end, start):
        return end - start


def best_of(func, arg, runs=7):
    """The fastest and the slowest of several runs, in microseconds."""
    times = []
    for _ in range(runs):
        gc.collect()  # start each run with no garbage left to collect
        start = ticks_us()
        func(arg)
        times.append(ticks_diff(ticks_us(), start))
    return min(times), max(times)

The recorded run is CPython 3.14.8 on a computer, and Run in this page runs Pyodide, CPython compiled for the browser: two different numbers, and a board gives a third. MicroPython’s interpreter is not CPython, and a Pico, which the rp2 port runs at 125 MHz, is not a laptop, so only the board’s own run says how fast the code is there.

Measuring on the board also says where to start improving speed. Once it shows the code is too slow, these changes make a hot loop faster, roughly in the order to try them:

• Less work per sample. The speed guide puts the algorithm first: a moving average that adds up its window again for every sample does far more work than one that keeps a running total.
• Integer maths. On rp2 and esp32 every float result is a new heap object, and some ports compute floats in software. Whole units, such as millivolts instead of volts, keep the loop on small integers.
• Local names. A local is read from a slot of the function’s frame, while a global or an attribute such as self.buf is looked up by name. Copying it into a local before the loop, buf = self.buf, saves that lookup.
• const(). _LIMIT = const(500)const(): MicroPython's declaration NAME = const(expr): the compiler works out expr and writes its value into the bytecode wherever NAME is used. A name that starts with an underscore is not kept in the module's globals at all. makes the compiler write 500 into the bytecode wherever _LIMIT appears, so no lookup happens at all. With the leading underscore, the name is not even kept in the module’s globals.
• Machine code. The native and viper emitters compile a function to machine code: the next lesson.

How much improving speed in one place buys the whole program depends on the share of its time that hot spothot spot: The part of a program where it spends most of its running time, found by measuring. Speeding it up shortens the whole run only by the time it takes away, so its share of the time decides what a change can win. takes.

Check yourself

Ticks and timing on the board, one question at a time; a wrong choice says what it misses.

Benchmarks that hold up: the clock's limits and the hot spot's share, worked out Pro: opens with a Pro, Premium or Ultimate pass

Hot-loop rewrites: const(), local names and less work per sample, checked Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Warm-up (fresher): Why use time.ticks_diff() instead of subtracting two ticks_us() values?

ticks_us() wraps: on 32-bit ports it counts to 2³⁰ − 1 and starts again at 0. A plain end - start across the wrap is wrong by about a billion. ticks_diff(end, start) works modulo the period and gives the right signed difference as long as the two readings are less than half a period apart, about 8.9 minutes for microseconds.

Key takeaways

• Ticks wrap at 2³⁰ on 32-bit ports, so subtract them only with ticks_diff() and add to them only with ticks_add().
• Time a function several times on the board itself, with gc.collect() before each run, and keep the best run; numbers from a computer or a browser say nothing about the board.
• Make a hot loop faster by doing less work per sample first, then integer maths, local names and const().