Instructor guide

Why we teach this lesson

Performance work often begins too early. Learners may time code whose result is wrong, optimize a convenient function rather than the measured bottleneck, or report one number without its workload and environment. The cumulative word-count case makes the full reasoning chain visible in three hours while remaining quick to reset and safe to run on shared infrastructure.

Timing

Part

Teaching

Guided work and discussion

Total

Setup

10

5

15 min

Debug before measuring

10

15

25 min

Benchmark reproducibly

15

20

35 min

Profile the application

15

25

40 min

Lines, memory, and tools

10

20

30 min

Optimize from evidence

10

25

35 min

Total

70

110

180 min

The knowledge check is included in the final 35 minutes rather than added afterward.

Before the course

  • Test the locked environment and all commands on the actual teaching platform.

  • Supply site-specific allocation, module, storage, and remote-visualization instructions.

  • Decide whether learners will use terminals, IPython, or notebooks; mark % magics as IPython-only.

  • If teaching with notebooks, build the CI-equivalent preview with python scripts/build_notebooks.py, open _build/notebook-preview/index.html, and distribute the complete artifact. From its root, prepare and start the environment with uv sync --all-groups and uv run jupyter lab so notebook cells and terminal commands share the preserved course layout.

  • Pre-create an interactive allocation if queue delay would consume teaching time.

  • Verify that browser-based SnakeViz use complies with site policy, or demonstrate a saved screenshot locally.

  • Verify that wordcount_working.py is ignored. Learners edit this disposable copy, leaving wordcount_buggy.py as the reusable starting point.

The included SLURM script is deliberately generic. Do not present it as validated for a site until it has been tested there.

Information required before delivery

The final participant cap, instructor/helper ratio, online or in-person mode, and named teaching system have not been supplied. Record those decisions here after they are approved. Until then, the material supports individual or paired terminal work on a laptop or one allocated CPU core, but this is an implementation capability rather than a delivery recommendation.

Learner personas and hardware

The primary learner is a computational scientist or research software engineer who can write small Python programs but has not followed a systematic performance workflow. A secondary learner maintains Python analysis or workflow code on a shared HPC system. Each learner or pair needs Python 3.12+, roughly 1 GB of storage, a terminal, and one CPU core; the exercises do not require a GPU or external dataset.

Delivery notes

Ask learners for evidence before accepting a diagnosis: the reduced input, one debugger observation, the relevant profile row, or the benchmark method. Do not announce an expected speedup. Hardware, Python versions, and system load can change the result, and an unexpected result is useful material for interpretation.

The examples are intentionally CPU-only and small. On shared clusters, learners should remain within their allocation and avoid profiling unrelated processes. Profile files, log files, and diagnostic output can contain source paths, hostnames, arguments, and input-derived values; use synthetic course data and delete artifacts according to local policy.

The notebook route complements rather than replaces the terminal workflow. Run the prediction and interpretation prompts as pauses between cells. The generated notebook omits Sphinx-only directive syntax, makes solutions collapsible, and skips optional IPython profiler magics during CI execution.

Typical pitfalls

  • A learner edited the canonical faulty file. Restore wordcount_buggy.py, create wordcount_working.py, and make the one-line fix only in the ignored working copy.

  • Learners run %timeit in a shell. Explain that % commands require IPython or Jupyter; use the prepared script in a terminal.

  • The profiler table differs. Ask whether the workload and sort key agree before comparing ranks. Never require fixed timings.

  • kernprof cannot find the module. Run from content/episodes/code in the activated environment.

  • Profiling output overwhelms the terminal. Restrict output with print_stats(12) and instrument only the selected function.

  • IceCream output leaks into results. Remind learners that it writes to standard error, may format sensitive values, and must be removed or disabled before measurement.

  • A browser cannot reach SnakeViz remotely. Use a local copy of a non-sensitive .prof file or skip visualization; never open an unapproved network listener.

Discussion prompts

  • Which part of your own workflow provides the correctness oracle?

  • Which cost belongs inside your application-level timing boundary?

  • When would profiler overhead make sampling preferable?

  • What evidence would persuade a colleague to accept—or reject—an optimization?

Assessment

The final performance note is the practical assessment. It should identify a question, revision and environment, fixed workload, correctness result, measurement method, observations, interpretation, and limitations. The knowledge check tests vocabulary and tool selection. Prefer reasoning tied to observed evidence over memorized command syntax.