Debugging, Benchmarking and Profiling Python for HPC

Overview

When an HPC Python program is wrong or slow, changing code immediately is tempting. It is also risky: a faster wrong answer is still wrong, and an optimization aimed at the wrong function only adds complexity. This module teaches a more dependable rhythm: reproduce the problem, protect the expected result, measure a representative workload, locate the cost, and change one thing at a time.

Learners investigate one deliberately imperfect word-count application from its first failing test through an evidence-backed optimization report. The example is compact, but the workflow transfers to simulation setup, analysis pipelines, and larger scientific applications.

Prerequisites

• Comfortable writing Python functions, loops, imports, and simple tests.

• Basic terminal use and familiarity with an HPC batch scheduler are helpful.

• Python 3.12 or newer and the software described in the setup episode.

No prior experience with a debugger or profiler is required.

Table of contents

Setup

• Software setup

Episodes

• Debug before measuring
• Benchmark reproducibly
• Profile the application
• Investigate lines, memory, and third-party tools
• Optimize from evidence
• Knowledge check

Reference

• Instructor guide
• Reference for learners

Learning outcomes

Estimated commitment: 3 hours, including setup, type-alongs, exercises, discussion, and the knowledge check.

This material is for Python developers, computational scientists, and research software engineers who need trustworthy evidence before changing an HPC application.

By the end of this module, learners should be able to:

• reproduce and isolate a Python defect using a small test and debugger;

• design and interpret a repeatable benchmark without promising machine-independent timings;

• use cProfile and pstats to identify costly call paths;

• use line-level evidence and select an appropriate third-party profiling tool;

• optimize a measured bottleneck while preserving correctness;

• report performance evidence with enough context for another person to assess it.

In the EVITA Competence and Qualification Framework, this is module SD1.2.9.3 — Debugging, Benchmarking & Profiling. It supports the HPC Certification Forum areas PE2 — Measuring System Performance and PE2.3 — Profiling Tools.

Credits and licences

Credit

The benchmarking and profiling backbone is adapted from Python for HPC. Supporting material comes from Writing Performant Python. The repository and lesson structure follows Introduction to GPU Programming. The debugging narrative and cumulative example were written for this module. Exact source revisions and adaptation notes appear in the repository README.md.

Pedagogical material and media are available under CC BY-SA 4.0. Source code and code snippets are available under the MIT License. See LICENSE and LICENSE.code.