1  Introduction

I will start with anecdote—an email thread that has actually happened in real file, in which I am only replacing one of the names for preserving the privacy of the persons involved.

Luca: good morning, Dave! Would you mind sharing the exact model parameters for your nice paper about Cyg-X1? And, if at all possible, the entire XSPEC session for the spectral analysis, so that I can re-run it? I am trying to simulate the source for a data analysis challenge I am preparing for the IXPE collaboration and I would like to start from the state of the art.

David: sure thing! The parameters are in the paper!

Luca: well, I have read the paper. Not all the relevant parameters are listed in table 2, and I am unable to repeat the analysis at this time.

David: oh, well… unfortunately that particular analysis was done on my old laptop, and I had to give it back to my previous employer, when I changed institution a couple of years back. I have no more access to that material.

David: ah! And, by the way, a couple of the fit parameters were running all the way up to their boundaries, so I would not trust the fit too much…

1.1 Reproducibility

Reproducible: (adjective) able to be shown, done, or made again. Source: the Cambridge Dictionary

Pretty simple, eh? Most of us would agree that research should be correct and reproducible. You don’t just want to get things right the first time. You also want to be able to get them right again the second time around—be that tomorrow, a year or a decade from now. You also want your fellow colleagues scientists to be able to reproduce what you published, should they be interested in doing so.

Reproducible research is data analysis that arrives to the same answer when starting from the same raw data.

The fact is, often times physicists are better at correctness than reproducibility. There are entire communities (which I will refrain from naming) that are lagging behind on the best practices that are ubiquitous among professional software developers. This, in turns, tend to result in poor-quality software.

While there are many reasons why that is actually happening—none of us is a software engineer by training, and it is totally legitimate for us to focus on science rather than software—but we argue that software plays a paramount role in modern experimental physics, and is therefore a crucial ingredient in reproducibility of research. It should be developed under controlled conditions, just like the experiments are performed.

This is what these notes are about. It will be boring all along the way, but if you do pay attention and are willing to entertain the notion that this might be actually useful in the long term… well, you might be surprised!

1.2 More ranting

Most certainly, all of you have written code in their life—no matter in which language or how complex that was. Now, think about that for a second, and try answering a few simple questions.

• Would somebody else able to use it without your help?
• Would it run as is on somebody else’s computer?
• Would you be able to adapt it for somebody else’s computer?
• Would you be able to run it on your computer now?

If the answer to any of those questions is no, that doesn’t necessarily mean that something went horribly wrong, but you shall agree that things might have probably gone better than they did.

(And note we are just ignoring the efficiency of your code, at this time. Could your software run significantly faster, and would you care if it did? We shall come back on this one, and learn that premature optimization is the root of all evil, but just to be clear: we are not even asking if the code you produces was optimal in any sense—just if you think you could get it to do the same thing twice. Not a very high bar.)

And now take a quick look at the last paper that you have read. (You do read papers, do you?) Do you think that, given enough time, it would be possible to re-run the same analysis and obtain exactly the same results? Note this implies a number of things, none of which is immediately obvious…

• Have the raw data been preserved in a readable format?
• Is the analysis software still available?
• Is there still somebody around understanding what the software does?
• Are there machines around that can run the analysis software?

Spoiler alert: you would be shocked in many cases.

Due to a number of coincidences I cannot even explain, I happen to be a high-energy astrophysicist, and I know first-hand that NASA makes a deliberate effort for all the data from the high-energy mission to continue to be readable across the decades. This is largely achieved, at least in principle, via the FITS standard and the HEASARC archive of analysis software and calibration products.

Is this a good thing or a bad thing? Well, the intent is admirable—although being anchored to a standard that was cast in stone in 1993, and builds upon software and formats that were already decades old at that time does not exactly strikes as something that would look anywhere close to high-performance computing in 2026. (Is it only me or the FITS standard page still has that distinct nineties look and feel?)

But even letting that go for a second, this brings us back to the anecdote at the beginning of the chapter: if we do not proactively seek reproducibility in our day-to-day workflow, there is very little that standards can do!

1.3 Developing software collaboratively

Most modern high-energy physics experiments are run by large teams—the big LHC collaborations count thousands of members. This immediately brings up a number of difficult questions. For instance:

• How do you handle development in such an environment?
• How do you distribute the source code?
• How do you know which version is any single person running?
• How do hundreds of people develop the same code concurrently?
• How do you make sure that your last awesome change isn’t breaking everybody else’s code?

Now, depending on what you decide to do for a living, you might or not end up in a big collaboration. You might work in a small team, instead. The thing is: the scale of the challenges will be different, but their nature will be pretty much the same. At the end of the day you will have to decide how you exchange code with your collaborators, how you collect feedback, how you distribute updates—in a sentence how you keep track of the development.

(If you bring this to its extreme consequences, you will immediately realize that in fact all of the above still holds event when you develop software by yourself.)

1.4 And so what?

All right. Lots of hard questions. How do we fix all of this?

Well, the first thing is a terribly boring thing most likely you have never heard of: version control. Much of these notes is directly connected, one way or the other, to version control. Hopefully when you get to the last page you will have everything under version control—from your master thesis down to your shopping list.

But before we dive into the matter we have to make sure we have something to version control, which is why in the next chapter we shall take a brief detour wondering into the magic of Python.