change the course narrative to start with the optimisation

Author: msarkis-icr

episodes/long-break1.md

@@ -1,5 +1,5 @@
 ---
-title: Break
+title: Lunch Break
 teaching: 0
 exercises: 0
 break: 60

episodes/optimisation-introduction.md

@@ -18,37 +18,37 @@ exercises: 0
 
 ## Introduction
 
-<!-- Enable you to look at hotspots identified by compiler, identify whether it's efficient -->
-Now that you're able to find the most expensive components of your code with profiling, it becomes time to learn how to identify whether that expense is reasonable.
-
+<!-- Changing the narrative: you'd better learn how to write a good code an what are the good practice -->
+Think about optimization as the first step on your journey to writing high-performance code.
+It’s like a race: the faster you can go without taking unnecessary detours, the better. 
+Code optmisation is all about understanding the principles of efficiency in Python and being conscious of how small changes can yield massive improvements.
+  
 <!-- Necessary to understand how code executes (to a degree) -->
-In order to optimise code for performance, it is necessary to have an understanding of what a computer is doing to execute it.
+These are the first steps in code optimization: making better choices as you write your code and have an understanding of what a computer is doing to execute it.
 
 <!-- Goal is to give you a high level understanding of how your code executes. You don't need to be an expert, even a vague general understanding will leave you in a stronger position. -->
-Even a high-level understanding of how you code executes, such as how Python and the most common data-structures and algorithms are implemented, can help you to identify suboptimal approaches when programming. If you have learned to write code informally out of necessity, to get something to work, it's not uncommon to have collected some bad habits along the way.
+A high-level understanding of how your code executes, such as how Python and the most common data-structures and algorithms are implemented, can help you identify suboptimal approaches when programming. If you have learned to write code informally out of necessity, to get something to work, it's not uncommon to have collected some bad habits along the way.
 
 <!-- This is largely high-level/abstract knowledge applicable to the vast majority of programming languages, applies even more strongly if using compiled Python features like numba -->
 The remaining content is often abstract knowledge, that is transferable to the vast majority of programming languages. This is because the hardware architecture, data-structures and algorithms used are common to many languages and they hold some of the greatest influence over performance bottlenecks.
 
-## Premature Optimisation
+## Optimising code from scratch: trade-off between performance and maintainability
 
 > Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: **premature optimization is the root of all evil**. Yet we should not pass up our opportunities in that critical 3%. - Donald Knuth
 
 This classic quote among computer scientists states; when considering optimisation it is important to focus on the potential impact, both to the performance and maintainability of the code.
 
-Profiling is a valuable tool in this cause. Should effort be expended to optimise a component which occupies 1% of the runtime? Or would that time be better spent focusing on the most expensive components?
-
 Advanced optimisations, mostly outside the scope of this course, can increase the cost of maintenance by obfuscating what code is doing. Even if you are a solo-developer working on private code, your future self should be able to easily comprehend your implementation.
 
 Therefore, the balance between the impact to both performance and maintainability should be considered when optimising code.
 
-This is not to say, don't consider performance when first writing code. The selection of appropriate algorithms and data-structures covered in this course form good practice, simply don't fret over a need to micro-optimise every small component of the code that you write.
+This is not to say, don't consider performance when first writing code. The selection of appropriate algorithms and data-structures covered in this course form a good practice, simply don't fret over a need to micro-optimise every small component of the code that you write.
 
 
-## Ensuring Reproducible Results
+## Ensuring Reproducible Results when optimising an existing code
 
 <!-- This is also good practice when optimising your code, to ensure mistakes aren't made -->
-When optimising your code, you are making speculative changes. It's easy to make mistakes, many of which can be subtle. Therefore, it's important to have a strategy in place to check that the outputs remain correct.
+When optimising an existing code, you are making speculative changes. It's easy to make mistakes, many of which can be subtle. Therefore, it's important to have a strategy in place to check that the outputs remain correct.
 
 Testing is hopefully already a seamless part of your research software development process.
 Test can be used to clarify how your software should perform, ensuring that new features work as intended and protecting against unintended changes to old functionality.

episodes/profiling-introduction.md

@@ -22,6 +22,9 @@ exercises: 10
 
 ## Introduction
 
+<!-- what if my code is not performnant -->
+But what if, despite your best efforts, performance still isn’t up to par? This is where profiling comes into play — and it’s a game-changer. You can’t always guess what’s slow. Profiling helps you see hidden inefficiencies that might be buried deep within the code.
+
 <!-- Profiling is (what) -->
 Performance profiling is the process of analysing and measuring the performance of a program or script, to understand where time is being spent during execution.
 

learners/setup.md

@@ -22,8 +22,12 @@ This course uses Python and was developed using Python 3.11, therefore it is rec
 
 You may want to create a new Python virtual environment for the course, this can be done with your preferred Python environment manager (e.g. `conda`, `pipenv`), the required packages can all be installed via `pip`.
 
-<!-- conda create -n pando python
-     conda activate pando -->
+To create a new Anaconda environment named `py311_env` with Python 3.11, use the following command for conda:
+
+```bash
+     conda create --name py311_env python=3.11
+     conda activate py311_env
+```
 
 The non-core Python packages required by the course are `pytest`, `snakeviz`, `line_profiler`, `numpy`, `pandas` and `matplotlib` which can be installed via `pip`.