Add motivation section including green computing info

[liz-is]

This PR adds a "Motivation" section to the "Summary and Setup" page, to give some background on how profiling and optimisation can be helpful.

My personal motivation for adding this was to make an explicit link to computing sustainability, but I tried to also include all the other key reasons to optimise your code! Happy to make additional edits if something is missing.

[github-actions]

Thank you!

Thank you for your pull request 😃

🤖 This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• 🎯 correct output
• 🖼️ correct figures
• ❓ new warnings
• ‼️ new errors

Rendered Changes

🔍 Inspect the changes: https://github.com/carpentries-incubator/pando-python/compare/md-outputs..md-outputs-PR-30

The following changes were observed in the rendered markdown documents:

 index.md   | 19 +++++++++++++++++++
 md5sum.txt |  2 +-
 2 files changed, 20 insertions(+), 1 deletion(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible.

This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

⏱️ Updated at 2026-02-05 15:37:50 +0000

[Robadob]

Added a couple of suggestions to suite my own taste, however it looks good in principle. Will leave final approval to @JostMigenda as I presume you work closely.

E.g. ignore my comments if you feel like it. They're definitely rough, and I'd probably feed them through GPT to clean them up if I were writing it.

[Robadob]

Rough tweak, putting a bit more emphasis on confidence in code quality (e.g. there's still a benefit even if profiling looks reasonable)

Suggested change

	The simplest answer is that optimisation let you get results faster. It may also allow you to scale up your code to perform larger analyses that would otherwise have taken too long to be practical.
	The simplest answer is that profiling helps you validate that the performance of your code matches your expectations. If it doesn't, then you'll either identify an optimisation which will let you get results faster, or have gained a better understanding of what your code is doing.

[JostMigenda]

Hm … this is probably dependent on the target audience? I think for experienced software engineers, profiling becomes more about confirming that the performance matches expectations; but software performance is notoriously unintuitive—and especially so in a high-level language like Python, where you’d need to understand an additional layer of language implementation details to develop a decent intuition.

For the target audience of this course, I’d expect that most of them don’t have a well-developed intuition (yet—that’s part of what we try to develop in the optimisation section, after all!) … so I don’t think opening with this as the main motivation is a good fit.

[Robadob]

That's fair, however I'd contend that many of the most obvious performance issues in novice code flagged by a profiler require no expertise to identify beyond being the author of the code.

E.g. an old crude validation method, file IO or merely anything that isn't the "computational" bit of an algorithm.

However, I have definitely seen cases where it's not immediately obvious to the "novice", e.g. bespoke C++ vector class, nothing is inlined, their response was "well that's the maths, of-course it's expensive (or something to that effect).

Your position definitely applies to the more nuanced stuff, such as using NumPy and data-structures correctly though.

[JostMigenda]

If we want to include this, I’d probably leave Liz’ writing unmodified and rather add a separate paragraph at the end—maybe framing it like “Even if you don’t find any major performance gains, this will be useful because … [confidence, better understanding, …]”

[Robadob]

Trying to merge in the bit I had to strip out above.

Suggested change

	Making your code faster can have additional benefits: faster software uses less compute power. If you use paid-for compute resources, such as cloud computing or some HPC facilities, optimising your code can therefore reduce your costs.
	Making your code faster can either enable larger analyses that would otherwise be impractical or reduce redundant computation. If you use paid-for compute resources, such as cloud computing or some HPC facilities, optimising your code can therefore reduce your costs.

[JostMigenda]

I don’t think that works with the following sentence—enabling larger analyses (implicitly: using the same resources) will not “reduce your costs”, it will just get more results at the same cost.

[Robadob]

true, "reduce your cost per unit of work", but that sounds shit.

[Robadob]

And you've now made me review this recent longform article, I don't think I even mentioned get more work done/larger models/less energy (though I did cover coding confidence in the last paragraph before case studies!).

https://sig-rpc.github.io/getting-started/

[JostMigenda]

Suggested change

Using less compute power also helps make your software more environmentally sustainable. As funders and research insitutions set Net Zero goals, and computationally-intensive research expands, sustainability is increasingly becoming a concern for researchers. Energy efficiency, alongside hardware efficiency and carbon awareness, is one of the key principles of reducing carbon emissions from software.

Using less computing power also helps make your software more environmentally sustainable. As funders and research insitutions set Net Zero goals, and computationally-intensive research expands, sustainability is increasingly becoming a concern for researchers. Hardware efficiency, alongside energy efficiency and carbon awareness, is one of the key principles of reducing carbon emissions from software.

Using “compute” like that feels too informal to me?

Separately—why the emphasis on energy efficiency in the last sentence? Isn’t hardware efficiency the thing that software developers can influence best by optimising their code? Or am I misunderstanding what the two mean?

[liz-is]

I think of them like this: energy efficiency = doing the same work with less energy, hardware efficiency = using existing hardware to its full capacity (e.g. actually using all the HPC resources you request).

Optimising your code can help you do more work on the same hardware at the same time - but it gets there via being more CPU efficient, and therefore more energy efficient. Does that make sense?

Maybe we need to include full definitions of energy and hardware efficiency in the text?

[JostMigenda]

Huh, then I did have a different understanding of these terms. I think our key difference is in what we mean by “same work”. I intuitively thought of it as “performing the same operations with less energy” (so e.g. a new CPU would be more energy efficient if it needs fewer Watts to perform 1B floating point operations), whereas yours is more like “performing the same task with less energy” (e.g. by using a clever implementation) if I understand you correctly.

And instead, I thought of “performing the same task with less RAM/fewer CPU cycles/etc.” as hardware efficiency.

Good to understand our misunderstanding there! 🫣

So, yes, these terms are not quite obvious and defining them on first use would probably help clarify things. That said, in the context of a Motivation section, going into the definitions feels like a distraction to me. “Funders and institutions care about this, so you need to, too” in the sentence before is an excellent motivation; background explanations about these three principles are not (especially if two out of three are things that the software author has no control over). So maybe we should just drop that final sentence completely?

[JostMigenda]

Suggested change

	However, it's sensible to focus your optimisation efforts on the parts of the code that take the longest. This is where profiling comes in: by profiling your code, you can identify which parts contribute the most to its runtime, and target these for optimisation.
	However, it's sensible to focus your optimisation efforts on the parts of the code that take the longest. This is where profiling comes in: By profiling your code, you can identify which parts contribute the most to its runtime, and target these for optimisation.

Feel free to ignore if this is something where different style guides disagree, but I was taught to use sentence case after a colon if a complete sentence follows.

[JostMigenda]

Suggested change

Using less compute power also helps make your software more environmentally sustainable. As funders and research insitutions set Net Zero goals, and computationally-intensive research expands, sustainability is increasingly becoming a concern for researchers. Energy efficiency, alongside hardware efficiency and carbon awareness, is one of the key principles of reducing carbon emissions from software.

Using less compute power also helps make your software more environmentally sustainable. As funders and research institutions set Net Zero goals, and computationally-intensive research expands, sustainability is increasingly becoming a concern for researchers. Energy efficiency, alongside hardware efficiency and carbon awareness, is one of the key principles of reducing carbon emissions from software.