% LaTeX source for ``Modeling and Simulation in Python''

% Copyright 2017 Allen B. Downey.

% License: Creative Commons Attribution-NonCommercial 4.0 Unported License.

% https://creativecommons.org/licenses/by-nc/4.0/

%

\documentclass[12pt]{book}

\title{Modeling and Simulation in Python}

\author{Allen B. Downey}

\newcommand{\thetitle}{Modeling and Simulation in Python}

\newcommand{\thesubtitle}{}

\newcommand{\theauthors}{Allen B. Downey}

\newcommand{\theversion}{2.3}

%%%% Both LATEX and PLASTEX

\usepackage{graphicx}

\usepackage{hevea}

\usepackage{makeidx}

\usepackage{setspace}

\usepackage{xcolor}

\usepackage{upquote}

\usepackage[listings]{tcolorbox}

% to get siunitx

% sudo apt-get install texlive-science

\usepackage{siunitx}

\sisetup{per-mode=symbol}

\definecolor{light-gray}{gray}{0.95}

\newtcblisting{python}{

skin=standard,

boxrule=0.4pt,

colback=light-gray,

listing only,

top=0pt,

bottom=0pt,

left=0pt,

right=0pt,

boxsep=2pt,

listing options={

basicstyle=\ttfamily,

language=python,

showstringspaces=false,

},

}

\newtcblisting{result}{

skin=standard,

boxrule=0.0pt,

colback=white,

listing only,

top=0pt,

bottom=0pt,

left=0pt,

right=0pt,

boxsep=2pt,

listing options={

basicstyle=\ttfamily,

language=python,

showstringspaces=false,

},

}

\makeindex

% automatically index glossary terms

\newcommand{\term}[1]{%

\item[#1:]\index{#1}}

\usepackage{amsmath}

\usepackage{amsthm}

% format end of chapter excercises

\newtheoremstyle{exercise}

{12pt} % space above

{12pt} % space below

{} % body font

{} % indent amount

{\bfseries} % head font

{} % punctuation

{12pt} % head space

{} % custom head

\theoremstyle{exercise}

\newtheorem{exercise}{Exercise}[chapter]

\usepackage{afterpage}

\newcommand\blankpage{%

\null

\thispagestyle{empty}%

\addtocounter{page}{-1}%

\newpage}

\newif\ifplastex

\plastexfalse

%%%% PLASTEX ONLY

\ifplastex

\usepackage{localdef}

\usepackage{url}

\newcount\anchorcnt

\newcommand*{\Anchor}[1]{%

\@bsphack%

\Hy@GlobalStepCount\anchorcnt%

\edef\@currentHref{anchor.\the\anchorcnt}%

\Hy@raisedlink{\hyper@anchorstart{\@currentHref}\hyper@anchorend}%

\M@gettitle{}\label{#1}%

\@esphack%

}

% code listing environments:

% we don't need these for plastex because they get replaced

% by preprocess.py

%\newenvironment{code}{\begin{code}}{\end{code}}

%\newenvironment{stdout}{\begin{code}}{\end{code}}

% inline syntax formatting

\newcommand{\py}{\verb}%}

%%%% LATEX ONLY

\else

\input{latexonly}

\fi

%%%% END OF PREAMBLE

\begin{document}

\frontmatter

%%%% PLASTEX ONLY

\ifplastex

\maketitle

%%%% LATEX ONLY

\else

\begin{latexonly}

%-half title--------------------------------------------------

%\thispagestyle{empty}

%

%\begin{flushright}

%\vspace*{2.0in}

%

%\begin{spacing}{3}

%{\huge \thetitle}

%\end{spacing}

%

%\vspace{0.25in}

%

%Version \theversion

%

%\vfill

%

%\end{flushright}

%--verso------------------------------------------------------

%\afterpage{\blankpage}

%\newpage

%\newpage

%\clearemptydoublepage

%\pagebreak

%\thispagestyle{empty}

%\vspace*{6in}

%--title page--------------------------------------------------

\pagebreak

\thispagestyle{empty}

\begin{flushright}

\vspace*{2.0in}

\begin{spacing}{3}

{\huge \thetitle}

\end{spacing}

\vspace{0.25in}

Version \theversion

\vspace{1in}

{\Large

\theauthors \\

}

\vspace{0.5in}

{\Large Green Tea Press}

{\small Needham, Massachusetts}

%\includegraphics[width=1in]{figs/logo1.eps}

\vfill

\end{flushright}

%--copyright--------------------------------------------------

\pagebreak

\thispagestyle{empty}

Copyright \copyright ~2017 \theauthors.

\vspace{0.2in}

\begin{flushleft}

Green Tea Press \\

9 Washburn Ave \\

Needham MA 02492

\end{flushleft}

Permission is granted to copy, distribute, transmit and adapt this work under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License: \url{http://modsimpy.com/license}.

% TODO: get the shortened URLs working with https

If you are interested in distributing a commercial version of this

work, please contact the author.

The \LaTeX\ source and code for this book is available from

\begin{code}

https://github.com/AllenDowney/ModSimPy

\end{code}

%--table of contents------------------------------------------

\cleardoublepage

\setcounter{tocdepth}{1}

\tableofcontents

\end{latexonly}

% HTML title page------------------------------------------

\begin{htmlonly}

\vspace{1em}

{\Large \thetitle}

{\large \theauthors}

Version \theversion

\vspace{1em}

Copyright \copyright ~2017 \theauthors.

Permission is granted to copy, distribute, and/or modify this work

under the terms of the Creative Commons

Attribution-NonCommercial-ShareAlike 4.0 International License, which is

available at \url{http://modsimpy.com/license}.

\vspace{1em}

\setcounter{chapter}{-1}

\end{htmlonly}

% END OF THE PART WE SKIP FOR PLASTEX

\fi

\chapter{Preface}

\label{preface}

\section{Can modeling be taught?}

The essential skills of modeling --- abstraction, analysis, simulation, and validation --- are central in engineering, natural sciences, social sciences, medicine, and many other fields. Some students learn these skills implicitly, but in most schools they are not taught explicitly, and students get little practice. That's the problem this book is meant to address.

At Olin College, we use this book in a class called Modeling and Simulation, which all students take in their first semester. My colleagues, John Geddes and Mark Somerville, and I developed this class and taught it for the first time in 2009.

It is based on our belief that modeling should be taught explicitly, early, and throughout the curriculum. It is also based on our conviction that computation is an essential part of this process.

If students are limited to the mathematical analysis they can do by hand, they are restricted to a small number of simple physical systems, like a projectile moving in a vacuum or a block on a frictionless plane.

And they will only work with bad models; that is, models that are too simple for their intended purpose. In nearly every mechanical system, air resistance and friction are essential features; if we ignore them, our predictions will be wrong and our designs won't work.

In most freshman physics classes, students don't make modeling decisions; sometimes they are not even aware of the decisions that have been made for them. Our goal is to teach the entire modeling process and give students a chance to practice it.

\section{How much programming do I need?}

If you have never programmed before, you should be able to read this book, understand it, and do the exercises. I will do my best to explain everything you need to know; in particular, I have chosen carefully the vocabulary I introduce, and I try to define each term the first time it is used. If you find that I have used a term without defining it, let me know.

If you have programmed before, you will have an easier time getting started, but you might be uncomfortable in some places. I take an approach to programming you have probably not seen before.

Most programming classes\footnote{Including many I have taught.} have two big problems:

\begin{enumerate}

\item They go ``bottom up", starting with basic language features and gradually adding more powerful tools. As a result, it takes a long time before students can do anything more interesting than convert Fahrenheit to Celsius.

\index{bottom up}

\item They have no context. Students learn to program with no particular goal in mind, so the exercises span an incoherent collection of topics, and the exercises tend to be unmotivated.

\end{enumerate}

In this book, you learn to program with an immediate goal in mind: writing simulations of physical systems. And we proceed ``top down", by which I mean we use professional-strength data structures and language features right away. In particular, we use the following Python {\bf libraries}:

\index{top down}

\begin{itemize}

\item NumPy for basic numerical computation (see \url{https://www.numpy.org/}).

\index{NumPy}

\item SciPy for scientific computation (see \url{https://www.scipy.org/}).

\index{SciPy}

\item Matplotlib for visualization (see \url{https://matplotlib.org/}).

\index{Matplotlib}

\item Pandas for working with data (see \url{https://pandas.pydata.org/}).

\index{Pandas}

\item SymPy for symbolic computation, (see \url{https://www.sympy.org}).

\index{SymPy}

\item Pint for units like kilograms and meters (see \url{https://pint.readthedocs.io}).

\index{Pint}

\item Jupyter for reading, running, and developing code (see \url{https://jupyter.org}).

\index{Jupyter}

\end{itemize}

These tools let you work on more interesting programs sooner, but there are some drawbacks: they can be hard to use, and it can be challenging to keep track of which library does what and how they interact.

I have tried to mitigate these problems by providing a library, called \py{modsim}, that makes it easier to get started with these tools, and provides some additional capabilities.

\index{modsim library}

Some features in the \py{modsim} library are like training wheels; at some point you will probably stop using them and start working with the underlying libraries directly. Other features you might find useful the whole time you are working through the book, and later.

I encourage you to read the the \py{modsim} library code. Most of it is not complicated, and I tried to make it readable. Particularly if you have some programming experience, you might learn something by reverse engineering my design decisions.

\section{How much math and science do I need?}

I assume that you know what derivatives and integrals are, but that's about all. In particular, you don't need to know (or remember) much about finding derivatives or integrals of functions analytically. If you know the derivative of $x^2$ and you can integrate $2x~dx$, that will do it\footnote{And if you noticed that those two questions answer each other, even better.}. More importantly, you should understand what those concepts {\em mean}; but if you don't, this book might help you figure it out.

\index{calculus}

You don't have to know anything about differential equations.

As for science, we will cover topics from a variety of fields, including demography, epidemiology, medicine, thermodynamics, and mechanics. For the most part, I don't assume you know anything about these topics. In fact, one of the skills you need to do modeling is the ability to learn enough about new fields to develop models and simulations.

When we get to mechanics, I assume you understand the relationship between position, velocity, and acceleration, and that you are familiar with Newton's laws of motion, especially the second law, which is often expressed as $F = ma$ (force equals mass times acceleration).

\index{science}

\index{mechanics}

I think that's everything you need, but if you find that I left something out, please let me know.

\section{Getting started}

\label{code}

To run the examples and work on the exercises in this book, you have to:

\begin{enumerate}

\item Install Python on your computer, along with the libraries we will use.

\item Copy my files onto your computer.

\item Run Jupyter, which is a tool for running and writing programs, and load a {\bf notebook}, which is a file that contains code and text.

\end{enumerate}

The next three sections provide details for these steps. I wish there were an easier way to get started; it's regrettable that you have to do so much work before you write your first program. Be persistent!

\section{Installing Python}

You might already have Python installed on your computer, but you might not have the latest version. To use the code in this book, you need Python 3.6 or later. Even if you have the latest version, you probably don't have all of the libraries we need.

\index{installing Python}

You could update Python and install these libraries, but I strongly recommend that you don't go down that road. I think you will find it easier to use {\bf Anaconda}, which is a free Python distribution that includes all the libraries you need for this book (and more).

\index{Anaconda}

Anaconda is available for Linux, macOS, and Windows. By default, it puts all files in your home directory, so you don't need administrator (root) permission to install it, and if you have a version of Python already, Anaconda will not remove or modify it.

Start at \url{https://www.anaconda.com/download}. Download the installer for your system and run it. You don't need administrative privileges to install Anaconda, so I recommend you run the installer as a normal user, not as administrator or root.

I suggest you accept the recommended options.

On Windows you have the option to install Visual Studio Code, which is an interactive environment for writing programs. You won't need it for this book, but you might want it for other projects.

By default, Anaconda installs most of the packages you need, but there are a few more you might have to add. Once the installation is complete, open a command window. On macOS or Linux, you can use Terminal. On Windows, open Git Bash.

Run the following command (copy and paste it if you can, to avoid typos):

\begin{code}

conda install jupyterlab pandas seaborn sympy beautifulsoup4 lxml

\end{code}

Some of these packages might already be installed. Then run this command:

\begin{code}

conda install -c unidata pint

\end{code}

That should be everything you need.

\section{Copying my files}

The code for this book is available from

\url{https://github.com/AllenDowney/ModSimPy}, which is a {\bf Git repository}. Git is a software tool that helps you keep track of the programs and other files that make up a project. A collection of files under Git's control is called a repository (the cool kids call it a ``repo"). GitHub is a hosting service that provides storage for Git repositories and a convenient web interface.

\index{repository}

\index{Git}

\index{GitHub}

Before you download these files, I suggest you copy my repository on GitHub, which is called {\bf forking}. If you don't already have a GitHub account, you'll need to create one.

Use a browser to view the homepage of my repository at \url{https://github.com/AllenDowney/ModSimPy}. You should see a gray button in the upper right that says {\sf Fork}. If you press it, GitHub will create a copy of my repository that belongs to you.

Now, the best way to download the files is to use a {\bf Git client}, which is a program that manages git repositories. You can get installation instructions for Windows, macOS, and Linux at \url{http://modsimpy.com/getgit}.

In Windows, I suggest you accept the options recommended by the installer, with two exceptions:

\begin{itemize}

\item As the default editor, choose \py{nano} instead of \py{vim}.

\item For ``Configuring line ending conversions", select ``Check out as is, commit as is".

\end{itemize}

For macOS and Linux, I suggest you accept the recommended options.

Once the installation is complete, open a command window. On Windows, open Git Bash, which should be in your Start menu. On macOS or Linux, you can use Terminal.

To find out what directory you are in, type \py{pwd}, which stands for ``print working directory". On Windows, most likely you are in \py{Users\\yourusername}. On MacOS or Linux, you are probably in your home directory, \py{/home/yourusername}.

The next step is to copy files from your repository on GitHub to your computer; in Git vocabulary, this process is called {\bf cloning}. Run this command:

\begin{python}

git clone https://github.com/YourGitHubUserName/ModSimPy

\end{python}

Of course, you should replace \py{YourGitHubUserName} with your GitHub user name. After cloning, you should have a new directory called \py{ModSimPy}.

If you don't want to use Git, you can download my files

in a Zip archive from \url{http://modsimpy.com/zip}. You will need a program like WinZip or gzip to unpack the Zip file. Make a note of the location of the files you download.

\section{Running Jupyter}

The code for each chapter, and starter code for the exercises, is in

Jupyter notebooks. If you have not used Jupyter before, you can read

about it at \url{https://jupyter.org}.

\index{Jupyter}

To start Jupyter on macOS or Linux, open a Terminal; on Windows, open Git Bash. Use \py{cd} to ``change directory" into the code directory in the repository:

\begin{code}

cd ModSimPy/code

\end{code}

Then launch the Jupyter notebook server:

\begin{code}

jupyter notebook

\end{code}

Jupyter should open a window in a browser, and you should see the list of notebooks in my repository. Click on the first notebook, \py{chap01.ipynb} and follow the instructions to run the first few ``cells". The first time you run a notebook, it might take several seconds to start, while some Python files get initialized. After that, it should run faster.

Feel free to read through the notebook, but it might not make sense until you read Chapter~\ref{chap01}.

You can also launch Jupyter from the Start menu on Windows, the Dock on macOS, or the Anaconda Navigator on any system. If you do that, Jupyter might start in your home directory or somewhere else in your file system, so you might have to navigate to find the \py{ModSimPy} directory.

\section*{Contributor List}

If you have a suggestion or correction, send it to

{\tt downey@allendowney.com}. Or if you are a Git user, send me a pull request!

If I make a change based on your feedback, I will add you to the contributor list, unless you ask to be omitted.

\index{contributors}

If you include at least part of the sentence the error appears in, that makes it easy for me to search. Page and section numbers are fine, too, but not as easy to work with. Thanks!

\begin{itemize}

\item I am grateful to John Geddes and Mark Somerville for their early collaboration with me to create Modeling and Simulation, the class at Olin College this book is based on.

\item My early work on this book benefited from conversations with

my amazing colleagues at Olin College, including John Geddes, Alison

Wood, Chris Lee, and Jason Woodard.

\item I am grateful to Lisa Downey and Jason Woodard for their thoughtful and careful copy editing.

\item Thanks to Alessandra Ferzoco, Erhardt Graeff, Emily Tow,

Kelsey Houston-Edwards, Linda Vanasupa, Matt Neal, Joanne Pratt, and Steve Matsumoto for their helpful suggestions.

% ENDCONTRIB

\end{itemize}

\normalsize

\cleardoublepage

% TABLE OF CONTENTS

\begin{latexonly}

% \tableofcontents

\cleardoublepage

\end{latexonly}

% START THE BOOK

\mainmatter

\chapter{Modeling}

\label{chap01}

This book is about modeling and simulation of physical systems.

The following diagram shows what I mean by ``modeling":

\index{modeling}

\vspace{0.2in}

\centerline{\includegraphics[height=3in]{figs/modeling_framework.pdf}}

Starting in the lower left, the {\bf system} is something in the real world we are interested in. Often, it is something complicated, so we have to decide which details can be left out; removing details is called {\bf abstraction}.

\index{system}

The result of abstraction is a {\bf model}, which is a description of the system that includes only the features we think are essential. A model can be represented in the form of diagrams and equations, which can be used for mathematical {\bf analysis}. It can also be implemented in the form of a computer program, which can run {\bf simulations}.

\index{model}

\index{abstraction}

\index{analysis}

The result of analysis and simulation might be a {\bf prediction} about what the system will do, an {\bf explanation} of why it behaves the way it does, or a {\bf design} intended to achieve a purpose.

\index{prediction}

\index{explanation}

\index{design}

We can {\bf validate} predictions and test designs by taking {\bf measurements} from the real world and comparing the {\bf data} we get with the results from analysis and simulation.

\index{validation}

\index{data}

For any physical system, there are many possible models, each one including and excluding different features, or including different levels of detail. The goal of the modeling process is to find the model best suited to its purpose (prediction, explanation, or design).

\index{iterative modeling}

Sometimes the best model is the most detailed. If we include more features, the model is more realistic, and we expect its predictions to be more accurate.

\index{realism}

But often a simpler model is better. If we include only the essential features and leave out the rest, we get models that are easier to work with, and the explanations they provide can be clearer and more compelling.

\index{simplicity}

As an example, suppose someone asked you why the orbit of the Earth is nearly elliptical. If you model the Earth and Sun as point masses (ignoring their actual size), compute the gravitational force between them using Newton's law of universal gravitation, and compute the resulting orbit using Newton's laws of motion, you can show that the result is an ellipse.

\index{orbit}

\index{ellipse}

Of course, the actual orbit of Earth is not a perfect ellipse, because of the gravitational forces of the Moon, Jupiter, and other objects in the solar system, and because Newton's laws of motion are only approximately true (they don't take into account relativistic effects).

\index{Newton}

\index{relativity}

But adding these features to the model would not improve the explanation; more detail would only be a distraction from the fundamental cause. However, if the goal is to predict the position of the Earth with great precision, including more details might be necessary.

Choosing the best model depends on what the model is for. It is usually a good idea to start with a simple model, even if it is likely to be too simple, and test whether it is good enough for its purpose. Then you can add features gradually, starting with the ones you expect to be most essential. This process is called {\bf iterative modeling}.

Comparing results of successive models provides a form of {\bf internal validation}, so you can catch conceptual, mathematical, and software errors. And by adding and removing features, you can tell which ones have the biggest effect on the results, and which can be ignored.

\index{internal validation}

\index{validation!internal}

\index{external validation}

\index{validation!external}

Comparing results to data from the real world provides {\bf external validation}, which is generally the strongest test.

\section{The falling penny myth}

\label{penny}

Let's see an example of how models are used. You might have heard that a penny dropped from the top of the Empire State Building would be going so fast when it hit the pavement that it would be embedded in the concrete; or if it hit a person, it would break their skull.

\index{Empire State Building}

\index{penny}

\index{myth}

We can test this myth by making and analyzing a model. To get started, we'll assume that the effect of air resistance is small. This will turn out to be a bad assumption, but bear with me.

If air resistance is negligible, the primary force acting on the penny is gravity, which causes the penny to accelerate downward.

\index{air resistance}

If the initial velocity is 0, the velocity after $t$ seconds is $a t$, and the distance the penny has dropped is

%

\[ h = a t^2 / 2 \]

%

Using algebra, we can solve for $t$:

%

\[ t = \sqrt{ 2 h / a} \]

%

Plugging in the acceleration of gravity, $a = \SI{9.8}{\meter\per\second\squared}$, and the height of the Empire State Building, $h=\SI{381}{\meter}$, we get $t = \SI{8.8}{\second}$. Then computing $v = a t$ we get a velocity on impact of $\SI{86}{\meter\per\second}$, which is about 190 miles per hour. That sounds like it could hurt.

Of course, these results are not exact because the model is based on simplifications. For example, we assume that gravity is constant. In fact, the force of gravity is different on different parts of the globe, and gets weaker as you move away from the surface. But these differences are small, so ignoring them is probably a good choice for this scenario.

\index{gravity}

On the other hand, ignoring air resistance is not a good choice. Once the penny gets to about \SI{18}{\meter\per\second}, the upward force of air resistance equals the downward force of gravity, so the penny stops accelerating. After that, it doesn't matter how far the penny falls; it hits the sidewalk (or your head) at about \SI{18}{\meter\per\second}, much less than \SI{86}{\meter\per\second}, as the simple model predicts.

The statistician George Box famously said ``All models are wrong, but some are useful." He was talking about statistical models, but his wise words apply to all kinds of models. Our first model, which ignores air resistance, is very wrong, and probably not useful. In the notebook for this chapter, you will see another model, which assumes that acceleration is constant until the penny reaches terminal velocity. This model is also wrong, but it's better, and it's good enough to refute the myth.

\index{Box, George}

The television show {\it Mythbusters} has tested the myth of the falling penny more carefully; you can view the results at \url{http://modsimpy.com/myth}. Their work is based on a mathematical model of motion, measurements to determine the force of air resistance on a penny, and a physical model of a human head.

\index{Mythbusters}

\section{Computation}

\label{computation}

There are (at least) two ways to work with mathematical models, {\bf analysis} and {\bf simulation}. Analysis often involves algebra and other kinds of symbolic manipulation. Simulation often involves computers.

\index{analysis}

\index{simulation}

In this book we do some analysis and a lot of simulation; along the way, I discuss the pros and cons of each. The primary tools we use for simulation are the Python programming language and Jupyter, which is an environment for writing and running programs.

As a first example, I'll show you how I computed the results from the previous section using Python.

First I create a {\bf variable} to represent acceleration.

\index{variable}

\index{value}

\begin{python}

a = 9.8 * meter / second**2

\end{python}

A variable is a name that corresponds to a value. In this example, the name is \py{a} and the value is the number \py{9.8} multiplied by the units \py{meter / second**2}. This example demonstrates some of the symbols Python uses to perform mathematical operations:

\index{operator!mathematical}

\begin{tabular}{l|c}

{\bf Operation} & {\bf Symbol} \\

\hline

Addition & \py{+} \\

Subtraction & \py{-} \\

Multiplication & \py{*} \\

Division & \py{/} \\

Exponentiation & \py{**} \\

\end{tabular}

Next, we can compute the time it takes for the penny to drop \SI{381}{\meter}, the height of the Empire State Building.

\begin{python}

h = 381 * meter

t = sqrt(2 * h / a)

\end{python}

These lines create two more variables: \py{h} gets the height of the building in meters; \py{t} gets the time, in seconds, for the penny to fall to the sidewalk. \py{sqrt} is a {\bf function} that computes square roots. Python keeps track of units, so the result, \py{t}, has the correct units, seconds.

\index{unit}

\index{function}

\index{sqrt}

Finally, we can compute the velocity of the penny after $t$ seconds:

\begin{python}

v = a * t

\end{python}

The result is about \SI{86}{\meter\per\second}, again with the correct units.

This example demonstrates analysis and computation using Python. Next we'll see an example of simulation.

Before you go on, you might want to read the notebook for this chapter, \py{chap01.ipynb}, and work on the exercises. For instructions on downloading and running the code, see Section~\ref{code}.

\chapter{Bike share}

\label{chap02}

This chapter presents a simple model of a bike share system and demonstrates the features of Python we'll use to develop simulations of real-world systems.

Along the way, we'll make decisions about how to model the system. In the next chapter we'll review these decisions and gradually improve the model.

\section{Bikeshare}

\label{modeling}

Imagine a bike share system for students traveling between Olin College and Wellesley College, which are about 3 miles apart in eastern Massachusetts.

\index{Wellesley College}

\index{Olin College}

Suppose the system contains 12 bikes and two bike racks, one at Olin and one at Wellesley, each with the capacity to hold 12 bikes.

\index{bike share system}

As students arrive, check out a bike, and ride to the other campus, the number of bikes in each location changes. In the simulation, we'll need to keep track of where the bikes are. To do that, I'll create a \py{State} object, which is defined in the \py{modsim} library.

\index{State object}

Before we can use the library, we have to \py{import} it:

\begin{python}

from modsim import *

\end{python}

This line of code is an {\bf import statement} that tells Python

to read the file {\tt modsim.py} and make the functions it defines available.

\index{import statement}

Functions in the \py{modsim.py} library include \py{sqrt}, which we used in the previous section, and \py{State}, which we are using now. \py{State} creates a \py{State} object, which is a collection of {\bf state variables}.

\index{state variable}

\begin{python}

bikeshare = State(olin=10, wellesley=2)

\end{python}

The state variables, \py{olin} and \py{wellesley}, represent the number of bikes at each location. The initial values are 10 and 2, indicating that there are 10 bikes at Olin and 2 at Wellesley. The \py{State} object created by \py{State} is assigned to a new variable named \py{bikeshare}.

\index{dot operator}

\index{operator!dot}

We can read the variables inside a \py{State} object using the {\bf dot operator}, like this:

\begin{python}

bikeshare.olin

\end{python}

The result is the value 10. Similarly, for:

\begin{python}

bikeshare.wellesley

\end{python}

The result is 2. If you forget what variables a state object has, you can just type the name:

\begin{python}

bikeshare

\end{python}

The result looks like a table with the variable names and their values:

\begin{tabular}{lr}

& {\bf \sf value} \\

\hline

{\bf \sf olin} & 10 \\

{\bf \sf wellesley} & 2 \\

\end{tabular}

The state variables and their values make up the {\bf state} of the system. We can update the state by assigning new values to the variables. For example, if a student moves a bike from Olin to Wellesley, we can figure out the new values and assign them:

\index{state}

\begin{python}

bikeshare.olin = 9

bikeshare.wellesley = 3

\end{python}

Or we can use {\bf update operators}, \py{-=} and \py{+=}, to subtract 1 from \py{olin} and add 1 to \py{wellesley}:

\index{update operator}

\index{operator!update}

\begin{python}

bikeshare.olin -= 1

bikeshare.wellesley += 1

\end{python}

The result is the same either way, but the second version is more versatile.

\section{Defining functions}

So far we have used functions defined in \py{modsim} and other libraries. Now we're going to define our own functions.

\index{function}

\index{defining functions}

When you are developing code in Jupyter, it is often efficient to

write a few lines of code, test them to confirm they do what

you intend, and then use them to define a new function. For

example, these lines move a bike from Olin to Wellesley:

\begin{python}

bikeshare.olin -= 1

bikeshare.wellesley += 1

\end{python}

Rather than repeat them every time a bike moves, we can define a

new function:

\begin{python}

def bike_to_wellesley():

bikeshare.olin -= 1

bikeshare.wellesley += 1

\end{python}

\py{def} is a special word in Python that indicates we are defining a new

function. The name of the function is \py{bike_to_wellesley}. The empty parentheses indicate that this function requires no additional information when it runs. The colon indicates the beginning of an indented

{\bf code block}.

\index{def}

\index{code block}

\index{body}

\index{indentation}

The next two lines are the {\bf body} of the function. They have

to be indented; by convention, the indentation is 4 spaces.

When you define a function, it has no immediate effect. The body

of the function doesn't run until you {\bf call} the function.

Here's how to call this function:

\index{call}

\begin{python}

bike_to_wellesley()

\end{python}

When you call the function, it runs the statements in the body, which update the variables of the {\tt bikeshare} object; you can check by displaying

or plotting the new state.

When you call a function, you have to include the parentheses. If you leave them out, like this:

\index{argument}

\index{parentheses}

\begin{python}

bike_to_wellesley

\end{python}

Python looks up the name of the function and displays:

\begin{python}

<function __main__.bike_to_wellesley>

\end{python}

This result indicates that \py{bike_to_wellesley} is a function. You don't have to know what \py{__main__} means, but if you see something like this, it probably means that you looked up a function but you didn't

actually call it. So don't forget the parentheses.

Just like \py{bike_to_wellesley}, we can define a function that moves a bike from Wellesley to Olin:

\begin{python}

def bike_to_olin():

bikeshare.wellesley -= 1

bikeshare.olin += 1

\end{python}

And call it like this:

\begin{python}

bike_to_olin()

\end{python}

One benefit of defining functions is that you avoid repeating chunks

of code, which makes programs smaller. Another benefit is that the

name you give the function documents what it does, which makes programs

more readable.

\section{Print statements}

As you write more complicated programs, it is easy to lose track of what is going on. One of the most useful tools for debugging is the {\bf print statement}, which displays text in the Jupyter notebook.

\index{print statement}

\index{statement!print}

Normally when Jupyter runs the code in a cell, it displays the value of the last line of code. For example, if you run:

\begin{python}

bikeshare.olin

bikeshare.wellesley

\end{python}

Jupyter runs both lines of code, but it only displays the value of the second line. If you want to display more than one value, you can use print statements:

\begin{python}

print(bikeshare.olin)

print(bikeshare.wellesley)

\end{python}

\py{print} is a function, so it takes an argument in parentheses. It can also take a sequence of arguments separated by commas, like this:

\begin{python}

print(bikeshare.olin, bikeshare.wellesley)

\end{python}

In this example, the two values appear on the same line, separated by a space.

Print statements are also useful for debugging functions. For example, we can add a print statement to \py{move_bike}, like this:

\begin{python}

def bike_to_wellesley():

print('Moving a bike to Wellesley')

bikeshare.olin -= 1

bikeshare.wellesley += 1

\end{python}

Each time we call this version of the function, it displays a message, which can help us keep track of what the program is doing.

\index{string}

The argument of this \py{print} is a {\bf string}, which is a sequence of letters and other symbols in quotes.

\section{If statements}

The \py{modsim} library provides a function called \py{flip} that takes

as an argument a probability between 0 and 1:

\begin{python}

flip(0.7)

\end{python}

The result is one of two values: \py{True} with probability 0.7 or \py{False} with probability 0.3. If you run this function 100 times, you should get \py{True} about 70 times and \py{False} about 30 times. But the results are random, so they might differ from these expectations.

\index{flip}

\index{True}

\index{False}

\py{True} and \py{False} are special values defined by Python. Note

that they are not strings. There is a difference between \py{True},

which is a special value, and \py{'True'}, which is a string.

\index{string}

\index{boolean}

\py{True} and \py{False} are called {\bf boolean} values because

they are related to Boolean algebra (\url{http://modsimpy.com/boolean}).

We can use boolean values to control the behavior of the program, using

an {\bf if statement}:

\index{if statement}

\index{statement!if}

\begin{python}

if flip(0.5):

print('heads')

\end{python}

If the result from \py{flip} is \py{True}, the program displays the string \py{'heads'}. Otherwise it does nothing.

The punctuation for if statements is similar to the punctuation for function definitions: the first line has to end with a colon, and the lines inside the if statement have to be indented.

\index{indentation}

\index{else clause}

Optionally, you can add an {\bf else clause} to indicate what should happen if the result is \py{False}:

\begin{python}

if flip(0.5):

print('heads')

else:

print('tails')

\end{python}

Now we can use \py{flip} to simulate the arrival of students who want to borrow a bike. Suppose students arrive at the Olin station every 2 minutes, on average. In that case, the chance of an arrival during any one-minute period is 50\%, and we can simulate it like this:

\begin{python}

if flip(0.5):

bike_to_wellesley()

\end{python}