Software setup¶

Objectives

Create a reproducible environment for the lesson.
Verify that Python can compile a Cython extension and run a local Dask scheduler.

Instructor note

10 min setup
5 min verification

Requirements¶

Use Python 3.12 or newer, a C compiler, and approximately 1 GB of free disk space. On an HPC system, work inside an interactive allocation on a compute node; do not run the exercises on a login node.

The exact Python dependency resolution is recorded in uv.lock and pylock.toml; use those files rather than copying package versions by hand.

Check the compiler before creating the environment:

$ cc --version

On Linux, install the distribution’s C development tools if this command is unavailable (for example, build-essential on Debian/Ubuntu or the Development Tools group on Fedora-family systems). On macOS, install the Command Line Tools with xcode-select --install. On Windows, use a Visual Studio C++ Build Tools command prompt or WSL and run all environment commands inside that same environment.

Create the environment¶

Clone the module, enter its directory, and use one of these supported routes.

$ 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 .

Windows PowerShell users activate the environment with .venv\Scripts\Activate.ps1.

Verify Cython¶

Build the example extension in place:

$ cd content/episodes/code
$ python setup.py build_ext --inplace
$ python -c "from integrate_cython import integrate; print(integrate(10000, 0.0))"

A floating-point value close to \(\pi\) (approximately 3.14159) confirms that the extension can be imported and is numerically correct. Generated C and extension files are build products and should not be committed.

Verify Dask¶

From the repository root, run:

$ python -c "import dask, distributed; print(dask.__version__)"

The Dask dashboard used later normally opens at http://localhost:8787/status. On a remote compute node, use your site’s documented SSH port-forwarding method or continue without the dashboard.

HPC batch starting point¶

The repository includes code/run_exercises.slurm, a conservative one-node SLURM starting point. Submit it only after creating the environment on the target system:

$ sbatch content/episodes/code/run_exercises.slurm

Sites may require an account, partition, QoS, storage path, or environment modules. The course owner must validate and document those details for the selected teaching system before delivery; the portable script does not replace site documentation.

Dataset¶

No external dataset is required. All exercises generate their numerical inputs locally.

Keypoints

Cython requires both its Python package and a working native compiler.
The Dask examples use only resources on the current machine or compute node.
Reproduce measurements in one documented environment; do not compare numbers from unrelated machines.