\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}

%common math and LaTeX packages
\usepackage{amsmath,amsthm,amsfonts,amssymb,amscd}
\usepackage{multirow,booktabs}
\usepackage[table]{xcolor}
\usepackage{fullpage}
\usepackage{lastpage}
\usepackage{enumitem}
\usepackage{fancyhdr}
\usepackage{mathrsfs}
\usepackage{wrapfig}
\usepackage{setspace}
\usepackage{calc}
\usepackage{multicol}
\usepackage{hyperref}
\usepackage{cancel}
\usepackage[retainorgcmds]{IEEEtrantools}
\usepackage[margin=1in]{geometry}
\usepackage{amsmath}
\newlength{\tabcont}
\setlength{\parindent}{0.0in}
\setlength{\parskip}{0.0in}
\usepackage{empheq}

\setcounter{tocdepth}{1}

%shaded environment for important equations/notes
\usepackage{mdframed}
\colorlet{shaded}{blue!15}
\colorlet{shadedtext}{black}
\newenvironment{shaded}
   {
     \raggedright
     \color{shadedtext}%
   }{}
\surroundwithmdframed[
   hidealllines=true,
   backgroundcolor=shaded
]{shaded}

%page geometry definitions
\usepackage[most]{tcolorbox}
\usepackage{xcolor}
\parindent 0in
\parskip 6pt
\geometry{margin=1in, headsep=0.25in}

%custom theorem definitions
\theoremstyle{definition}
\newtheorem{innercustomgeneric}{\customgenericname}
\providecommand{\customgenericname}{}
\newcommand{\newcustomtheorem}[2]{%
  \newenvironment{#1}[1]
  {%
   \renewcommand\customgenericname{#2}%
   \renewcommand\theinnercustomgeneric{##1}%
   \innercustomgeneric
  }
  {\endinnercustomgeneric}
}
\newcustomtheorem{thm}{Theorem}
\newcustomtheorem{lem}{Lemma}
\newcustomtheorem{defn}{Definition}
\newcustomtheorem{prop}{Proposition}
\newcustomtheorem{exer}{Exercise}
\newcustomtheorem{note}{Note}
\renewcommand{\qedsymbol}{$\blacksquare$}

\let\a\alpha
\let\b\beta
\let\g\gamma
\let\e\varepsilon
\let\t\theta
\let\phi\varphi
\newcommand{\R}{\mathbb{R}}
\newcommand{\Q}{\mathbb{Q}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\PP}{\mathbb{P}}
\newcommand{\C}{\mathcal{C}}
\newcommand{\Lagr}{\mathcal{L}}
\newcommand{\I}{\mathcal{I}}

\begin{document}

%document header
\begin{center}
{\LARGE \bf MA 214 - Introduction to Numerical Analysis}\\
{Instructor: \textit{Prof. Saikat Mazumdar}}\\
Last updated \today \\~\\
{\large \bf Om Prabhu}\\
Undergraduate, Mechanical Engineering\\
Indian Institute of Technology Bombay\\~\\
\textsc{Note To Reader}
\end{center}
\vspace{-6pt}

This document is a compilation of the notes I made while taking the course MA 214 (Introduction to Numerical Analysis) in my 4$^{\text{th}}$ semester at IIT Bombay. It is not meant to serve as a replacement for any formal textbook or lecture on the subject, since I sometimes overlook the theory parts.

There will probably be many instances where I use certain symbols without explicitly mentioning what they mean. It is to be assumed that they carry their usual meanings. I may also change the order of notes compared to those in the slides if I find it more convenient.

If you have any suggestions and/or spot any errors, you know where to contact me.

\hrulefill
\vspace{-5mm}
\tableofcontents
\hrulefill
\vspace{2mm}

{\large \bf Notation}
\vspace{2mm}

\begin{tabular}{p{0.1\textwidth}p{0.85\textwidth}}
$\mathbb{P}_n$ & set of all polynomials of degree $\leqslant n$\\
$\mathcal{C}[a,b]$ & set of all continuous functions on $[a,b]$ (an infinite dimensional vector space)\\
$\mathcal{C}^n[a,b]$ & set of all $n^{th}$-order continuously differentiable functions on $[a,b]$
\end{tabular}
\vspace{-2mm}

\hrulefill

\newpage
\section{Interpolation Theory}
Suppose $(n+1)$ real points $(x_0,y_0), (x_1,y_1),\dots,(x_n,y_n)$ are known. Further these \textbf{interpolation points} $x_i$ are spread out over the interval $[a,b]$. Then the problem of approximating a function over the interval $[a,b]$ passing through these points is called interpolation.

There are infinite such functions. We mainly consider polynomial interpolation in this section i.e. we approximate the \textbf{interpolant} $f$ by an \textbf{interpolating polynomial} $p_n\in\mathbb{P}_n$.

\subsection{Some existence theorems}

\begin{enumerate}
	\item The \textbf{Joseph-Louis Lagrange Theorem} states that given a set of $n+1$ real, unique data points $S=\{(x_i,y_i)\text{ }|\text{ }i=0,1,\dots,n\}$, there exists a unique polynomial $p_n\in\mathbb{P}_n$ such that $$p(x_i)=y_i\text{ for }i=0,1,\dots,n$$
\end{enumerate}
We define the norm on $\mathcal{C}[a.b]$ as:
$\displaystyle||f||=\max_{x\in[a,b]}|f(x)|$. To define the `closeness' of 2 functions formally, we consider the quantity
$\displaystyle||f-g||=\max_{x\in [a,b]}\left|f(x)-g(x)\right|$.
\begin{enumerate}
	\setcounter{enumi}{1}
	\item  Take a function $f\in\C[a,b]$. The \textbf{Weierstrass Approximation Theorem} states that given any real number $\e>0$, there exists a polynomial $p$ such that
$$||f-p||<\e\implies |f(x)-p(x)|<\e\text{\hspace{12pt}}\forall x\in[a,b]$$
\end{enumerate}

\subsection{Lagrange interpolation formula}
Given $n+1$ distinct real points $x_0,x_1,\dots,x_n$ and a function $f$ whose values are known at these points, there exists a unique polynomial $p_n\in\mathbb{P}_n$ such that $p_n(x_i)=f(x_i)$ for $ i=0,1,\dots,n$. Construct $n^{th}$ degree polynomials $L_0^n(x),L_1^n(x),\dots,L_n^n(x)$ such that
$$L_k^n(x_i)=\delta_{ki}=\left\lbrace\begin{array}{lr}
1 & \text{if } i=k\\
0 & \text{if } i\neq k
\end{array}\right.\implies \boxed{p_n(x):=\sum_{k=0}^nf(x_k)L_k^n(x)}$$
The \textbf{lagrange polynomials} $L_k^n$ can be found using the following algorithm
$$\boxed{L_k^n(x):=\prod_{j=0,j\neq k}^n\frac{(x-x_j)}{(x_k-x_j)}}$$
\textsc{Note:} As will be seen later, the method of divided differences can also be used for polynomial interpolation. A little bit of manipulation on the Lagrange interpolation formula gives us an alternative way to calculate the divided difference $f[x_0,x_1,\dots,x_n]$, given by $$f[x_0,x_1,\dots,x_n]:=\sum_{k=0}^nf(x_k)\prod_{j=0,j\neq k}^{n}\frac{1}{x-x_j}$$
\newpage
\subsection{Newton's divided differences}
Let $x_0,x_1,\dots,x_n$ be $n+1$ real distinct points in $[a,b].$ Let $f:[a,b]\to\R$ be a function whose values are known at these points. We want to find a polynomial $p_n(x)\in\mathbb{P}_n$ such that $p_n(x_i)=f(x_i)$ for $i=0,1,\dots,n$.

We define the \textbf{divided differences} (independant of order of points) using the recursive relation: $$f[x_0]:=f(x_0)$$$$
f[x_0,x_1,\dots,x_{m+1}]:=\frac{f[x_1,\dots,x_{m+1}]-f[x_0,\dots,x_m]}{x_{m+1}-x_0}$$
Then the polynomial $p_n(x)$ can be written as:
$$\boxed{p_n(x) := f[x_0]  + f[x_0, x_1](x - x_0)+\cdots+f[x_0,x_1,\dots,x_n]\prod_{k=0}^{n-1}(x-x_k)}$$

\subsection{Matrix representation}
The problem of interpolation can also be expressed as a system of linear equations and solved for the coefficients. A matrix similar to the Vandermonde matrix is generated.

$$\begin{bmatrix}
1 & x_0 & x_0^2 & \cdots & x_0^n\\
1 & x_1 & x_1^2 & \cdots & x_1^n\\
\vdots & & \ddots & & \vdots\\
1 & x_n & x_n^2 & \cdots & x_n^n\\
\end{bmatrix}
\begin{bmatrix}
a_0\\
a_1\\
\vdots\\
a_n
\end{bmatrix}=
\begin{bmatrix}
y_0\\
y_1\\
\vdots\\
y_n
\end{bmatrix}
$$
\subsection{Error estimation}
\label{subsec:error_eq}
Take $f\in\C^{n+1}[a,b]$. Let $x_0,x_1,\dots,x_n$ be $n+1$ distinct points in $[a,b]$. Let $p\in\mathbb{P}_n$ such that $p(x_i)=f(x_i)$ for $i=1,2,\dots,n$. Then for all $x\in[a,b]$, there exists $\xi=\xi(x)\in (a,b)$ such that
$$f(x)-p(x)=\frac{1}{(n+1)!}f^{(n+1)}(\xi)\prod_{k=0}^n (x-x_k)$$
Taking maximum over $x\in[a,b]$, we can see that our choice of interpolation points influences the error significantly.
$$\max_{x\in[a,b]}|f(x)-p(x)|\leqslant\frac{1}{(n+1)!}||f^{(n+1)}||\max_{x\in[a,b]}\prod_{k=0}^n|(x-x_k)|$$
This invokes the concept of \textbf{Chebyshev's interpolation points}. These are essentially the vertical projections of equally spaced points on a half-circle with center $\displaystyle\frac{a+b}{2}$ and radius $\displaystyle\frac{b-a}{2}$, given by $$x_k=\frac{a+b}{2}+\frac{b-a}{2}\cos\left(\frac{k\pi}{n}\right)$$
\newpage
\subsection{Piecewise interpolation}
A function $\phi\in\C[a,b]$ is a \textbf{piecewise polynomial} on $[a,b]$ if
\vspace{-3mm}
\begin{itemize}
\itemsep0em
	\item[$-$] there exist points $\{x_i\}_{i=0}^n$ such that $a=x_0<x_1<\dots<x_n=b$
	\item[$-$] $\phi\in\PP_m$ is defined in each interval $[x_{i-1},x_i]$ but not necessarily on the entire domain
	\item[$-$] $m\leqslant n$ and $m\geqslant 0$
\end{itemize}
\vspace{-2mm}
Piecewise interpolation involves building a function $\phi\in\C[a,b]$ such that $\phi\in\PP_n$ on $[x_{i-1},x_i]$ and $\phi(x_{i-1})=f_{i-1}\text{ and }\psi(x_i)=f_i$. The general algorithm for piecewise interpolation is:
\vspace{-3mm}
\begin{itemize}
\itemsep0em
	\item[$-$] pick data points $\{(x_i,f_i)\text{ }|\text{ }i=0,1,\dots,n\}$ such that $a=x_0<x_1<\dots<x_n=b$
	\item[$-$] build $\phi\in\C[a,b]$ on each $[x_{i-1},x_i]$ such that $\phi\in\PP_m[x_{i-1},x_i]$ and $\phi(x_{i-1})=f_{i-1}$
	$$\phi(x_i)=f(x_i)=f_i\text{ for }i=0,1,\dots,n\rightarrow(n+1)\text{ conditions}$$
	$$\phi(x)=\left\lbrace\begin{array}{rl}
		a_0^{(1)}+a_1^{(1)}x+\cdots+a_m^{(1)}x^m & \text{ on }[x_0,x_1]\\
		a_0^{(2)}+a_1^{(2)}x+\cdots+a_m^{(2)}x^m & \text{ on }[x_1,x_2]\\
		\vdots & \\
		a_0^{(n)}+a_1^{(n)}x+\cdots+a_m^{(n)}x^m & \text{ on }[x_{n-1},x_n]
	\end{array}\right\rbrace\text{ }n(m+1)\text{ coefficients}$$
	\item[$-$] continuity of derivatives on interior points $\{x_i\mid i=1,2,\dots,n-1\}$
	$$\left.\begin{array}{c}
	\displaystyle\lim_{h\to 0^{+}}\phi(x_i-h)=\lim_{h\to 0^{+}}\phi(x_i+h)\\
	\displaystyle\lim_{h\to 0^{+}}\phi^1(x_i-h)=\lim_{h\to 0^{+}}\phi^1(x_i+h)\\
	\vdots\\
	\displaystyle\lim_{h\to 0^{+}}\phi^{m-1}(x_i-h)=\lim_{h\to 0^{+}}\phi^{m-1}(x_i+h)\\
	\end{array}\right\rbrace\text{ }m(n-1)\text{ more conditions}$$
	\item[$-$] still need $(m-1)$ more conditions
\end{itemize}
\subsection{Linear interpolating splines}
Take $n+1$ points such that $a=x_0<x_1<\dots<x_n=b$ and a function $f\in\C[a,b]$. The linear interpolating spline $s_L(x)$ is $$\boxed{s_L(x)=\left(\frac{x_i-x}{x_i-x_{i-1}}\right)f_{i-1}+\left(\frac{x-x_{i-1}}{x_i-x_{i-1}}\right)f_i}$$
This is nothing different from connecting each pair of consecutive points with a straight line. Clearly, there will be some error in interpolation since we are approximating $f$ by a set of polynomials in $\PP_1$. The error bound can be quantified as
$$||f-s_L||\leqslant \frac{h^2}{8}||f^{\prime\prime}||\text{ }\text{ }\text{ }\text{ }\text{ where }h=\max_{1\leqslant i\leqslant n}h_i=\max_{1\leqslant i\leqslant n}(x_i-x_{i-1})$$
The proof relies on the error equation introduced in \hyperref[subsec:error_eq]{Section 1.5}. Substitute $n=1$ and note how $\max|(x-x_{i-1})(x-x_i)|=h_i^2/4$ where $h_i=x_i-x_{i-1}$. Finally take a maximum over all the $i'$s.
\newpage
\subsection{Cubic splines}
This is another case of spline interpolation where $s\in\C^2[x_0,x_n]$ such that $s\in\PP_3$ on each $[x_{i},x_{i+1}]$.
\vspace{-8mm}
\begin{itemize}
	\itemsep0em
	\item[$-$] interpolation conditions:
	\vspace{-3.5mm}
	\begin{align*}
		\text{function value}\rightarrow &\left\lbrace\begin{array}{l}
		s_i(x_i)=f_i\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\text{ }\hspace{1mm}\text{ for }i=0,1,\dots,n-1\\
		s_{n-1}(x_n)=f_n
	\end{array}\right.\\
	\text{continuity of }s\rightarrow & \text{ }\text{ }\text{ }\text{ }s_i(x_{i+1})=s_{i+1}(x_{i+1})\text{ }\text{ }\text{ }\text{ for }i=0,1,\dots,n-2\\
	\text{continuity of }s^{\prime}\rightarrow & \text{ }\text{ }\text{ }\text{ }s_i^{\prime}(x_{i+1})=s_{i+1}^{\prime}(x_{i+1})\text{ }\text{ }\text{ }\text{ for }i=0,1,\dots,n-2\\
	\text{continuity of }s^{\prime\prime}\rightarrow &  \text{ }\text{ }\text{ }\text{ }s_i^{\prime\prime}(x_{i+1})=s_{i+1}^{\prime\prime}(x_{i+1})\text{ }\hspace{2mm}\text{ for }i=0,1,\dots,n-2
	\end{align*}
	\vspace{-7mm}
	\item[$-$] take polynomials of the form $s_i(x)=a_i(x-x_i)^3+b_i(x-x_i)^2+c_i(x-x_i)+d_i$ for $x\in[x_{i},x_{i+1}]$ and $i=0,1,\dots,n-1$
	\item[$-$] $4n$ coefficients \& $4n-2$ conditions, need 2 more conditions $\rightarrow s_0^{\prime\prime}(x_0)=s_{n-1}^{\prime\prime}(x_n)=0$
\end{itemize}
\vspace{-2mm}

Instead of solving a $4n\times 4n$ matrix, we can make our life a little easier. Take equally spaced knots $h=|x_{i+1}-x_i|$ for $i=0,1,\dots, n-1$. Using the general form for $s_i(x)$, we get $$s_i(x_i)=f_i\implies \boxed{d_i=f_i}\text{ }\text{ }\text{ }\text{ for }i=0,1,\dots,n-1$$
We further define new variables as $\sigma_i=s^{\prime\prime}(x_i)$ for $i=0,1,\dots,n$. We already know $\sigma_0=\sigma_n=0$, thus we have $n-1$ unknown quantities. We have
\begin{equation}
s_i^{\prime\prime}(x)=6a_i(x-x_i)+2b_i\implies \sigma_i=s_i^{\prime\prime}(x_i)=2b_i\implies \boxed{b_i=\frac{\sigma_i}{2}}
\end{equation}
Using the condition that $s_i^{\prime\prime}(x_{i+1})=s_{i+1}^{\prime\prime}(x_{i+1})$, we have
\begin{equation}
6a_i(x_{i+1}-x_i)+2b_i=\sigma_{i+1}\implies \boxed{a_i=\frac{\sigma_{i+1}-\sigma_i}{6h}}
\end{equation}
Next, we evaluate $s_i(x)$ at $x=x_{i+1}$ to get
\begin{equation}
f_{i+1}=s_i(x_{i+1})=a_ih^3+b_ih^2+c_ih+d_i\implies \boxed{c_i=\frac{f_{i+1}-f_i}{h}-\frac{h}{6}(2\sigma_i+\sigma_{i+1})}
\end{equation}
Finally using the continuity of $s^{\prime}$ i.e. $s_i^{\prime}(x_{i+1})=s_{i+1}^{\prime}(x_{i+1})$, we get
$$\left.\begin{array}{r}
	s_i^{\prime}(x)=3a_i(x-x_i)^2+2b_i(x-x_i)+c_i\\
	s_{i+1}^{\prime}(x)=3a_{i+1}(x-x_i)^2+2b_{i+1}(x-x_i)+c_{i+1}
\end{array}\right\rbrace\implies 3a_ih^2+2b_ih+c_i=c_{i+1}$$
A little bit of careful manipulation using equations (1), (2) and (3) yields us the recursive relation for $i=1,\dots,n-1$: $$\sigma_{i-1}+4\sigma_i+\sigma_{i+1}=\dfrac{6}{h^2}(f_{i-1}-2f_i+f_{i+1})\left\lbrace\arraycolsep=2pt\def\arraystretch{1.8}
\begin{array}{l}
	\sigma_{0}+4\sigma_1+\sigma_{2}=\dfrac{6}{h^2}(f_{0}-2f_1+f_{2})\\
	\sigma_{1}+4\sigma_2+\sigma_{3}=\dfrac{6}{h^2}(f_{1}-2f_2+f_{3})\\
	\vdots\\
	\sigma_{n-2}+4\sigma_{n-1}+\sigma_{n}=\dfrac{6}{h^2}(f_{n-2}-2f_{n-1}+f_{n})\\
\end{array}\right.
$$
This system of equations can be expressed as a matrix equation which is more convenient to solve:
$$\begin{bmatrix}
	4 & 1 & 0 & \cdots & 0 & 0 & 0\\
	1 & 4 & 1 & \cdots & 0 & 0 & 0\\
	0 & 1 & 4 & \cdots & 0 & 0 & 0\\
	\vdots & \vdots & \vdots & \ddots & \vdots & \vdots & \vdots\\
	0 & 0 & 0 & \cdots & 4 & 1 & 0\\
	0 & 0 & 0 & \cdots & 1 & 4 & 1\\
	0 & 0 & 0 & \cdots & 0 & 1 & 4\\
\end{bmatrix}
\begin{bmatrix}
	\sigma_1\\
	\sigma_2\\
	\sigma_3\\
	\vdots\\
	\sigma_{n-3}\\
	\sigma_{n-2}\\
	\sigma_{n-1}\\
\end{bmatrix}=\frac{6}{h^2}\begin{bmatrix}
	f_0 - 2f_1+f_2\\
	f_1 - 2f_2+f_3\\
	f_2 - 2f_3+f_4\\
	\vdots\\
	f_{n-4}-2f_{n-3}+f_{n-2}\\
	f_{n-3}-2f_{n-2}+f_{n-1}\\
	f_{n-2}-2f_{n-1}+f_{n}\\
\end{bmatrix}
$$
As with linear splines, there is also an error bound associated with cubic splines. This is given by
$$||f-s||\leqslant Ch^4||f^{(iv)}||\text{ }\text{ }\text{ where }h=\max_{1\leqslant i\leqslant n}h_i=\max_{1\leqslant i\leqslant n}(x_i-x_{i-1})\text{ and } C=\text{constant}$$
\section{Numerical Integration}
Given a real function $f$, we want to compute the integral $\displaystyle\int_a^b f(x)\text{d}x$. While it might seem straightforward, finding an antiderivative is not always easy. Hence, we resort to approximating it.
\subsection{Newton-Cotes formula}
Let $f:[a,b]\to\R$ and $p\in\PP_n$ be the interpolating polynomial. Define the \textbf{quadrature points} as $a=x_0<\dots<x_n=b$. Then $\displaystyle\int_a^b f(x)\text{d}x$ can be approximated as
\begin{align*}
	\int_a^bf(x)\text{d}x&\approx \int_a^bp(x)\text{d}x\implies \int_a^bf(x)\text{d}x\approx\int_a^b\sum_{i=0}^nf(x_i)L_i(x)\text{d}x=\sum_{i=0}^nf(x_i)\int_a^bL_i(x)\text{d}x
\end{align*}
Assume equally spaced intervals such that $x_i=a+ih$. Further let $x=a+th$ for $t\in[0,n]$. We can then express the lagrange polynomials in terms of $t$.
$$L_i(x)=\prod_{k=0,k\neq i}^n\frac{(x-x_k)}{(x_i-x_k)}=\prod_{k=0,k\neq i}^n\frac{(t-k)}{(i-k)}=\phi_i(t)\implies \int_a^bL_i(x)\text{d}x=h\int_0^n\phi_i(t)\text{d}t$$
Defining the quadrature weights as $\displaystyle w_i=\int_0^n\phi_i(t)\text{d}t$ for $i=0,\dots, n$, we get
$$\boxed{\int_a^bf(x)\text{d}x\approx h\sum_{i=0}^nw_if(x_i)}$$

\textsc{Note:} The weights $w_i$ are dependent only on $n$ and are independent of $f,a,b$ and $h$. Further, all the $w_i$'s are symmetric i.e. $w_k=w_{n-k}$. Finally, all the weights add up to $n$ i.e. $\displaystyle\sum_{i=0}^nw_i=n$.
\newpage
\subsection{Special cases of the Newton-Cotes formula}
Let $\I_f$ be the desired integral and $\displaystyle\I_p=\int_a^bp(x)\text{d}x$ be the approximated integral. We can substitute values of $n$ in the Newton-Cotes formula to get the following cases:
\begin{enumerate}
	\item \textbf{Trapezium rule} ($n=1$): $\displaystyle\I_{p_1}=\frac{h}{2}(f(a)+f(b))$
	\item \textbf{Simpson's $\displaystyle\frac{1}{3}$ rule} ($n=2$): $\displaystyle\I_{p_2}=\frac{h}{3}(f(a)+4f(a+h)+f(b))$
	\item Simpson's $\displaystyle\frac{3}{8}$ rule ($n=3$): $\displaystyle\I_{p_3}=\frac{3h}{8}(f(a)+3f(a+h)+3f(a+2h)+f(b))$
	\item Milne's rule ($n=4$): $\displaystyle\I_{p_4}=\frac{h}{45}(14f(a)+64f(a+h)+24f(a+2h)+64f(a+3h)+14f(b))$
\end{enumerate}
\subsection{Error in the Newton-Cotes formula}
Recall the error equation from \hyperref[subsec:error_eq]{Section 1.5}. We use it to find the error in the Newton-Cotes formula as follows:
\begin{align*}
	\left|\I_f-\I_{p_n}\right|&=\left|\int_a^b(f(x)-p_n(x))\text{d}x\right|\leqslant \int_a^b\left|f(x)-p_n(x)\right|\text{d}x\\
	\therefore \left|\I_f-\I_{p_n}\right|&\leqslant \left[\frac{1}{(n+1)!}\max_{\eta\in[a,b]}|f^{(n+1)}(\eta)|\right]\int_a^b\left|\prod_{i=0}^n(x-x_i)\right|\text{d}x\\
	&=\frac{1}{(n+1)!}||f^{(n+1)}||\int_a^b\prod_{i=0}^n\mid x-x_i\mid\text{d}x
\end{align*}
\begin{itemize}
	\item[$-$] Trapezium rule: $\displaystyle |\I_f-\I_{p_1}|\leqslant\frac{1}{12}\mid\mid f^{\prime\prime}\mid\mid(b-a)^3$
	\item[$-$] Simpson's rule: $\displaystyle |\I_f-\I_{p_2}|\leqslant\frac{1}{192}\mid\mid f^{\prime\prime\prime}\mid\mid(b-a)^4$
\end{itemize}
As we increase $n$, some of the weights take negative values. As a result, the error does not converge to zero with $n$.
\subsection{Gaussian quadrature}
In order for the error to converge to 0, we must ensure that the weights are all positive. We define the Gaussian quadrature of order $n$ as follows:
$$\mathcal{G}_n(f)=\sum_{i=0}^nW_if(x_i)\text{ where }W_i=\int_a^b[L_i(x)]^2\text{d}x=\int_a^b\prod_{k=0,k\neq i}^n\left(\frac{x-x_k}{x_i-x_k}\right)^2$$
The quadrature points are not equally spaced, and are roots of certain polynomials.
$$\lim_{n\to\infty}|\mathcal{G}_n(f)-\I_f|=0$$
\subsection{Composite rules}
This is very similar to spline interpolation, where we interpolated $f$ by a piecewise cubic over each sub-interval. Here, we divide $[a,b]$ into $m$ sub-intervals of equal length and apply Newton-Cotes on each set of quadrature points.
\end{document}


\subsection{Single accelerating object in space}
 Accelerating objects like pulsars can create gravitational wave \cite{Creighton:2011zz}. According to general relativity, mass creates stress in space-time and thus can change the geometry of it by bending and changing the curvature. Then if this object moves, then the curvature also moves along with it. But if the object accelerates in space-time in a circular manner, then the ripples will be created in space-time which is which radiates gravitational waves. This is similar to creation of water waves when we move our finger in a circular fashion in water. So higher the mass of object and it's acceleration, stronger is the gravitational wave it produces \cite{Linear}.

Any imperfections on the continuously spinning bodies like pulsar produces continuous gravitational waves, where it's nature is sinusoidal for a longer period of time. This happens only if spin rate of this object is constant. Such gravitational waves have same frequency and amplitude. But these types of gravitational waves are not yet discovered.\\

\begin{figure}[h]
    \centering
    \includegraphics[scale = 0.4]{images.tex/continuous_gw.jpg}
    \caption{Continuous gravitational wave by a pulsar. Source :- \href{https://earthsky.org/space/gravitational-waves-single-neutron-stars-planck-einsteinhome}{Earthsky.org}}
\end{figure}

\begin{figure}[h]
    \centering
    \includegraphics[height=5.5cm]{images.tex/continuous_gw_by_imperfection.jpg}
    \caption{A rotating pulsar. Source :- \href{}{} \url{https://astronomy.com/news/2018/02/}}
\end{figure}

\pagebreak

gw-physics-and-ligo/4 Source.tex/4.1 Single accelerating object.tex


\documentclass[journal, retainorgcmds]{IEEEtran}
\usepackage{cite}
\usepackage[cmex10]{amsmath}
\usepackage{array}
\usepackage{url}

\usepackage{amssymb}
\usepackage{bbm}
\usepackage[greek,english]{babel}
\usepackage{textgreek}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}
\usepackage{autofe}
\usepackage{minted}
\usepackage{fancyvrb}

% Missing unicode characters for Agda
\usepackage{MnSymbol}
\DeclareUnicodeCharacter{"2237}{$\squaredots$}
\DeclareUnicodeCharacter{"25C2}{$\blacktriangleleft$}
\DeclareUnicodeCharacter{"25B8}{$\blacktriangleright$}
\DeclareUnicodeCharacter{"1D9C}{$^{c}$}
\DeclareUnicodeCharacter{"225F}{$\stackrel{?}{=}$}

% More readable mintinline
\newcommand{\iagda}[1]{\mintinline{agda}{#1}}
\newcommand{\ihask}[1]{\mintinline{haskell}{#1}}

% correct bad hyphenation here
\hyphenation{op-tical net-works semi-conduc-tor}

\begin{document}

\title{Verified Red-Black Trees: A comparison between Agda and Haskell}
\author{Toon~Nolten\\ \texttt{<toon.nolten@student.kuleuven.be>}}%
\maketitle

\begin{abstract}
  Dependent types are an advanced feature of some type systems that allow
  properties of programs to be embedded in their types.
  Originally this was applied in proof assistants, a property is represented
  as a type and its proof is a function of that type.
  However this also works the other way around, we can embed proofs in our
  programs and in doing so prevent certain bugs from passing a static
  verification, i.e. type checking the program.
  This correspondence between propositions and types is called the
  Curry-Howard correspondence and is what gives dependent types their
  expressiveness.
  Several languages have such types, most of them are on a spectrum between
  being a proof assistant and a programming language, Agda leans more towards
  the latter.
  In contrast, languages with a Hindley-Milner type system are not dependently
  typed but in the case of Haskell, extensions to the Glasgow Haskell Compiler
  have been developed that borrow concepts and fit them into the existing
  system.
  In this paper we demonstrate how dependent types can be used to add some
  verification to the implementation of red-black trees by Chris Okasaki.
  This is done once for a fully dependently typed language, i.e. Agda, and in
  comparison, in Haskell with the appropriate GHC extensions.
  Although these implementations are longer than the original, they prevent us
  from violating some of the red-black tree invariants which is exactly what
  they were supposed to accomplish.
\end{abstract}

\begin{IEEEkeywords}
  Dependent Types, Agda, Haskell, Red-Black Trees, Comparison.
\end{IEEEkeywords}

\section{Introduction}
\IEEEPARstart{D}{ependent} types are a powerful tool to improve software
development.
Type systems in general are used to prevent certain simple but hard to spot
bugs, e.g. a function that returns an integer instead of a floating point
number.
Dependent types are more expressive than simple types because they can
\emph{depend} on values.
The canonical introductory example of a dependent type is the type for vectors
(lists of fixed length):

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  data Vec (A : Set) : ℕ → Set where
    []  : Vec A zero
    _∷_ : ∀ {n} (x : A) (xs : Vec A n)
          → Vec A (suc n)
\end{minted}

For someone with a background in functional programming languages this may be
a good example of how dependent types are more expressive but for someone with
a background in imperative languages a list with a fixed length is just an
array.
Hopefully the running example in this paper, i.e. red-black trees
\cite{rbtrees}, will serve to convince those yet unimpressed of the
expressiveness of dependent types.

\hfill July 15, 2015

\subsection{Red-Black Trees}

Red-black trees are (approximately) balanced binary search trees.
Relying on color information (essentially an extra bit of data per node) to
maintain balance.
The approximate balancing is good enough to guarantee $\mathcal{O}(\log{}n)$
time complexity for search, insertion and deletion.
Binary search trees are often used to implement more abstract data structures
such as sets and maps.
Especially for ordered sets and maps this approach has advantages when compared
to a hash table based implementation, as search trees maintain order by
definition.

An elegant implementation of red-black trees in a functional programming
language is that by Chris Okasaki \cite{okasaki}, in Haskell \cite{haskell},
which is what the implementations in the examples are based on:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  data Color = R | B
  data Tree elt =
    E | T Color (Tree elt) elt (Tree elt)

  type Set a = Tree a

  empty :: Set elt
  empty = E

  member :: Ord elt => elt -> Set elt -> Bool
  member x E = False
  member x (T _ a y b) | x <  y = member x a
                       | x == y = True
                       | x >  y = member x b

  -- originally without type signature
  balance :: Color -> Tree elt -> elt
             -> Tree elt -> Tree elt
  balance B (T R (T R a x b) y c) z d =
    T R (T B a x b) y (T B c z d)
  balance B (T R a x (T R b y c)) z d =
    T R (T B a x b) y (T B c z d)
  balance B a x (T R (T R b y c) z d) =
    T R (T B a x b) y (T B c z d)
  balance B a x (T R b y (T R c z d)) =
    T R (T B a x b) y (T B c z d)
  balance color a x b = T color a x b

  insert :: Ord elt => elt -> Set elt
            -> Set elt
  insert x s = makeBlack (ins s)
    where
      ins E = T R E x E
      ins (T color a y b)
        | x <  y = balance color (ins a) y b
        | x == y = T color a y b
        | x >  y = balance color a y (ins b)

      makeBlack (T _ a y b) = T B a y b
\end{minted}

Okasaki based his implementation on a succinct formulation of the red-black tree
invariants:
\begin{LaTeXdescription}
  \item[Invariant 1] No red node has a red parent.
  \item[Invariant 2] Every path from the root to an empty node contains the
                     same number of black nodes.
\end{LaTeXdescription}
While this implementation is short and simple enough for most people with some
functional programming experience to understand, it is really important for
data structures to be correctly implemented.
This is usually achieved by writing a suite of tests that exercise the
implementation.
Even though this is a proven methodology, there is undeniably some maintenance
overhead involved: tests need to be written and updated when the interface
changes.
Another disadvantage of this approach is that it is difficult to ensure that
each and every possible case is tested, usually tests are aimed at corner cases
that are identified by simply reasoning about the code.
Randomized testing tools such as QuickCheck \cite{quickcheck} were created for
precisely these reasons.
In the examples that follow, the expressiveness of dependent types is exploited
to provide static verification of the correctness of the implementations.

\section{Red-Black Trees in Agda}

The code for this section can be found in its entirety in appendix
\ref{app:agda}.
No matter how elegant Okasaki's implementation, the \ihask{Tree} data type
in no way prevents misuse, e.g. \ihask{T R (T R E 1 E) 2 E} and
\ihask{T B (T B E 1 E) 2 E} are both valid values of the type \ihask{Tree}
while they don't satisfy the invariants on red-black trees.
Because of this we have to be careful when implementing a function that
produces a \ihask{Tree}.
Not to mention how we should handle invalid red-black trees?
The easiest solution is not to think about it, but then a runtime error could
occur because somewhere we defined a function with the implicit assumption it
would receive a valid red-black tree and it does not have a matching clause for
an invalid tree.
The other possible outcome is that it does not cause an error; every function
an invalid tree passes through may have done something and all we see is the
end result, this could be a debugging nightmare.
The expressiveness of dependent types can ensure that only valid red-black
trees can be created, in a way the \iagda{Tree} type will more accurately
represent all possible red-black trees, in Agda \cite{agda}:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  data Color : Set where
    R B : Color
  Height = ℕ

  data Tree : Color → Height → Set a where
    E : Tree B 0
    R : ∀{h} → Tree B h → A → Tree B h
        → Tree R h
    B : ∀{cl cr h} → Tree cl h → A → Tree cr h
        → Tree B (suc h)
\end{minted}

Instead of the algebraic data type (ADT) \cite{adt} in Haskell we use an
inductive family \cite{indfam} to define the \iagda{Tree} type, this time
including the \iagda{Color} (of the root node) and \iagda{Height} (number of
black nodes on a path from the root to an empty node) in the type.
This type enforces both red-black tree invariants: the constructor for a
red node only allows children with a black root, therefore preventing a red
node from having a red parent which is invariant 1. The constructors for red
and black nodes demand their children be of the same height, thereby enforcing
invariant 2.
Now the type system guarantees that our functions always produce valid
red-black trees.
If we define a function that tries to create an invalid \iagda{Tree} the code
will not type check.
As a side effect type checking becomes part of writing code, instead of writing
a large part of the program and then type checking at compile time.
Agda integrates type checking into the editor which facilitates a more
interactive workflow, alternately writing some code and type checking, making
use of feedback from the type checker to correct the code.

The biggest advantage of this stronger, more precise type is also somewhat of
a disadvantage at the same time.
Oftentimes an algorithm will temporarily violate invariants because it is
easier to mess up and restore than do everything right immediately, especially
when changes can cascade.
Okasaki makes use of this in his \ihask{ins} function: \ihask{ins} may return
an invalid \ihask{Tree} which is why the calls only occur as part of a call
to \ihask{makeBlack} or \ihask{balance}.
Because of how \ihask{ins} is implemented it may return a \ihask{Tree} with a
red root that has one red child, this is also called an \emph{infrared} tree.
Transforming an infrared tree into a valid tree can be done by blackening
(just changing the color to black) the root node, however this increases the
height of the tree by one.
During insertion a height increase is undesirable because then the tree has to
be rebalanced.
Since the tree has to be rebalanced anyway, this is what happens in \ihask{ins}.
\ihask{ins} recurses by deconstructing the node and then deciding which child
the new value belongs to.
If this child is infrared and the current node is black Okasaki's rebalancing
algorithm restores the red-black tree invariants: this is where the elegance
of his solution comes from.
It is also the only way such an imbalance can occur, because a child can only be
infrared, if it had a red root before the insertion which means the node that
was just deconstructed is black. So every time we need to rebalance there is a
black node with an infrared child; of course this relies on the assumption that
the original tree was a valid red-black tree.
Since this kind of temporary violation of invariants is not allowed by the
dependently typed implementation we need a new data type to represent infrared
trees:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  data IRTree : Height → Set a where
    IRl : ∀{h} → Tree R h → A → Tree B h
      → IRTree h
    IRr : ∀{h} → Tree B h → A → Tree R h
      → IRTree h
\end{minted}

Because the type for an infrared tree and a red-black tree are now distinct we
cannot define \iagda{balance} as Okasaki did because the left tree can be
infrared and the right red-black or the other way around.
However we can easily mimick this behaviour using another data type:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  data OutOfBalance : Height → Set a where
    _◂_◂_ : ∀{c h} → IRTree h → A → Tree c h
            → OutOfBalance h
    _▸_▸_ : ∀{c h} → Tree c h → A → IRTree h
            → OutOfBalance h
\end{minted}

Thanks to Agda's flexible mixfix syntax, this Haskell code
\ihask{balance B infra b c}, turns into this Agda code:
\iagda{balance (infra ◂ b ◂ c)}.
Notice also that we do not require the color argument, we will come back to
this.
There's still one type missing, some of Okasaki's functions like \ihask{ins}
can return either a red-black or an infrared tree.
Because those are represented by two separate types we need an extra type to
act as a disjoint sum:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  data Treeish : Color → Height → Set a where
    RB : ∀{c h} → Tree c h → Treeish c h
    IR : ∀{h} → IRTree h → Treeish R h
\end{minted}

Being more precise takes more effort, one data type is replaced by four.
The increase in precision goes hand in hand with an increase of verbosity, this
will also be apparent in the implementation of the functions.
The first function to consider is balance because this is the main source of
elegance:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  balance : ∀{h} → OutOfBalance h → Tree R (suc h)
  balance (IRl (R a x b) y c ◂ z ◂ d) =
    R (B a x b) y (B c z d)
  balance (IRr a x (R b y c) ◂ z ◂ d) =
    R (B a x b) y (B c z d)
  balance (a ▸ x ▸ IRl (R b y c) z d) =
    R (B a x b) y (B c z d)
  balance (a ▸ x ▸ IRr b y (R c z d)) =
    R (B a x b) y (B c z d)
\end{minted}

This is fairly similar to Okasaki's implementation, arguably it is more
elegant, but there are subtle differences.
The color argument is no longer necessary, it could be replaced by a pattern
match on the constructor, but we only balance trees that are out of balance and
they only produce red trees.
The reason for this as well as the removal of the \emph{catch-all} clause is
that the type no longer permits a valid red-black tree.
In Okasaki's implementation, when \ihask{balance} was called with a valid
red-black tree it would be returned unaltered, that way the function can be
called indiscriminately.
With the more restricted implementation it is necessary to ensure
\iagda{balance} is only called when necessary.
Often this requires more extensive case analysis but this can be a good thing
because if there's a bug in Okasaki's implementation, it can be harder to find
since every \ihask{Tree} could go through \ihask{balance}, which means we'd
have to check that \ihask{balance} has the right behaviour even for trees that
shouldn't even be rebalanced in the first place.

The local functions Okasaki declared in \ihask{insert} have changed a lot more.
They are not defined locally because we need multiple clauses for
\iagda{insert}.
The simplest of these is \iagda{blacken}, similar to Okasaki's
\ihask{makeBlack}:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  blacken : ∀{c h} → (Treeish c h)
            → (if c =ᶜ B then Tree B h
                         else Tree B (suc h))
  blacken (RB E) = E
  blacken (RB (R l b r)) = (B l b r)
  blacken (RB (B l b r)) = (B l b r)
  blacken (IR (IRl l b r)) = (B l b r)
  blacken (IR (IRr l b r)) = (B l b r)
\end{minted}

All \iagda{blacken} does is take a tree and make the root node black.
However, this function has to handle valid red-black trees as well as infrared
trees (which corresponds to \iagda{Treeish}) and for each of these we have to
consider each constructor because we need to access the values used to
construct the root node.
When a red root is colored black the \iagda{Height} of the \iagda{Tree}
increases by one, that's why we have a return type that is conditional on the
color of the original \iagda{Tree}.

Because \iagda{ins} is no longer defined locally we need an explicit argument
for the value to be inserted.
\iagda{ins} takes a red-black \iagda{Tree} and returns a \iagda{Tree} if the
given \iagda{Tree} was black or a possibly infrared \iagda{Treeish} if it was
not.
Either of these would have the same \iagda{Height} which can be guaranteed only
because the function can return infrared trees.
The color of the resulting tree is left undecided by using a dependent pair,
this does mean we have to return a pair of a \iagda{Color} and a \iagda{Tree}.
Okasaki's rebalancing algorithm can't balance infrared trees by themselves but
it doesn't need to because an infrared tree can be turned into a red-black tree
by coloring the root black:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  ins : ∀{c h} → (a : A) → (t : Tree c h)
        → Σ[ c' ∈ Color ]
           (if c =ᶜ B then (Tree c' h)
                      else (Treeish c' h))
  ins a E = R , R E a E
  --
  ins a (R _ b _) with a ≤ b
  ins a (R l _ _) | LT with ins a l
  ins _ (R _ b r) | LT | R , t =
    R , IR (IRl t b r)
  ins _ (R _ b r) | LT | B , t =
    R , (RB (R t b r))
  ins _ (R l b r) | EQ = R , RB (R l b r)
  ins a (R _ _ r) | GT with ins a r
  ins _ (R l b _) | GT | R , t =
    R , (IR (IRr l b t))
  ins _ (R l b _) | GT | B , t =
    R , (RB (R l b t))
  --
  ins a (B _ b _) with a ≤ b
  ins a (B l _ _) | LT with ins a l
  ins _ (B {R} _ b r) | LT | c , RB t =
    B , B t b r
  ins _ (B {R} _ b r) | LT | .R , IR t =
    R , balance (t ◂ b ◂ r)
  ins _ (B {B} _ b r) | LT | c , t =
    B , B t b r
  ins _ (B l b r) | EQ = B , B l b r
  ins a (B _ _ r) | GT with ins a r
  ins _ (B {cr = R} l b _) | GT | c , RB t =
    B , B l b t
  ins _ (B {cr = R} l b _) | GT | .R , IR t =
    R , balance (l ▸ b ▸ t)
  ins _ (B {cr = B} l b _) | GT | c , t =
    B , B l b t
\end{minted}

\iagda{ins} is a lot longer in this implementation, mostly because we need to
be more precise.
Whether we return a red-black or an infrared tree and whether we should call
\iagda{balance} or not, matters.
The \iagda{with} construct enables pattern matching on intermediate results to
decide which child a value belongs in and if the intermediate \iagda{Tree}
needs to be rebalanced or not.

The \iagda{insert} function has a more precise type than Okasaki's
implementation but it is not as precise as possible, i.e. the resulting
\iagda{Tree} cannot have just any \iagda{Height}, but it is not uniquely defined
either.
The constructors for the disjoint sum have been aliased to make it more obvious
what the resulting type is, either the resulting \iagda{Tree} has the same
\iagda{Height} (h+0) or the \iagda{Height} has increased by one (h+1).
Returning a value as part of a disjoint sum here is a concession, the problem
with being more precise is that it is difficult to say in advance whether a
given \iagda{Tree} will increase in \iagda{Height} upon inserting a given value.
A function that decides this can easily be defined and used in the type of
\iagda{insert} but Agda cannot reason about this function which gives problems
because Agda only allows total functions.
If such a function is part of the type Agda cannot infer when certain results
of the function are impossible and this combined with the necessity to cover
all cases that Agda can't rule out, makes this very difficult.
This can probably be remedied by providing Agda with an appropriate proof, but
this is a trade-off that has to be made, considering the added effort of a
proof against a small increase in precision.
In this case simplicity was chosen over precision:

%----------------------------------------%
\begin{minted}[fontsize=\small]{agda}
  insert : ∀{c h} → (a : A) → (t : Tree c h)
           → Tree B h ⊎ Tree B (suc h)
  insert {R} a t with ins a t
  ... | R , t' = h+1 (blacken t')
  ... | B , t' = h+0 (blacken t')
  insert {B} a t with ins a t
  ... | R , t' = h+1 (blacken (RB t'))
  ... | B , t' = h+0 (blacken (RB t'))
\end{minted}

\iagda{insert} takes a value and a red-black \iagda{Tree} and returns a black
\iagda{Tree} of the same \iagda{Height} or one level higher.
The cases for a red \iagda{Tree} or a black \iagda{Tree} are split up because
\iagda{ins} respectively returns a \iagda{Tree} or a red-black \iagda{Treeish}.

\section{Red-Black Trees in Haskell}

The code for this section can be found in its entirety in appendix
\ref{app:haskell}.
Haskell as a language is certainly not dependently typed but GHC \cite{ghc} has
several extensions that try to retrofit similar features into the
Hindley-Milner type system \cite{hindley}.
One of Haskell's most important features is the type inference of its type
system, this has to be preserved by whatever extension may be added.
Dependent types in general do not allow for type inference, Agda for example
has no type inference.
This implies that Haskell will never be a fully dependently typed system.
This also means that from time to time we will have to jump through hoops to
achieve similar guarantees from the type system.
In this section we will see how we can achieve most of the benefits of the
implementation in the last section in a not quite dependently typed language.
The code in this section relies on the following GHC extensions: GADTs
\cite{gadts}, DataKinds \cite{datakinds} and KindSignatures which are analogous
to type signatures at the kind level.
These extensions are attempts to make the Haskell type system more expressive
without giving up on type inference.
The \ihask{Tree} data type is fairly similar:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  data Nat = Z | S Nat
    deriving (Show, Eq, Ord)

  data Color = R | B
    deriving (Show, Eq)

  data Tree :: Color -> Nat -> * -> * where
    ET :: Tree B Z a
    RT :: Tree B  h a -> a -> Tree B  h a
          -> Tree R h a
    BT :: Tree cl h a -> a -> Tree cr h a
          -> Tree B (S h) a
\end{minted}

Other than syntax and constructor names, the most visible difference is the
extra parameter for polymorphism.
Agda's type system is not polymorphic, implicit arguments allow a very
similar approach.
In the previous implementation this problem as well as making sure the elements
that are put in trees can be compared, was solved in a different way
through Agda's module system, but that would take us too far.
In Haskell we can use and \ihask{Ord} constraint when we need to be able to
compare elements.
The \ihask{Tree} data type is not an ordinary ADT but a generalised algebraic
data type (GADT).
A GADT enables the specification of the type signature of each constructor
individually, this also permits the definition of constructors that result in a
value of a more restricted type.
There's also a kind \cite{kind} signature on \ihask{Tree}, just as a value has
a type, a type in Haskell has a kind.
Most types in Haskell have kind \ihask{*} and without extensions it is actually
impossible to define new kinds.
The kind signature for \ihask{Tree} indicates that \ihask{Tree} is a type, the
resulting kind is \ihask{*}, that takes three parameters, i.e. one of kind
\ihask{Color}, one of kind \ihask{Nat} and one of kind \ihask{*}.
The \ihask{Color} and \ihask{Nat} kinds are not defined explicitly, they are
created by data type promotion through the DataKinds extension.
The type \ihask{Color} is promoted to the kind \ihask{Color} and the
constructors \ihask{R} and \ihask{B} are promoted to the types \ihask{R} and
\ihask{B}, any of the promoted objects can be preceded by a single quote, e.g.
\verb|'Color| if there is a possibility of ambiguity.

Because the \ihask{Tree} type is more specific than in Okasaki's implementation
we run into the same problem as in the last section and we need several
additional types:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  data IRTree :: Nat -> * -> * where
    IRl :: Tree R h a -> a -> Tree B h a
           -> IRTree h a
    IRr :: Tree B h a -> a -> Tree R h a
           -> IRTree h a

  data OutOfBalance :: Nat -> * -> * where
    (:<:) :: IRTree h a -> a -> Tree c h a
             -> OutOfBalance h a
    (:>:) :: Tree c h a -> a -> IRTree h a
             -> OutOfBalance h a

  data Treeish :: Color -> Nat -> * -> * where
    RB :: Tree c h a -> Treeish c h a
    IR :: IRTree h a -> Treeish R h a
\end{minted}

Except for minor differences, i.e. these are GADTs instead of inductive
families, polymorphism and not allowing mixfix notation, these types are the
same as the ones in Agda.

The \ihask{balance} function is also very similar:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  balance :: OutOfBalance h a -> Tree R (S h) a
  balance ((:<:) (IRl (RT a x b) y c) z d) =
    RT (BT a x b) y (BT c z d)
  balance ((:<:) (IRr a x (RT b y c)) z d) =
    RT (BT a x b) y (BT c z d)
  balance ((:>:) a x (IRl (RT b y c) z d)) =
    RT (BT a x b) y (BT c z d)
  balance ((:>:) a x (IRr b y (RT c z d))) =
    RT (BT a x b) y (BT c z d)
\end{minted}

\ihask{blacken} has a slightly less specific type.
Functions that operate on the type level are a lot more restricted in Haskell,
precisely because there is a type level, whereas in Agda all types are values.
Type families \cite{typefam} are a GHC extension that provides something like a
function at the type level but for simplicity's sake we will just relax the
type:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  blacken :: Treeish c h a
             -> Either (Tree B h a)
                       (Tree B (S h) a)
  blacken (RB ET) = Left ET
  blacken (RB (RT l b r)) = Right (BT l b r)
  blacken (RB (BT l b r)) = Left (BT l b r)
  blacken (IR (IRl l b r)) = Right (BT l b r)
  blacken (IR (IRr l b r)) = Right (BT l b r)
\end{minted}

The return type is now a disjoint sum, this means the result has to be
explicitly tagged as having remained the same height or having increased by
one.

The \ihask{ins} function also has a slightly relaxed type in that we always
return a \ihask{Treeish}.
The disjoint sum with \ihask{Either} in this case replaces the existential
quantification of the dependent pair in the Agda implementation.
Of course a disjoint sum can only replace such a dependent pair if the type we
want to quantify over has exactly two elements.
Because this function needs to decide where an element belongs in the
\ihask{Tree} there is an \ihask{Ord} constraint on the type variable
representing the element type:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  ins :: Ord a => a -> Tree c h a
         -> Either (Treeish R h a)
                   (Treeish B h a)
  ins a ET = Left $ RB (RT ET a ET)
  --
  ins a (RT l b r)
    | a < b , Left (RB t) <- ins a l =
      Left $ IR (IRl t b r)
    | a < b , Right (RB t) <- ins a l =
      Left $ RB (RT t b r)
    | a == b = Left $ RB (RT l b r)
    | a > b , Left (RB t) <- ins a r =
      Left $ IR (IRr l b t)
    | a > b , Right (RB t) <- ins a r =
      Left $ RB (RT l b t)
  --
  ins a (BT l b r)
    | a < b , Left (RB t) <- ins a l =
      Right $ RB (BT t b r)
    | a < b , Left (IR t) <- ins a l =
      Left $ RB (balance ((:<:) t b r))
    | a < b , Right (RB t) <- ins a l =
      Right $ RB (BT t b r)
    | a == b = Right $ RB (BT l b r)
    | a > b , Left (RB t) <- ins a r =
      Right $ RB (BT l b t)
    | a > b , Left (IR t) <- ins a r =
      Left $ RB (balance ((:>:) l b t))
    | a > b , Right (RB t) <- ins a r =
      Right $ RB (BT l b t)
\end{minted}

\ihask{ins} makes use of pattern guards \cite{patguard} to unwrap the
\ihask{Tree} or \ihask{IRTree} from the tagged \ihask{Treeish} \ihask{ins} now
invariably returns.
The return type always being a \ihask{Treeish} would be problematic in Agda.
Because Agda is a total language, if a function returns a \iagda{Treeish} and
you want to pattern match on the result, you \emph{have} to provide patterns
that cover each possible value of that type.
In the case of \iagda{ins} this would mean that you'd have to cover infrared
trees as a result of each of the recursive calls even though a call to
\iagda{ins} on a \iagda{Tree} with a black root can never result in an infrared
tree.
What can we return as a result for a case that can not possibly occur?
It doesn't really matter what it is as long as it's a valid value of the return
type of the function.
However, you can't extract the \iagda{Height} from the \iagda{Tree} because
that information is in the type, not the value.
Creating a \iagda{Tree} of the right \iagda{Height} would have to be done
recursively while deconstructing the \iagda{Tree}, which would require an
entire new function just to cover a case that will never occur.
In Agda it clearly makes more sense to restrict the type.
Haskell is a partial language so we don't have to worry about cases we know
will never occur, of course without the totality check we might miss cases that
actually can occur.

The \ihask{insert} function is simpler this time because \ihask{ins} will
always return a \ihask{Treeish}.
The type is the same as for the Agda implementation, glossing over the
\ihask{Ord} constraint and polymorphism.
Again a pattern guard unwraps the intermediate result before passing it on to
\ihask{blacken}:

%----------------------------------------%
\begin{minted}[fontsize=\small]{haskell}
  insert :: Ord a => a -> Tree c h a
            -> Either (Tree B h a)
                      (Tree B (S h) a)
  insert a t
    | Left t' <- ins a t = blacken t'
    | Right t' <- ins a t = blacken t'
\end{minted}

\section{Conclusion}
Dependent types are expressive enough to allow for the specification of complex
properties.
These properties are then statically verified by the type system, thereby
preventing bugs.
Agda because of its design as a fully dependently typed language, allows us to
specify arbitrarily complex properties about our code without much friction.
Haskell on the other hand does allow us to specify interesting properties but
it is clear that the necessary functionality comes from extensions and is not
as neatly accommodated by the language.

\appendices
\section{Agda code \label{app:agda}}
Note that this symbol {\tiny\ensuremath{\hookrightarrow}} is
used to indicate a line that was automatically wrapped to fit the narrow
column format. Do not confuse this symbol with the arrows used to define
function types.
\inputminted[fontsize=\small,breaklines]{agda}{../RedBlackTree.agda}

\section{Haskell code \label{app:haskell}}
\inputminted[fontsize=\small,breaklines]{haskell}{../RedBlackTree.hs}

% use section* for acknowledgement
\section*{Acknowledgment}
I would like to thank my advisors, Jesper Cockx and Dominique Devriese, for
their patient support when writing the code discussed in this paper and their
apt suggestions for improvement of the article itself.
Furthermore I would like to thank professor Frank Piessens as my promotor
without whom I would not have gotten involved in type theory and static
program verification.
Many thanks also to the wonderful people of the \#agda and \#haskell irc
channels on the freenode network who've helped me better understand both
languages.

\bibliographystyle{IEEEtran}
\bibliography{./sciartt}

\end{document}


\documentclass[main.tex]{subfiles}
\begin{document}

\marginpar{Thursday\\ 2021-11-11}

The name ``axion'' comes from a brand of detergent.
%
\begin{align}
\mathscr{L} _{\text{QCD}}
= - \frac{1}{4} G^{a}_{\mu \nu }
G^{a \mu \nu }
+ \sum _{q}
\overline{q} \qty(i \gamma_{\mu } D^{\mu } - \mathcal{M}_q) q
+
\underbrace{\frac{\theta g^2}{32 \pi^2} G^{a}_{\mu \nu }
\widetilde{G}^{a \mu \nu }}_{\text{CP - violating}}
\,.
\end{align}

This term would give an electric dipole moment to the neutron
%
\begin{align}
\abs{d_n} = \frac{e m_u m_d}{(m_u + m_d) m_n^2} \overline{\theta}
\,,
\end{align}
%
where \(\overline{\theta} = \theta + \arg \det \mathcal{M}\), \(\mathcal{M}\) being the quark mass matrix.

The CP-violating term is allowed in the QCD Lagrangian, but we do not experimentally observe it: \(\overline{\theta} < \num{5e-11}\) \cite{chadha-dayAxionDarkMatter2021} (see also \textcite[]{kolbEarlyUniverse1994}).

\begin{extracontent}
The neutron dipole moment is bounded at a \SI{90}{\percent} CL by \(\abs{d_n} < \SI{1.8e-26}{cm}\ e\) \cite{groupReviewParticlePhysics2020} (as opposed to the older value \(\abs{d_n} < \SI{2.9e-26}{cm}\ e\) quoted in the lecture).

Using the PDG values for the quark masses \cite[]{groupReviewParticlePhysics2020}: \(m_u \approx \SI{2.16}{MeV}\), \(m_d \approx \SI{4.67}{MeV}\), and the neutron mass \(m_n \approx \SI{939.57}{MeV}\), we get
%
\begin{align}
\frac{m_u m_d}{(m_u + m_d) m_n^2} \approx \SI{1.67}{MeV^{-1}} \approx \SI{3.30e-17}{cm}
\,.
\end{align}
\end{extracontent}

\todo[inline]{Computing this value does lead to the correct result: it is off by an order of magnitude.
\textcite[]{chadha-dayAxionDarkMatter2021} report \(\abs{d_n} = \num{3.6e-16} \overline{\theta} e \SI{}{cm}\), while this computation yields \num{3.3e-17}!

Computing the ratio between the two, using the formula given in the slides, yields \(\overline{\theta} \leq \num{5e-10}\).}

Why is this CP-violating phase so (``unnaturally'') small?

The Peccei-Quinn mechanism promotes this phase to a dynamical field \(a\), with its own kinetic term \(\partial_{\mu } a \partial^{\mu } a  / 2\),

If we define the dimensionless parameter \(\theta = a / f_a\), this is minimized for \(\theta _{\text{eff}} = \theta + \expval{a} / f_a\).

This field is driven to 0 under the spontaneous breaking of a new global \(U(1)\) symmetry.

If we assume the SM gauge group, the mass of this axion will be on the order of the \SI{}{\micro eV}.

This axion may couple to photons, or to gluons, or to fermions.
The photon coupling would allow for a \(a \to \gamma \gamma \) process.

\section{WIMP-like DM experimental detection}

What may DM couple to?
\begin{enumerate}
    \item nuclear matter (quarks, gluons)?
    \item leptons (electrons, muons, taus, neutrinos)?
    \item photons, or other \(W\), \(Z\), \(h\) bosons?
    \item other dark particles?
\end{enumerate}

We don't know, so we try them all.
We must do it in different contexts, both astrohysical and from particle physics.

Consider the Feynman diagram for a process \(\chi \chi \leftrightarrow q q \), where \(q\) means ``quark'' but it could be substituted for any SM particle.

We can look at it from different angles:
\begin{enumerate}
    \item efficient annihilation: \(\chi \chi \to q q\), so indirect detection (in the sky);
    \item efficient scattering: \(\chi q \to \chi q\) (underground);
    \item efficient production: \(q q \to \chi \chi \) (in particle colliders).
\end{enumerate}

In particle colliders a \(\chi \) may be produced, but it would be among a huge amount of other things.
There, the particle physics people also must do trigger selection, so they may easily miss DM even if they do produce it.

Particle detectors measure the energy of the final state particles with calorimeters, as well as their momentum and trajectory with a tracking detector equipped with a magnetic field.
In detectors such as ATLAS or CMS, neutrinos are indirectly measured by the missing energy.

\begin{extracontent}
The relative uncertainty in the energy measurement of calorimeters is typically proportional to \(1 / \sqrt{E}\), therefore the accuracy is reported as \(\sigma (E) / E = x \SI{}{\percent} / \sqrt{ E / \SI{}{GeV}}\), often shortened to \(\sigma (E) / E = x\SI{}{\percent}/ \sqrt{E}\).
\end{extracontent}

Conservation of energy does not really apply, since the quarks are moving around inside the protons before the collision, while the conservation of transverse momentum can be used.

Search paradigms include:
\begin{enumerate}
    \item mono-X searches: a SM particle recoiling against ``nothing'';
    \item mediator searches: a DM particle acting as a mediator, so it yields a bump in the mass spectrum of SM particle pairs;
    \item Higgs portal: if DM couples to it, a Higgs can decay into DM.
\end{enumerate}

Several model-dependent bounds have been given, most of which are below \SI{1}{TeV}.\footnote{One can find many of these plots at \url{https://twiki.cern.ch/twiki/bin/view/CMSPublic/SummaryPlotsEXO13TeV}.}

Indirect DM searches involve DM particles annihilating into SM particles somewhere in the universe, which we can then detect.
This is a good idea in principle, but many candidates have their own issues.
Photons point to the source, but they lose energy in the ISM if they scatter, and we have a large background of them from astrophysical sources.
Protons and positrons are deviated by magnetic fields therefore we cannot assign them a direction, and we don't accurately know their background level.
Neutrinos have a very small cross-section, and while they do point back to the source their directions are hard to determine; also, there is a large neutrino background.

\paragraph{The inverse problem problem}

It is easy for new data to be modelled as a detection of DM, since we know very little about DM, even if it is actually just background.

\subsection{Direct WIMP-like DM searches}

The idea is to detect the dark matter particle ``bumping into'' something we can see, which is typically a nucleus.

The Solar System is moving through the galaxy, towards the Cygnus constellation.
Therefore, we expect to see an apparent ``wind of DM'' in that direction.

Our signal is WIMPs bumping into nuclei, with recoil velocity \(v/c \sim \num{7e-4}\), and recoil energy \(E_R \sim \SI{10}{keV}\).

Our background is both electromagnetic (photons bumping into nuclei) and neutral (neutrons or neutrinos bumping into nuclei).

The expected rate is
%
\begin{align}
R = N_N \phi_0 \sigma_{WN} = \frac{N_A}{A} \frac{\rho_0 }{m_W} \expval{v} \sigma_{WN}
\,,
\end{align}
%
where \(\rho_0 \approx \SI{.3}{GeV / cm^3}\) is the local DM density, the mean velocity is \(\expval{v} \approx \SI{220}{km/s} \approx \num{.75e-3} c\), but the cross-section is \(\sigma_{WN} \lesssim \SI{e-38}{cm^2}\).

Therefore, we get \(R \sim \num{0.13}\) events per kg per year.

The interaction rate is very low, while backgrounds are very high.

A single banana, on the other hand, yields \(\sim \SI{100}{events/kg/s}\), or about a billion times more.

% \todo[inline]{Calcare is ``limestone''}

Environmental natural radioactivity is a mess.
At LNGS we have more \(\gamma \)s than at Boulby in the UK, because that is a salt mine.

% \todo[inline]{Why is the neutron flux reported as single data points?}

We need to shield the detector from all possible backgrounds.

The chain is \(\alpha \) easier to block then \(\beta \), then \(\gamma \) (where we need steel plates), then finally neutrons (for which we need a water tank).

This is because hydrogen has the best kinematic match: same-mass moderators for neutrons are the best.

Roman lead! the production process makes lead radioactive,
but if it was produced 2000 years ago we are fine.

Another approach is to have active shielding: have detectors which are sensitive to backgrounds around the detector, and then actively remove the background.

\end{document}


% !TeX root = ../wi-screen.tex

\chapter{Preface}

This is an introductory textbook on non-classical logics. Or rather,
it will be when it's done.  Right now it's a work in progress. We will
use it as the main text in our courses on non-classical logic at the
Universities of Victoria and Calgary, respectively, in Fall 2020. It
is based on material from the \href{https://openlogicproject.org}{Open
Logic Project}.

The main text assumes familiarity with some elementary set theory and
the basics of (propositional) logic. The textbook
\href{https://slc.openlogicproject.org}{\emph{Sets, Logic,
Computation}}, is also based on the OLP, provides this background. But
the required material is also included here: the basics of classical
propositional logic in \cref{part:classical}, and the material on set
theory, and some introductory material on proofs and induction, in
\cref{appendices}.


\documentclass[10pt]{beamer}

  % Math Packages
  \usepackage{amsmath}
  \usepackage{amsthm}
  \usepackage{mathtools}

  % Graphics Packages
  \usepackage{graphicx}
  \graphicspath{ {../_static/images/} }
  \usepackage{pgf}
  \usepackage[export]{adjustbox}

  % Code listings
  \usepackage{listings}
  \lstset{language=Python, basicstyle=\footnotesize}

  % Misc packages
  \usepackage{hyperref}
  \hypersetup{colorlinks=true,linkcolor=,urlcolor=blue}

  % Colors
  \definecolor{myblue}{RGB}{25,98,148}
  \definecolor{mygray}{RGB}{66,66,66}

  % Theme Settings
  \usetheme[subsectionpage=progressbar]{metropolis}

  % \setbeamercolor{normal text}{fg=mygray}
  % \setbeamercolor{alerted text}{fg=myblue}
  % \setbeamercolor{title text}{fg=mygray}
  % \setbeamercolor{title separator}{fg=myblue}
  % \setbeamercolor{progress bar}{fg=myblue}
  % \setbeamercolor{frametitle}{bg=myblue}

\title{Writing Python Packages}

\date[]{\today}

\begin{document}

% Title Slide
\begin{frame}
  \titlepage
\end{frame}

% ------------------------- %
% Motivation
% ------------------------- %
\section{``Good'' research}

  \begin{frame} \frametitle{What does good research look like?}

    Good research is:

    \begin{enumerate}
      \item<2-> Accurate: Mitigate potential errors
      \item<3-> Collaborative: Two brains are better than one
      \item<4-> Constructive: Engages with previous research
      \item<5-> Foundational: Provides foundation for others to engage with your work
    \end{enumerate}

    \vspace{0.25cm}

    \textbf{How can we make sure our research reflects these values?}

  \end{frame}

  \begin{frame} \frametitle{Themes of this weekend}

    This weekend we will cover tools that help us achieve these values:

    \begin{itemize}
      \item Code style, code modularity, and package development
      \item Unit and integration testing
      \item Model testing
    \end{itemize}

  \end{frame}

% ------------------------- %
% Code structure and style
% ------------------------- %
\section{Code structure and style}

  \begin{frame} \frametitle{Stylistic Python code}

    \textbf{Coding is a form of communication\dots}

    \vspace{0.5cm}

    \begin{quote}
      Always code as if the guy who ends up maintaining your code will be a violent psychopath who
      knows where you live. Code for readability. --- John Woods
    \end{quote}

    \vspace{0.2cm}

    \begin{quote}
      Measuring programming progress by lines of code is like measuring aircraft building progress
      by weight --- Bill Gates
    \end{quote}

  \end{frame}

  \begin{frame} \frametitle{``Non-negotiable'' stylistic rules}

    These are rules I feel (maybe overly) strongly about,

    \begin{itemize}
      \item A space after EVERY comma... Except when trailing --- \texttt{foo = (0,)}
      \item Avoid wildcard imports (i.e. \texttt{from <module> import *})
      \item Four spaces for block indentation... No more, no less.
      \item Limit lines of code to roughly 80 characters
      \item Try to organize code into logical blocks
      \item No space before or after a colon
    \end{itemize}

  \end{frame}

  \begin{frame} \frametitle{Stylistic choices}

    I feel less strongly about some of these rules, but I find that they improve readability for me

    \begin{itemize}
      \item Two lines before and after a function definition
      \item Don't repeat yourself (DRY)
      \item Don't align your \texttt{=}
    \end{itemize}

  \end{frame}

  \begin{frame}[fragile] \frametitle{Examples of good code}

    {\small
    \begin{lstlisting}{GoodCode}

    import numpy as np
    from scipy.linalg import lstsq

    # Create data
    y = np.array([1.0, 4.0, 3.0, 2.0])
    x = np.array([
        [1.0, 0.5],
        [1.0, 2.0],
        [1.0, 1.5],
        [1.0, 1.0]
    ])

    # Find coefficients
    coeffs, resid, _, _ = lstsq(x, y)

    \end{lstlisting}
    }

  \end{frame}

  \begin{frame}[fragile] \frametitle{Examples of bad code}

    {\small
    \begin{lstlisting}{BadCode}

    import numpy as np
    from scipy.linalg import *
    y                = np.array([1.0, 4.0, 3.0,2.0])
    x                = np.array([[1.0,0.5],[1.0,2.0],[1.0, 1.5],[1.0, 1.0]])
    coeffs,resid,_,_ = lstsq(x,y)

    \end{lstlisting}
    }

  \end{frame}

% ------------------------- %
% Exercise
% ------------------------- %
\section{Motivational exercise!}

  \begin{frame} \frametitle{Exercise: Why write packages?}

    We are going to begin by doing some economics for two reasons:

    \begin{enumerate}
      \item We are economists --- \textbf{How will these tools help us as economists?}
      \item Understanding the costs associated with using low quality code helps
        motivate me to produce high quality code
    \end{enumerate}

  \end{frame}

  \begin{frame} \frametitle{Hendricks Leukhina 2017}

    Our exercise will be to replicate analysis done in \textit{How risky is college
    investment} by Lutz Hendricks and Oksana Leukhina.

    \begin{itemize}
      \item One of the key components of risk to consider when deciding to pursue college
        is ``failure to graduate'' risk
      \item To motivate the credit accumulation component of their structural model, the authors
            propose a simplified model of credit accumulation
      \item We will only replicate a small piece of their paper (Section 2)
    \end{itemize}

  \end{frame}

  \begin{frame} \frametitle{The model}

    Each individual begins as a college freshman with $n_0 = 0$ college credits

    \begin{itemize}
      \item Individual's draw an ability level $a_i \sim N(0, 1)$
      \item An individual's HS GPA is correlated with their ability level,
        $\text{GPA} = a + \varepsilon$ where $\varepsilon \sim N(0, \sigma^2)$
      \item Each year, student attempts 12 courses each worth 3 credits. They pass each
        course with a probability given by $p(a)$
      \item A student graduates if they accumulate 125 credits within 6 years and fail
        to graduate otherwise
    \end{itemize}

  \end{frame}

  \begin{frame} \frametitle{Data}

    The authors use restricted-use microdata from National Center for Education
    Statistics which has college transcript data for each student in the HS\&B survey.

    They ``calibrate'' their model through a simulated method of moments with a target
    of 10 moments:

    \begin{enumerate}
      \item The correlation between credits earned by a student the first two years of
        college
      \item The 10th/20th/\dots/80th/90th quantiles of total credits earned after two
        years
    \end{enumerate}

  \end{frame}

  \begin{frame} \frametitle{Exercise instructions}

    Everyone should clone the
    \href{https://github.com/cc7768/transcripty}{transcripty repository}

    \vspace{0.25cm}

    We will break into 4 groups and each group will receive a group number. There are a
    few constraints that groups should satisfy:

    \begin{itemize}
      \item The person who is ``driving'' should not have been the ``driver'' in the
        previous session
      \item The people who ``drove'' last time should separate themselves amongst the
        groups
      \item The groups should roughly be the same size
    \end{itemize}

  \end{frame}

  \begin{frame} \frametitle{Exercise}

    See \href{https://github.com/nyupredocs/modularizationandtesting/blob/master/Projects/Project_1_HendricksLeukhina.md}{Project 1}

    \vspace{0.25cm}

    We will work on this for 30-45 mins

  \end{frame}

  \begin{frame} \frametitle{Debrief}

    \textbf{How did you find the exercise?}

    \vspace{0.25cm}

    \textbf{Which components of code were helpful?}

    \vspace{0.25cm}

    \textbf{What slowed you down?}

  \end{frame}

% ------------------------- %
% Package development
% ------------------------- %
\section{Package development}

  \begin{frame} \frametitle{Example package: pyblp}

    \begin{center}
      \includegraphics[width=\textwidth]{pyblp_gh_snapshot.png}
    \end{center}

    % Note the beautiful commit message conventions that Jeff uses. See
    % https://www.conventionalcommits.org/en/v1.0.0/
    % for more information and examples

  \end{frame}

  \begin{frame} \frametitle{Package structure}

    {\footnotesize
    Most Python packages share a similar structure:

    \begin{itemize}
      \item \texttt{docs}: This folder contains the files that help generate the documentation.
      \item \texttt{<package\_name>}: This folder contains the package source code and is what will
        be loaded by Python when \texttt{import <package\_name>} is called.
      \item \texttt{tests}: This folder contains the unit and integration tests
      \item \texttt{README.\{md,rst,txt\}}: This is a file that introduces the package and will be
        rendered on the github landing page.
      \item \texttt{LICENSE.txt}: You should not use a package that is not licensed because
        (according to people who know more about the law than I do) your work is under an
        exclusive copyright by default. Useful to read through \url{https://choosealicense.com}
        to learn a bit more about each license. I tend to prefer relatively permissive Apache/BSD/MIT
        licenses as opposed to copyleft licenses like GPL.
      \item Various files used to build and maintain the package. These files include
        \texttt{setup.py}, \texttt{readthedocs.yml}, \texttt{requirements.txt}, etc\dots
    \end{itemize}

    }

  \end{frame}

  \subsection{Package source code}

  \begin{frame} \frametitle{Package source code: structure}

    The package source code is organized into a collection of files and folders. We will
    refer to the folders within the package as ``sub-packages''\footnote{
    Some people get technical and refer to the elements inside of a package as modules,
    sub-modules, and sub-packages, but we're going to try and avoid these details for
    now\dots See
    \href{
    https://stackoverflow.com/questions/7948494/whats-the-difference-between-a-python-module-and-a-python-package
    }{this SO question} if you'd like to know more of the details}.

    \vspace{0.25cm}

    In \texttt{pyblp} there is a class called \texttt{SimulationMarket} in
    \texttt{pyblp/markets/simulation\_market.py}.

    \vspace{0.25cm}

    There are two ways to access this class in your Python code\dots

  \end{frame}

  \begin{frame}[fragile] \frametitle{Package source code: structure}

    First, we could do:

    \vspace{0.5cm}

    \begin{lstlisting}
    import pyblp.markets  # We could create an alias here!

    pyblp.markets.SimulationMarket(args...)
    \end{lstlisting}

  \end{frame}

  \begin{frame}[fragile] \frametitle{Package source code: structure}

    or, we could do:

    \vspace{0.5cm}

    \begin{lstlisting}
    from pyblp.markets import SimulationMarket

    SimulationMarket(args...)
    \end{lstlisting}

  \end{frame}

  \begin{frame} \frametitle{Package source code: \texttt{\_\_init\_\_.py}}

    Your Python package should have an \texttt{\_\_init\_\_.py} file within the main
    source code directory and within each sub-package.

    \vspace{0.25cm}

    This file used to be required in order to identify a directory as a package, but, as
    of Python 3.3, it is no longer a requirement.

    \vspace{0.25cm}

    However, we think it is still a good idea to include this file because it will be run
    whenever the package is imported and can be a good place to initialize relevant
    features or expose particular methods.\footnote{Can find more details in
    \href{http://python-notes.curiousefficiency.org/en/latest/python_concepts/import_traps.html}{this blogpost}
    }

  \end{frame}

  \begin{frame} \frametitle{Package source code: setuptools}

    \onslide<1->{To make your package installable, you need to create a \texttt{setup.py} file which
    uses \href{https://setuptools.readthedocs.io/en/latest/index.html}{the setuptools package}}

    \vspace{0.25cm}

    \onslide<2->{After creating a \texttt{setup.py} file, the package can be installed with
    \texttt{python setup.py install}}

    \vspace{0.25cm}

    \onslide<3->{What's in a \texttt{setup.py} file? Only \texttt{name}, \texttt{version}, and
    \texttt{packages} are required  arguments to \texttt{setup}, but it's useful to add
    include many others}

  \end{frame}

  \subsection{Documentation}

  \begin{frame} \frametitle{Documentation: writing docstrings}

    Documentation is your chance to provide your users (including yourself!) with instructions
    on what each function does and how it should be used.

    \vspace{0.25cm}

    The vast majority of functions should have a doc string.

    \vspace{0.25cm}

    I like to follow the
    \href{https://numpydoc.readthedocs.io/en/latest/format.html}{numpydoc docstring guide},
    but any format you like is fine as long as you're consistent.

  \end{frame}

  \begin{frame}[fragile] \frametitle{Documentation: numpydoc docstring conventions}

    \begin{lstlisting}{numpydoc}
    def myfunction(arg1, arg2):
        """
        This paragraph provides a description of the function.

        Parameters
        ----------
        arg1 : type(arg1)
            Description of arg1
        arg2 : type(arg2)
            Description of arg2

        Returns
        -------
        return_value : type(return_value)
            Description of return value

        See Also
        --------
        other_function : This is a related function
        """
        ...
    \end{lstlisting}

  \end{frame}

  \begin{frame}[fragile] \frametitle{Documentation: sphinx}

    \textbf{Step 1}: Create a folder called \texttt{docs}. Within that folder, run the
    command \texttt{sphinx-quickstart} from a terminal

    \vspace{0.25cm}

    \textbf{Step 2}: Edit \texttt{conf.py}
    \begin{itemize}
      \item Ensure that the first code in the file includes
        \begin{lstlisting}
        import os
        import sys
        sys.path.insert(0, os.path.abspath(".."))
        \end{lstlisting}
        this ensures that your packages will be found.
      \item Add relevant extensions to \texttt{extensions} variable ---
        This includes at least \texttt{sphinx.ext.autodoc} and
        \texttt{sphinx.ext.napoleon}\footnote{The napoleon extension is required for
        sphinx to understand documentation that follows the numpy or google doc
        standards. The autodoc extensions is just to simplify your life.}
    \end{itemize}

  \end{frame}

  \begin{frame} \frametitle{Documentation: sphinx}

     \textbf{Step 3}: Generate documentation from your package by running
     \texttt{sphinx-apidoc -o source/  ../<package\_name>} in a terminal in
     the \texttt{docs} directory --- We could also do this step manually for more control
     on the documentation organization

     \vspace{0.25cm}

     \textbf{Step 4}: Run \texttt{make html} in a terminal from the \texttt{docs}
     directory

     \vspace{0.25cm}

     \textbf{Step 5}: Open \texttt{\_build/html/index.html} in a browser and review the
     (excruciatingly ugly) docs that were generated! Clicking on \textit{Module Index}
     will take you to a page which has the documentation for all of your functions!

  \end{frame}

  \begin{frame} \frametitle{Documentation: sphinx}

    The first step to making the documentation slightly less ugly is to edit the
    \texttt{index.rst} file. It helps to add an introduction to your package at the top
    of the page.

    \vspace{0.25cm}

    You can (and should) also write some instructions for how users could use your
    package\footnote{\texttt{pyblp} has an exceptionally good documentation page\dots
    You should mimic the level of detail included.}.

  \end{frame}

  \begin{frame} \frametitle{Documentation: Read the Docs}

    \textit{Read the Docs}\footnote{Many of the sites on their page can also be accessed with
    \href{https://www.urbandictionary.com/define.php?term=RTFD}{https://rtfd.org}} is a
    site that hosts documentation (and, more importantly, automates documentation
    updates).

    \vspace{0.25cm}

    Many open source projects (especially in the Python world) use \textit{Read the Docs} to host
    their documentation because of its ease of use and flexibility

  \end{frame}

  \begin{frame} \frametitle{Documentation: Read the Docs}

    \textbf{Step 1}: Create an account (I log in with my github account)

    \vspace{0.25cm}

    \textbf{Step 2}: Create a \texttt{readthedocs.yml} file for setting project
    specific configuration --- You won't always need this but it doesn't hurt to have a
    placeholder

    \vspace{0.25cm}

    \textbf{Step 3}: Import your package using their online tool --- Doing this takes
    care of the webhook that will automatically rebuild your docs whenever a push happens
    to the desired branch

  \end{frame}

  \subsection{Publishing Python packages}

  \begin{frame} \frametitle{Python Package Index}

    The \textit{Python Package Index} (PyPI) is ``a repository of software for the Python programming
    language.'' There are over 200,000 projects currently on PyPI

    \vspace{0.3cm}

    Any package on PyPI should be able to be installed with pip\footnote{pip is a recursive
    acronym and stands for \textit{pip installs packages}} by running
    \texttt{pip install <package\_name>}

  \end{frame}

  \begin{frame} \frametitle{Publish package on PyPI}

    \textbf{Step 1}: Install the \texttt{twine} package with \texttt{pip install twine}

    \vspace{0.25cm}

    \textbf{Step 2}: Register on \href{https://pypi.org/account/register/}{PyPI} (and
    \href{https://test.pypi.org/account/register/}{test PyPI}) --- Today we'll upload our
    packages to the test index, but you would typically use the main one

    \vspace{0.25cm}

    \textbf{Step 3}: Create the \textit{distribution package} which is essentially just
    a zipped file with your code using \texttt{python setup.py sdist bdist\_wheel}

  \end{frame}

  \begin{frame} \frametitle{Publish package on PyPI}

    \textbf{Step 4}: Check that the long description will correctly render using
    \texttt{twine check dist/*}

    \vspace{0.25cm}

    \textbf{Optional}: You can create a keyring so that you won't have to type your
    username and password each time you upload a package --- We won't do it today, but
    see the \href{https://github.com/pypa/twine\#keyring-support}{twine documentation}
    for details

    \vspace{0.25cm}

    \textbf{Step 5}: Upload to \texttt{test.pypi.org} using
    \texttt{twine upload --repository-url https://test.pypi.org/legacy dist/*} --- If
    you were uploading to main PyPI, you could simply leave out the
    \texttt{-repository-url} argument

  \end{frame}

% --------------------------------- %
% Exercise: Write your own package
% --------------------------------- %
\section{Exercise: Writing your own package}

\begin{frame} \frametitle{Exercise: Writing your own package}

  Return to your groups from before. You will now be writing your own packages.

  \vspace{0.25cm}

  The instructions for this exercise can be found in
  \href{https://github.com/nyupredocs/modularizationandtesting/blob/master/Projects/Project_2_PackageBuilding.md}{Project 2}.

\end{frame}

\end{document}