diff --git a/book/_toc.yml b/book/_toc.yml
index 2f9af635766e65953831aa32ffe49877326addd5..02700e480a54d300e04cde7a86f41cc6047a53d9 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -2,9 +2,20 @@ format: jb-book
root: intro
parts:
- - caption: New Material
+ - caption: Programming
chapters:
- - file: new/blank
+ - file: programming/overview
+ title: Overview
+ - file: programming/golden_rules_dont_execute.ipynb
+ title: The Golden Rules
+ - file: programming/computers/overview
+ title: Computers
+ - file: programming/code/overview
+ title: Code
+ - file: programming/programs/overview
+ title: Programs
+ - file: programming/communication/overview
+ title: Communication
- caption: Sandbox
chapters:
- file: sandbox/blank
diff --git a/book/intro.md b/book/intro.md
index 2292ffa80c680d6048859b130de815392f7794cb..5d7d4566f3ed006fddfde8c605908c0d5586ed5b 100644
--- a/book/intro.md
+++ b/book/intro.md
@@ -1,8 +1,27 @@
-# Home
+# Welcome to the MUDE Textbook
-```{note}
+Welcome to the MUDE textbook.
+
+_this is where stuff will be written later_
+
+````{admonition} Update for MUDE Teachers
+:class: note
+I got rid of the README that used to be here, because you should have your workflow set by now, and you should know by now that you can always check it on GitLab [here](https://gitlab.tudelft.nl/mude/book/). **I'll put recent updates here for the 2 weeks leading up to the start of Q1**:
+- Draft of Programming Part is ready---the first content for the "new" book to be placed! Note that it is located in `book/book/programming`.
+- As you finalize the ToC for your material, move it to the same level directory as the programming part. All Parts should be a sub-directory of `book`.
+- By the start of Q1, all material in `cookbook`, `old`, `sandbox` should be removed, moved or hidden (preferably by YOU!)
+````
+
+````{admonition} Dicatorial Proclamation by the MUDE Manager
+:class: warning
+The MUDE content formerly known as **coding** shall henceforth be called **programming.**
+
+Don't like it? Too bad, maybe you can become manager next year and change it back. I have plenty of reasons, but rather than type them I believe they are better discussed over a cold beverage.
+````
+
+<!-- ```{note}
Right now, the home page of the book simply displays `README.md` which is located at `./book/` or you can [read on GitLab here](https://gitlab.tudelft.nl/mude/book/-/blob/main/README.md).
```
```{include} ../README.md
-```
+``` -->
diff --git a/book/new/blank.md b/book/new/blank.md
deleted file mode 100644
index ac8948e6de7cd9d99bf2499c11bb42a56c368b07..0000000000000000000000000000000000000000
--- a/book/new/blank.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# blank chapter
-
-There is no content here yet. This file is a chapter. Use this for unorganized material. If it's organized (e.g., the prob design/risk part) it does not need to go into `book/book/new/`
\ No newline at end of file
diff --git a/book/programming/code/overview.md b/book/programming/code/overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..3ab2e6e44eff7605f6225c1d1a0b07007e475e03
--- /dev/null
+++ b/book/programming/code/overview.md
@@ -0,0 +1,7 @@
+# Code
+
+text. Matlab also high level and multi-purpose like Python.
+
+Things that will definitely go here:
+- functions (a brief overview/highlight of features, then link to the object part of programs)
+- complexity: where does it come from and why is it important (work backwards to know which concepts need to be included (e.g., bits and flops etc)); can find good reference rather than repeat chapters of numerical analysis textbook material
\ No newline at end of file
diff --git a/book/programming/communication/overview.md b/book/programming/communication/overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..8bd01f8d16276f92b583c26f6647cda08aca7c05
--- /dev/null
+++ b/book/programming/communication/overview.md
@@ -0,0 +1,3 @@
+# Communication
+
+text.
\ No newline at end of file
diff --git a/book/programming/computers/overview.md b/book/programming/computers/overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..13c659f033f96443eaf7b7c296ac0ffd257689b7
--- /dev/null
+++ b/book/programming/computers/overview.md
@@ -0,0 +1,4 @@
+# Computers
+
+text.
+
diff --git a/book/programming/golden_rules_dont_execute.ipynb b/book/programming/golden_rules_dont_execute.ipynb
new file mode 100644
index 0000000000000000000000000000000000000000..c3d9fb8e1bc80eeaddc3d06205ab4399cc58ce66
--- /dev/null
+++ b/book/programming/golden_rules_dont_execute.ipynb
@@ -0,0 +1,556 @@
+{
+ "cells": [
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "id": "6c618b60",
+ "metadata": {},
+ "source": [
+ "(programming-gr)=\n",
+ "# The Golden Rules\n",
+ " \n",
+ "*This is the first document presenting the MUDE Golden Rules of Code, a series of guidelines and reccommendations that are focused on promoting good habits related to coding and programming. We expect to periodically update this document and perhaps share other topics in the 'Golden Rules' series. Whether you are a student, teacher or practitioner, we encourage you to refer back to this document often and feel free to share.*\n",
+ "\n",
+ "*We greatly appreciate feedback from anyone, especially students (send to R.C.Lanzafame@tudelft.nl).*\n",
+ "\n",
+ "Contributors: Robert Lanzafame, Kiril Vasilev and a list of reviewers, too long to name.\n",
+ "\n",
+ "<div class=\"alert alert-block alert-success\">\n",
+ "<b> Note to MUDE Students </b>\n",
+ " \n",
+ "For the September 13 workshop, you should read the entire document, but if short on time focus on Rules 1, 2, 3 and 5 (but only the one-line docstrings for 5). Some topics will be revisited or extended in later workshops. You are not required to install `autopep8`, but we reccommend it since it is easy to use. You are expected to incorporate the guidelins in this document progressively throughout the semester, so we suggest you refer to it often.\n",
+ "</div>"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "id": "9c81abf5",
+ "metadata": {},
+ "source": [
+ "## Why do the Golden Rules for Documentation and Communication exist?\n",
+ "\n",
+ "You will spend a lot of your study hours in the MUDE module writing, reading and debugging Python code, regardless of your prior programming experience. Your time is valuable, especially once you start working after graduation! Yet it is all too common that most code is never re-used because it is poorly *documented*, making it not understandable to others, or even to yourself at a later moment. In addition, as a young practicing engineer or researcher it is critical that you are able to use your code to effectively *communicate* your results, otherwise the effort put into your analysis is wasted. Good code writing, code documentation and presentation of results such as figures, tables and numbers are all essential for effective collaboration. Even when working individually, it is important to preserve your work such that you can easily understand and re-use in the future. This document will provide and explain a number of reccommendations to help you accomplish that.\n",
+ "\n",
+ "The following quote summarizes the philosophy of this document concisely:\n",
+ "\n",
+ "<div style=\"text-align: right\"><em>Any fool can write code that a computer can understand. Good programmers write code that humans can understand.</em></div> \n",
+ "<div style=\"text-align: right\"><em> ― Martin Fowler </em></div> \n",
+ "\n",
+ "### A note of encouragement\n",
+ "\n",
+ "This document contains a lot of information that might not appear to be useful to you...*yet*. Keep in mind that the content here was created in collaboration with many colleagues who are working in industry and will be looking to hire you after you graduate from TU Delft: they will appreciate good coding documentation and communication skills! Our primary advice in MUDE, and for the rest of your MSc program, is that you take a look at this material now, but also keep the Golden Rules in mind and refer back to them often. If you can incorporate them into your work in MUDE, you will have made good habits for yourself that we know will serve you well in the future. \n",
+ "\n",
+ "We focused on illustrating good coding practice in a format and language that is approachable to engineers with a varied programming background. As such, specific fundamental programming and computer science concepts are avoided. If you would like to learn more about theses concepts, specifically related to Python, the textbook by Guttag (2021) is an excellent reference."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e283df9f",
+ "metadata": {},
+ "source": [
+ "## Contents\n",
+ "- [Documentation and Communication](#Documentation-and-Communication)\n",
+ "- [The Golden Rules](#The-Golden-Rules)\n",
+ "- [References and resources](#References-and-resources)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2245c370",
+ "metadata": {},
+ "source": [
+ "## Documentation and Communication\n",
+ "\n",
+ "The words in the title of this lesson were chosen very carefully. *Documentation* refers to all the work related to a problem you are working on. In MUDE, documentation is not limited to describing the purpose and function of your code only. Clearly documented code is important, but in CEG it is also critical to describe all the steps in your analysis, for example: data and data sources, assumptions, results, discussion and recommendations. Jupyter notebooks provide the ideal platform for combining documentation and analysis in one file, which is why we rely on them heavily in MUDE and the focus of this lesson. However, remember there are many other options available to you for proper documentation of your work, and the topics we cover here always apply. \n",
+ "\n",
+ "*Communication* refers to how you use your code, the analysis you run and the format by which you share it. Rarely are you running a piece of code purely for yourself, but often to share with others---perhaps for a homework assignment, to include in a thesis, a scientific publication, a design at a consultancy, et cetera. Why go through all the trouble of writing and using code if no one can understand what you did with it? It may be clear to you right now, but what if someone wants to use it in the future, or ask about your results, when you are not there? Will the audience understand your work if you have unreadable or overly complex tables and figures in a MSc thesis or conference presentation? Good communication is therefore critical, and there are many aspects, for example: visual formatting (visual appearance of code, text output, figures, tables); transparency and understadability (what did you do? is it repeatable? will someone understand it in the future, perhaps out of context?); and, for code explicitly: readability. This lesson provides a number of useful guidelines that will help your communication improve.\n",
+ "\n",
+ "In summary, the title of this document is a bit simplistic. In reality, it should be: *the Golden Rules: a non-exhaustive list of highly recommended habits to build into your life to make sure you can easily and consistently document your work in a way that ensures effective communication with others, as well as your future self.* But that doesn’t roll off the tongue like our current title does. And it doesn’t fit in 79 characters either 😉."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ac1ccc55",
+ "metadata": {},
+ "source": [
+ "## The Golden Rules\n",
+ "\n",
+ "These are the Golden rules:\n",
+ "1. [Use descriptive names](#Rule-1:-Use-descriptive-names)\n",
+ "1. [Make readable code](#Rule-2:-Make-readable-code)\n",
+ "1. [Make readable results](#Rule-3:-Make-readable-results)\n",
+ "1. [Write simple functions, then use them](#Rule-4:-Write-simple-functions,-then-use-them)\n",
+ "1. [Document your code](#Rule-5:-Document-your-code)\n",
+ "1. [Test your code](#Rule-6:-Test-your-code)\n",
+ "1. [Learn to collaborate](#Rule-7:-Learn-to-collaborate)\n",
+ "\n",
+ "The sections below will provide explanations and examples of each Golden Rule, but first we need to introduce something that may seem like it belongs in a Computer Science course. However, we will see that it contains a number of useful guidelines and insight into how one can write readable Python code: the PEP-8 Style Guide."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a98880d3",
+ "metadata": {},
+ "source": [
+ "## Style Guide for Python (PEP 8)\n",
+ "\n",
+ "PEP stands for Python Enhancement Proposals, which is how the Python community describes new features and guidelines related to the development and (reccommended) use of the programming language. Although there are many [PEPs](https://peps.python.org/), the MUDE Golden Rules are in part inspired by one in particular: [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/). PEP 8 is important because it directly addresses the readability of Python code and is thus directly aligned with the objectives of our Golden Rules. Unfortunately, PEP 8 can also seem boring, tedious and unimportant to engineers who are learning to use Python. The Golden Rules are created in part to help with this, so for now, we ask that you read carefully the [first](https://peps.python.org/pep-0008/#introduction) and [second](https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds) sections of PEP 8 to help understand the general motivation, then scan through PEP 8 to get an idea of the structure. You may want to use the website [pep8.org](https://pep8.org/), which uses text formatting and is (visually) much easier to read. Don't just open the website; you should devote at least 15 minutes reading the text and example code and consider how this might influence the way you write code. You don't need to read every word, but rather focus on the background, justification and examples for the sections that are most relevant to us: \n",
+ "- Code lay-out: indentation, line length, line breaks, blank lines\n",
+ "- Whitespace\n",
+ "- Comments\n",
+ "- Naming conventions \n",
+ "\n",
+ "After around 15 minutes of reading, you should have a good idea of the general philosophy and specific ways to change the way you write Python code. Many of these guidelines are incorporated into the Golden Rules, but sometimes PEP 8 will provide more detail or background, and most importantly: example code. Therefore, you should bookmark the website and refer back to it often.\n",
+ "\n",
+ "You may have noticed that checking some of the PEP 8 guidelines could be quite tedious, like counting 4 spaces on indentation or checking to make sure there are no spaces at the end of a line. This is just the type of thing that computers are good at! Fortunately there are a number of tools available to autocheck (and even autocorrect) Python code based on some (but not all!) of the reccommendations in PEP 8. The elements of PEP 8 that are most relevant to us are summarized here: \n",
+ "- Indentation\n",
+ "- Whitespace and blank lines\n",
+ "- Line length and line break location\n",
+ "- Import statements\n",
+ "\n",
+ "Compliance with PEP 8 is carried out by the package [`pycodestyle`](https://pycodestyle.pycqa.org/), and you can see a detailed list of what is being checked in your code by looking at the the [list of error codes](https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes). There are a few other PEP 8 guidelines that are not included in the list above or in our Golden Rules (specifically, issues in the statement and runtime groups in `pycodestyle`). If these come up as warnings or errors when reviewing your code with an autochecker you can read more about what the problem is in the PEP 8 documentation.\n",
+ "\n",
+ "The next section covers PEP 8 autocheckers, but you should **always remember: only a subset the PEP 8 guidelines can be evaluated by automatic PEP 8 checkers and fixers.** For example, a computer cannot tell you whether or not your variable name is descriptive enough, or consider what variable name length is appropriate for the specific piece of code you are writing---this is something that you must determine on your own or with your team that may be hard at first, but becomes easier with a bit of practice. To convey this perspective, we adapt the quote by Martin Fowler given above:\n",
+ "\n",
+ "\n",
+ "<div style=\"text-align: right\"><em>Any fool can use </em><code>autopep8</code><em> to comply with PEP 8 guidelines. Good engineers use PEP 8 carefully to write code that humans can understand.</em></div> \n",
+ "<div style=\"text-align: right\"><em> ― MUDE Golden Rules, adapted from Martin Fowler </em></div> "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a85327b9",
+ "metadata": {},
+ "source": [
+ "### Checking PEP 8 automatically with `autopep8`\n",
+ "\n",
+ "Although PEP 8 may look quite complicated and tedious at first glance, automatic PEP 8 formatters exist. The one we recommend you to use is `autopep8`, which can be applied on both `.py` files and `.ipynb` jupyter notebooks. A full explanation about the capabilities of this tool can be found at the [Python Package Index page](https://pypi.org/project/autopep8/). \n",
+ "\n",
+ "*Bonus tip: the Python Package Index, PyPI, is the official website for Python software, where most publicly available packages can be found, and is the default source when you install packages using `pip`.*\n",
+ "\n",
+ "#### Installation (Optional, but reccommended)\n",
+ "In order to install `autopep8`, you can simply run the following `pip` command in your terminal:\n",
+ "```bash\n",
+ "pip install autopep8\n",
+ "```\n",
+ "\n",
+ "#### Usage\n",
+ "\n",
+ "You can run the following command to auto-format python files and jupyter notebooks in-place. After the command execution has finished, your files will have been autoformatted. Make sure you replace `<filename>` with the name and extension of the file you wish to auto-format.\n",
+ "```bash\n",
+ "autopep8 --in-place <filename>\n",
+ "```\n",
+ "\n",
+ "#### Additional Resources\n",
+ "\n",
+ "`autopep8` can be added as an extension to JupyterHub, which allows you to interact with the tool through a Jupyter Notebook rather than the terminal. This can be achieved with the help of a `Jupyter Nbextensions Configurator`, which you may need to install first, before setting up `autopep8` as an extension.\n",
+ "\n",
+ "Many of the IDEs such as Spyder and PyCharm contain add-ons that can be installed to automate the PEP 8 checks. Rather than providing a long list of installation instructions here, we'd encourage you to already get started with Rule X: using Google and Stack Overflow to help you identify and install a PEP 8 tool that will work for you. If you are using the JupyterHub, you can always copy and paste text into [PEP8 Online](http://pep8online.com/), as done in the first example above."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "909271f9",
+ "metadata": {},
+ "source": [
+ "## Rule 1: Use descriptive names\n",
+ "\n",
+ "*My colleague/student constantly shares code with me but the variables are acronyms and are overwritten, which makes it difficult to read and use.*\n",
+ "\n",
+ "*X1, X2, X3... oh, again X1 (overwrite). Was the previous X1 important?*\n",
+ "\n",
+ "Often when you work, you will be sharing your code with other people and you need make sure that they understand what each variable is doing and how it relates to the other variables. However, this may difficult or even impossible when the variable names do not represent the purpose they have.\n",
+ "\n",
+ "For example, variable names such as `a`, `a1`, `x`, `plot`, `plot1` may not be descriptive enough to use in your code. Additionally, `kruidnoten` may not be a good variable name for a weather time series plot.\n",
+ "\n",
+ "Coming up with descriptive names requires practice, but when in doubt don't be afraid to use longer names to be specific. It's easy to change names in a script later with find and replace. The only downside if your names are too long is that you have to add a few more line breaks (we give you a few tips for this in ***Golden Role***), however, the downside of names that are too short is that you or a colleague has to spend hours in the future interpreting, or even rewriting your code.\n",
+ "\n",
+ "However, there are some names to avoid. Namely, never use the characters `l` (lowercase letter el), `O` (uppercase letter oh), or `I` (uppercase letter eye) as single character variable names. In some fonts, these characters are indistinguishable from the numerals one and zero. When tempted to use `l`, use `L` instead. Better yet: consider a variable name that is longer than one character.\n",
+ "\n",
+ "Function names should be lowercase, with words separated by underscores as necessary to improve readability: \n",
+ "`this_is_a_properly_formatted_function_name_its_too_long_but_very_readable`\n",
+ "\n",
+ "Variable names follow the same convention as function names. We will cover some of the other naming guidelines in later tutorials. ***For now, remember: functions and variables should be written in all lower case and underscores.*** That makes it easy to remember! For everything else, you can refer to PEP 8."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a3fbc8c5",
+ "metadata": {},
+ "source": [
+ "## Rule 2: Make readable code\n",
+ "\n",
+ "*I hate it when a piece of code is passed to me that I cannot understand on itself.*\n",
+ "\n",
+ "This rule pretty much speaks for itself, and is also the Golden Rule most closely linked to PEP 8. So rather than rewrite it, we reccommend that at the start you focus on the four aspects of PEP 8 listed here. And don't forget to read the document every once in a while to refresh your memory and see examples. \n",
+ "- blank lines are great for making space, but don't overuse them\n",
+ "- use indentation to make your line breaks readable\n",
+ "- space around operators, especially =, +, -, and after function arguments\n",
+ "- incorporate a maximum line length\n",
+ "\n",
+ "The 79 character maximum line length reccommendation in PEP 8 is often a contentious one. It's important to limit line length because not all documentation software, word processers, text viewers, etc, know how to present long lines of code. Line breaks may introduced in a way that makes the code completely unreadable, or worse, large portions of your code may not be visible when printed. However, you will find that in practice it is very difficult to limit your lines to 79 characters, especially if you are using descriptive variable and function names (Golden Rule 1). On the other hand, once you learn a few tricks for making easy line breaks (below), it becomes much easier. So, our advice is to *definitely* incorporate a maximum line length in your code, but start with 79 and feel free to increase it doesn't work for a certain project. It's generally not a problem to increase the maximum length to 100 or even 120 characters, and autoformatters can be set up to help enforce this. Whatever you do, just make sure that your lines don't get cut off or broken in a way that makes your code unreadable. To help, we provide a few tips for adding line breaks to your code. Can you find the PEP 8 violations in this example? Try copying this code into [pep8online.com](http://pep8online.com/) to test yourself.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "63b5a341",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# You can always break items inside brackets wherever you like\n",
+ "my_sum = sum([1,\n",
+ " 2])\n",
+ "\n",
+ "bad_bracket_alignment = sum([1,\n",
+ " 2\n",
+ " ]) \n",
+ "\n",
+ "# When you split function arguments use indentation to make sure\n",
+ "# the entire function can be easily read with breaks\n",
+ "OK = sum([1, 2, 3, 4, 5, 6, 7, 8,\n",
+ " 9, 10, 11, 12])\n",
+ "\n",
+ "not_good = sum([1, 2, 3,\n",
+ " 4, 5, 6,\n",
+ " 7, 8, 9, 10, 11, 12])\n",
+ "\n",
+ "much_better = sum([1, 2, 3, 4,\n",
+ " 5, 6, 7, 8,\n",
+ " 9, 10, 11, 12])\n",
+ "\n",
+ "# Line breaks with strings\n",
+ "this_is_one_string_in_two_parts = (\"This string has to be split in two. \"\n",
+ " \"Notice how this line is aligned above.\\n\")\n",
+ "\n",
+ "print(this_is_one_string_in_two_parts) \n"
+ ]
+ },
+ {
+ "attachments": {},
+ "cell_type": "markdown",
+ "id": "876df9a5",
+ "metadata": {},
+ "source": [
+ "## Rule 3: Make readable results\n",
+ "\n",
+ "*Your professors are old and their eyes are bad---why torture them with thin lines and tiny text on your figures?*\n",
+ "\n",
+ "There are courses and books devoted to this Golden Rule, not to mention professional editors and typesetters. While you should aways make sure your results are readable, there are three main categories where it is easy to make significant improvements to readability and communication: figures, tables and numbers.\n",
+ "\n",
+ "### Figures\n",
+ "\n",
+ "You've gone through all the work to write code, run analyses, collect results and present them in figures. Why not spend a little extra effort to make the figure easy for your reader or audience to interpret? You should always make sure a figure contains enough information for a viewer to understand the main variables even if taken out of context, which can be done easily by including axis labels and a title, both with units, as well as a legend. Use of high contrast colors, symbols and line types is important if a lot of curves or data types are included. Finally, depending on the importance and use consider: setting good axis limits and increments (e.g., tics every 5 instead of 7), equal scale axes, grid lines, etc. \n",
+ "\n",
+ "Our advice is to get in the habit of always adding a few simple commands to format to make it easy to repeat when it matters. Rather than take up space here with examples, keep an eye out for nicely formatted figures in MUDE notebooks.\n",
+ "\n",
+ "### Tables\n",
+ "\n",
+ "Similar to figures, make sure key information about the contents such as variable name, type and units are included. Limiting the number of significant figures to 3, adding more only when needed, can significantly improve the readability of a table. There are a number of tools available for creating tables, so we encourage you to use Google to find a few that work for your working method.\n",
+ "\n",
+ "### Significant digits \n",
+ "\n",
+ "Did you know that computers can store decimals up to 16 digits? If you let it, Python will try to return as many of these digits as possible. When you present results of your calculation with 6 or 8 decimal values, you give a false (and at times silly) impression of precision. For example, is that wind speed *really* 14.4613587 m/s? Especially when the accuracy of the sensor is +/-10% and the wind is gusting significantly? For most engineering purposes, 3 significant digits is plenty and can be considered a default. You can always add more if you have a good reason to do so.\n",
+ "\n",
+ "Fortunately Python has a great tool to help you use an appropriate number of significant digits: `f-strings`. A few quick examples are provided below, and you can [read more about f-strings here](https://realpython.com/python-f-strings/), or any of the other good resources online."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "725b7cc3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from math import pi\n",
+ "# Easiest f-string:\n",
+ "print(f'Add f before string, use curly braces to round pi = {pi:.3f}')\n",
+ "print(f'Different formats are possible, pi = {pi:.3e}\\n')\n",
+ "\n",
+ "three_things = [1.21581651, 3.8, 3.43454]\n",
+ "\n",
+ "print('Unpack all numbers using the same format:')\n",
+ "print(*[f'{i:.3f}' for i in three_things])\n",
+ "\n",
+ "print('\\nNow list each on a separate line:')\n",
+ "print(*[f'{i:.3f}' for i in three_things], sep='\\n')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3bfcb9b1",
+ "metadata": {},
+ "source": [
+ "## Rule 4: Write simple functions, then use them\n",
+ "\n",
+ "*I hate it when students/colleagues copy-paste their code with small modifications instead of using functions or classes*\n",
+ "\n",
+ "Often in our code, it may be necessary to do the same thing multiple times. Without the use of functions, the code may become unreadable and there is also high risk of making errors. Take as an example the calculation of daily water use for a residential house as a function of time. You would also like to consider how this demand changes throughout the day depending on who is living in the house, specifically, the number and ages of the residents. based on the number and age of the residents as well as time of day. The following example illustrates how this is commonly evaluated when you don't think in advance about your code structure, or the use of functions.\n",
+ "\n",
+ "*Note that in reality each line described below may be multiple lines in the 'real' file.*\n",
+ "```\n",
+ "1 calculate water use for 1 adult resident\n",
+ "2 plot result\n",
+ " \n",
+ "3 copy of line 1: modified to consider teenager\n",
+ "4 copy of line 1: modified to consider child\n",
+ " \n",
+ "5 copy of line 2: plot redrawn with 3 lines\n",
+ " \n",
+ "6 copy lines 1, 4, 5 to sum water use for several users\n",
+ "```\n",
+ "Here are a few examples of how this style of code-writing can go wrong (numbers correspond to the line in the example): \n",
+ "- The code calculating water use as a function of time of day (1) may be wrong. Thus, the mistake will be repeated in multiple places (4, 5, 6). Extracting that code in a separate function and calling it multiple times is beneficial. \n",
+ "- The code becomes too long. As the calculations of water use (1) and plotting functions (2) in reality span multiple lines, the code can grow significantly. Therefore, using a separate function will reduce code duplication (3, 4, 5, 6). \n",
+ "- Functions (with descriptive names!) can increase code readability. Suppose you have water use calculations for different types of water users inside your code (e.g., industrial, commercial, residential). Making new functions for each will reduce the complexity of your code because the logic behind them will be placed somewhere else. \n",
+ "\n",
+ "```\n",
+ "1 define function for water use with resident as input\n",
+ "2 define function to plot water use (uses function on line 1)\n",
+ " \n",
+ "3 plot water use for one resident (uses line 2)\n",
+ "4 plot water use for multiple residents (uses line 2)\n",
+ "5 sum water use for several users (uses line 1)\n",
+ "```\n",
+ "\n",
+ "It is clear that lines 1 and 2 are used repeatedly, not duplicated. If we had written out these steps entirely, rather than outlining with pseudocode, the total number of lines would be significantly less because the steps to calculate water use (1) are written once. In addition, the instructions for formatting the figure can be included in the plotting function (2).\n",
+ "\n",
+ "This illustrates the concept of **modularity**: using functions to decompose the code into smaller pieces that minimize repetition and the chance of including errors. **Modules** and modular code are important general programming concepts, but also have particular significance for the Python language. This topic will be explained in a later workshop, so for now we encourage you to use functions and modularise your code. Simply taking a few moments to think about: 1) which part(s) of your analysis can be defined in a function, 2) write the functions at the top of your notebook or script (after importing your packages), then using them below, hence the name of this rule: **write simple functions, then use them.** It looks like this:\n",
+ "\n",
+ "```\n",
+ "import Python packages\n",
+ "define your new functions\n",
+ "use your new functions\n",
+ "```\n",
+ "\n",
+ "Would you like to learn more about this? In more general programming or computer science fields, modularity is a result of applying the concepts of *decomposition* and *abstraction.* See Guttag (2021).\n",
+ "\n",
+ "*The next version of this document will also discuss hardcoding, and why it is better to pass fixed values into your function as arguments to keep the functions simple and easy to use.*"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "bf647dda",
+ "metadata": {},
+ "source": [
+ "## Rule 5: Document your code\n",
+ "\n",
+ "*I had to hand over my code (semi-english, semi-dutch, unreadable and a complete mess) to real programmers about a year ago and I am still embarrassed by it.*\n",
+ "\n",
+ "Do you remember what you had for dinner 2 weeks ago? If the answer is **no**, then documenting your code could be useful not only for others, but also for you.\n",
+ "\n",
+ "Document what your functions and classes are doing. In addition, if you have many nested for loops or some very complex code, do not hesitate to put some in-line comments to describe what your code is doing. Overall, do not overdo it by commenting every single line, but rather try to elaborate in the way you structure your code and give names to your objects. This is why ***Golden Rule*** is closely tied to ***Rule 1: Use descriptive names***: if you do the latter, the use of the former is much less needed. Here are a few examples to illustrate unnecessary comments or poorly documented code: \n",
+ "\n",
+ "```\n",
+ "1 x = case.one + case.too #sum\n",
+ "\n",
+ "2 f = first.second.third.fourth() #gets the data\n",
+ "\n",
+ "3 engineeringConcept = 2 * thisAwesomeVariable #multiplication by 2\n",
+ "\n",
+ "4 global globalVariable ## define global variable globalVar\n",
+ "\n",
+ "5 for i in range(200): \n",
+ " for j in range(300):\n",
+ " for k in range(i,j):\n",
+ " answer = (i + j)**k\n",
+ "\n",
+ "6 if a and b or c and d or not b and not c:\n",
+ " print('here')\n",
+ "```"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2c770286",
+ "metadata": {},
+ "source": [
+ "Did you notice in example 4 that the variable name in the comment didn't match the code? Clearly the variable name changed after the comment was written. To quote PEP 8: *comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes!* Relying too much on comments to document your code can easily result in a lot of extra work; use of descriptive object names can help minimize the number of comments necessary to provide sufficient documentation.\n",
+ "\n",
+ "### Comparison of bad and good documentation\n",
+ "\n",
+ "The following functions are the same, the only difference is the documentation and object names, can you tell what the function does from the bad example?"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c0d4b841",
+ "metadata": {},
+ "source": [
+ "#### Example with bad documentation "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e57f2a3e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def HF(h,p):\n",
+ " return 0.5*p*9.81*h**2\n",
+ " \n",
+ "print('HF(10,1) = ',HP(10,1))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e93a3cd7",
+ "metadata": {},
+ "source": [
+ "#### Example with good documentation "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "fda75b0f",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def force_on_wall(wall_height, density_water):\n",
+ " '''Calculate hydrostatic force on a vertical wall.'''\n",
+ " return 0.5*density_water*9.81*wall_height**2\n",
+ " \n",
+ "print(f'force_on_wall(wall_height=10, density_water=1) = {force_on_wall(10,1):.1f} N')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b062d7e3",
+ "metadata": {},
+ "source": [
+ "It seems pretty obvious that the second example is more clear, and even if you understood what was happening in the first function, the second one probably would have brought you to the same conclusion much faster. And it didn't take much longer to write the second function.\n",
+ "\n",
+ "The example above includes a string immediately after the function definition line (`def`), except it uses three quote symbols. This is a ***documentation string***, also known as a \"***docstring***\" a key tool for documenting your code. It actually has it's own PEP guideline ([PEP 257]() if you are curious), but we will cover this more during a future week in MUDE. ***For now, our advice is to get in the habit of at least using a one-line docstring whenever you create function.***\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "69434da9",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def my_well_documented_function():\n",
+ " \"\"\"Illustrate a simple one-line docstring---that's it!\"\"\"\n",
+ " pass"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9cc60029",
+ "metadata": {},
+ "source": [
+ "You should use the imperative verb tense, a command, for example: return, integrate or compute. This helps keep the docstring compact. Compare the following one--liners with the non-imperative equivalents: \n",
+ "- `Compute area of circle` \n",
+ "- `Computes the area of a circle` \n",
+ "\n",
+ "And: \n",
+ "- `Return int number_of_PSOR_coins` \n",
+ "- `Returns the number of PSOR coins as an integer` \n",
+ "\n",
+ "If told us that it seems silly to write a one-line docstring for such a simple function, especially with such descriptive object names, we'd actually agree with you, especially if you were working in a small group of CEG colleagues, or by yourself. However, there is another benefit of adding a docstring: Python automatically knows to include the first line of a docsting in its built-in help functionality. Try it out here by adding a `?` after the function name (this is a handy trick that works in Jupyter notebooks)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "65dbd634",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "my_well_documented_function?"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "44256b0b",
+ "metadata": {},
+ "source": [
+ "You can also use the `help()` function:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "f1a76cfc",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "help(my_well_documented_function)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e95e7e91",
+ "metadata": {},
+ "source": [
+ "## Rule 6: Test your code\n",
+ "\n",
+ "*A team member once sent me a script that predicts X for the next 5 weeks. Unfortunately, the script gave me the exact same predictions every time I used it.*\n",
+ "\n",
+ "Testing that your code works properly is very important to mitigate such problems. Testing can be done in many ways, but the most simple of all is by manually running your code with different values and verifying that the final result is indeed correct.\n",
+ "\n",
+ "In one of the next workshops, we are going to teach you how to debug and test your code, however, for now the recommendation for you would be to test if your code is doing its job correctly by trying different variable values.\n",
+ "\n",
+ "For example, suppose you have a method that calculates the volume of a pyramid given its height and base width and length. Testing the method can be done by trying different values for each of the 3 inputs and manually checking if the final volume matches your hand calculations. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7428c43d",
+ "metadata": {},
+ "source": [
+ "## Rule 7: Learn to collaborate\n",
+ "\n",
+ "*Let me just make a new zip file of the 200MB project and send it to you via Google Drive...*\n",
+ "\n",
+ "Exchanging project archives and lack of version control are key problems in project collaborations. First, the changes made are not explicitly visible, unless you go over the entire project and compare new and old versions. Second, such exchanges of files is dangerous because one may confuse which is the final version. This is especially common with file names, for example, \"Document-1\", \"Document-2\", \"Document-2-Draft\", \"Document-2-DraftFinal\", \"Document-2-DraftFinal2\", et cetera. Third, it hardly allows working in parallel as merging work requires manual copy-pasting of each member's progress.\n",
+ "\n",
+ "In one of the coming coding workshops, we will cover version control systems, namely collaborating using `git` and GitLab. Although it may seem complicated at first, we are confident that once you learn about the capabilities of these systems, you will not regret it. 😉"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d8658baf",
+ "metadata": {},
+ "source": [
+ "## References and resources\n",
+ "\n",
+ "Guttag, J. V. (2021). *Introduction to Computation and Programming Using Python: With Application to Computational Modeling and Understanding Data.* MIT Press.\n",
+ "\n",
+ "PEP 8 - Style Guide for Python code - https://peps.python.org/pep-0008/\n",
+ "\n",
+ "Python 3's f-Strings: An Improved String Formatting Syntax (Guide) - https://realpython.com/python-f-strings/"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "base",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.9.13"
+ },
+ "vscode": {
+ "interpreter": {
+ "hash": "b3d2c42f8ea709076bc5b173c4ba6d021b4bbbddbef7af6142452ecb0f2070bf"
+ }
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/book/programming/overview.md b/book/programming/overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..1558d33ef448f516add608a75facbcfac73ffaaa
--- /dev/null
+++ b/book/programming/overview.md
@@ -0,0 +1,36 @@
+# Programming Overview
+
+Riccardo ideas. For now, when in doubt add content to the JB. Can move text to website later as needed.
+1. theory + best practices with examples for efficient numerical practices
+2. theory + best practices with examples of for loops (and not for loops)
+3. Visualization:
+ 1. how to reduce the size of images (matplotlib plots) when large datasets are used (can use SHIP project as a case study)
+ 2. advanced figure creation: define axes as objects and modifying attribues (i have some recent examples from another TA if needed)
+ 3. saving a figure (vector/raster; file types; optimize file size; automatically regenerate it; add a test?)
+4. Memory considerations: how can you tell whether or not your code is working efficiently? (e.g., loading data, copies of objects, recopying or reloading on every nb run)
+5. Run time:
+ 1. may need a bit of theory about computations, processor speeds, cores, comparison of disk, RAM, CPU/GPU etc, but doesn't need to be long, and perhaps we can find existing content with CC license to include directly (embedded video, copy content, direct link all ok...this applies to all generic programming and coding topics)
+ 2. strategies for evaluating code efficiency and identifying slowest parts to improve: in a notebook and in an IDE (VS Code).
+ 3. saving results of analyses---would this be pickle? ideally we should teach them how to create a JSON and binary (pickle) format, then they choose whats best (for example, the JSON is readable and may be useful to share with a colleague who cannot run nb's in combination with a PDF printout of the nb). This is a great example where we should have content in the book that then is referred to as needed when students run into issues in submitting reports (i.e., their nb is 10 MB, now what?)
+6. IDE's: a brief overview, then a recommendation and case study with Jupyter Lab and VS Code
+7. package management: we need some theory on this, but it should be concise. Since Robert is already working with the TA's about environments, maybe it's best to leave this one alone till the end
+8. Some handy tricks (we can make a special page on the website to quickly illustrate things described above, and provide links to the theory, explanation and case studies in the textbook)
+
+
+
+Loosely broken down into 4 Chapters, with some ideas for possible contents (will fine tune location as we create it!):
+
+1. Golden Rules (part of Communication, but introduced at beginning to set the stage)
+2. Computers: essentials concepts for Scientific Computation and Numerical Analysis
+ 1. Machine code, compilers, low- and high-level languages; Bits and bytes, storage, memory, precision; File types (e.g., txt, csv, ipynb, py, md; text and binary);
+Data types (e.g., csv, JSON, netcdf, etc); FLOPS, run time; Complexity
+3. Code: Instructions. Executed.
+ 1. Programming language (Python), Environments and package management, Fundamentals of programming, Executing code, Other languages
+4. Programs: essentials for scientific computing
+ 1. Modular programming; Object-oriented programming, Version control, Debugging and error handling
+5. Communication (and documentation)
+ 1. Golden Rules, Visualization, Version control, Sharing your work (Static (*.ipynb, *.pdf, *.html) and Dynamic/Interactive (something with a Python kernel), Open-Source Projects / Collaboration
+ 2. some of this may be moved to the website; most will be short, except git
+
+
+Software is also considered a programming category, but that will be covered exclusively on the website.
\ No newline at end of file
diff --git a/book/programming/programs/overview.md b/book/programming/programs/overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..364140a33a1512e67774c2755030e13d03d09a37
--- /dev/null
+++ b/book/programming/programs/overview.md
@@ -0,0 +1,16 @@
+# Programs
+
+text. Can briefly mention programming paradigms and that we focus on object-oriented and functional. FORTRAN was old standard in engineering, which is declarative.
+
+Things that will definitely go here:
+- Objects
+ - theory: what it is, why it's useful
+ - Case studies: interactive pages that focus on variables, functions, figures as objects
+- Modular programming workshop
+ - importing py files
+ - connection to how packages function (explore with interactive features)
+- Writing efficient programs for numerical analysis
+ - add theory missing from Code chapter
+ - explicit case studies illustrating best practices
+ - examples that quantitatively show the effect of bad practices
+ - e.g., sparse matrices, for loops and why they should be avoided
\ No newline at end of file