notebook_formatting.ipynb

Kernel: Python 3

Formatting Project Notebooks in ModSim

Steve Matsumoto [email protected]

This notebook is designed to briefly walk you through basic formatting in Jupyter, as well as give you a sample structure for your ModSim project.

Markdown

Text cells in Jupyter are formatted using a text-like language called Markdown. Jupyter notebooks are particularly nice in that you can double-click (or otherwise enter editing mode) on any cell to see what the underlying source text looks like. So if you are interested in seeing how to do bold or italic text, you can double-click on this cell. (In CoCalc, the cell border will turn green when you are in this mode.)

There is a lot I could say on this topic, but GitHub has two great and often-circulated pages on this: Basic writing and formatting syntax and Mastering Markdown. You should definitely look through these pages when you get the chance, as they cover the vast majority of formatting typically done in notebooks.

Embedding Images

Typically, embedding images from the Web is easy. Just do something like this:

The actual text source looks like this: ![Olin Logo](https://www.olin.edu/sites/all/themes/genuine/logo.png)

The [Olin Logo] part is called the alt-text and is what is shown if a browser cannot display the image for some reason. Alt-text is also used for screen readers, which are especially useful for visually impaired users. You should include alt-texts if you can.

If you want to embed an image from your local project directory, you can use the text source ![CoCalc Logo](CoCalc_Logo.png). When you run the cell, you will see this:

The filename you type is relative, which means that it starts by looking in the same folder that your notebook is in. So if you are embedding an image from the same directory, you can simply just type the filename CoCalc_Logo.png. The filename is case sensitive.

The folder your notebook is in is called the working directory. If your working directory itself has a folder called foo and you want to embed an image bar.png contained in the folder, type the filename as foo/bar.png. If you try something like this and see the alt-text instead of the image, make sure the text source you typed is correct.

If the folder is outside of your working directory, you can refer to the folder containing your working directory with .. as the "folder". This is called the parent folder. So you could type something like ../baz.png. You can also navigate successively outside folders by repeating the .. as many times as you need. So ../../../bob.png would look for bob.png in the parent's parent's parent folder.

ModSim Project Structure

It's helpful to have each of the four QMRI portions as their own separate sections. So your overall notebook might look something like this:

# Title of Computational Essay

Name <email>

## Question

<Introduce the topic and why the question is important here>

Therefore, we ask: in order to maintain airspeed velocity, how many times per second does a swallow need to beat its wings?

## Model

We modeled a swallow as a point mass at the center of two perfectly flat wings of equal surface area. We assumed the use of a European swallow due to...

## Results

Our parameter sweep of the weight of the swallow shows how many times per second a European swallow needs to beat its wings.

<Plot here>

## Interpretation

We concluded that a 5-ounce swallow would need to beat its wings approximately 43 times per second to maintain airspeed velocity. If this swallow were instead 21 ounces, it would need to beat its wings many more times a second than has ever been observed in nature. We can therefore conclude that it is likely impossible for a 5-ounce swallow to carry a 1-pound coconut.

For the Model section of your notebook, it may help you, both in your model design and in your writeup, to explicitly list the components of your model. In keeping with the theme of the example, you can remember these components as SPAM: State, Parameters, Actions, and Metrics. So the Model section of your notebook might look like this:

## Model

<some intro text here>

### State

<Describe the variables used in your state object, and why you need to keep track of those variables over time>

### Parameters

<Describe parameters used in your simulation, and how you chose those parameters based on data>

### Actions

<Describe the actions that take place in your model - you can frame this an explanation of what your update function does, given a state and system>

### Metrics

<Describe what metrics you will collect while running your simulation - you can frame this as an explanation of your simulation function>