Research Computing in Python

#2 Practicalities — best practices for research software

2026-07-24

This course

• A biased take on what you need to get started using computers in research
• Not a computer science course, not exhaustive
• A mixture of high-level concepts, empirical truths and practical advice
• Not a real Python course, either - you can’t learn a language by reading the dictionary

Recap

• A century of hardware, one enduring idea: the stored program, fetch–decode–execute — everything else is miniaturisation
• Languages are abstractions over that machine: compiled ones (C, Fortran) stay close to it; Python trades machine time for your time
• Types are rules for reading bits — and every abstraction leaks (overflow, 0.1 + 0.2, “why is this slow?”)
• Python hides the machinery in objects and dicts; when you need speed, offload to the compiled layer (NumPy) — or fix the algorithm first

Software is a living ecosystem

• Everything you’ve seen today changes: languages, libraries, hardware — software grows organically around historical biases (x86’s baggage, Fortran’s arrays, Python’s dicts)
• You are part of the ecosystem: the code you write and the tools you choose feed back into it
• So the same code will not always work, everywhere, forever — unless you fence it in: pinned dependencies, recorded environments, containerisation

This lecture: research programming in practice

• The Scientific Python stack
• Structuring your code: functions, modules, packages
• Environments and packaging, using uv
• Editors, terminals, and other tools of the trade
• Version control with git and GitHub
• Testing your code, and why it matters
• Research software engineering, as a discipline
• If we have time: AI code generation and agents: what changes, what doesn’t

NumPy and Mandelbrot

Scientific Python

Nearly all of it stands on one shared abstraction: the NumPy array.

• NumPy — the n-dimensional array: memory laid out like Fortran, driven from Python
• SciPy — the numerical toolbox: integration, optimisation, linear algebra, statistics, signal processing
• matplotlib — plotting (most of the figures in most of the papers you’ll read)
• pandas — labelled tables (“dataframes”) for messy real-world data
• Jupyter — notebooks: code, figures and narrative in one document
• scikit-learn — classical machine learning; PyTorch / JAX at the deep-learning end
• …and domain layers on top: astropy (astronomy), ASE / pymatgen (materials), RDKit (molecules), Biopython, MDAnalysis, …

• The shared array is what makes the stack composable: a pandas column, a scikit-learn input, and a matplotlib series are all NumPy arrays underneath — everything interoperates.
• All community-built, open source — the living ecosystem from a few slides ago, working in your favour.
• Advice: before writing your own file parser or fitting routine, check whether your field’s domain package already has it. It usually does.

NumPy: putting the speed back

Remember why arrays are fast — one contiguous block. NumPy brings that to Python:

import numpy as np

measurements = [[1.2, 1.4, 1.1],     # a nested list of Python objects…
                [0.9, 1.3, 1.5]]
arr = np.array(measurements)         # …becomes one contiguous block of float64

2 * arr             # array([[2.4, 2.8, 2.2],
                    #        [1.8, 2.6, 3. ]])
arr.mean()          # 1.2333333333333332
arr.max(axis=1)     # array([1.4, 1.5]) — the max of each row

One line of Python = one compiled loop over the whole block

arr[0]              # first row
arr[:, 2]           # third column: array([1.1, 1.5])
arr[arr > 1.2]      # by condition:  array([1.4, 1.3, 1.5])

Slicing and masking replace most of the loops you’d otherwise write

• This cashes in the arrays/vectors slide: same contiguous memory as C/Fortran (it is C underneath), driven from Python. The wardrobe overhead is paid once per array, not once per number.
• The loop still happens — but in compiled code, over the whole block, with the types checked once. That’s the whole “why Python survives being slow” trick in one object.
• The mask arr[arr > 1.2] is the same idea the NumPy Mandelbrot uses at scale (coming up).
• All outputs shown are real (numpy prints 3. for 3.0 — floats, again).

The Mandelbrot set

Iterate one very simple map:

\[z_{n+1} = z_n^2 + c, \qquad z_0 = 0\]

for a complex number \(c\) — i.e. a point in the plane.

• The set is every \(c\) for which \(z_n\) stays bounded forever
• We can’t iterate forever, but there’s an escape test: once \(|z_n| > 2\), the orbit is gone for good — so iterate each pixel’s \(c\) up to max_iter times and colour it by when it escaped
• The boundary is a fractal: infinitely detailed, new structure at every zoom
• And it’s a perfect benchmark: millions of pixels × hundreds of iterations of pure arithmetic, nothing to hide behind

• Named for Benoît Mandelbrot, who first plotted it at IBM in 1980 — a computational discovery: nobody had seen it before computers, despite the underlying maths (Julia, Fatou) dating to ~1918.
• Why 2? If \(|z_n|\) ever exceeds 2, the \(z^2\) term dominates and the orbit provably diverges — that’s what makes a finite test correct, not a heuristic.
• Black pixels = never escaped within max_iter = (approximately) in the set; the colour bands are escape times.

Structuring your code

Functions, modules, packages

As a project grows, one script stops being enough. Python gives you a few levels of structure, each one built out of the last.

• A function groups a few lines of code under one name, so you can reuse it and so it can have a name that explains what it does (e.g., scipy.stats.linregress)
• A module is a single .py file of related functions and classes, which can be imported with import my_module (e.g., scipy.stats)
• A package is a folder of modules that can be imported as a single unit, even though it contains many files (e.g., scipy)

# analysis.py, a module
def parse_xrd(file): ...
def plot_experiment(data, sample_name, expt_number, output_dir): ...

# elsewhere, in a different file
import analysis

data = analysis.parse_xrd("sample4.dat")
analysis.plot_experiment(data, "sample4", 7, "figures")

• A package needs an __init__.py file in the folder to mark it as importable (this requirement is being relaxed in modern Python, but it is still the safe, portable choice).
• import searches, in order, the current directory, then any installed packages. This is exactly the mechanism uv and pip hook into when they “install” a package: they just put its files somewhere Python already looks.
• This is precisely what anti-pattern #1 leads to: parse_nmr, parse_xrd, plot_experiment, plot_experiments, and export_json are exactly the right shape to live together in one module, analysis.py, imported by as many scripts as you like.

Libraries vs applications vs scripts vs frameworks

Four words for four different shapes of software. Knowing which one you are looking at (or writing) tells you what to expect from it.

• A script is a short, linear program, meant to be run from start to finish, like plot_experiment.py from earlier. It is not usually imported by other code
• A library (or package) is code written to be imported and reused. NumPy and Matplotlib are libraries: you never “run” NumPy, you import it
• An application is a complete, user-facing program built for a particular purpose, often assembled out of several libraries
• A framework is a library that calls your code, rather than the other way around. You write code that fits into its structure, and it takes charge of the overall flow

• Examples of frameworks: pytest itself, which is coming up next, discovers and calls your test functions rather than being called by them; web frameworks like Django or Flask; training frameworks like PyTorch Lightning.
• Today’s course mostly writes scripts and small libraries. Recognising the other two matters the day you inherit someone else’s codebase and need to work out how it is meant to be used.
• A script can grow an entry point (console_scripts in pyproject.toml) and become a small installable application, e.g. a plot-experiment command available anywhere on the machine. Worth mentioning if there is time, otherwise skip.

Common anti-pattern #1: hard-coded everything

import matplotlib.pyplot as plt
import numpy as np

expt_number = 7
file = "data/experiments/sample4.csv"

data_file = []
with open(file, "r") as f:
    for line in f.readlines():
        if (
            line.startswith("nmr-sample4") 
            and line.split(",")[-1] == expt_number
        ):
            data_file.append(",".join(line.split(",")[1:]))

with open("output.txt", "w") as f:
    f.writelines(data_file)

data = np.loadtxt(
    data_file, delimiter=",", skiprows=1, comments="%"
)
plt.scatter(data[:, 0], data[:, 1])
plt.title("Sample 4")
plt.savefig("/home/mevans/figures/sample4_expt7.png")

Paths, sample names, and “constants” that should be arguments, all baked into the script.

What happens with sample 5?

• The bug: line.split(",")[-1] == expt_number compares a string (the last CSV field, newline and all) to the int expt_number. That is always False, so data_file stays empty, and np.loadtxt warns “input contained no data” before the plot line crashes outright.
• The fix is int(line.split(",")[-1]) == expt_number, int() also strips the trailing newline for free. Worth fixing live rather than just stating it.
• Everything else here is real, working NumPy: np.loadtxt happily accepts a list of lines (not just a filename), which is what the filter step is exploiting.
• Ask the room: what happens the day you need to plot sample 5? Or experiment 8? Right now that means editing the script.

The fix: wrap it in a function

def plot_experiment(
    data_dir, sample_name, expt_number, output_dir
):
    """Scatter-plot one experiment's full spectrum 
    from a sample's CSV.
    """
    file = data_dir / f"{sample_name}.csv"

    data_file = []
    with open(file) as f:
        for line in f:
            tag, *values = line.strip().split(",")
            if (tag == f"nmr-{sample_name}" 
                and int(values[-1]) == expt_number):
                data_file.append(",".join(values[:-1]))

    data = np.loadtxt(
        data_file, delimiter=",", skiprows=1, comments="%"
    )

    plt.scatter(data[:, 0], data[:, 1])
    plt.title(f"{sample_name}, experiment {expt_number}")
    plt.savefig(output_dir / f"{sample_name}_expt{expt_number}.png")

• Every hard-coded value became a parameter, the function works for any sample, any experiment, any directory
• But where do we call it? A script?

…then a command-line script

if __name__ == "__main__":
    import argparse
    from pathlib import Path

    parser = argparse.ArgumentParser()
    parser.add_argument("sample_name")
    parser.add_argument("expt_number", type=int)
    parser.add_argument("--data-dir", 
        type=Path, default=Path("data/experiments"))
    parser.add_argument("--output-dir", 
        type=Path, default=Path("figures"))
    args = parser.parse_args()

    plot_experiment(args.data_dir, args.sample_name, args.expt_number, args.output_dir)

python plot_experiment.py sample4 7 --output-dir figures/
python plot_experiment.py sample5 3

• The same function, now driven by whoever’s typing, not whoever’s editing
• Next step, when this function is useful to more than one script: package it up

Anti-pattern #2: all-in-one functions

The “good” function from before, but the lab now runs two instruments, and the second one’s output looks nothing like the first:

def plot_experiment(data_dir, sample_name, expt_number, output_dir):
    """Scatter-plot one experiment's full spectrum from a sample's CSV."""
    file = data_dir / f"{sample_name}.csv"

    data_file = []
    with open(file) as f:
        for line in f:
            tag, *values = line.strip().split(",")
            if tag == f"nmr-{sample_name}" and int(values[-1]) == expt_number:
                data_file.append(",".join(values[:-1]))

    data = np.loadtxt(data_file, delimiter=",", skiprows=1, comments="%")

    plt.scatter(data[:, 0], data[:, 1])
    plt.title(f"{sample_name}, experiment {expt_number}")
    plt.savefig(output_dir / f"{sample_name}_expt{expt_number}.png")

• The NMR-specific bits (the nmr- tag, the CSV filtering) are now welded into a function whose name promises nothing instrument-specific
• Supporting the second instrument means an if fmt == ...: branch inside, and a third means another, and a fourth
• Worse: to test the parsing, you now also have to test the plotting. One function, three jobs: read a format, extract data, draw a figure

• This is the same shape as anti-pattern #1 but one level up: last time we extracted parameters; the bug this time is extracting the wrong boundary. Parametrising isn’t enough if the thing you parametrised is still one function doing three unrelated jobs.
• Ask the room: what would the diff look like to add a third file format here? (Answer: it touches the one function everything else depends on.)

The fix: one function per job

def parse_nmr(file, sample_name):
    """Parse every NMR row for one sample, all experiments together."""
    data_file = []
    with open(file) as f:
        for line in f:
            tag, *values = line.strip().split(",")
            if tag == f"nmr-{sample_name}":
                data_file.append(",".join(values))
    return np.loadtxt(data_file, delimiter=",", skiprows=1, comments="%")

def parse_xrd(file):
    """Parse the XRD instrument's whitespace-delimited export."""
    return np.loadtxt(file, skiprows=3)

def parse(file, sample_name, fmt):
    """Parse one experiment file, whatever instrument it came from."""
    if fmt == "nmr":
        return parse_nmr(file, sample_name)
    elif fmt == "xrd":
        return parse_xrd(file)
    else:
        raise ValueError(f"unknown format {fmt!r}")

def plot_experiment(data, sample_name, expt_number, output_dir):
    """Scatter-plot one experiment's spectrum, picked out of parsed data."""
    spectrum = data[data[:, -1] == expt_number]
    plt.scatter(spectrum[:, 0], spectrum[:, 1])
    plt.title(f"{sample_name}, experiment {expt_number}")
    plt.savefig(output_dir / f"{sample_name}_expt{expt_number}.png")

• Parsing and plotting are now separate functions, each does one job, and each can be tested on its own
• A new instrument means writing one new parse_* function and adding one elif, nothing else changes
• plot_experiment picks its own rows out with a mask, the same arr[arr > 1.2] trick from the NumPy slide, data[:, -1] is the expt_number column, kept alongside x and y

• The mask in plot_experiment assumes an expt_number column, true for sample4.csv/sample4.nmr, not true for sample4.xrd, which is a single, already-one-experiment file with no such column. Fine to gloss over live, or a good “what would you change here” question for the room.

…and now, for free: plot many experiments

Because parsing happens once and plotting is separate, looping is trivial, and the file is only read once, not once per experiment:

def plot_experiments(data_dir, sample_name, expt_numbers, fmt, output_dir):
    """Plot several experiments from the same sample in one go."""
    file = data_dir / f"{sample_name}.{fmt}"
    data = parse(file, sample_name, fmt)

    for expt_number in expt_numbers:
        plot_experiment(data, sample_name, expt_number, output_dir)

plot_experiments("data/experiments", "sample4", [3, 7, 12], "nmr", "figures")

def compare_samples(data_dir, sample_names, expt_number, fmt, output_dir):
    """Overlay one experiment from several different samples on one plot."""
    for sample_name in sample_names:
        file = data_dir / f"{sample_name}.{fmt}"
        data = parse(file, sample_name, fmt)
        spectrum = data[data[:, -1] == expt_number]
        plt.scatter(spectrum[:, 0], spectrum[:, 1], label=sample_name)

    plt.legend()
    plt.savefig(output_dir / f"comparison_expt{expt_number}.png")

• plot_experiments didn’t exist before, and cost almost nothing to write, it’s just a loop over a function we already had and trusted
• That’s the real payoff of splitting responsibilities: not tidiness for its own sake, but new capability from recombining small pieces
• compare_samples loops over files, not experiment numbers, and adds each one to the same plot instead of saving a new figure every time. plot_experiment doesn’t fit here, it saves and closes a figure per call, so this is a genuinely new, small function, built directly on parse() again

…or export to something generic

plot_experiment isn’t the only thing that can consume parsed data. Remember JSON, from last time?

import json

def export_json(data, sample_name, expt_number, output_dir):
    """Save one experiment's spectrum as JSON, for any tool to read."""
    spectrum = data[data[:, -1] == expt_number]
    record = {
        "sample": sample_name,
        "experiment": expt_number,
        "xy": spectrum[:, :2].tolist(),   # ndarray isn't JSON-serialisable
    }
    with open(output_dir / f"{sample_name}_expt{expt_number}.json", "w") as f:
        json.dump(record, f)

data = parse("data/experiments/sample4.nmr", "sample4", "nmr")
export_json(data, "sample4", 7, "results")

• Same parse(), same data, a completely different destination. A PNG is for you; JSON is for a colleague’s script, a website, a database
• .tolist() matters: json.dump doesn’t know what a NumPy array is, convert to plain Python first, at the boundary
• This is only possible because parsing was split from plotting in the first place

Interfaces, e.g., Winamp

Winamp Skin Museum

• In the late 1990s, one of the most popular pieces of software in the world was a small music player called Winamp. Its underlying job never changed: read an audio file, decode it, and play the sound. Its appearance was another matter entirely.
• Anyone could write a “skin”, a set of images and layout files, and change how the player looked, without touching a single line of the code that actually played the music. The second image is a fraction of the Winamp Skin Museum’s archive, every one of them the same player underneath.
• Good line to say out loud: “It really whips the llama’s ass” was Winamp’s own launch tagline, an early example of software with real personality in its interface, not just its engine.
• The interface and the engine were always two separate things, and could be designed, changed, or swapped out, independently of each other. That is the whole point of this slide.
• After the second image: switch to the live website (skins.webamp.org) and show a few skins running for real.

What is a computer interface?

An interface is the surface where two different things meet, a person, or another program, and your code.

• A function is the interface between one piece of code and another: its arguments and return value are the whole contract
• A command-line interface (CLI) is the interface between a person, or a script, and a program run from a terminal, like plot_experiment.py from earlier today
• A library or package is the interface between your code and anyone else’s code that wants to reuse it, once it can be installed and imported
• A web API is the interface between programs running on entirely different computers, talking over the network, usually by exchanging JSON, exactly like the file exported a few slides ago
• A graphical user interface (GUI), like Winamp’s window, or a website, is the interface between a person and a program, with no command to type

• Point back explicitly at earlier examples: today already built three different interfaces onto the same underlying parse() and plot_experiment() functions, a function call, a CLI script, and a JSON export. That is this entire slide, already demonstrated live before it was named.
• The right interface depends entirely on who, or what, needs to use the code. A script only you will ever run needs none of this ceremony. A tool a whole lab depends on for years probably needs several of these at once.

Case study: datalab’s interfaces

datalab, mentioned on the very first slide of this course, is one underlying platform with several different interfaces built on top.

A plain web request, the interface for any program at all:

curl https://datalab.odbx.science/samples

[
  {"refcode": "grey_0001", "type": "samples"},
  {"refcode": "grey_0002", "type": "samples"}
]

The same thing, wrapped for Python:

from datalab_api import DatalabClient

with DatalabClient("https://datalab.odbx.science") as client:
    samples = client.get_items()

The web interface, for a person:

• The core logic and the web API are both tested with pytest: ordinary unit tests for the logic itself, and tests that send real requests to the API and check what comes back
• The web interface is tested with Cypress, which drives a real browser automatically, clicking buttons and filling in forms the way a person would, and records a video of every run
• Different interfaces, tested in different ways, but all built on the same handful of ideas from this lecture: write the test, run it automatically, trust the result

Live: a recent Cypress run, played from the cloud dashboard.

• The general shape is the point, regardless of exact tool names: an interface left untested is exactly where problems reach real users first, since it is the one thing everybody actually touches.
• Swap in a real, current sample response for the JSON example before presenting; only the refcode is guaranteed to exist on any given instance, everything else varies group to group.
• Cypress link goes straight to the project’s run history; pick a recent, clean run before presenting so the video is ready to play without searching for one live.

Developer environments

Editor and terminal

• A good editor adds autocompletion, inline documentation, error checking, a debugger, and version control, all while you type, catching many mistakes before you even run the code
• VS Code https://code.visualstudio.com is a popular, free choice with excellent Python support through extensions (unfortunately developed by Microsoft)
• Extensions are third-party code with real access to your files: install only official ones for the language you are using (for Python, Microsoft’s own “Python” and “Pylance”), and treat unsolicited “recommended extension” prompts with real scepticism, not automatic trust
• Learn to be comfortable in a terminal and shell too, bash or zsh: most of today’s tools, uv, git, pytest, are run from the command line, and it is often the fastest way to work
• Jupyter notebooks are excellent for exploring data, but ordinary .py files in a proper editor are usually better for anything meant to be kept, reused, or shared. Worth saying if there is time.

Live in this lecture: a short click-through tour of VS Code, and a look at its built-in debugger.

• Real incidents exist of malicious or typo-squatted VS Code extensions harvesting credentials or injecting code. “Official” here means published by the language’s own maintainers or a widely recognised organisation, Microsoft for Python and Pylance, the Rust team for rust-analyzer, and so on, not simply whatever has the most downloads or whatever the editor itself suggests unprompted.
• Demo shape: open a Python file, show autocompletion and inline docs, introduce a small deliberate bug, set a breakpoint, and step through it live with the debugger to find it.
• Other useful extensions worth naming: GitLens, and Remote-SSH, which is particularly valuable for working directly on an HPC cluster or lab machine.

A hammer, first and foremost

A code editor should, before anything else, be an excellent plain text editor. Everything else it offers is only worth having on top of that foundation, not instead of it.

“The Homer”

• The hammer is “The Wizard of Evergreen Terrace” (season 10), in which Homer, inspired by Thomas Edison, invents an electric hammer among other over-engineered gadgets. It works, but it is far more machine than the job needed.
• “The Homer” is from “Oh Brother, Where Art Thou?” (season 2): Homer’s long-lost half-brother, a car executive, asks him to design his ideal car with no budget or constraint. The result has three horns, a bubble dome, giant cupholders, and bankrupts the company: every feature anyone could want, and a car nobody actually wants to drive.
• The analogy: a plain hammer, used well, drives a nail perfectly. An editor loaded with every extension going, none of them learned properly, is the electric hammer, or worse, “The Homer”: more likely to fail at the one job that actually matters than a simple tool used with skill.

Virtual environments

Your computer probably already has a Python installed, maybe several. Installing every package you ever need into that one, shared Python is how projects end up fighting each other.

• Different projects need different, sometimes incompatible, versions of the same library: one needs NumPy 1.x, another needs NumPy 2.x
• Installing everything into one global Python turns your computer into a fragile, one-of-a-kind setup that is hard for anyone else, including you in six months, to reproduce
• A virtual environment is a self-contained copy of Python and its installed packages, kept in its own folder, one per project
• Treat environments as cattle, not pets: if one breaks, delete it and rebuild it from a written record of what it needs, rather than nursing it back to health

Common pitfalls without a virtual environment

• “It works on my machine”: your script quietly depends on a package version that happens to be installed on your laptop, and fails for someone else, or for you on a different computer
• Installing a new project’s dependencies can silently upgrade or downgrade a package that an older project relies on, breaking code that used to work “dependency hell”
• Libraries usually specify fairly precisely which versions of their own dependencies they need, but older tools did not always check this properly against what was already installed, and could leave a genuinely broken combination in place without so much as a warning
• Installing packages without a virtual environment can need administrator permissions, or install into the wrong Python entirely, which is a particular hazard on shared machines like a university cluster
• With no written record of what is installed, nobody, not even you in a year, can say exactly what a script needs to run

• This is “dependency hell”: two packages your project needs each depend on a third package, but on different, incompatible versions of it.
• pip, before version 20.3 in 2020, had no real dependency resolver: it installed packages one at a time, and if two packages needed conflicting versions of a third, whichever was installed last simply won, silently. Modern pip and uv both solve the whole dependency graph together before installing anything, and will refuse outright rather than produce a broken environment.
• Mixing pip and conda installs in the same environment is still a classic way to reintroduce this exact problem, since neither tool tracks what the other has already done.
• On managed or shared machines (HPC login nodes are the classic case), you often cannot install into the system Python at all, which is precisely the situation a per-project virtual environment sidesteps.
• which python and pip list are the two commands to reach for when diagnosing “which Python am I even using, and what is installed in it.”

The saviour: uv

uv is a single, fast tool that replaces most of the separate tools that used to be needed to manage a Python project: pip, conda, venv, virtualenv, pip-tools, and pyenv, among others.

• uv init my-project creates a new project, with its own isolated environment and its own list of dependencies
• uv add numpy adds a dependency, installs it into the project’s environment, and records the exact version installed
• uv run script.py always runs your code inside the correct, up-to-date environment, with no separate “activation” step to remember
• uv.lock is a complete, exact record of every installed package and its version, so the environment can be recreated identically on another machine, or in a year’s time
• You can then reinstall exactly the same environment with uv sync.

• uv also manages Python versions themselves (replacing pyenv): uv python install 3.12 fetches an interpreter, no system package manager required.
• The example code from the first lecture already used this: the PEP 723 header at the top of each mandelbrot_*.py file lists its dependencies inline, so uv run mandelbrot_numpy.py builds the right environment on the fly, with no separate install step. Worth pointing back at.
• uv tool install ruff (or pytest, or anything else) installs a command-line tool globally, in its own isolated environment, without polluting any project’s dependencies.
• uv.lock should be committed to version control; the pyproject.toml it is generated from states what you depend on, the lock file states exactly which versions were resolved, down to the last patch release.

Testing

Why test your code?

Writing tests can feel like it slows you down, since it is extra code that produces no new results by itself. In practice, it saves time overall, because it catches mistakes early, while they are still cheap to fix.

• A bug caught the moment you introduce it costs a minute to fix. The same bug, caught after it has quietly shaped three months of results, costs far more
• Tests are a safety net: they let you restructure code, like splitting one function into several, with confidence that nothing has broken
• Once there is enough code, you stop understanding it by reading every line, and start understanding it by how it behaves. Tests are the systematic version of that: a description of the behaviour you expect
• Tests are also documentation: they show which functions are the important entry points and workflows, and exactly how each one is meant to be used, more reliably than a comment that can quietly drift out of date
• Testing and documentation matter most for collaboration, especially collaboration with your past self, who will not remember why a piece of code was written the way it was

Testing in Python: pytest

pytest is the standard tool for writing and running tests in Python. A test is a function whose name starts with test_, that checks something is true using a plain assert.

# test_analysis.py
from analysis import parse_xrd

def test_parse_xrd_shape():
    data = parse_xrd("tests/data/example.dat")
    assert data.shape[1] == 2   # every row should be an (x, y) pair

• Put tests in files named test_*.py, with functions named test_*. pytest finds and runs them automatically, no registration needed
• Run the whole test suite with one command: uv run pytest
• A failing test prints exactly which assert failed, and the values involved, so you can see straight away what went wrong

• Notice that every function written in today’s earlier demo, parse_nmr, parse_xrd, plot_experiment, already had a clear one-line docstring. If you cannot write that one line, it is often a sign the function is doing too much, exactly the anti-pattern from earlier.
• Beyond a plain assert, pytest supports fixtures (reusable setup code) and parametrised tests (running the same test body over many inputs). Worth a mention, not a deep dive today.
• GitHub Actions, or similar continuous integration, can run uv run pytest automatically on every push and every pull request, so a broken change is caught before it is merged, not after.

What makes a good test?

• It exists Even a trivial test that just imports the code and runs it once catches the vast majority of problems someone else will actually hit: a broken install, a missing dependency, a typo that stops everything before it starts
• Real examples come next. Test against actual data, or a small, realistic version of it, not numbers invented purely because they were convenient to type
• Real numbers matter too. Pin down a known, checked value, and assert the code still produces it, so a change that quietly shifts a result gets caught the moment it happens, not months later in a paper
• Combinations of arguments and testing functions together Test the edge cases and unusual inputs together, not just the one case the function happened to be written for

• Existence-only example: def test_import(): import analysis looks trivial, but it is exactly the test that catches “it works on my machine” the moment someone else tries to run the code.
• Real examples: test parse_xrd against an actual, small file saved in the repository, tests/data/example.dat, not a hand-typed string that merely looks plausible.
• Real numbers: something like assert abs(mean([1.0, 2.0, 3.0]) - 2.0) < 1e-9, a genuinely checked answer, not just “the function returned something.”
• Combinations: an empty list, a single value, negative numbers, a huge array. @pytest.mark.parametrize runs the same test body over many inputs without repeating code, worth a one-line mention if there is time.
• The four levels build on each other, and coverage beats elegance early on: a hundred simple existence-and-example tests are worth more than three perfectly designed ones.

Collaboration, version control, and GitHub

Version control

Version control is a system for recording the history of changes to a set of files over time.

• Every change is saved as a snapshot, with a short message explaining what changed and why, building a complete history of a project
• You can return to any earlier point, see exactly what changed and when, and work out why something broke
• Several people can edit the same files without overwriting each other’s work
• git is by far the most widely used version control system, in research and in industry, and is worth learning properly

For a proper hands-on treatment, see the dedicated git-tutorial.

git and GitHub

git tracks history on your own computer. GitHub, and similar sites like GitLab, host a copy online, so it can be shared, backed up, and collaborated on.

• Commit: a saved snapshot of the project, with a message describing the change
• Branch: an independent line of development, so you can try something new without touching the working version
• Clone: download a full copy of a project, including its entire history, from GitHub to your own computer
• Fork: your own copy of someone else’s GitHub project, which you can change freely, most often used to propose changes to a project you don’t have direct write access to
• Pull request: a request to merge your changes into someone else’s project, or another branch, with a chance for discussion and review before anything is merged
• Merge: combining the changes from one branch, or pull request, into another

• If time allows, a live demo of opening a small pull request against the course repository itself is the single most useful thing to show here: branch, commit, push, open the PR on GitHub, and merge it.
• Worth naming explicitly: a pull request is also where code review happens, which is one of the most effective ways to catch mistakes and spread knowledge around a group, and is a core RSE practice, coming up next.

GitHub story: navani

navani started, like a lot of research software does, as a set of scripts Ben Smith wrote during his PhD to process battery cycler data.

• Other people in the group hit the same problem, reading awkward, instrument-specific file formats, so the scripts were tidied into a proper package, with the same parse-then-do-something shape as today’s demo
• It was published on PyPI, so installing it became one line, uv add navani, instead of emailing someone for a script
• Once it was public, people outside the group started using it, and started filing issues on GitHub asking for new instrument formats to be supported
• New formats have since been added by contributors well beyond the original group, each one arriving with an issue describing the format, and tests to prove it parses correctly

We also have a Grey Group GitHub!

• Checked facts, worth reconfirming before presenting since the project moves: navani is on PyPI, MIT licensed, maintained by Ben Smith, and reads formats from several cycler vendors including BioLogic, Arbin, and Neware.
• Continuous integration (CI), one line only: it is what runs the test suite automatically on every pull request, on GitHub’s own servers, so a new format’s tests are checked before anything is merged, not after.

Research software engineering (RSE)

Put together, everything in this lecture, structuring code, managing environments, version control, and testing, is what the growing field of research software engineering is about.

• RSE is the practice of applying professional software engineering skills to research code, and is now a recognised career path, with its own community, conferences, and job title: a Research Software Engineer
• The goal is not software for its own sake: it is making research faster, more robust, and more reproducible, so results can be trusted and built upon
• Good RSE practice removes duplication of effort: instead of every student in a group writing their own slightly different parser for the same instrument, there is one, tested, shared version
• It is a process, not an end goal: environments get updated, tests get added, code gets refactored, continuously, alongside the science itself

• The UK has an active RSE community (the Society of Research Software Engineering) with regular conferences and a Slack workspace; most large universities now have a dedicated RSE group.
• Personal example, if useful to mention: datalab, referenced on the opening slide of lecture one, exists precisely because this kind of shared, tested, reusable tooling saves a research group from everyone reinventing the same data management scripts.

RSE community

• You can join the UK’s RSE society https://society-rse.org/ who host events, training and job boards

• You could even join the RS-Triple-E https://east-england.society-rse.org/), the East of England RSE group, who meet monthly in Cambridge and online (spoilers: I run this)

• Supposedly there are careers doing this work specifically in academia, with 40 groups in the UK

Wrap-up

• This is deliberately the permission-giving slide: adopting every idea from this lecture on every piece of code is neither realistic nor the point. Judgement about where on this scale a given piece of code sits is the actual skill, and it gets easier with practice, not by doing everything at once.
• Good live examples to offer if useful: a quick plot for your own eyes needs none of this; a script three people in the group now rely on needs a test; a result underpinning a paper’s headline claim needs both structure and real scrutiny, however few people will ever read the code itself.
• The company comparison is worth dwelling on: nobody at a well-run software company writes a full test suite for a five-minute throwaway script either. The skill everyone there has learned is exactly this triage, not blanket rigour.
• Ties back explicitly to “research software engineering, a process, not an end goal”: the process is exactly this incremental adoption, not a checklist completed once.

Not covered

• Logging: beyond print statements to figure out what your code is doing
• Debugging: beyond print statements (again) to find out why it is doing it
• Linting and code style: enforcing best practices automatically (ruff, mypy etc.)
• Packaging and publishing: beyond a single project, how to make your code installable and reusable
• Continuous integration: beyond running tests locally, how to run them automatically on every change
• Documentation: beyond docstrings, how to make your code understandable to others

Take-home messages

• Nobody in this room needs to do all of this, every time, but knowing about the process and adopting it where necessary is important:
  • structuring your code
  • testing
  • version control
  • collaboration
• This is not an academic ideal. It is how almost every company, software or otherwise, actually operates.
• AI doesn’t solve this – the coordination problem of software development still exists

Further reading

• Software Carpentry: https://software-carpentry.org/
• Intermediate RSE with Python https://carpentries-incubator.github.io/python-intermediate-development
• Git tutorial (by me) https://github.com/ml-evs/git-tutorial
• Accelerate course (Cambridge): https://science.ai.cam.ac.uk/resources/python-programming-for-science
• Part II Computational Physics (Cambridge): https://computational-physics.tripos.org/
• CS50 Introduction to Computer Science and CS50P Python (Harvard): https://cs50.harvard.edu/python/

AI code generation and agents (optional)

Chat windows versus coding agents

Most people’s first experience of AI and code is a chat window: paste in a function, ask a question, copy the answer back into the editor by hand.

• A chat tool like ChatGPT sees only what you paste in, and its answer only exists as text in a chat window. Every change still has to be copied back by hand
• A coding agent, sometimes called a harness, instead runs alongside the actual project: it can read files, run tests, execute commands like git or uv, and edit files directly
• That difference matters in practice: an agent that can run pytest itself, see a failure, and try again is doing something a copy-paste chat window structurally cannot
• Claude Code, GitHub Copilot’s agent mode, Cursor, and OpenCode are all harnesses in this sense, not just chat windows
• Lots of free options out there!

• This slide deck, refined live across two lecture-prep sessions, was itself built with exactly this kind of harness, reading and editing the .qmd files directly rather than being pasted in and out of a chat window.
• The general shape to narrate: describe an operation in plain English, watch the agent read the relevant files, propose or apply an edit, run a check, and report back, rather than receiving one single, unverified answer.

Vibe coding vs pair programming

• Agents will not do RSE for you (unless you tell them)
• A coding agent is very good at producing code that matches whatever it is shown. It is not, by itself, good at deciding whether code should be well structured, tested, or version controlled.
• An agent pitches its code to your level: if the surrounding codebase is one long hard-coded script, that is what it will tend to extend
• Left unprompted, an agent will happily produce a working, untested, unstructured function, because “it ran successfully” is often enough to satisfy the request as asked
• Everything from this lecture is still something you have to ask for, or set up once so it happens by default: clear responsibilities, a proper environment, tests, sensible commits
• The tools change fast. The judgement about what good research software looks like does not, and that judgement is the actual subject of this course

An AI coding tool is most helpful when you already know what you want to write, and can tell whether what it produces is actually correct (via tool calls to e.g., run tests).

• A useful framing for the room: an agent is an extremely capable pair of hands, not a substitute for engineering judgement. It will write tests if asked, and can write thorough ones, but usually will not volunteer to unless the project already has a testing habit for it to follow.
• This is the closing thought of the whole two-lecture course: everything from bits and types through to functions, environments, and testing exists to build exactly those two skills, knowing what correct code should look like, and being able to check that it is.
• Concrete demo idea, if time allows: ask the agent to “add a function to do X” with no further guidance, then ask again for the same task but explicitly requesting a parametrised function with a test, and compare the two results side by side.
• This closes the lecture’s arc: structure, environments, testing, version control, and RSE as a discipline are precisely the checklist an agent will not reliably apply on its own.

How this deck actually got made

• Every slide here was built one at a time, across many sessions, in conversation with Claude Code, not generated from a single prompt
• Real commands ran the whole way through: compiling C and Fortran, timing the Mandelbrot demos, checking image licences before downloading anything, and once, tracking down a genuine compiler bug in a Fortran do concurrent loop
• Plenty of ideas were tried and then undone. A “try it yourself” box got added, then removed the same afternoon, because it did not feel right
• One rule applied to every new slide in this lecture: no em dashes, anywhere. The next slide is what happens the moment that rule gets lifted, on purpose

• Good moment to be honest with the room about what this process actually was: not “AI wrote my lecture,” closer to pair programming, with Matt directing every decision and Claude Code doing the typing, the checking, and the occasional deep dive into a segfault.
• Worth naming explicitly: nothing in this deck went in unreviewed. Every fact was checked, most images were licence-checked, and several drafts were rejected outright, including, at one point, this very sentence.