\lab{Data Visualization}{Data Visualization}
\objective{Use data visualizations to explore data and communicate it to others.}
\label{lab:DataVis}

\noindent\emph{The purpose of visualization is insight, not pictures.} \small{---Card, Mackinlay, \& Shneiderman (after Hamming)}

\medskip

\noindent\emph{The ability to take data---to be able to understand it, to process it,
to extract value from it, to visualize it, to communicate it---that's
going to be a hugely important skill in the next decades,... because
now we really do have essentially free and ubiquitous data. So the
complimentary scarce factor is the ability to understand that data and
extract value from it.} \small{---Hal Varian (Google's Chief Economist)}
% in The McKinsey Quarterly, Jan 2009

\section*{What is data visualization?}
Data visualizations (or graphs) are used to understand and explore data as well as communicate results to others.  Often data is more easily interpreted or understood in graphical format than as a list of numbers or data points.

\section*{Types of visualizations}

Here are some of the most useful types of data visualizations.  We explain each of these in more detail below.

\begin{enumerate}

\item A \emph{line plot} plots $(x,y)$-pairs as points and connects them with a line.
You should use a line plot for plotting continuous functions or when there is a natural order to your two-dimensional data---for example when the data is a time series (a sequence of values over time).

\item A \emph{bar chart} is generally the preferred method for displaying a small (discrete) collection of one-dimensional data points. Each discrete data point is represented as a bar whose length is determined by the value of the data.

\item A \emph{histogram} is a special type of  bar graph where the length of each bar corresponds to the number of data points in a certain range (sometimes called a \emph{bin}).
(see Figure \ref{fig:healthcare}).
Histograms are useful for revealing statistical distributions.

\item A \emph{scatter plot} plots $(x,y)$ tuples as discrete points.  This should be used instead of line plot when the data is two-dimensional but has no natural order.

A scatter plot can reveal correlation (or lack thereof) between $x$ and $y$.

\item Three dimensional data can be displayed on a two-dimensional page with a \emph{contour plot}.  This draws lines in the plane where the third value is constant---like a geological map.  Filling in the contours with successive colors gives a  \emph{heat map}.

\item A \emph{pseudocolor plot} or \emph{heat map} uses color to display a third dimension on a two-dimensional page (see Figure \ref{fig:heatmap}).

Three-dimensional data can also be plotted as a surface in 3-space, but it is often difficult to find a view where none of the important features of the data are obscured.
A contour plot or a heatmap can help avoid this problem and is often easier for the viewer to decode.

%
%
%\item A \emph{sparkline} is a word-sized graphic that is often embedded inline with the text.
%Created by Edward Tufte, an innovator and recognized leader in the field of data visualizations, sparklines can be used to quickly communicate large-scale trends in a data set. They are also ideal for binary data sets.
%Two sources for creating sparkplots in Python are \cite{sparkplots} and \cite{sparklineshtml}.
%%TODO: Add an example of a sparkline
%
%
%\item \emph{Small multiples} are several minature graphics of the same type in a single visualization.
%Like sparklines, they were pioneered by Edward Tufte. Any of the plots discussed so far may be assembled into a small multiple.
%Small multiples are useful for viewing trends over time, when the data associated to each time is more complex than a single number.
%More generally, they can be used to compare many sets of similar data (\cite{tufte1990} p. 67).
%Figure \ref{fig:log_plots} could be called a small multiple, though frequently they contain more subplots.
%Recall that this kind of plot can be created in matplotlib with the command \li{plt.subplot()}.
\end{enumerate}

\subsection*{Bar Charts}

Bar charts are best for relatively small sets of discrete, one-dimensional data.  They are usually best presented with the bars running horizontally because when the bars are vertical the labels tend to run together (and the other possible solution to that problem---making the text vertical---is harder to read) as seen in Figure \ref{fig:barchart}.

\begin{figure}[h]
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{bar_chart_horizontal_sorted.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{bar_chart_unsorted.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{bar_chart_vertical_bars_horizontal_labels.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{bar_chart_vertical_bars_vertical_labels.png}
\end{subfigure}

\caption{Bar Chart Examples}
\label{fig:barchart}
\end{figure}

The data in a bar chart should generally be sorted in some natural way, based on the intended use.  If the chart will be used to compare the value of different data points, we usually sort by size; whereas if the chart will be used for looking up specific values, the data could be sorted alphabetically or in some other logical order that facilitates finding specific values.

As a general rule, bars should always start at zero because people are conditioned to expect that.  Failing to do this can be confusing or misleading.

\begin{problem}

The following table provides average heights of men and women in 17 countries. Order the data and plot a horizontal bar chart.

\begin{tabular}{ | l || l | l | }
\hline
Country & Average Male Height & Average Female Height \\
\hline
Austria & 179.2 cm (5 ft 7.5 in) & 167.6 cm (5 ft 6 in) \\
Bolivia & 160.0 cm (5 ft 3 in) & 142.2 cm (4 ft 8 in) \\
England & 177.8 cm (5 ft 10 in) & 164.5 cm (5 ft 5 in) \\
Finland & 178.9 cm (5 ft 10.5 in) & 165.3 cm (5 ft 5 in) \\
Germany & 178 cm (5 ft 10 in) & 165 cm (5 ft 5 in) \\
Hungary & 176 cm (5 ft 9.5 in) & 164 cm (5 ft 4.5 in) \\
Japan & 172.5 cm (5 ft 7.5 in) & 158 cm (5 ft 2 in) \\
North Korea & 165.6 cm (5 ft 5 in) & 154.9 cm (5 ft 1 in) \\
South Korea & 170.8 cm (5 ft 7 in) & 157.4 cm (5 ft 2 in) \\
Montenegro & 183.2 cm (6 ft 0 in) & 168.4 cm (5 ft 6.5 in) \\
Norway & 182.4 cm (6 ft 0 in) & 168 cm (5 ft 6 in) \\
Peru & 164 cm (5ft 4.5 in) & 151 cm (4 ft 11.5 in) \\
Sri Lanka & 163.6 cm (5 ft 4.5 in) & 151.4 cm (4 ft 11.5 in) \\
Switzerland & 175.4 cm (5 ft 9 in) & 164 cm (5 ft 4.5 in) \\
Turkey & 174 cm (5 ft 8.5 in) & 158.9 cm (5 ft 2.5 in) \\
U.S. & 176.1 cm (5 ft 9.5 in) & 162.1 cm (5 ft 4 in) \\
Vietnam & 165.7 cm (5 ft 5 in) & 155.2 cm (5 ft 1 in) \\
\hline
\end{tabular}
\label{prob1}
\end{problem}

\subsection*{Histograms}

A histogram depicts a distribution of numerical data. They can be used to look for trends over time and to investigate statistical distributions.
Histograms can give a clear view of the way data is distributed, but sometimes changing the size and position of the bins (a small interval of that data) can change the picture substantially.

You can create a histogram in matplotlib with the command \li{plt.hist()}.

When plotting histograms, it can sometimes be useful to include reference lines.  A nice way to do this without cluttering the figure is to make the reference lines white.  You can do this in matplotlib with the command \li{plt.grid(True, color='w',linestyle='-')}.

%TODO example of a basic histogram.  Be sure to show the data so the reader can see how this is different from a standard bar.  Also give an example of the same data with bins a different size that gives a different picture.

\begin{lstlisting}
from numpy.random import randn
from matplotlib import pyplot as plt

data = randn(75) + randn(75) + randn(75) + randn(75)
plt.hist(data)
plt.grid(True, color = 'w', linestyle = '-')

plt.title("histogram)
plt.show()

\end{lstlisting}

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{histogram.png}
\end{subfigure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{histogram_referenceLines.png}
\end{subfigure}
\caption{Histogram and Histogram with Reference Lines}
\label{fig:histogram}
\end{figure}

\begin{problem}
Using 1000 random numbers from a Gaussian distribution,
\begin{lstlisting}
from numpy.random import normal
gaussian_numbers = normal(size=1000)
\end{lstlisting}
plot a histogram with white reference lines. Vary the number of bins and compare.

\end{problem}

\subsection*{Line Plot}

Line plots should not be used for data that has no natural ordering or progression because it gives the misimpression that there is an order or progression when there is none (see Figure \ref{fig:lineplot_bad}.

Recall that you can create a line plot in matplotlib with the command \li{plt.plot()}.

When plotting line graphs in matplotlib, the default line width is usually a little too thin.  It will help your reader (or you) if you set the line width to 2 or more with the argument \li{lw=2}.

%\li{plt.plot(x,y,lw=2)}

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{line_plot_bad_thin.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{line_plot_bad_thick.png}
\end{subfigure}
\caption{Line Plot with previous bar chart data}
\label{fig:lineplot_bad}
\end{figure}

\begin{problem}
Using 1000 subintervals, plot the equation

$$y = x^2np.sin(x)$$,
$$x \in [0,100]$$

It should look like Figure \ref{fig:lineplot}.
\end{problem}

\begin{figure}
\centering
\begin{subfigure}{.5\textwidth}
\centering
\includegraphics[width=\textwidth]{line_plot.png}
\end{subfigure}
\caption{solution to Problem 3}
\label{fig:lineplot}
\end{figure}

\subsection*{Scatter Plots}

Scatter plots should be used instead of line plot when the data is two-dimensional but has no natural order.

You can create a scatter plot in matplotlib with the command \li{plt.scatter()}.

\begin{figure}[h]
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{scale_scatter_zoomed_in.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{scale_scatter_zoomed_out.png}
\end{subfigure}
\caption{scatter plots with and without a strong correlation}
\label{fig:scatter_correlation}
\end{figure}

Figure \ref{fig:scatter_correlation} displays two scatter plots, the first appearing to have no strong correlation and the second a strong correlation. However, the same data is being plotted and the only difference is the scale and window size. Manipulating these can change your interpretation and should be done only after careful consideration.

\begin{problem}
Plot the average heights of men against women using the data from Problem \ref{prob1}. Zoom in and zoom out to see what difference that makes.
\end{problem}

\subsection*{Contour Plots and Heatmaps}

Three dimensional data can be displayed on a two-dimensional page with a \emph{contour plot}.  This draws lines in the plane where the third value is constant---like a geological map.

You can create a contour plot in matplotlib with
\li{plt.contour()}.

Filling in the contours with successive colors gives a  \emph{heat map}.

Note that the default color map for matplotlib is the so-called \emph{rainbow color map}.  This is a very poor choice for a heat map or colored contour map because people do not naturally interpret one color to be greater than another.  To solve this problem in matplotlib, use the argument \li{cmap='NAME\_OF\_COLORMAP'}
where \li{NAME\_OF\_COLORMAP} is one of matplotlib's sequential or diverging colormaps.

\begin{lstlisting}
import numpy as np
from matplotlib import pyplot as plt

n=400
xrange = np.linspace(-1.5,1.5,n)
yrange = np.linspace(-1.5,1.5,n)
X, Y = np.meshgrid(xrange,yrange)
F = Y**2 - X**3 + X**2
plt.contourf(X, Y, F, [-2,-1,0.0001,1,2,3,4,5] ,cmap=plt.get_cmap('afmhot'))
\end{lstlisting}

\begin{figure}[h]
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{contour_map.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{contour_map_filled.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{contour_map_rainbow_filled.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{contour_map_rainbow.png}
\end{subfigure}
\caption{Contour Maps}
\label{fig:contour}
\end{figure}

TODO add in the list (and pix) of sequential and diverging colormaps from \url{http://matplotlib.org/examples/color/colormaps_reference.html}

\begin{problem}
Using 400 intervals, plot a filled contour map of

$$z = sin(x) + sin(y)$$,$$ x\in[0,12\pi], y\in[0,12\pi]$$.

Be sure to use an appropriate color map.
\end{problem}

\begin{figure}
\centering
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{heatmap_color.png}
\end{subfigure}%
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{heatmap_hot.png}
\end{subfigure}
%\includegraphics[width=\textwidth]{heatmap.png}
\caption{Both of these pseudocolor plots depict the function $z = \sin(x)\sin(y)$ on the domain $[-1,4] \times [-4,1]$.
The plot at left uses a rainbow gradient which is pretty to look at but whose choice of colors has no meaningful relationship to the data.
The plot at right uses the colormap called \li{afmhot}, which has the important benefit that the lighter colors are naturally associated with higher values, while the darker colors are naturally associated with lower values.}
\label{fig:heatmap}
\end{figure}

You can also create a pseudocolor plot in matplotlib with the \li{plt.pcolormesh()} command.

One situation where heatmaps are very useful is when data is naturally associated to a geographic location.  When a heatmap is plotted on a map it is often called a \emph{cloropleth}.
\begin{comment}
TODO example of a cloropleth---maybe percentage income donated to charity by county? (makes Utah look good).

As in the case of a histogram, if the data is relatively coarse then the way the data is divided up can have an effect on the overall picture of the heatmap.

TODO make an example where things are binned in two different ways  and give a different-looking result.

\end{comment}

Finally, three-dimensional data can also be plotted as a surface in 3-space, but it is often difficult to find a view where none of the important features of the data are obscured.
A heatmap can help avoid this problem and is often easier for the viewer to decode.

TODO give example of how the surface can obscure your view and how the contour or heatmap gives a clearer picture.

\section*{Exploring data with visualizations}
When you visualize data you may notice trends that are not apparent from the numbers.
The following problem is a famous example of this phenomenon.

\begin{problem}\label{prob:anscombe}
The data sets I-IV in Table \ref{table:anscombe} are known as Anscombe's quartet.
Each dat set has identical statistical properties.
In each case,
\begin{itemize}
\item The mean of $x$ is 9 and the mean of $y$ is $7.5$.
\item The variance of $x$ is 11 and the variance of $y$ is 4.127.
\item The correlation between $x$ and $y$ is .816.
\item The linear regression line is $y=3+5x$.
\end{itemize}
Plot each data set. What do you notice?

\begin{table}[H]
\begin{tabular}{l l  |  l l  |  l l  |  l l }
I & & II & & III & & IV\\
x & y & x & y & x & y & x & y \\
\hline
10.0 & 8.04 & 10.0 & 9.14 & 10.0 & 7.46 & 8.0 & 6.58 \\
8.0 & 6.95 & 8.0 & 8.14 & 8.0 & 6.77 & 8.0 & 5.76 \\
13.0 & 7.58 & 13.0 & 8.74 & 13.0 & 12.74 & 8.0 & 7.71 \\
9.0 & 8.81 & 9.0 & 8.77 & 9.0 & 7.11 & 8.0 & 8.84 \\
11.0 & 8.33 & 11.0 & 9.26 & 11.0 & 7.81 & 8.0 & 8.47 \\
14.0 & 9.96 & 14.0 & 8.10 & 14.0 & 8.84 & 8.0 & 7.04 \\
6.0 & 7.24 & 6.0 & 6.13 & 6.0 & 6.08 & 8.0 & 5.25 \\
4.0 & 4.26 & 4.0 & 3.10 & 4.0 & 5.39 & 19.0 & 12.50 \\
12.0 & 10.84 & 12.0 & 9.13 & 12.0 & 8.15 & 8.0 & 5.56 \\
7.0 & 4.82 & 7.0 & 7.26 & 7.0 & 6.42 & 8.0 & 7.91 \\
5.0 & 5.68 & 5.0 & 4.74 & 5.0 & 5.73 & 8.0 & 6.89 \\
\end{tabular}
\caption{These four sets of data are known as Anscombe's quartet.}
\label{table:anscombe}
\end{table}
\end{problem}

As Problem \ref{prob:anscombe} demonstrates, a picture can quickly reveal properties of the data that are difficult to see in a list of numbers.

\subsection*{The Iterative Process of Exploratory Visualization}

Understanding a data set through visualization is often an iterative process. We start with an initial visualization---usually a broad overview.  Examining the result leads to observations that provoke questions.  We then filter or transform the data and adjust the visualization based on those questions and observations, and then repeat the process until we converge on a useful result.

Some of the questions that you should be asking in this iterative process include:
\begin{enumerate}
\item Are the data correct and reliable?
\item Are there any clear patterns, trends, or irregularities?
\item Would a different type of visualization give more information?
\item Is something unusual or interesting going on outside my view?
\item Would filtering the data to look at a particular subset give a more informative picture?
\item Would a transformation of the data give a more informative picture?
\end{enumerate}

\subsubsection*{Data integrity}

Visualization is a powerful way to identify problems with your data set.  Ask yourself, whether the results look like what you expect.  Are they the right magnitude? Are there missing values?

\subsubsection*{Trends, patterns, and irregularities}

Some patterns you may look for:
\begin{enumerate}
\item Are there trends in time (up, down, flat, cyclical)?
\item Does the data look random, cyclical, or patterned?
\item Are there clear correlations between the $x$- and $y$- values?
\item Is the trend linear or curved?
\item Do lines intersect, or are they parallel?
\item Are the data symmetric or skewed?
\item What is the variance (wide vs narrow)?
\item Are there clusters and gaps?
\item Are the data dense or sparse?
\end{enumerate}

\subsubsection*{Using different types of visualization}

Data can be visualized using different types of visualization and is relatively easy to transform.

\begin{problem}
This data

\begin{tabular}{ | l || l | l | }
\hline
Number of students playing each instrument \\
\hline
cello & 14 \\
clarinet & 41 \\
flute & 30 \\
guitar & 15 \\
piano & 53 \\
saxophone & 18 \\
violin & 22 \\
\hline
\end{tabular}

 is visualized in Figure \ref{fig:pie} as a pie chart.

Choose another type of visualization and plot the data again. What are the relative merits of your plot compared to the pie chart?

\end{problem}

\begin{figure}
\centering
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{pie_instruments.png}
\end{subfigure}%
\caption{Pie Chart for Instrument Problem}
\label{fig:pie}
\end{figure}
\subsubsection*{Changing the view}

By choosing to plot only a portion of your data, you may be able to focus your attention on the most relevant data.  On the other hand, you may also miss some interesting behavior in the data you didn't graph. Figures \ref{fig:scatter_correlation} and \ref{fig:line_scale} are two such examples.

Another issue to consider is scale. If a number changes from 50,000 to 55,000 over some period, that  increase can appear small or large, depending on where we start the $y$-axis and how long we stretch out the $x$-axis (see Figure \ref{fig:dog_plots}).

You can modify the scale of an existing plot using \li{plt.yscale()} or \li{plt.xscale()}.

\begin{figure}
\centering
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{scale_line_zoomed_in.png}
\end{subfigure}%
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{scale_line_zoomed_out.png}
\end{subfigure}
\caption{Scale Issues}
\label{fig:line_scale}
\end{figure}

\begin{problem}
Return to your plot of

$$y = x^2sin(x)$$ $$x\in[0,100]$$

from problem 3 and plot again a few times adjusting the scale.
\end{problem}

\subsubsection*{Filtering the data}

Sometimes important information about a subset of the data can be obscured by considering the whole data set.
\begin{comment}
TODO example where scatterplot of all people looks random, but separating by something like education level shows clear trends for one level.
\end{comment}

\subsubsection*{Transforming the data}

Often a transformation of the data can reveal useful information that was previously hidden.

For example, data that grows very rapidly or that is tightly clustered may be better visualized by plotting the logarithm of the data, instead of the original data, A log-lin plot (also called a log plot) is constructed by by taking the logarithm of only the $y$-values of your data set.

This is easily done in matplotlib with the command \li{plt.semilogy(x,y)}.  The syntax is the same as \li{plt.plot}.

On the left side of Figure \ref{fig:exp}, $x^{14}$ and $x^{13}$ look almost idential. Graphic them on a log-lin plot (as on the right side of Figure \ref{fig:exp}), their differences become apparent.

\begin{figure}[h]
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{exponential.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{exponential_loglin}
\end{subfigure}
\caption{Plotting exponential graphs on a log-lin plot}
\label{fig:exp}
\end{figure}

Similarly, if the data grows very slowly, you may find that a lin-log plot (given by by taking the logarithm of only the $x$-values) gives a more useful view.
This is easily done in matplotlib with the command \li{plt.semilogx(x,y)}

Transformations can also be useful for histograms.
As an example, let us look at the cost of health care claims.
Our data set is bogus but created to closely resemble real-life data.
An initial plotting of the data produces the histogram on the left in Figure \ref{fig:healthcare}.
From this picture, it is hard to see the nature of the data---the plot just looks like a single bar.
We may think that all health care claims are cheap.
However, when we take the logarithm of the claims prices, we get the histogram on the right in Figure \ref{fig:healthcare}.
Graphed on this scale, the data has a bell-shaped distribution similar to a normal distribution.
Moreover, we see that there are some very expensive claims being submitted, though they are few.
\begin{figure}
\centering
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{healthcare_linscale.pdf}
\end{subfigure}%
\begin{subfigure}{.5\textwidth}
  \centering
  \includegraphics[width=\textwidth]{healthcare_logscale.pdf}
\end{subfigure}
\caption{The same data (meant to resemble the prices of health care claims) is plotted in both histograms above.
The plot at left is a lin-lin scale, whereas the plot at right is a log-lin scale.
In this case, changing scales revealed important information about the data.}
\label{fig:healthcare}
\end{figure}

As a general rule, log-lin plots are useful when the range of the $y$-values is orders of magnitude larger than the range of the $x$-values.
Our health care data was an example of this.
Similarly, lin-log plots are useful when the range of the $x$-values is much bigger than the range of the $y$-values.
In any case, you can try applying a log scale to one or both of your axes as a way to explore your data.

Let us analyze the mathematics behind log plots.
Suppose we have some data that roughly follows the line $y=cx^a$ where $c$ and $a$ are constants.
Taking the logarithm of both sides yields
\[
\log(y) = a\log(x) + \log(c).
\]
If we set new variables $X = \log(x)$ and $Y = \log(y)$, then this equation becomes $Y = aX + \log(c)$, which is the equation of a straight line.
So  on a log-log plot, polynomial-shaped data looks linear.
Similarly, taking the log of $y = a^x$ yields
\[
\log(y) = \log(a)x,
\]
so exponential data looks linear on a log-lin plot.
Finally, data of the form $y = a\log(x)+b$ will look linear on a lin-log plot.
See Figure \ref{fig:log_plots}.

\begin{figure}
\centering
\includegraphics[width=\textwidth]{log_plots.pdf}
\caption{Here are some functions plotted on various logarithmic and linear scales.
The dark blue line is $y=x$, the green line is $y=\log(x)$, the red line is $y=e^x$, and the light blue line is $y=x^3$.
We have used different ranges on the $y$-axes to highlight appropriate parts of the graphs.}
\label{fig:log_plots}
\end{figure}

Be warned that many different functions can look linear on log plots.
Thus, if you graph your data on a log-log plot and you see a line, you CANNOT conclude that your data must follow a polynomial.
In general, you need more information.

\begin{problem}
Graph your data from Problem 1 in the Complexity and Sparse Matrices lab on a (a) log-log scale, (b) log-lin scale, and (c) lin-log scale.
Which plot makes the data easiest to understand?

In this problem you will analyze the complexity of the following functions.

\begin{enumerate}
\renewcommand{\theenumi}{\alph{enumi}}
\item (Optional)
\begin{lstlisting}
# Single ``for'' loop
def func1(n):
    n = 500*n
    sum(xrange(n))
\end{lstlisting}

\item
\begin{lstlisting}
# Double ``for'' loop
def func2(n):
    n = 3*n
    t = 0
    for i in xrange(n):
        for j in xrange(i):
            t += j
\end{lstlisting}

\item
\begin{lstlisting}
# Square a matrix
def func3(n):
    n = int(1.2*n)
    A = np.random.rand(n, n)
    np.power(A, 2)
\end{lstlisting}

\item
\begin{lstlisting}
# Invert a matrix
from scipy import linalg as la
def func4(n):
    A = np.random.rand(n, n)
    la.inv(A)
\end{lstlisting}

\item (Optional)
\begin{lstlisting}
# Find the determinant of a matrix.
from scipy import linalg as la
def func5(n):
    n = int(1.25*n)
    A = np.random.rand(n, n)
    la.det(A)
\end{lstlisting}
\end{enumerate}

Do this as follows:
\begin{enumerate}
\item Time how long each function takes to run on an input of size $n$ for $n=100, 200, 400$, and $800$.
\item Graph your data as follows. Note that we rescaled the inputs to the functions so that your lines would begin at roughly the same place on the y-axis.
\begin{enumerate}
\item For each function, plot a line using $n=100, 200, 400$, and $800$ for $x$-values and your runtimes for $y$-values. Make sure your $y$-values are all in the same units! When you call the function \li{plt.plot()}, specify a value for the keyword parameter \li{label} so you can reference each line later. For example, the call \li{plt.plot( x, y, label="Function 1")} attaches the label "Function 1" to this line.
\item After plotting all your lines, call \li{plt.legend()} to draw a legend on your graph. Use the keyword argument \li{loc} to specify the location of the legend. Some possible values are \li{'upper left'} and \li{'right'}. See the documentation for more options. Your final graph should look something like the figure below.\footnote{From this graph, you can see that inverting a matrix is an incredibly time consuming operation. In Lab \ref{lab:ChangeBasis} you will learn fast algorithms for solving linear systems without inverting matrices. In fact, inverting matrices is so costly in terms of temporal and spatial complexity that there is hardly ever a good reason to do it.}
\end{enumerate}
\item For each function, discuss how its spatial and temporal complexity could have contributed to its runtime.
\end{enumerate}

\end{problem}

\begin{problem}
Given the following data,

\begin{tabular}{| l | l | l | l | l | l | l |}
\hline
male & female & age & marital status & college & pet owner & employed \\
\hline
Y & N & 21 & S &  N & N & N \\
N & Y & 25 & M & Y & Y & Y\\
Y & N & 26 & M & Y & Y & Y\\
Y & N & 20 & S & Y & N & Y\\
Y & N & 27 & M & Y & N & Y\\
N & Y & 22 & S & N & N & N\\
Y & N & 28 & M & Y & Y & Y\\
N & Y & 29 & M &  N & N & N\\
N & Y & 23 & S &  N & N & N\\
N & Y & 28 & M & N & N & Y\\
Y & N &  24 & S & Y & Y & Y\\
\end{tabular}

explore it. Plot it in different ways, zoom in and out, and do a transformation.
\end{problem}

\section*{Communicating data with visualizations}

As the saying has it, ``a picture is worth a thousand words.''
Certainly, a data visualization is far more valuable than a thousand data points to a colleague who wants to understand the results of your analysis.
Data visualizations are critical for communication in both business and research.

\subsection*{Choosing the right visualization}
At this point, you have already used visualization to explore your data and draw conclusions, and you are ready to tell your results to someone else.
The first step in creating a graphic to do this is to choose the right type of visualization.
As we saw in the section ``Types of Visualizations,'' there are many possibilities, each with different strengths.
You should carefully consider which one best suits your data set and communication needs.  Your goal should always be communicating as clearly, effectively, and accurately as possible.

\subsubsection*{Visualizations to avoid}
There are also several popular types of visualizations that you should generally \textbf{not} use.  These may look pretty, but they tend to obscure information or are easily confused, because of natural difficulties humans have interpreting them.

For example, people have much more difficulty judging changes and variation in area than they do in length.
As a result, charts that depend on distinguishing variation in area will be less effective.  One of the most common charts that has this problem is the pie chart. Figure \ref{fig:pievsbar} indicates the difficult in judging the difference in area between the lobster and beans.

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{pie_chart_sorted.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{bar_chart_horizontal_sorted.png}
\end{subfigure}
\caption{A pie chart on the left that has been transformed into a bar chart on the right}
\label{fig:pievsbar}
\end{figure}

As bad as the pie chart may be, there is a way to make things worse---make the chart three-dimensional.  It seems to be very popular for people to convert a visualization that is naturally 2 or 1 dimensional into one that is artificially three dimensional, but this inevitably makes things more confusing.  For example, we already have difficulty distinguishing the variation in area in a pie chart, and when we add a third dimension, it becomes even harder (see Figure \ref{fig:pie3d}.

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{pie_chart3d.png}
\end{subfigure}
\caption{a 3d pie chart}
\label{fig:pie3d}
\end{figure}

Other visualization types that tend to be confusing and ineffective include the stacked bar and the radar graph.  The radar graph is just generally confusing.  While problem with stacking bars is that the second bar is not based at zero, so it becomes difficult to compare the different parts, as in Figure \ref{fig:stacked}

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{stackedbar.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
\includegraphics[width=\textwidth]{stackedbarinv.png}
\end{subfigure}
\caption{Stacked Bar Chart comparison}
\label{fig:stacked}
\end{figure}

In these examples differences in design give completely different impressions of the data, so the reality of the data is obscured rather than illuminated by the design.  As the famous visualization guru, Edward Tufte, says, ``Show data variation, not design variation.''  Pie charts and stacked bar charts show design variation more than data variation.

\subsection*{Simplify}

\noindent\emph{A sentence should contain no unnecessary words, a paragraph no unnecessary sentences for the same reason that a drawing should contain no unnecessary lines and a machine no unnecessary parts.} \small{---Strunk and White}

Once you have chosen the visualization best suited to your data, you should design the details so that all elements contribute to the communication of data.

Edward Tufte offers two principles for simplifying graphics: (1) erase ink that does not communicate data, and (2) erase ink that communicates data redundantly.  (\cite{tufte2001} pp.96-100). According to these principles, decorative backgrounds, fancy lettering, and cute graphics in the corner of you plots should all be deleted.

Other opportunities for simplification are harder to notice and implement. As an example, let us examine the plot on the right of Figure \ref{fig:healthcare}.
This plot was created with the following code.

\begin{lstlisting}
import numpy as np
import scipy as sp
from matplotlib import pyplot as plt

m = 2.07
s = 0.63
num_samples = 10000
samples = []

for i in xrange(num_samples):
    samples.append(sp.random.lognormal(m, s))

sp_samples = sp.array(samples)

# Plot the histogram
plt.hist(sp_samples, 100)
\end{lstlisting}

For purposes of this example, the only important part of the above code is the line \li{plt.hist(sp_samples, 100)} that plots the histogram.
What ink in this plot can we erase because it communicates no data?

First, let's get rid of the vertical black lines that separate the bars of the histograph and the black outline. These are meaningless for our application and only distract.
We can do this by modifying our call to \li{plt.hist()} as follows.

\begin{lstlisting}
plt.hist(sp_samples, 100, edgecolor='none')
\end{lstlisting}

Next, let us turn off the top and right lines that box in the graph.
To do this, we need to access the ``axis'' object associated with the figure.
We can access the ``axis'' object with the command \li{plt.gca()} (get current axis).

\begin{lstlisting}
# Get current axis instance
axis = plt.gca()

# Hide top and right spines
axis.spines['right'].set_visible(False)
axis.spines['top'].set_visible(False)
\end{lstlisting}

These commands only turn off the sides of the box, not the tick marks.
To turn off the tick marks we run the following commands.

\begin{lstlisting}
# Only show bottom and left tick marks
axis.yaxis.set_ticks_position('left')
axis.xaxis.set_ticks_position('bottom')
\end{lstlisting}

Finally, we do not need so many tick marks on the $x$- and $y$-axes.
We adjust those along with specifying the range on each axis.

\begin{lstlisting}
# Fix x and y ranges
plt.xlim(0,70)
plt.ylim(0, 800)

# Use fewer axis ticks
plt.xticks(np.arange(0, 71, 35))
plt.yticks(np.arange(0, 801, 200))
\end{lstlisting}

The final graph is shown in Figure \ref{fig:simplify}.
Note how much cleaner this looks than the original.

\begin{figure}
\centering
\includegraphics[width=\textwidth]{simplify.pdf}
\caption{A simplified version of the histogram in Figure \ref{fig:healthcare}.}
\label{fig:simplify}
\end{figure}

%TODO: Rewrite this problem to use a specific image with a specific context
\begin{problem}
Choose a graph you previously created that you think could use simplification.
Apply at least 3 of the following to simplify your plot:
\begin{enumerate}
\item Turn off some of the spines.
\item Fix the x or y range to better fit your data.
\item Change the number of x or y ticks.
\item Choose a better color scheme.
\end{enumerate}
Simplify your image in any other ways you can think of.
\end{problem}

\subsection*{Small Multiples}

Often we have too much information to display cleanly in one chart.  One indicator of this is if the reader must often look back and forth between a legend and the chart to decode the images.  A very useful way to deal with this problem is the method of \emph{small multiples}, an idea made famous by Edward Tufte.

The idea is to separate the data into many small graphics, placed near each other in a way that allows us to easily compare them.

For example, one might wish to compare the first six Chebyshev polynomials.  It would be natural to plot them together on the same graph, as in Figure \ref{fig:PoT}.  But this graph is too cluttered and one must constantly refer back to the legend to identify which colored line is which.

\begin{figure}
\centering
\begin{subfigure}{.45\textwidth}
  \centering
  \includegraphics[width=\textwidth]{PoT.png}
\end{subfigure}
\begin{subfigure}{.45\textwidth}
\centering
  \includegraphics[width=\textwidth]{PoT_separate.png}
\end{subfigure}
\caption{Plotting on top variations and plotting separately}
\label{fig:PoT}
\end{figure}

The small multiple approach is to plot each polynomial on its own set of axes, adjacent to each other and aligned in such a way that you can easily compare the different plots as in Figure\ref{fig:PoT}

Note how even with 9 plots instead of 6, it is much easier to identify the different polynomials and to compare them.

The main tool you need to make small multiples is the command \li{ax = plt.subplot()}.  This allows you to set up multiple plots, and access them one at a time.

\begin{lstlisting}
import numpy as np
from matplotlib import pyplot as plt
from numpy.polynomial import Chebyshev as T

def Chebyshev_subplots():
    fig = plt.figure(dpi=100)
    fig.set_size_inches(10,10)
    fig.suptitle('Chebyshev Polynomials', fontsize=20)

    x = np.linspace(-1,1,500)

    for i in xrange(9):
        ax = plt.subplot(3,3,i+1)
        ax.plot(x, T.basis(i)(x), lw=2, label="$T_%d$"%i)
        plt.xlim(-1.1,1.1)
        plt.ylim(-1.1,1.1)
        ax.set_title('$T_%d$'%i)
        if i%3:
            ax.set_yticklabels([])
            ax.yaxis.set_ticks_position('none')
        if i<6:
            ax.xaxis.set_ticks_position('none')
            ax.set_xticklabels([])

    plt.show()
\end{lstlisting}

\begin{problem}

The $n+1$ Bernstein basis polynomials of degree $n$ are defined as

$$b_{v,n} = {{n} \choose {k}} x^v (1-x)^{n-v}, v = 0, 1,..., n.$$

Plot the first few Bernstein basis polynomials up to $v,n$ [0,3] as small multiples and compare that to the cluttered version of plotting them on top of each other.

\end{problem}

\subsection*{Tell the truth}

Just as graphics can tell your reader about your data, they can also give your viewer false impressions.
You should never use data visualizations to mislead your reader.
There are many ways pictures can be used to lie, and some of them can be unintentional.

\subsubsection*{2- and 3-d effects}
For example, if we see differences in flat shapes by area, not width or height.
Suppose you are creating a pictogram to demonstrate the recent increase in housing prices, which have doubled in the last $n$ years.
So, you draw two houses, one whose sides are 1cm and one whose sides are 2cm.
The area of the second house is now $2^2=4$ times as big as the area of the first. And your reader will likely interpret the picture as a four-fold increase rather than just double.
Hence, you should make two-dimensional pictures proportional in \emph{area} to the numbers they represent.

Even worse, volume is cubed rather than squared, so if a picture is intended to look like a three-dimensional object, doubling the side lengths will give the impression of an eight-fold increase.

%TODO add figures with 2- and 3-d houses doubling in side length.

Three-dimensional special effects also tend to be misleading.  As mentioned above, a 3-D pie chart, for example, can be used to distort the sizes of its slices.
Similarly, a 3-D histogram can use perspective to distort the relative differences between bars.

\subsubsection*{Base, Scale, and Labels}

As mentioned above, bar charts should be based at 0 and all charts should be scaled in the way the most clearly conveys the most important and relevant information.  When there is a possibility of confusion, axes and key data values should be labeled for clarity.

\begin{figure}
\centering
\includegraphics[width=\textwidth]{dog_plots.pdf}
\caption{The graph of some data can look very different depending on the scale.
Here are two graphs of the ``same'' line over the same range (1 to 4).
The only difference is the $y$-range. Notice easy it is to manipulate the y-scale to imply either a large or small increase in $y$.
These figures are especially misleading when we leave the range markers off of the $y$-axes.}
\label{fig:dog_plots}
\end{figure}

As in any form of communication, integrity is important in data visualization.
You will win more respect for yourself and those you represent if you avoid misleading diagrams.

\subsection*{Additional Resources}

There are many software packages that facilitate the visual exploration of data.
One Python library is Glue (see \cite{glue}).

Some packages for making nicer looking plots include \li{Seaborn} and \li{prettyplotlib}.  TODO get refs

For more about visualization of data, we highly recommend the following books:

TODO get full refs for the follwoing

\begin{itemize}
\item \emph{How to lie with statistics}
\item \emph{Envisioning Information} by Edward Tufte
\item \emph{The visual display of quantitative information} by Edward Tufte (2nd edition)
\item \emph{Now you see it} by Stephen Few
\end{itemize}

\printbibliography


\section{Objects and Event selections}
\label{sec:vbszz_selection}

\subsection{Object selections}

The selection of analysis relies on the definition of multiple objects: \textit{electrons}, \textit{Muons}, and \textit{jets}.
Details of definition for each object are described as below:

\textbf{Muon:}
To increase the acceptance range in reconstruction (reco) -level for \llll channel, all four types of muons
(CB, ST, CT, ME muons, described in section~\ref{sec:muon}) are used.
The identified muons are then required to pass $p_{T} > 7~\gev$ and $|\eta| < 2.7$,
and satisfy the \textit{Loose} identification criterion (see definition in sec~\ref{sec:muon}).
The impact parameter cuts are further applied to suppress the contribution from cosmic muons and non-prompt muons,
with the value of: $|d_{0}/\sigma(d_{0})| < 3.0$ and $|z_{0} sin\theta|$ < 0.5 mm,
where $d_{0}$ is the transverse impact parameter relative to the beam line, $\sigma(d_{0})$ is its uncertainty,
and $z_{0}$ is the longitudinal impact parameter relative to the primary vertex.
In order to avoid muons associated with jets, all muons are required to be isolated and pass \textit{FixedCutLoose} isolation criteria of $E_{T}^{topocone20} / p_{T} < 0.3$ and $p_{T}^{varcone30} / p_{T} < 0.15$.

\textbf{Electron:}
As described in section~\ref{sec:electron}, electrons are reconstructed from energy deposits in the EM calorimeter matched to a track in the inner detector.
The electron candidates must satisfy the \textit{Loose} criterion defined by the likelihood-based (LH) method.
And electrons are required to have $p_{T} > 7~\gev$ and $|\eta| < 2.47$.
Moreover, the impact parameter requirements of $|d_{0}/\sigma(d_{0})| < 5.0$ and $|z_{0} sin\theta|$ < 0.5 mm are applied.
Same as muon, all electrons are required to satisfy \textit{FixedCutLoose} isolation criteria,
which, for electrons, is $E_{T}^{topocone20} / p_{T} < 0.2$ and $p_{T}^{varcone20} / p_{T} < 0.15$.

\textbf{Jets:}
Jet are key signatures for VBS processes.
This analysis use the jets clustered using the anti-$k_t$ algorithm with radius parameter $R$ = 0.4, more details of jets' reconstruction can be found in section~\ref{sec:jet}.
The jets are required to satisfy $\pT >$ 30 (40)~\gev~in the $|\eta| <$ 2.4 ($2.4 < |\eta| < 4.5)$ region.
To further reduce the effects of pile-up jets, a jet vertex tagger (JVT) is applied to jets with $p_{T} <$ 60~\gev~and $|\eta| < 2.4$ to select jets from hard-scattering vertex~\cite{PERF-2014-03}.

\textbf{Overlap removal:}
An overlap-removal procedure is applied to selected leptons and jets.
To enhance the selection efficiency, leptons are given higher priority to be kept when overlapping with jets.
%With this lepton preferred method, the events of EW signal after selection increases about 19\% while background only increases about 14\%.
More details of the strategy is summarized in table~\ref{tab:OR_4l}.
\begin{table}[htbp]
\begin{center}
\renewcommand\arraystretch{1.8}
\resizebox{\linewidth}{!}{
\small
\begin{tabular}{ l | c | c}
\hline
\centering & Reference objects & Criteria\\
\hline \hline
Remove electrons & electrons & Share a track or have overlapping calorimeter cluster. Keep higher \pt electron \\
\hline
Remove muons & electrons & Share track and muon is calo-tagged \\
\hline
Remove electrons & muons & Share track \\
\hline
\multirow{3}{*}{Remove jets} & electrons & $\Delta R_{e-jet}$ < 0.2  \\
\cline{2-3}
                   & \multirow{2}{*}{muons}     & $\Delta R_{\mu-jet}$ < 0.2 OR muon track is ghost-associated to jet \\
                   &       &  \textbf{AND} ($N_{Trk}(jet)<3$ OR ($p_T^{jet}/p_T^{\mu}<2$ and $p_T^{\mu}/\Sigma_{TrkPt}>0.7$)) \\
\hline\hline
\end{tabular}}
\end{center}
\caption{Overlap removal criteria between pre-selection objects for the \llll channel. The overlap removal follows the order shown in this table. Once an object has been marked as removed, it does not participate in the subsequent stages of the overlap removal procedure. }
\label{tab:OR_4l}
\end{table}

%% ========================================================================
\subsection{Event selections}

The events are required to additionally be recorded by single or multi-lepton triggers, with transverse momentum ($p_{T}$) thresholds varying from 8 to 26~\gev.
The overall trigger efficiency for selected inclusive \lllljj signal events in the analysis region are from 95 to 99\%.

The \llll quadruplets are formed by two opposite-sign, same-flavour (OSSF) lepton pairs ($\ell^{+}\ell^{-}$),
in which leptons are required to be separated by $\Delta R > 0.2$ in table~\ref{tab:OR_4l}.
At most one muon is allowed to be ME or CT muon.
The $\pT$ threshold of first three leading leptons are 20, 20 and 10~\gev.
If more than one quadruplets are found, the one with minimum sum of difference between two dilepton pair masses and Z boson mass
($|m_{l_{1}^{+}l_{1}^{-}} - m_{Z}| + |m_{l_{2}^{+}l_{2}^{-}} - m_{Z}|$) is selected.
Both two dilepton pair masses are required to be between 66 to 116~\gev.
In addition, the invariant masses of all possible OSSF pairs are required to be greater than 10~\gev~ to reject events from $J/\phi$ or $\Upsilon$ decay.

For VBS topology, the two most energetic jets in different detector side ($y_{j1} \times y_{j2} < 0$) are selected.
Furthermore, the invariant mass of two jets ($\mjj$) is required to be greater than 300~\gev,
while $\dyjj$ is required to be larger than 2.
Table~\ref{tab:selection_reco} summarizes the above selection requirements, which is defined as signal region (SR).

\begin{table}[!htbp]
\begin{center}
\scalebox{0.75} {
\begin{tabular}{c c}
\hline
\hline \noalign{\smallskip}
\multirow{2}{*}{Electrons}     & $\pT >$ 7~\GeV{}, $|\eta| <$ 2.47            \\
                     & $|d_0/\sigma_{d_0}|<5$ and $|z_0\times\sin\theta|<0.5$ mm                                                             \\
\noalign{\smallskip}\hline\noalign{\smallskip}
\multirow{2}{*}{Muons}         & $\pT >$ 7~\GeV{}, $|\eta| <$ 2.7             \\
                     & $|d_0/\sigma_{d_0}|<3$ and $|z_0\times\sin\theta|<0.5$ mm                                                              \\
\noalign{\smallskip}\hline\noalign{\smallskip}
Jets                 & $\pT >$ 30 (40)~\GeV{} for $|\eta| <$ 2.4 ($2.4<|\eta|<4.5$)       \\
\noalign{\smallskip}\hline\noalign{\smallskip}
\multirow{5}{*}{$ZZ$ selection}  & $\pT >$ 20, 20, 10~\GeV{} for the leading, sub-leading and third leptons      \\
                     & Two OSSF lepton pairs with smallest $|m_{\ell^+\ell^-} - m_Z| + |m_{\ell^{'+}\ell^{'-}} - m_Z|$      \\
                     & $m_{\ell^+\ell^-} >$ 10~\GeV{} for all OSSF lepton pairs                                            \\
                     & $\Delta R(\ell,\ell') >$ 0.2                                                               \\
                     & 66 $< m_{\ell^+\ell^-} <$ 116~\GeV{}                                                       \\
\noalign{\smallskip}\hline\noalign{\smallskip}
\multirow{2}{*}{Dijet selection}  & Two most energetic jets with $y_{j_1} \times y_{j_2} < 0$                                \\
                     & $\mjj >$ 300~\GeV{} and $|\dyjj| >$ 2                                                         \\
\noalign{\smallskip}\hline
\hline
\end{tabular}}
\end{center}
\caption{Summary of selection of physics objects and candidate events at detector level in the \lllljj signal region.}
\label{tab:selection_reco}
\end{table}
%Besides, a QCD Control region (CR) is defined by reverting either the $\mjj$ or $\dyjj$ requirements.


\section{Pin Assignment}

During the compilation above, the Quartus Prime Compiler was free to choose any
pins on the selected FPGA to serve as inputs and outputs. However, the DE-series board
has hardwired connections between the FPGA pins and the other components on the board.
We will use two toggle switches, labeled $SW_0$ and $SW_1$, to provide the
external inputs, $x_1$ and $x_2$, to our example circuit. These switches are connected
to the FPGA pins listed in Table \ref{tab:pinassign}. We will connect the output $f$ to a
light-emitting diode $LED_0$ on your DE5a-Net board.
The FPGA pin assignment for the LEDs can also be found in Table~\ref{tab:pinassign}.

\begin{table}[H]
\centering
\begin{tabular}{| c | c | c | c |}
\hline
Component & $SW_0$ & $SW_1$ & {\it LED}$_0$ \\
\hline
DE5a-Net & PIN$\_$AY28 & PIN$\_$AM27 & PIN$\_$T11 \\
\hline
\end{tabular}

\caption{DE-Series Pin Assignments}
\label{tab:pinassign}
\end{table}

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure22.png}
   \caption{The Assignment Editor window.}
	 \label{fig:22}
	 \end{center}
\end{figure}

Pin assignments are made by using the Assignment Editor.
Select {\sf Assignments $>$ Assignment Editor} to reach the window in Figure~\ref{fig:22}
(shown here as a detached window).
In the {\sf Category} drop-down menu select {\sf All}. Click on the {\sf $<$$<$new$>$$>$} button
located near the top left corner to make a new item appear in the table. Double click the box
under the column labeled To so that the Node Finder button \includegraphics[scale=0.65]{figures/icon7.png}
appears. Click on the button (not the drop down arrow) to reach the window in Figure~\ref{fig:23}. Click on \includegraphics[scale=0.6]{figures/icon12.png} and \includegraphics[scale=0.6]{figures/icon15.png} to show or hide more search options.
In the {\sf Filter} drop-down menu select {\sf Pins: all}. Then click the {\sf Search} button to display
the input and output pins to be assigned: $f$, $x1$, and $x2$.
Click on $x1$ as the first pin to be assigned and click the {\sf >} button; this will enter
$x1$ in the Selected Nodes box.  Click {\sf OK}. $x1$ will now appear in the box under the column
labeled To. Alternatively, the node name can be entered directly by double-clicking the box
under the To column and typing in the node name.

Follow this by double-clicking on the box to the right of this new $x1$ entry, in the column
labeled Assignment Name. Now, the drop-down menu in Figure~\ref{fig:24} appears. Scroll down and select
{\sf Location (Accepts wildcards)}. Instead of scrolling down the menu to find the desired item,
you can just type the first letter of the item in the Assignment Name box. In this case the desired
item happens to be the first item beginning with L. Finally, double-click the box in the column labeled Value.
Type the pin assignment corresponding to $SW_0$ for the DE5a-Net board, as listed in Table \ref{tab:pinassign}.

Use the same procedure to assign input $x2$ and output $f$ to the appropriate pins listed in
Table \ref{tab:pinassign}. An example using a DE5a-Net board is shown in Figure~\ref{fig:25}.
To save the assignments made, choose {\sf File $>$ Save}. You can also simply close
the Assignment Editor window, in which case a pop-up box will ask if you want to save
the changes to assignments; click {\sf Yes}.
Recompile the circuit, so that it will be compiled with the correct pin assignments.

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure23.png}
   \caption{The Node Finder displays the input and output names.}
	 \label{fig:23}
	 \end{center}
\end{figure}

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure24.png}
   \caption{The available assignment names for a DE-series board.}
	 \label{fig:24}
	 \end{center}
\end{figure}

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure25.png}
   \caption{The complete assignment.}
	 \label{fig:25}
	 \end{center}
\end{figure}

The DE-series board has fixed pin assignments. Having finished one design, the user will want
to use the same pin assignment for subsequent designs. Going through the procedure
described above becomes tedious if there are many pins used in the design.
A useful Quartus Prime feature allows the user to both
export and import the pin assignments from a special file format,
rather than creating them manually
using the Assignment Editor. A simple file format that can be used for this purpose
is the {\it Quartus Settings File (QSF)} format. The format for the file for our simple project (on a DE5a-Net board) is

\begin{center}
\begin{verbatim}
	set_location_assignment PIN_AY28 -to x1
	set_location_assignment PIN_AM27 -to x2
	set_location_assignment PIN_T11 -to f
\end{verbatim}
\end{center}

\noindent
By adding lines to the file, any number of pin assignments can be created.
Such {\it qsf} files can be imported into any design project.

If you created a pin assignment for a particular project, you can export it
for use in a different project. To see how this is done, open again the Assignment Editor
to reach the window in Figure~\ref{fig:25}. Select {\sf Assignments $>$ Export Assignment} which leads to the
window in Figure~\ref{fig:26}. Here, the file {\it light.qsf} is available for export.
Click on {\sf OK}.
If you now look in the directory, you will see that
the file {\it light.qsf} has been created.

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure26.png}
   \caption{Exporting the pin assignment.}
	 \label{fig:26}
	 \end{center}
\end{figure}

You can import a pin assignment by choosing {\sf Assignments $>$ Import Assignments}.
This opens the dialogue in Figure~\ref{fig:27} to select the file to import.
Type the name of the file, including the {\it qsf} extension and the full path
to the directory that holds the file, in the File Name box and press {\sf OK}.
Of course, you can also browse to find the desired file.

\begin{figure}[H]
   \begin{center}
      \includegraphics[scale=0.65]{figures/figure27.png}
   \caption{Importing the pin assignment.}
	 \label{fig:27}
	 \end{center}
\end{figure}


%%
%% Automatically generated file from DocOnce source
%% (https://github.com/hplgit/doconce/)
%%
%%

%-------------------- begin preamble ----------------------

\documentclass[%
oneside,                 % oneside: electronic viewing, twoside: printing
final,                   % draft: marks overfull hboxes, figures with paths
10pt]{article}

\listfiles               %  print all files needed to compile this document

\usepackage{relsize,makeidx,color,setspace,amsmath,amsfonts,amssymb}
\usepackage[table]{xcolor}
\usepackage{bm,ltablex,microtype}

\usepackage[pdftex]{graphicx}

\usepackage[T1]{fontenc}
%\usepackage[latin1]{inputenc}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}

\usepackage{lmodern}         % Latin Modern fonts derived from Computer Modern

% Hyperlinks in PDF:
\definecolor{linkcolor}{rgb}{0,0,0.4}
\usepackage{hyperref}
\hypersetup{
    breaklinks=true,
    colorlinks=true,
    linkcolor=linkcolor,
    urlcolor=linkcolor,
    citecolor=black,
    filecolor=black,
    %filecolor=blue,
    pdfmenubar=true,
    pdftoolbar=true,
    bookmarksdepth=3   % Uncomment (and tweak) for PDF bookmarks with more levels than the TOC
    }
%\hyperbaseurl{}   % hyperlinks are relative to this root

\setcounter{tocdepth}{2}  % levels in table of contents

% prevent orhpans and widows
\clubpenalty = 10000
\widowpenalty = 10000

% --- end of standard preamble for documents ---

% insert custom LaTeX commands...

\raggedbottom
\makeindex
\usepackage[totoc]{idxlayout}   % for index in the toc
\usepackage[nottoc]{tocbibind}  % for references/bibliography in the toc

%-------------------- end preamble ----------------------

\begin{document}

% matching end for #ifdef PREAMBLE

\newcommand{\exercisesection}[1]{\subsection*{#1}}

% ------------------- main content ----------------------

% ----------------- title -------------------------

\thispagestyle{empty}

\begin{center}
{\LARGE\bf
\begin{spacing}{1.25}
Project 5, deadline  December 14, 2018
\end{spacing}
}
\end{center}

% ----------------- author(s) -------------------------

\begin{center}
{\bf Molecular Dynamics project${}^{}$} \\ [0mm]
\end{center}

\begin{center}
% List of all institutions:
\end{center}

% ----------------- end author(s) -------------------------

% --- begin date ---
\begin{center}
Fall semester 2018
\end{center}
% --- end date ---

\vspace{1cm}

\subsection*{Theoretical background and description of the physical system}

In this project we will implement a model called molecular dynamics
(MD). Molecular dynamics allows us to study the dynamics of atoms and
explore the phase space. For those of you who are taking FYS2160 -
Thermodynamics, this project will be an excellent choice. The atoms
interact through a force given by the negative gradient of a potential
energy function. With this force, we can integrate Newton's
laws. While exploring the phase space, we will sample statistical
properties of the system like energy, temperature, pressure, diffusion
constant and so on.  The project can be seen also as an extension from project 3,
where you wrote an object-oriented code for the solar system.

Here we will use another potential  for modeling the interaction between atoms.
Molecular dynamics is based on the assumption that even atoms move
according to the laws of Newton, given the correct model for
interactions. The goal of this project is to model an argon gas, where
the atoms interact according to the famous Lennard-Jones potential,

\begin{equation}
    U(r) = 4\varepsilon\qty(\qty(\frac{\sigma}{r})^{12} - \qty(\frac{\sigma}{r})^6), \label{eq:lj}
\end{equation}

where $r$ is the distance between two atoms,
$r=\norm{\bm{r}_i-\bm{r}_j}$. The quantity $\sigma$ and $\varepsilon$
are parameters which determine which chemical compound is
modelled. This potential is a good approximation for noble
gases. Before you begin it is also useful to find the force on atom
$i$ at position $\bm{r}_i$ from atom $j$ at position $\bm{r}_j$.

We will also learn how to do write object oriented code. You can use your code
from project 3 or look at a
a code skeleton that contains the basic structure of an MD code.
You can find the \href{{https://github.com/andeplane/molecular-dynamics-fys3150}}{code skeleton
here}. You
can clone or fork this repository into your own.  The class structure
which you developed for project 3 can also be used again here, as well
as the Velocity Verlet algorithm of project 3.

After you have downloaded the repository, open the project in Qt
Creator and see if it runs. The program should create 100 argon atoms
and place them uniformly inside a cubic box with sides 10
Angstroms. Each atom is given a velocity according to the
Maxwell-Boltzmann distribution so that
\begin{align}
P(v_i)d\mathrm{v}_i = \left(\frac{m}{2\pi k_B
T}\right)^{1/2} \exp\left(-\frac{m v_i^2}{2k_B T}\right)d\mathrm{v}_i,
\end{align}
where $m$ is the mass of the atom, $k_B$ is
Boltzmann's constant and $T$ is the temperature. We recognize this as
a normal distribution with zero mean and standard deviation $\sigma =
\sqrt{k_B T/m}$. We recognize this also as the Boltzmann distribution $P(E) \propto \exp{(-\beta E)}$, with $E = 0.5mv^2$.
The program will evolve the system in time with no
forces so that all atoms move in a straight line. It will create a
file called \emph{movie.xyz} containing all the timesteps ready to
visualize with for example Ovito. You can download Ovito from this \href{{http://www.ovito.org/index.php/download}}{site}. You should start
with the fun part - to look at the simulation in Ovito. We then
strongly recommend that, before you start, you look at the code
structure and try to understand how the different classes are
connected to each other and how a typical timestep is computed. You
can skip understanding the contents of \emph{unitconverter.cpp} and \emph{vec3.cpp}.

\textbf{For this project you can collaborate with fellow students and you can  hand in a common report.}
This project (together with projects 3 and 4) counts 1/3 of the final mark.

\subsection*{Before starting}

If you wish to study the above program, while you develop your own code, it may be useful to
pay attention to the following two steps:
\begin{enumerate}
 \item First, spend some 30 minutes figuring out what molecular dynamics is and which problems it can be applied to. What areas of physics can it be used in? What about chemistry and biology? What you find here should be part of the  introductory section in your report.

 \item Then run the program, visualize the output with for example Ovito (as mentioned above). Now, spend some 30-60 minutes looking at the code and understand how the output is produced and try to understand every step in the code. The best way to do this is to start at the top of the \emph{main()} function and follow every line and every function call, step by step. \textbf{As a part of your report, you should explain the code structure and draw a flow chart (a diagram showing how the program is executed).} This part is extremely important and will save you a lot of time. And of course, please ask us teachers if you have any questions!
\end{enumerate}

\noindent
\paragraph{Project 5a): Getting started.}
When working with MD, the system size is usually limited by available computer resources. A typical large MD simulation (with a parallelized code) contains a few million atoms corresponding to a system much smaller than a cubic micron. In order to get rid of boundary effects, we usually apply periodic boundary conditions so that we simulate a system of infinite size. You need to implement the \emph{applyPeriodicBoundaryConditions} function in the \emph{System} class. After doing so, run the program again and notice how the atoms now are contained inside a box. Discuss the benefits of this strategy.

\paragraph{Project 5b): Velocity distribution.}
The atoms are usually given velocities according to the Maxwell-Boltzmann distribution (you should discuss why this is the case) which will result in a nonzero net momentum in the system. Implement the \emph{removeMomentum} function in the \emph{System} class so that the net momentum is zero.

\paragraph{Project 5c): FCC lattice.}
The atoms are now uniformly distributed in space. This is not very physical, so we should place the atoms in a crystal structure. When we later implement the Lennard-Jones potential, we will see that the face-centered cubic (FCC) lattice is a stable structure for the potential (it is actually the crystalline structure of argon). A lattice is built up by \emph{unit cells} - a group of atoms - so that a larger system can be created by repeating these cells in space. An FCC lattice unit cell of size $b$ in Angstroms (this is the lattice constant) consists of four atoms with local coordinates

\begin{align}
	\mathbf{r}_1 &= 0 \hat{\mathbf{i}} + 0 \hat{\mathbf{j}} + 0 \hat{\mathbf{k}},\\
	\mathbf{r}_2 &= \frac{b}{2} \hat{\mathbf{i}} + \frac{b}{2} \hat{\mathbf{j}} + 0 \hat{\mathbf{k}},\\
	\mathbf{r}_3 &= 0 \hat{\mathbf{i}} + \frac{b}{2} \hat{\mathbf{j}} + \frac{b}{2} \hat{\mathbf{k}},\\
	\mathbf{r}_4 &= \frac{b}{2} \hat{\mathbf{i}} + 0 \hat{\mathbf{j}} + \frac{b}{2} \hat{\mathbf{k}}.
\end{align}
You can now create $N_x \times N_y \times N_z$ such unit cells next to each other to form a larger system so that the origin of unit cell $(i,j,k)$ is

\begin{align}
	\mathbf{R}_{i,j,k} = i \hat{\mathbf{u}}_1 + j \hat{\mathbf{u}}_2 + k \hat{\mathbf{u}}_3,
\end{align}
where $i=0,1,..., N_x-1, j=0,1,..., N_y-1, k=0,1,..., N_z-1$. The unit vectors of the unit cells are scaled with the lattice constant $b$ so that

\begin{align}
	\hat{\mathbf{u}}_1 = b\hat{\mathbf{i}}, \quad \hat{\mathbf{u}}_2 = b\hat{\mathbf{j}}, \quad \hat{\mathbf{u}}_3 = b\hat{\mathbf{k}}.
\end{align}
Implement the function \emph{createFCCLattice(int numberOfUnitCellsEachDimension, double latticeConstant)} in the \emph{System} class. Remember to remove the 100 atoms that are created as the code is right now. Use lattice constant $b=5.26$ $\mathrm{Angstrom}$. Remember to update the system size so the \emph{applyPeriodicBoundaryConditions} function works properly. If you now visualize the result of the program, you should see the nice crystalline structure in the beginning of the simulation. What is the density $\rho$ in your system?

\paragraph{Project 5d): Calculation of forces.}
While this looks nice, we need to implement the computation of forces in order to see interesting physics. In this project, we will use the \href{{http://en.wikipedia.org/wiki/Lennard-Jones_potential}}{Lennard-Jones potential}  which calculates the energy between two atoms $i$ and $j$ as

\begin{align}
	U(r_{ij}) = 4\epsilon\left[\left(\frac{\sigma}{r_{ij}}\right)^{12} - \left(\frac{\sigma}{r_{ij}}\right)^6\right],
\end{align}
where $r_{ij} = \vert\mathbf{r}_i - \mathbf{r}_j\vert$ is the distance from atom $i$ to atom $j$, $\epsilon$ is the depth of the potential well (with dimension energy) and $\sigma$ is the distance at which the potential is zero. For argon, optimal values of the parameters are:

\begin{align}
	\frac{\epsilon}{k_B} = 119.8\mathrm{K}, \sigma=3.405 \mathrm{Angstrom}.
\end{align}
In our code, we use the so called MD units (see the units definition at the end). This potential reproduces thermodynamic equilibrium properties that are in good agreement with experimental values for argon. The equation of state for this system is the van der Waals equation of state. Phases such as solid, liquid and gas are reproduced from this simple model with phase transitions and other properties as well with a  remarkable agreement with data.

The total potential energy $V$ in the system is computed by summing over all pairs of atoms (counting each pair only once)

\begin{align}
	V = \sum_{i>j} U(r_{ij}).
\end{align}
The force is calculated by taking the negative gradient of the potential

\begin{align}
	\mathbf{F}(r_{ij}) = -\nabla U(r_{ij}),
\end{align}
giving the $x$-component (the other components are calculated the same way)

\begin{align}
	F_x(r_{ij}) = -\frac{\partial U}{\partial r_{ij}}\frac{\partial r_{ij}}{\partial x_{ij}},
\end{align}
where $x_{ij}$ is the $x$-component of $\mathbf{r}_{ij}$.

Calculate (analytically) the force and implement the \emph{calculateForces} function in the LennardJones class, using the Velocity Verlet algorithm that you developed for project 3. You will have to take care of the periodic boundary conditions. You could use the minimum image convention as described \href{{http://en.wikipedia.org/wiki/Periodic_boundary_conditions}}{here}. Now run the simulation with 5 unit cells in each dimension (500 atoms) for different initial temperatures. Can you tell if the system is in a solid state just by looking at the system in Ovito? At what initial temperature is the crystal melting?

\paragraph{Project 5e): Kinetic and potential energies.}
We now have a working Molecular dynamics code! The next step is to calculate some physical properties of the system. The easiest properties to measure are the kinetic and potential energy (calculated in the LennardJones class). The kinetic energy is defined as

\begin{align}
	E_k = \sum_{i=1}^{N_\text{atoms}} \frac{1}{2} m_i v_i^2,
\end{align}
where $m_i$ and $v_i$ is the mass and the speed of atom $i$. You can use the function \emph{atom->velocity.lengthSquared()} to calculate the dot product of the velocities.

You can also calculate an estimate of the temperature through the equipartition theorem, see for example D. Schroeder's \emph{An Introduction to Thermal Physics} for details,
\begin{align}
	\langle E_k \rangle = \frac{3}{2}N_\text{atoms} k_B T.
\end{align}
We can use this to define an \emph{instantaneous} temperature

\begin{align}
	T = \frac{2}{3}\frac{E_k}{N_\text{atoms} k_B}.
\end{align}

All of these quantities should be calculated in the \emph{StatisticsSampler} class. All the statistical quantities should be saved to a file which needs to be implemented in the \emph{saveToFile} function in the same class.

As you will see, since the temperature is proportional to the kinetic energy, its initial value will drop in the beginning when the system is initialized in the crystal structure. Why does this happen? What happens to the total energy? In order to have a system with final temperature $T$, what initial temperature $T_i$ is needed? What is the ratio $T/T_i$? Do multiple simulations with different random seeds and plot this ratio as a function of time. Again visualize with for example \emph{Ovito} and try to determine at what temperature the system actually melts at. After the temperature drops, it will reach a more or less stable value. The system is then said to be in an equilibrium state.

\paragraph{Project 5f): Diffusion constant.}
The last exercise is to compute the diffusion constant and use this to measure the melting temperature. We use the Einstein relation that relates the so called mean square displacement (MSD) to the diffusion constant

\begin{align}
	\langle r^2(t) \rangle = 6Dt,
\end{align}
where $D$ is the diffusion constant, $t$ is time. The mean square displacement for atom $i$ is calculated as

\begin{align}
	r_i^2(t) = |\mathbf{r}_i(t) - \mathbf{r}_i(0)|^2,
\end{align}
where $\mathbf{r}_i(t)$ is the position of atom $i$ at time $t$. When you implement this you need to add the initial position as a new property in the \emph{Atom} class. You also need to update the \emph{applyPeriodicBoundaryConditions} so that $r_i^2(t)$ is the actual displacement as if no periodic boundary condition has occured. Why is this important?

We can use the diffusion constant to find the melting temperature. Atoms in a solid will not diffuse much, meaning that a solid will have a diffusion constant close to zero. Now solve the Einstein relation for the diffusion constant $D$ and add a function in \emph{StatisticsSampler} thats measures this quantity. Plot the diffusion constant as a function of temperature $T$ and use this to find an estimate for the melting temperature. Use what you found earlier  to make sure you simulate temperatures both above and below the melting temperature. Also remember not to use the initial temperature, but the measured temperature after the system has reached equilibrium. You can use the builtin \emph{UnitConverter} to convert the temperature to SI units as illustrated in the top of the \emph{main} function.

\section*{Link with FYS2160 - what is really going on here?}
The idea of an MD simulation is to sample microstates from a statistical ensemble. In our simulation, we have a constant number of atoms $N$, a constant volume $V$ and a (more or less, depending on our integrator) constant energy $E$. This corresponds to the microcanonical ensemble (NVE).

Although we produce the dynamics of atoms, we should not see MD as a model that will give the true trajectories of the atoms, but rather a model that allows us to explore the phase space according to the probabilities we can calculate with statistical mechanics. A fundamental assumption in any MD simulation is the ergodic hypothesis. It states that \emph{over long periods of time, the time spent by a system in some region of the phase space of microstates with the same energy is proportional to the volume of this region, i.e., that all accessible microstates are equiprobable over a long period of time}. This means that by evolving the atoms through time will visit microstates of the ensemble according to the true probabilities given by the ensemble.

\section*{Units}

The program uses by default a set of units. We have chosen the following four units

\begin{align}
	\text{1 unit of mass } &= 1 \text{ a.m.u} = 1.661\times 10^{-27}\mathrm{kg},\\
	\text{1 unit of length } &= 1.0 \mathrm{angstrom} = 1.0\times 10^{-10}\mathrm{m},\\
	\text{1 unit of energy } &= 1.651\times 10^{-21}\mathrm{J},\\
	\text{1 unit of temperature} &= 119.735\mathrm{K}.
\end{align}
Boltzmann's constant is then equal to one (convince yourself about this), and other units can be derived by using known relations. We can for example find the unit of time by using $E=mc^2$. We have that

\begin{align}
	\text{Energy} = \text{Mass} \times \frac{\text{Length}^2}{\text{Time}^2},
\end{align}
which can be solved for time

\begin{align}
	\text{Time} = \text{Length} \times \sqrt{\frac{\text{Mass}}{\text{Energy}}}.
\end{align}
By inserting the values above, we get

\begin{align}
	\text{1 unit of time } &= 1.0 \times 10^{-10}\sqrt{\frac{1.661\times 10^{-27}}{1.651\times 10^{-21}}} \text{ s} = 1.00224\times 10^{-13}\mathrm{s}.
\end{align}
This way, we can continue working out the values of the other units. What are the units of force? And pressure? In the project, a class that calculates these values is given.

\subsection*{Introduction to numerical projects}

Here follows a brief recipe and recommendation on how to write a report for each
project.

\begin{itemize}
  \item Give a short description of the nature of the problem and the eventual  numerical methods you have used.

  \item Describe the algorithm you have used and/or developed. Here you may find it convenient to use pseudocoding. In many cases you can describe the algorithm in the program itself.

  \item Include the source code of your program. Comment your program properly.

  \item If possible, try to find analytic solutions, or known limits in order to test your program when developing the code.

  \item Include your results either in figure form or in a table. Remember to        label your results. All tables and figures should have relevant captions        and labels on the axes.

  \item Try to evaluate the reliabilty and numerical stability/precision of your results. If possible, include a qualitative and/or quantitative discussion of the numerical stability, eventual loss of precision etc.

  \item Try to give an interpretation of you results in your answers to  the problems.

  \item Critique: if possible include your comments and reflections about the  exercise, whether you felt you learnt something, ideas for improvements and  other thoughts you've made when solving the exercise. We wish to keep this course at the interactive level and your comments can help us improve it.

  \item Try to establish a practice where you log your work at the  computerlab. You may find such a logbook very handy at later stages in your work, especially when you don't properly remember  what a previous test version  of your program did. Here you could also record  the time spent on solving the exercise, various algorithms you may have tested or other topics which you feel worthy of mentioning.
\end{itemize}

\noindent
\subsection*{Format for electronic delivery of report and programs}

The preferred format for the report is a PDF file. You can also use DOC or postscript formats or as an ipython notebook file.  As programming language we prefer that you choose between C/C++, Fortran2008 or Python. The following prescription should be followed when preparing the report:

\begin{itemize}
  \item Use Devilry to hand in your projects, log in  at  \href{{http://devilry.ifi.uio.no}}{\nolinkurl{http://devilry.ifi.uio.no}} with your normal UiO username and password and choose either 'fys3150' or 'fys4150'. There you can load up the files within the deadline.

  \item Upload \textbf{only} the report file!  For the source code file(s) you have developed please provide us with your link to your github domain.  The report file should include all of your discussions and a list of the codes you have developed.  Do not include library files which are available at the course homepage, unless you have made specific changes to them.

  \item In your git repository, please include a folder which contains selected results. These can be in the form of output from your code for a selected set of runs and input parametxers.

  \item In this and all later projects, you should include tests (for example unit tests) of your code(s).

  \item Comments  from us on your projects, approval or not, corrections to be made  etc can be found under your Devilry domain and are only visible to you and the teachers of the course.
\end{itemize}

\noindent
Finally,
we encourage you to work two and two together. Optimal working groups consist of
2-3 students. For this specific report you can  hand in a common report.

% ------------------- end of main content ---------------

\end{document}


% !Mode:: "TeX:UTF-8"
% !TEX program  = xelatex
\section{Summary}
\subsection{Proof Expression}
Mathematical proof is relatively easy in mathematics writing, but it requires clear and concise expression as well. Therefore, you can express mathematical proof skillfully after the amount of training.

Some examples are often used in proof\cite{Nicholas1998Handbook},
\begin{itemize}
	\item At the beginning of the proof, ``you should strive to keep the reader informed of where you are in the proof and what remains to be done.'' Useful phrases include
		\begin{itemize}
			\item First, we establish that \ldots
			\item Our task is now to \ldots
			\item Our problem reduces to \ldots
			\item It remains to show that \ldots
			\item We are almost ready to invoke \ldots
		\end{itemize}
	\item At the end of the proof, it is often marked by the halmos symbol □. Sometimes the abbreviation QED is used instead.
	\item If you omit part of a proof, ``it is best to indicate the nature and length of the omission'', via phrases such as the following.
		\begin{itemize}
			\item It is easy/simple/straightforward to show that \ldots
			\item Some tedious manipulation yields \ldots
			\item An easy/obvious induction gives \ldots
			\item After two applications of \ldots\ we find \ldots
			\item An argument similar to the ones used in \ldots\ shows that \ldots
		\end{itemize}
\end{itemize}

\subsection{Important Conjunction}
``Join clauses good, like a conjunction should.'' This sentence points out the importance of conjunctions in English writing, thus, we should be cautious when using conjunctions. This subsection explains the different functions of conjunctions through a series of examples, including the following functions,
\begin{itemize}
	\item Combinations:
		\begin{itemize}
			\item and, both, also, as well as, not only \ldots\ but also, apart from, in addition to, moreover, furthermore;
		\end{itemize}
	\item Implications or explanations;
		\begin{itemize}
			\item as, because, since, due to, in view of, owing to, on account of, given, it follows that, consequently, therefore, thus;
		\end{itemize}
	\item Modifications and restrictions;
		\begin{itemize}
			\item alternatively, although, though, but, whereas, by contrast, except, however, on the other hand, nevertheless, despite, in spite of, instead of, rather that.
		\end{itemize}
\end{itemize}

\subsection{Comparison}
\subsubsection{Symbols In the Sentences}
Halmos once said, ``the best notation is no notation''. That is, symbols should be used as little as possible when writing sentences that include mathematical symbols unless you have to.

Please see Section~2.7.1 in \emph{Mathematical Writing in English}\cite{2013数学之英文写作} for more examples.

\subsubsection{Definite Article and Indefinite Article}
It is difficult for speakers, who speak the languages that do not have articles, to use articles correctly in English. Therefore, there are two important rules\cite{Nicholas1998Handbook},
\begin{itemize}
	\item Do not use \emph{the} (with plural or uncountable nouns) to talk about things in general;
	\item Do not use singular countable nouns without articles.
\end{itemize}

Please see Section~2.7.2 in \emph{Mathematical Writing in English}\cite{2013数学之英文写作} for more examples.

\subsubsection{Common Misspellings or Confusions}
We often find that many words are spelling similar when learning English words, but we are not sure whether the words are used properly during the writing process. Thus we need software and accurate memory to reduce misspellings and confusion.

Please see Table~2.25 to Table~2.26 in \emph{Mathematical Writing in English}\cite{2013数学之英文写作}

\nocite{2013数学之英文写作,Nicholas1998Handbook}
\bibliography{ref}


\chapter{Preface}
The origin of the name ``Napkin''
comes from the following quote of mine.
\begin{quote}
\small
I'll be eating a quick lunch with some friends of mine
who are still in high school.
They'll ask me what I've been up to the last few weeks,
and I'll tell them that I've been learning category theory.
They'll ask me what category theory is about.
I tell them it's about abstracting things by looking at just the
structure-preserving morphisms between them, rather than the objects themselves.
I'll try to give them the standard example $\catname{Grp}$,
but then I'll realize that they don't know what a homomorphism is.
So then I'll start trying to explain what a homomorphism is,
but then I'll remember that they haven't learned what a group is.
So then I'll start trying to explain what a group is,
but by the time I finish writing the group axioms on my napkin,
they've already forgotten why I was talking about groups in the first place.
And then it's 1PM, people need to go places, and I can't help but think: \\[0.5ex]
\emph{``Man, if I had forty hours instead of forty minutes,
I bet I could actually have explained this all''.}
\end{quote}
This book was initially my attempt at those forty hours,
but has grown considerably since then.

\section*{About this book}
The \emph{Infinitely Large Napkin} is a light
but mostly self-contained introduction to a large
amount of higher math.

I should say at once that this book is not intended
as a replacement for dedicated books or courses;
the amount of depth is not comparable.
On the flip side, the benefit of this ``light'' approach
is that it becomes accessible to a larger audience,
since the goal is merely to give the reader a feeling for
any particular topic rather than to emulate a full semester of lectures.

I initially wrote this book with talented high-school students in mind,
particularly those with math-olympiad type backgrounds.
Some remnants of that cultural bias can still be felt throughout the book,
particularly in assorted challenge problems which are
taken from mathematical competitions.
However, in general I think this would be a good reference
for anyone with some amount of mathematical maturity and curiosity.
Examples include but certainly not limited to:
math undergraduate majors, physics/CS majors,
math PhD students who want to hear a little bit
about fields other than their own,
advanced high schoolers who like math but not math contests,
and unusually intelligent kittens fluent in English.

\section*{Source code}
The project is hosted on GitHub at
\url{https://github.com/vEnhance/napkin}.
Pull requests are quite welcome!
I am also happy to receive suggestions and corrections by email.

\section*{Philosophy behind the Napkin approach}
As far as I can tell, higher math for high-school students
comes in two flavors:
\begin{itemize}
	\ii Someone tells you about the hairy ball theorem in the form
	``you can't comb the hair on a spherical cat''
	then doesn't tell you anything about why it should be true,
	what it means to actually ``comb the hair'',
	or any of the underlying theory,
	leaving you with just some vague notion in your head.

	\ii You take a class and prove every result in full detail,
	and at some point you stop caring about what the professor is saying.
\end{itemize}
Presumably you already know how unsatisfying the first approach is.
So the second approach seems to be the default,
but I really think there should be some sort of middle ground here.

%I was talking to a friend of mine one day who described briefly
%what the Israel IMO training looked like.
%It turns out that rather than actually preparing for the IMO,
%the students would, say, get taught a semester's worth of
%undergraduate algebra in the couple weeks.
%This might seem absurd, but I think if your goal is to just show the students
%what this algebra thing they keeping hearing about is,
%and your students have substantially more mathematical maturity
%relative to their knowledge (e.g.\ are IMO medalists),
%it seems like you really could make a lot of headway.

%For example: often classes like to prove things for completeness.
%I personally find that many proofs don't really teach anything,
%and that it is often better to say
%``you could work this out if you wanted to,
%but it's not worth your time''.
Unlike university, it is \emph{not} the purpose of this book to
train you to solve exercises or write proofs\footnote{Which is
	not to say problem-solving isn't valuable;
	I myself am a math olympiad coach at heart.
	It's just not the point of this book.},
or prepare you for research in the field.
Instead I just want to show you some interesting math.
The things that are presented should be memorable and worth caring about.
For that reason, proofs that would be included for completeness
in any ordinary textbook are often omitted here,
unless there is some idea in the proof which I think is worth seeing.
In particular, I place a strong emphasis over explaining
why a theorem \emph{should} be true rather than writing down its proof.
This is a recurrent theme of this book:
\begin{moral}
	Natural explanations supersede proofs.
\end{moral}

My hope is that after reading any particular chapter in Napkin,
one might get the following out of it:
\begin{itemize}
	\ii Knowing what the precise definitions are of the main characters,

	\ii Being acquainted with the few really major examples,

	\ii Knowing the precise statements of famous theorems,
	and having a sense of why they \emph{should} be true.
\end{itemize}
Understanding ``why'' something is true can have many forms.
This is sometimes accomplished with a complete rigorous proof;
in other cases, it is given by the idea of the proof;
in still other cases, it is just a few key examples
with extensive cheerleading.

Obviously this is nowhere near enough if you want to e.g.\ do research in a field;
but if you are just a curious outsider,
I hope that it's more satisfying than the elevator pitch or Wikipedia articles.
Even if you do want to learn a topic with serious depth,
I hope that it can be a good zoomed-out overview before you really dive in,
because in many senses the choice of material is
``what I wish someone had told me before I started''.

%In terms of learning math, I suspect that
%there is some sense in which reading a textbook
%is like watching a movie.
%The first time you watch it, you spend most of your bandwidth
%getting to know the characters,
%keeping up with what's going on,
%trying to predict where it's headed next.
%But if you like the movie enough and watch it a second
%or third, or $n$th time, you'll pick up a lot of things
%that you didn't notice the first time through
%(e.g.\ all the hints that Z was the main villain all along).

\section*{More pedagogical comments and references}
The preface would become too long if I talked about
some of my pedagogical decisions chapter by chapter,
so \Cref{ch:refs} contains those comments instead.

In particular, I often name specific references,
and then end of that appendix has more references.
So this is a good place to look if you want further reading.

\section*{Historical and personal notes}
I began writing this book in December of 2014,
after having finished my first semester of undergraduate at Harvard.
It became my main focus for about 18 months after that,
as I became immersed in higher math.
I essentially took only math classes,
(gleefully ignoring all my other graduation requirements)
and merged as much of it as I could
(as well as lots of other math I learned on my own time)
into the Napkin.

Towards August of 2016, though, I finally lost steam.
The first public drafts went online then, and I decided to step back.
Having burnt out slightly,
I then took a break from higher math,
and spent the remaining two undergraduate years\footnote{Alternatively:
	`` \dots and spent the next two years forgetting everything
	I had painstakingly learned''.
	Which made me grateful for all the past notes in the Napkin!}
working extensively as a coach for the American math olympiad team,
and trying to spend as much time with my friends as I could
before they graduated and went their own ways.
% It was also at this time I started to get into Korean pop dance,
% which was the first (and only) extracurricular activity
% I did during my entire undergraduate stay.

During those two years, readers sent me many kind words of gratitude,
many reports of errors, and many suggestions for additions.
So in November of 2018,
some weeks into my first semester as a math PhD student,
I decided I should finish what I had started.
Some months later, here is what I have.

\section*{Acknowledgements}
\todo{add more acknowledgments}
I am indebted to countless people for this work.
Here is a partial (surely incomplete) list.

\begin{itemize}
\ii Thanks to all my teachers and professors for teaching me much of the
material covered in these notes,
as well as the authors of all the references I have cited here.
A special call-out to \cite{ref:55a}, \cite{ref:msci},
\cite{ref:manifolds}, \cite{ref:gathmann}, \cite{ref:18-435},
\cite{ref:etingof}, \cite{ref:145a}, \cite{ref:vakil},
\cite{ref:pugh}, \cite{ref:gorin},
which were especially influential.

\ii Thanks also to dozens of friends and strangers
who read through preview copies of my draft,
and pointed out errors and gave other suggestions.
Special mention to Andrej Vukovi\'c and Alexander Chua
for together catching over a thousand errors.
Thanks also to Brian Gu and Tom Tseng for many corrections.
(If you find mistakes or have suggestions yourself,
I would love to hear them!)

\ii I'd also like to express my gratitude for
many, many kind words I received
during the development of this project.
These generous comments led me to keep working on this,
and were largely responsible for my decision in November 2018
to begin updating the Napkin again.
\end{itemize}

Finally, a huge thanks to the math olympiad community,
from which the Napkin (and me) has its roots.
All the enthusiasm, encouragement, and thank-you notes I have received
over the years led me to begin writing this in the first place.
I otherwise would never have the arrogance to dream a project like this
was at all possible.
And of course I would be nowhere near where I am today were it not for the
life-changing journey I took in chasing my dreams to the IMO.
Forever TWN2!


\section{Model Description}

\subsection{Introduction}
The ephemeris converter module has the purpose of copying the spice sim messages into a flight software interface message. This allow flight software module to access planet ephemeris data.

\subsection{I/O}

The spice message, which is read in by the module, contains the following variables:

\begin{itemize}
\item J2000Current: the time of validity for the planet state
\item PositionVector : the true position of the planet for the time
    \item  VelocityVector[3]: the tue velocity of the planet for the time
    \item  J20002Pfix: the orientation matrix of planet-fixed relative to inertial
    \item  J20002Pfix\_dot: the derivative of the orientation matrix of planet-fixed relative to inertial
    \item  computeOrient: a flag indicating whether the reference should be computed
    \item  PlanetName
\end{itemize}

Only the position and velocity vectors are transferred to the output ephemeris message, which therefore contains:
\begin{itemize}
    \item r\_BdyZero\_N[3]: the position of orbital body in the inertial frame
    \item v\_BdyZero\_N[3]: the velocity of orbital body in the inertial frame
    \item timeTag: the vehicle Time-tag for state
\end{itemize}