Suggestions and Notes on Python and Jupyter Notebook Usage

3. Suggestions and Notes on Python and Jupyter Notebook Usage#

Brenton LeMesurier lemesurierb@cofc.edu

Version of September 25, 2022

This work is licensed under Creative Commons Attribution-ShareAlike 4.0 International

  1. Start every document (Notebook, Python code file, etc.) with:

    • A title (e.g. “Assignment 1”)

    • Your name (and maybe email address)

    • The date, of the latest version — so update this date after any major changes to the file.
      See the first cell above for an example!

  2. Put all import statements together in the first code cell of the notebook. Similarly, in Python code files (suffix .py) make the import statements the first code, straight below any opening comments.

  3. Put each function definition in its own cell, and only define a function once per notebook.

  4. More generally, divide both text and Python code into many, small cells; that makes it easier to edit, preview, debug and make changes. For example, start a new cell for each new section at any level (# ..., ## ..., etc.) so that each section heading is the first line of a Markdown cell.

  5. Whenever practical, use different names for similar but different items. For example, name sample functions f_1, f_2 and so on, rather than reusing the generic name f. Likewise for variants of a function, as with bisection1, bisection2 …

  6. Remember that Python is case-sensitive, so that ErrorBound, errorBound and errorbound are three different variables!

  7. On the last item, I suggest avoiding capital letters almost always, using them only when that style is “dictated” by standard mathematical notation. For example it makes sense to call a matrix A, but amongst the above three names, I would use only the latter or otherwise error_bound with an underscore to improve readability. The underscore _ is an “honorary letter:, often used as a fake space to separate words in a name. (Note: the underscore _ is not a dash -; it is typed as “shift-dash”.)

  8. One very common mistake is not reducing the indentation at the end of a block (the lines that go with an if, for, while or such).

  9. Another thing to check for: that wherever a variable is used (at right in an assignment, in the input parameters of a function, etc.) it already has a value — and an up-to-date value at that.

  10. Only use the Markdown section heading syntax # ..., ## ... and so on for items that are legitimately the titles of sections, sub-sections, and so on. Otherwise, emphasize with the *...* and **...** syntax for italics and boldface respectively.

  11. When the result of a numerical calculation is only an approximation (almost always in this course!) aim to also provide an upper bound on the absolute error — and if that is not feasable, then at least provide a plausable estimate of the error, or a measure of backward error.

  12. Avoid infinite loops! (In JupyterLab, the disk at top-right is black while code is running; goes white when finished; in case of execution never finishing, you can stop it with the square “Stop” button above.) One strategy is to avoid while loops, in particular while True or while 1; I will illustrate the folowing approach in sample codes for iterative methods:

    • set a maximum number of iterations maxiterations

    • use a for loop for iteration in range(maxiterations): instead of while not weAreDone:

    • Implement the stopping condition with if we_are_done: break somewhere inside the for loop.

  13. The last step before you submit a notebook or otherwise share it is to do a “clean run”, restarting the kernel and then running every cell, and then read it through, checking that the Python code has run succesfully, its output is correct, and so on.
    Usually the easiest way to do this in JupyterLab is with the “fast forward” double right-arrow button at the top; alternatively, there is a menu item Kernel > Restart Kernel and Run All Cells ...
    If you get Python errors but still want to share the file (for example, to ask for debugging help), this run will stop at the first error, so scan down to that first error, use menu item Run > Run Selected Cell and All Below, and repeat at each error till the run gets to the last cell.