Merge pull request #158 from kallejahn/2025

small changes to matplotlib notebook

Author: mnfienen

notebooks/part0_python_intro/01_functions_scripts.ipynb

@@ -13,7 +13,7 @@
    "source": [
     "## Why use functions?\n",
     "\n",
-    "functions are a great coding tool!  They allow to setup reusable bits of code that you might need over and over.  Using functions, you only have the write the code once, and, if you need to change it, only change it once.  \n",
+    "functions are a great coding tool! They allow you to set up reusable bits of code that you might need over and over. Using functions, you only have to write the code once, and if you need to change it, only change it once.  \n",
     "\n",
     "We can create a function that writes the Fibonacci series to an arbitrary boundary:"
    ]
@@ -77,7 +77,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The first statement of the function body can optionally be a string literal; this string literal is the function’s documentation string, or docstring. (More about docstrings can be found in the section Documentation Strings.) There are tools which use docstrings to automatically produce online or printed documentation, or to let the user interactively browse through code; it’s good practice to include docstrings in code that you write, so make a habit of it.\n"
+    "The first statement of the function body can optionally be a string literal; this string literal is the function's documentation string, or docstring. There are tools which use docstrings to automatically produce online or printed documentation, or to let the user interactively browse through code. It's good practice to include docstrings in code that you write, so make a habit of it.\n"
    ]
   },
   {
@@ -91,21 +91,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The execution of a function introduces a new symbol table used for the local variables of the function. More precisely, all variable assignments in a function store the value in the local symbol table; whereas variable references first look in the local symbol table, then in the local symbol tables of enclosing functions, then in the global symbol table, and finally in the table of built-in names. Thus, global variables cannot be directly assigned a value within a function (unless named in a global statement), although they may be referenced.  In plain english, that means the variables that are formed and used within a function can only be used within the function, unless they are ```return```-ed - they are sent back.\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The actual parameters (arguments) to a function call are introduced in the local symbol table of the called function when it is called; thus, arguments are passed using call by value (where the value is always an object reference, not the value of the object). [1] When a function calls another function, a new local symbol table is created for that call.\n"
+    "The variables that are formed and used within a function can only be used within the function, unless they are ```return```-ed.\n",
+    "\n",
+    "\n",
+    "**More detailed information**: *the execution of a function introduces a new symbol table used for the local variables of the function.  all variable assignments in a function store the value in the local symbol table; whereas variable references first look in the local symbol table, then in the local symbol tables of enclosing functions, then in the global symbol table, and finally in the table of built-in names. Thus, global variables cannot be directly assigned a value within a function (unless named in a global statement), although they may be referenced.*\n",
+    "\n",
+    "*The actual parameters (arguments) to a function call are introduced in the local symbol table of the called function when it is called; thus, arguments are passed using call by value (where the value is always an object reference, not the value of the object). Additionally, when a function calls another function, a new local symbol table is created for that call.*"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A function definition introduces the function name in the current symbol table. The value of the function name has a type that is recognized by the interpreter as a user-defined function. This value can be assigned to another name which can then also be used as a function. This serves as a general renaming mechanism:\n"
+    "A function definition introduces the function name, which has a ```type``` recognized by the interpreter as a user-defined function. \n",
+    "\n",
+    "This value can be assigned to another name which can then also be used as a function. This serves as a general renaming mechanism.\n"
    ]
   },
   {
@@ -148,7 +148,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Coming from other languages, you might object that fib is not a function but a procedure since it doesn’t return a value. In fact, even functions without a return statement do return a value, albeit a rather boring one. This value is called ```None``` (it’s a built-in name equivalent to null or not defined). Writing the value ```None``` is normally suppressed by the interpreter if it would be the only value written. You can see it if you really want to using print:\n"
+    "Coming from other languages, you might object that fib is not a function but a procedure since it doesn’t return a value. However, even functions without a return statement do return a value, albeit a rather boring one. This value is called ```None``` (it’s a built-in name equivalent to null or not defined). Writing the value ```None``` is normally suppressed by the interpreter if it would be the only value written. You can see it if you really want to using print:\n"
    ]
   },
   {
@@ -207,13 +207,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This example, as usual, demonstrates some new Python features:\n",
+    "This example demonstrates some new Python features:\n",
     "\n",
-    "The ```return``` statement returns with a value from a function. return without an expression argument returns None. Falling off the end of a function also returns None.\n",
+    "The ```return``` statement returns with a value from a function. ```return``` without an expression argument returns ```None```. Falling off the end of a function also returns ```None```.\n",
     "\n",
     "## An object oriented preview aside: <span style=\"color:red\">terminology alert!!!</span>\n",
     "\n",
-    "The statement ```result.append(a)``` calls a method of the ```list``` type object instance ```result```. A method is simply a function that ‘belongs’ to an object and is named obj.methodname, where obj is some object (this may be an expression), and methodname is the name of a method that is defined by the object’s type. Different types define different methods. Methods of different types may have the same name without causing ambiguity. (It is possible to define your own object types and methods, using classes, see Classes) The method append() shown in the example is defined for list objects; it adds a new element at the end of the list. In this example it is equivalent to result = result + [a], but more efficient."
+    "The statement ```result.append(a)``` calls a method of the ```list```-type object instance ```result```. \n",
+    "\n",
+    "**A method is simply a function that \"belongs\" to an object** and is named obj.methodname, where obj is some object (this may be an expression), and methodname is the name of a method that is defined by the object’s type. \n",
+    "\n",
+    "Different object types will have different methods associated with them. Methods of different types may have the same name without causing ambiguity. (It is possible to define your own object types and methods using ```Classes```).\n",
+    "\n",
+    "The method ```append()``` shown above is defined for ```list``` objects; it adds a new element at the end of the list. In this example it is equivalent to ```result = result + [a]```, but more efficient."
    ]
   },
   {
@@ -222,9 +228,9 @@
    "source": [
     "## back to functions\n",
     "\n",
-    "It is also possible to define functions with a variable number of arguments. In ```python```, there are three forms function arguments which can be combined. Each of these forms get used a lot.\n",
+    "It is also possible to define functions with a variable number of arguments. In Python, there are **three forms of function arguments** which can be combined: **default, keyword, or positional**. Each form is used frequently.\n",
     "\n",
-    "The most user-friendly form of a function argument is to specify an argument which has a default value. This creates a function that can be called with fewer arguments, but that also allows greater flexility in controlling the behavior within the function itself. \n",
+    "The most user-friendly function argument form is to **specify an argument with a default value**. This creates a function that can be called with fewer arguments, but also allows greater flexility in controlling the behavior within the function itself. \n",
     "\n",
     "For example:"
    ]
@@ -277,9 +283,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This function *requires* both ```T``` and ```r```.  All the rest use the defaults if not explicitly passed in. The default values are evaluated at the point of function definition in the defining scope.\n",
+    "This function *requires* both ```T``` and ```r```.  All the rest use the defaults if other values are not explicitly passed in. The default values are evaluated at the point of function definition in the defining scope.\n",
     "\n",
-    "Giving only mandatory arguments: `T`=100.0, `r`=300.0"
+    "The mandatory arguments `T` and `r` can be defined based on their **position** in the function definition:"
    ]
   },
   {
@@ -288,14 +294,32 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "#  T=100.0, r=300.0\n",
     "thiem(100.0, 300.0)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Giving one of the optional arguments using the implied position of `Q`: `T`=100.0, `r`=300.0, `Q`=500.0"
+    "They can also be defined **explicitly by their keyword**, and thus be passed in any order."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#  T=100.0, r=300.0\n",
+    "thiem(r=300.0, T=100.0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Passing optional argument `Q` using it's implied position in the function definition: `T`=100.0, `r`=300.0, `Q`=500.0"
    ]
   },
   {
@@ -304,7 +328,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "thiem(100.0, 300.0, 10)"
+    "thiem(100.0, 300.0, 500)"
    ]
   },
   {
@@ -329,7 +353,7 @@
    "source": [
     "## Your turn\n",
     "\n",
-    "1.) What is the thiem solution for `T`=1000.0, `r`=20.0?"
+    "1. What is the thiem solution for `T`=1000.0, `r`=20.0?"
    ]
   },
   {
@@ -343,7 +367,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "2.) What is the Thiem solution for `T`=1000.0, `r`=20.0, `h0`=40.0?"
+    "2. What is the Thiem solution for `T`=1000.0, `r`=20.0, `h0`=40.0?"
    ]
   },
   {
@@ -357,7 +381,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "3.) What is the Thiem solution for `T`=1000.0, `r`=20.0, `Q`=2000.0, `h0`=40.0"
+    "3. What is the Thiem solution for `T`=1000.0, `r`=20.0, `Q`=2000.0, `h0`=40.0"
    ]
   },
   {
@@ -371,7 +395,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "4.) What is the Thiem solution for `T`=1000.0, `r`=20.0, `Q`=2000.0, `h0`=40.0 if there is a lake 2000.0 units away?"
+    "4. What is the Thiem solution for `T`=1000.0, `r`=20.0, `Q`=2000.0, `h0`=40.0 if there is a lake 2000.0 units away?"
    ]
   },
   {
@@ -385,7 +409,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "5.) using a loop to accumulate Thiem results for `T`=1000.0, `r`=3000.0 for `Q` values ranging from 100.0 to 2000.0 by 100.0"
+    "5. using a loop to accumulate Thiem results for `T`=1000.0, `r`=3000.0 for `Q` values ranging from 100.0 to 2000.0 by 100.0"
    ]
   },
   {
@@ -399,7 +423,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "6.) redefine the Thiem function to take a list as the `Q` argument and return a list of ```h``` results.  Call the new function ```thiem_list()```.  Then call ```thiem_list()``` using the same Q as in 5.) above"
+    "6. redefine the Thiem function to take a list as the `Q` argument and return a list of ```h``` results.  Call the new function ```thiem_list()```.  Then call ```thiem_list()``` using the same Q as in 5. above"
    ]
   },
   {
@@ -430,7 +454,7 @@
     "    h: list of head s\n",
     "    \"\"\"\n",
     "    h = []\n",
-    "    # loop over all values of Q to create h list\n",
+    "    # TODO: loop over all values of Q to create h list\n",
     "\n",
     "    return h"
    ]
@@ -450,7 +474,7 @@
    "source": [
     "# More on functions: ```lambda``` functions\n",
     "\n",
-    "```lambda``` functions are a special type of function known as an \"in-line\" function.  They are present in virtually all modern programming languages (not Fortran, that's not modern) and are usually high-optimized.  They allow you to quickly define a simple-ish function that can only accept a single, *required* argument.  The only reason to introduce them is because they appear frequently when using a python library named ```pandas``` that we will cover later."
+    "```lambda``` functions are a special type of function known as an \"in-line\" function.  They are present in virtually all modern programming languages (not Fortran, that's not modern) and are usually highly optimized. They allow you to quickly define a simple-ish function that only accepts a single, *required* argument.  We're introducing them now because they appear frequently when using a python library named ```pandas``` that we will cover later."
    ]
   },
   {
@@ -621,9 +645,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A module can contain executable statements as well as function definitions. These statements are intended to initialize the module. They are executed only the first time the module name is encountered in an import statement. [1] (They are also run if the file is executed as a script.)\n",
+    "A module can contain executable statements as well as function definitions. These statements are intended to initialize the module. They are executed only the first time the module name is encountered in an import statement. (They are also run if the file is executed as a script.)\n",
     "\n",
-    "Each module has its own private symbol table, which is used as the global symbol table by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes with a user’s global variables. On the other hand, if you know what you are doing you can touch a module’s global variables with the same notation used to refer to its functions, modname.itemname.\n",
+    "Each module has its own private symbol table, which is used as the global symbol table by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes with a user's global variables. On the other hand, if you know what you are doing you can touch a module's global variables with the same notation used to refer to its functions, modname.itemname.\n",
     "\n",
     "Modules can import other modules. It is customary but not required to place all import statements at the beginning of a module (or script, for that matter). The imported module names are placed in the importing module’s global symbol table.\n",
     "\n",
@@ -666,8 +690,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "pyclass",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.11"
   }
  },
  "nbformat": 4,