Software setup¶

Reliable measurements begin with a known environment and a workload everyone can reproduce. This episode installs the lesson software, verifies the cumulative example, and separates portable commands from details that must be supplied by the teaching site.

Objectives

Create a reproducible environment for the lesson.
Verify the example application and profiling tools.

Instructor note

10 min environment setup
5 min verification

Requirements¶

Use Python 3.12 or newer and approximately 1 GB of free disk space. The examples need no external dataset and run on a laptop or a single compute node. On an HPC system, request an interactive allocation and run there rather than on a shared login node.

Create the environment¶

From the repository root, choose one route.

$ uv sync --all-groups
$ source .venv/bin/activate

$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install -e . pytest

PowerShell users activate with .venv\Scripts\Activate.ps1. The resolved environments are recorded in uv.lock and pylock.toml.

On Linux and macOS, run the shell commands in a terminal; on macOS, install the Xcode Command Line Tools first if Git is unavailable. On Windows, use PowerShell with a current Python installation, replace / with \ in executable paths when needed, and run .venv\Scripts\python -m pytest -q. Install pytest in the same environment when using the pip route. No compiler is required for the supplied examples.

Verify the example¶

$ python content/episodes/code/wordcount.py
$ pytest -q
$ python content/episodes/code/benchmark_wordcount.py

The first command should list common normalized words, and the tests should pass. Benchmark numbers will differ between machines; successful execution matters here, not a particular time.

HPC starting point¶

content/episodes/code/run_profile.slurm is a conservative one-node SLURM example:

$ sbatch content/episodes/code/run_profile.slurm

Your site may require an account, partition, QoS, storage path, or environment module. Those values are intentionally absent until the delivery platform is confirmed.

Dataset¶

No download is required. make_workload() creates deterministic text in memory, so exercises do not send learner or scientific data to an external service.

Keypoints

Reproducibility includes the environment, workload, command, and allocated resources.
Run compute work on a compute node, not a shared login node.
Treat the included batch script as a portable starting point, not site documentation.