\chapter{Methods and testing}

So far we've written programs that have only one method (\java{main}).
In this chapter, we'll show you how to organize programs into multiple methods.
We'll also learn how to trace the order in which a program runs.
Finally, we'll discuss strategies for incrementally developing and testing your code.

%At a conceptual level, a method represents a mathematical {\em function} or a general {\em procedure}.
%Regardless whether they return a value or not, methods enable you to break down a complex program into smaller units of code.

\section{Math methods}

%In the next two sections, we'll take a break from conditions and logic and discuss other areas of mathematics in Java.

\index{Math class}
\index{class!Math}

The Java library includes a \java{Math} class that provides common mathematical operations.
\java{Math} is in the \java{java.lang} package, so you don't have to import it.

%slr: 8-14-19
%\begin{code}
%double root = Math.sqrt(17.0);
%double angle = 1.5;
%double height = Math.sin(angle);
%\end{code}
% height = 130 + 11 * num_lines
\begin{trinket} [210] {UsingMath.java}
public class UsingMath {

    public static void main(String[] args) {
       double root = Math.sqrt(17.0);
       double angle = Math.PI; //radians
       double y = Math.sin(angle);
       System.out.printf("The square root of 17 is %f.\n",root);
       System.out.printf("sin(pi) is %f.", y);
    }
}
\end{trinket}
%slr:  end 8-14-19

The first line sets \java{root} to the square root of 17.
%slr: change to pi
The third line finds the sine of $\pi$ (the value of \java{angle}).

\index{degrees}
\index{radians}
\index{pi}

Values for the trigonometric functions -- \java{sin}, \java{cos}, and \java{tan} -- must be in {\em radians}.
To convert from degrees to radians, you can divide by 180 and multiply by $\pi$.
Conveniently, the \java{Math} class provides a constant double named \java{PI} that contains an approximation of $\pi$:

\begin{code}
double degrees = 90;
double angle = degrees / 180.0 * Math.PI;
\end{code}

Notice that \java{PI} is in capital letters.
Java does not recognize \java{Pi}, \java{pi}, or \java{pie}.
Also, \java{PI} is the name of a variable, not a method, so it doesn't have parentheses.
The same is true for the constant \java{Math.E}, which approximates Euler's number.

Converting to and from radians is a common operation, so the \java{Math} class provides methods that do that for you.

\begin{code}
double radians = Math.toRadians(180.0);
double degrees = Math.toDegrees(Math.PI);
\end{code}

\index{long}
\index{type!long}

Another useful method is \java{round}, which rounds a floating-point value to the nearest integer and returns a \java{long}.
The following result is 63 (rounded up from 62.8319).

\begin{code}
long x = Math.round(Math.PI * 20.0);
\end{code}

A \java{long} is like an \java{int}, but bigger.
More specifically, an \java{int} uses 32 bits of memory; the largest value it can hold is $2^{31}-1$, which is about 2 billion.
A \java{long} uses 64 bits, so the largest value is $2^{63}-1$, which is about 9 quintillion.

Take a minute to read the documentation for these and other methods in the \java{Math} class.
The easiest way to find documentation for Java classes is to do a web search for ``Java'' and the name of the class.

\section{Composition}

\index{expression}
\index{argument}

You have probably learned to evaluate simple expressions like $\sin(\pi/2)$ and $\log(1/x)$.
First, you evaluate the expression in parentheses, which is called the {\bf argument} of the function.
Then you can evaluate the function itself, either by hand or by punching it into a calculator.

This process can be applied repeatedly to evaluate more complex expressions like $\log(1/\sin(\pi/2))$.
First we evaluate the argument of the innermost function ($\pi/2 = 1.57...$), then evaluate the function itself ($\sin(1.57...) = 1.0$), and so on.

\index{composition}
\index{expression}

Just as with mathematical functions, Java methods can be {\bf composed} to solve complex problems.
That means you can use one method as part of another.
In fact, you can use any expression as an argument to a method, as long as the resulting value has the correct type:

\begin{code}
double x = Math.cos(angle + Math.PI / 2.0);
\end{code}

This statement divides \java{Math.PI} by two, adds the result to \java{angle}, and computes the cosine of the sum.
You can also take the result of one method and pass it as an argument to another:

\begin{code}
double x = Math.exp(Math.log(10.0));
\end{code}

In Java, the \java{log} method always uses base $e$.
So this statement finds the log base $e$ of 10, and then raises $e$ to that power.
The result gets assigned to \java{x}.

Some math methods take more than one argument.
For example, \java{Math.pow} takes two arguments and raises the first to the power of the second.
This line computes $2^{10}$ and assigns the value \java{1024.0} to the variable \java{x}:

\begin{code}
double x = Math.pow(2.0, 10.0);
\end{code}

When using \java{Math} methods, beginners often forget the word \java{Math}.
For example, if you just write \java{x = pow(2.0, 10.0)}, you will get a compiler error:

\begin{stdout}
File: Test.java  [line: 5]
Error: cannot find symbol
  symbol:   method pow(double,double)
  location: class Test
\end{stdout}

The message ``cannot find symbol'' is confusing, but the last two lines provide a useful hint.
The compiler is looking for a method named \java{pow} in the file \java{Test.java} (the file for this example).
If you don't specify a class name when referring to a method, the compiler looks in the current class by default.

%slr: 9-14-19
Here is an example progam:
% height = 130 + 11 * num_lines
\begin{trinket} [210] {MethodComposition.java}
public class MethodComposition {

    public static void main(String[] args) {
       double angle = Math.PI; //radians
       double x = Math.cos(angle + Math.PI / 2.0);
       System.out.printf("cos 3 pi / 2 is %f.\n",x);
       System.out.printf("e^(ln(10)) is %f.", Math.exp(Math.log(10.0)));
    }
}
\end{trinket}

\textbf{Section Exercises}
\begin{enumerate}
\item Mess around with the program in the trinket.  Try some other methods from the \java{Math} package, for example \java{Math.pow}.
\end{enumerate}
%slr: end 8-14-19

\section{Defining new methods}
\label{adding_methods}

\index{method!declaration}

%You have probably guessed by now that you can define more than one method in a class.

Some methods perform a computation and return a result.
For example, \java{Math.sqrt(25)} returns the value \java{5.0}.
Other methods (including \java{main}) carry out a sequence of actions, without returning a result.
Java uses the keyword \java{void} to define such methods.
Here's a simple example:

\index{NewLine.java}

\begin{trinket}[240]{NewLine.java}
public class NewLine {

    public static void newLine() {
        System.out.println();
    }

    public static void main(String[] args) {
        System.out.println("First line.");
        newLine(); //method invocation or call
        System.out.println("Second line.");
    }
}
\end{trinket}

\index{main}
\index{case-sensitive}

The name of the class is \java{NewLine}.
By convention, class names begin with a capital letter.
\java{NewLine} contains two methods, \java{newLine} and \java{main}.
Remember that Java is case-sensitive, so \java{NewLine} and \java{newLine} are not the same.

\index{camel case}

Method names should begin with a lowercase letter and use ``camel case'', which is a cute name for \java{jammingWordsTogetherLikeThis}.
You can use any name you want for methods, except \java{main} or any of the Java keywords.

\index{public}
\index{invoke}
\index{void}
\index{type!void}

\java{newLine} and \java{main} are \java{public}, which means they can be {\bf invoked} (or called) from other classes.
%They are both \java{static}, but we won't yet explain what that means.
And they are both \java{void}, which means that they don't return a result (unlike the \java{Math} methods, for example).

The output of this program is:

\begin{stdout}
First line.

Second line.
\end{stdout}

Notice the extra space between the lines.
If we wanted more space between them, we could invoke the same method repeatedly.
Or we could write yet another method (named \java{threeLine}) that displays three blank lines.
%Pulling together the code from the previous section, the complete program looks like this:

In the following program, \java{main} invokes \java{threeLine}, and \java{threeLine} invokes \java{newLine} three times.
%Since \java{newLine} has no parameters, it requires no arguments, as shown when it is invoked in \java{main}.
Because \java{newLine} is in the same class as \java{threeLine}, we don't have to specify the class name like \java{NewLine.newLine()}.

\begin{trinket} [320]{NewLine.java}
public class NewLine {

    public static void newLine() {
        System.out.println();
    }

    public static void threeLine() {
        newLine();
        newLine();
        newLine();
    }

    public static void main(String[] args) {
        System.out.println("First line.");
        threeLine();
        System.out.println("Second line.");
    }
}
\end{trinket}

\section{Flow of execution}

\index{flow of execution}

When you look at a class definition that contains several methods, it is tempting to read it from top to bottom.
But that is {\em not} the {\bf flow of execution}, or the order the program actually runs.
The \java{NewLine} program runs methods in the opposite order than they are listed.

Programs always begin at the first statement of \java{main}, regardless of where it is in the source file.
Statements are executed one at a time, in order, until you reach a method invocation, which you can think of as a detour.
Instead of going to the next statement, you jump to the first line of the invoked method, execute all the statements there, and then come back and pick up exactly where you left off.

That sounds simple enough, but remember that one method can invoke another one.
In the middle of \java{main}, the previous example goes off to execute the statements in \java{threeLine}.
While in \java{threeLine}, it goes off to execute \java{newLine}.
Then \java{newLine} invokes \java{println}, which causes yet another detour.

Fortunately, Java is good at keeping track of which methods are running.
So when \java{println} completes, it picks up where it left off in \java{newLine}; when \java{newLine} completes, it goes back to \java{threeLine}; and when \java{threeLine} completes, it gets back to \java{main}.

%In summary, when you read a program, don't read from top to bottom.
%Instead, follow the flow of execution.

%Technically, the program does not terminate at the end of \java{main}.
%Instead, execution picks up where it left off in the program that invoked \java{main}, which is the Java interpreter.
%The interpreter takes care of things like deleting windows and general cleanup, and {\em then} the program terminates.

Beginners often wonder why it's worth the trouble to write other methods, when they could just do everything in \java{main}.
The \java{NewLine} example demonstrates a few reasons:

\begin{itemize}

\item Creating a new method allows you to {\em name a block of statements}, which makes the code easier to read and understand.
%Methods simplify a program by hiding complex computations behind a single statement, and by using English words in place of arcane code.
%Which is clearer, \java{newLine} or \java{System.out.println()}?

\item Introducing new methods can {\em make the program shorter} by eliminating repetitive code.
For example, to display nine consecutive newlines, you could invoke \java{threeLine} three times.

\item A common problem-solving technique is to {\em break problems down} into sub-problems.
Methods allow you to focus on each sub-problem in isolation, and then compose them into a complete solution.

\end{itemize}

Perhaps most importantly, organizing your code into multiple methods allows you to test individual parts of your program separately.
It's easier to get a complex program working if you know that each method works correctly.

%slr:  8-14-19
\textbf{Section Exercises}
\begin{enumerate}
\item In the second version of NewLine, does the order in which the methods appear matter?  Try changing the order around and see what happens.
\item Change the program to produce nine blank lines by invoking (i.e. calling) the method \java{threeLine()} three times.
\end{enumerate}
%slr: end 8-14-19

\section{Parameters and arguments}

Some of the methods we have used require arguments, which are the values you provide in parentheses when you invoke the method.

For example, the \java{Math.sin} method takes a \java{double} argument.
To find the sine of a number, you have to provide the number: \java{Math.sin(0.0)}.
Similarly, the \java{System.out.println} method takes a \java{String} argument.
To display a message, you have to provide the message: \java{System.out.println("Hello")}.

\index{parameter}
\index{argument}

When you invoke a method, you provide the arguments.
When you define a method, you declare the {\bf parameters}, which are variables that indicate what arguments are required.
The following class shows an example:

\index{PrintTwice.java}

\begin{trinket}[255]{PrintTwice.java}
public class PrintTwice {

    //printTwice declares one paramenter
    public static void printTwice(String s) {
        System.out.println(s);
        System.out.println(s);
    }

    public static void main(String[] args) {
    	//the call to printTwice provides a String argument
        printTwice("Don't make me say this twice!");
    }
}
\end{trinket}

The \java{printTwice} method has a parameter named \java{s} with type \java{String}.
When you invoke \java{printTwice}, you have to provide an argument with type \java{String}.

%\java{main} has a single parameter, called \java{args}, which has type \java{String[]}.
%That means that whoever invokes \java{main} must provide an array of strings (we'll get to arrays in a later chapter).

Before the method executes, the argument gets assigned to the parameter.
In this example, the argument \java{"Don't make me say this twice!"} gets assigned to the parameter \java{s}.

\index{parameter passing}

This process is called {\bf parameter passing} because the value gets passed from outside the method to the inside.
An argument can be any kind of expression, so if you have a \java{String} variable, you can use its value as an argument:

\begin{code}
String message = "Never say never.";
printTwice(message);
\end{code}

The value you provide as an argument must have the same (or compatible) type as the parameter.
For example, if you try:

\begin{code}
printTwice(17);  // syntax error
\end{code}

You will get an error message like this:

\begin{stdout}
File: Test.java  [line: 10]
Error: method printTwice in class Test cannot be applied
       to given types;
  required: java.lang.String
  found: int
  reason: actual argument int cannot be converted to
          java.lang.String by method invocation conversion
\end{stdout}

Sometimes Java can convert an argument from one type to another automatically.
For example, \java{Math.sqrt} requires a \java{double}, but if you invoke \java{Math.sqrt(25)}, the integer value \java{25} is automatically converted to the floating-point value \java{25.0}.
But in the case of \java{printTwice}, Java can't (or won't) convert the integer \java{17} to a \java{String}.

\index{local variable}
\index{variable!local}

Parameters and other variables only exist inside their own methods.
Inside \java{main}, there is no such thing as \java{s}.
If you try to use it there, you'll get a compiler error.
Similarly, inside \java{printTwice} there is no such thing as \java{message}.
That variable belongs to \java{main}.
Because variables only exist inside the methods where they are defined, they are often called {\bf local variables} and are said to have {\bf local scope}.

%\section{Multiple parameters}

\index{parameter!multiple}
\index{method!parameters}

Here is an example of a method that takes two parameters:

\begin{code}
public static void printTime(int hour, int minute) {
    System.out.print(hour);
    System.out.print(":");
    System.out.println(minute);
}
\end{code}

In the parameter list, it may be tempting to write:

\begin{code}
public static void printTime(int hour, minute) {  // error
\end{code}

But that format (without the second \java{int}) is only allowed for local variables.
For parameters, you need to declare the type of each variable separately.

To invoke this method, we have to provide two integers as arguments:

\begin{code}
int hour = 11;
int minute = 59;
printTime(hour, minute);
\end{code}

Beginners sometimes make the mistake of ``declaring'' the arguments:

\begin{code}
int hour = 11;
int minute = 59;
printTime(int hour, int minute);  // syntax error
\end{code}

That's a syntax error, because the compiler sees \java{int hour} and \java{int minute} as variable declarations, not expressions.
You wouldn't declare the types of the arguments if they were simply integers:

\begin{code}
printTime(int 11, int 59);  // syntax error
\end{code}

Pulling together the code fragments, here is the complete program:

\index{PrintTime.java}

\begin{trinket}[270]{PrintTime.java}
public class PrintTime {

    public static void printTime(int hour, int minute) {
        System.out.print(hour);
        System.out.print(":");
        System.out.println(minute);
    }

    public static void main(String[] args) {
        int hour = 11;
        int minute = 59;
        printTime(hour, minute);
    }
}
\end{trinket}

%slr:  8-14-19
\textbf{Section Exercises}
\begin{enumerate}
\item Try calling the method \java{printTime()} more than once with different arguments.
\item Call \java{printTime()} with literal arguments (i.e. arguments that are constants).
\item Call \java{printTime()} passing as arguments the expressions \java{hour + 3} and \java{minute - 30}.
\end{enumerate}
%slr: end 8-14-19

\section{Stack diagrams}
\label{stack}

\java{printTime} has two parameters, named \java{hour} and \java{minute}.
And \java{main} has two variables, also named \java{hour} and \java{minute}.
Although they have the same names, these variables are not the same.
The \java{hour} in \java{printTime} and the \java{hour} in \java{main} refer to different memory locations, and they can have different values.
For example, you could invoke \java{printTime} like this:

\begin{code}
int hour = 11;
int minute = 59;
printTime(hour + 1, 0);
\end{code}

Before the method is invoked, Java evaluates the arguments; in this example, the results are \java{12} and \java{0}.
Then it assigns those values to the parameters.
Inside \java{printTime}, the value of \java{hour} is \java{12}, not \java{11}, and the value of \java{minute} is \java{0}, not \java{59}.
Furthermore, if \java{printTime} modifies one of its parameters, that change has no effect on the variables in \java{main}.

\index{stack diagram}
\index{diagram!stack}
\index{frame}

One way to keep track of everything is to draw a {\bf stack diagram}, which is a memory diagram (see Section~\ref{state}) that shows currently running methods.
For each method there is a box called a {\bf frame} that contains the method's parameters and local variables.
The name of the method appears outside the frame; the variables and parameters appear inside.

\begin{figure}[!ht]
\begin{center}
%slr: 12-18-19 original statement: \includegraphics[height=15em]{figs/stack1.pdf}
\includegraphics{figs/stack1.pdf}
\caption{Stack diagram for \java{printTime(hour + 1, 0)}.}
\label{fig.stack}
\end{center}
\end{figure}

As with memory diagrams, stack diagrams show variables and methods at a particular point in time.
Figure~\ref{fig.stack} is a stack diagram at the beginning of the \java{printTime} method.
Notice that \java{main} is on top, because it executed first.

%\index{scope}

%Stack diagrams help you to visualize the {\bf scope} of a variable, which is the area of a program where a variable exists.

\index{Java Tutor}
\index{tracing}

Stack diagrams are a good mental model for how variables and methods work at run-time.
Learning to trace the execution of a program on paper (or on a whiteboard) is a useful skill for communicating with other programmers.

There are educational tools that automatically draw stack diagrams for you.
For example, Java Tutor (\url{http://pythontutor.com/java.html}) allows you to step through an entire program, both forwards and backwards, and see the stack frames and variables at each step.
If you haven't already, you should check out the Java examples on that website.

%Or you can use a ``debugger'', like the one that comes with DrJava (see Appendix~\ref{debugger}).
%These tools also allow you to visualize the flow of execution.

\section{Return values}

\index{void}

When you invoke a \java{void} method, the invocation is usually on a line all by itself.
For example:

\begin{code}
printTime(hour + 1, 0);
\end{code}

On the other hand, when you invoke a value-returning method, you have to do something with the return value.
%slr:  8-14-19
%We usually assign it to a variable or use it as part of an expression, like this:
%
%\begin{code}
%double error = Math.abs(expect - actual);
%double height = radius * Math.sin(angle);
%\end{code}
Here is the program we looked at earlier in the chapter which calls methods in the /java{Math} class:
% height = 130 + 11 * num_lines
\begin{trinket} [220] {UsingMath.java}
public class UsingMath {

    public static void main(String[] args) {
       double root = Math.sqrt(17.0);
       double angle = Math.PI; //radians
       double y = Math.sin(angle);
       System.out.printf("The square root of 17 is %f.\n",root);
       System.out.printf("sin(pi) is %f.", y);
    }
}
\end{trinket}
%slr:  end 8-14-19

Here we see that, for example, the method \java{Math.sqrt} is a value-returning method and the program has to a assign it to a variable or use it as part of an expression.

\index{value method}
\index{method!value}

Compared to \java{void} methods, value-returning methods differ in two ways:

\index{return type}
\index{return value}

\begin{itemize}

\item They declare the type of the return value (the {\bf return type});

\item They use at least one \java{return} statement to provide a {\bf return value}.

\end{itemize}

Here's an example from a program named {\tt Circle.java}.
The \java{calculateArea} method takes a \java{double} as a parameter and returns the area of a circle with that radius (i.e., $\pi r^2$).

%slr:  8-14-19
%\begin{code}
%public static double calculateArea(double radius) {
%    double result = Math.PI * radius * radius;
%    return result;
%}
%\end{code}

% height = 130 + 11 * num_lines
\begin{trinket} [270] {Circle.java}
public class Circle {

    public static double calculateArea(double radius) {
        double result = Math.PI * radius * radius;
        return result;
    }

    public static void main(String[] args) {
       double diameter = 10.0;
       double area = calculateArea(diameter/2);
       System.out.printf("A circle of radius %f has an area of %f.", diameter/2, area);
    }
}
\end{trinket}
%slr: end 8-14-19

As usual, this method is \java{public} and \java{static}.
But in the place where we are used to seeing \java{void}, we see \java{double}, which means that the return value from this method is a \java{double}.

\index{return}
\index{statement!return}

The last line is a new form of the \java{return} statement that means, ``return immediately from this method, and use the following expression as the return value.''
The expression you provide can be arbitrarily complex, so we could have written this method more concisely:

\begin{code}
public static double calculateArea(double radius) {
    return Math.PI * radius * radius;
}
\end{code}

\index{temporary variable}
\index{variable!temporary}

On the other hand, {\bf temporary variables} like \java{result} often make debugging easier, especially when you are stepping through code using an interactive debugger (see Appendix~\ref{debugger}).

Figure~\ref{fig.param} illustrates how data values flows through the program.
When the \java{main} method invokes \java{calculateArea}, the value \java{5.0} is assigned to the parameter \java{radius}.
\java{calculateArea} then returns the value \java{78.54}, which is assigned to the variable \java{area}.
%Note that you don't ``pass variables'' as arguments and return values -- you copy their values.

\begin{figure}[!ht]
\begin{center}
\includegraphics{figs/param.pdf}
\caption{Passing a parameter and saving the return value.}
\label{fig.param}
\end{center}
\end{figure}

The type of the expression in the \java{return} statement must match the return type of the method itself.
When you declare that the return type is \java{double}, you are making a promise that this method will eventually produce a \java{double} value.
If you try to \java{return} with no expression, or \java{return} an expression with the wrong type, the compiler will give an error.

\section{Incremental development}
\label{distance}

\index{incremental development}
\index{design process}

People often make the mistake of writing a lot of code before they try to compile and run it.
Then they spend way too much time debugging.
A better approach is what we call {\bf incremental development}.
The key aspects of incremental development are:

\begin{itemize}

\item Start with a working program and make small, incremental changes.
At any point, if there is an error, you will know where to look.

\item Use variables to hold intermediate values so you can check them, either with print statements or by using a debugger.

\item Once the program is working, you can consolidate multiple statements into compound expressions (but only if it does not make the program more difficult to read).

\end{itemize}

As an example, suppose you want to find the distance between two points, given by the coordinates $(x_1, y_1)$ and $(x_2, y_2)$.
By the usual definition:

\[ distance = \sqrt{(x_2 - x_1)^2 +(y_2 - y_1)^2} \]

The first step is to consider what a \java{distance} method should look like in Java.
In other words, what are the inputs (parameters) and what is the output (return value)?
For this method, the parameters are the two points, and it is natural to represent them using four \java{double} values.
%, although we will see later that there is a \java{Point} object in Java that we could use.
The return value is the distance, which should also have type \java{double}.

\index{stub}

Already we can write an outline for the method, which is sometimes called a {\bf stub}.
The stub includes the method declaration and a \java{return} statement:

\begin{code}
public static double distance
        (double x1, double y1, double x2, double y2) {
    return 0.0;  // stub
}
\end{code}

The return statement is a placeholder that is only necessary for the program to compile.
At this stage the program doesn't do anything useful, but it is good to compile it so we can find any syntax errors before we add more code.

\index{testing}

It's usually a good idea to think about testing {\em before} you develop new methods; doing so can help you figure out how to implement them.
To test the method, we can invoke it from \java{main} using the sample values:

\begin{code}
double dist = distance(1.0, 2.0, 4.0, 6.0);
\end{code}

With these values, the horizontal distance is 3.0 and the vertical distance is 4.0.
So the result should be 5.0, the hypotenuse of a 3-4-5 triangle.
When you are testing a method, it is necessary to know the right answer.

Once we have compiled the stub, we can start adding code one line at a time.
After each incremental change, we recompile and run the program.
If there is an error, we have a good idea where to look: the lines we just added.

The next step is to find the differences $x_2 - x_1$ and $y_2 - y_1$.
We store those values in temporary variables named \java{dx} and \java{dy}, so that we can examine them with print statements before proceeding.
They should be 3.0 and 4.0.

\begin{code}
public static double distance
        (double x1, double y1, double x2, double y2) {
    double dx = x2 - x1;
    double dy = y2 - y1;
    System.out.println("dx is " + dx);
    System.out.println("dy is " + dy);
    return 0.0;  // stub
}
\end{code}

\index{scaffolding}

We will remove the print statements when the method is finished.
Code like that is called {\bf scaffolding}, because it is helpful for building the program, but it is not part of the final product.

The next step is to square \java{dx} and \java{dy}.
We could use the \java{Math.pow} method, but it is simpler (and more efficient) to multiply each term by itself.

\begin{code}
public static double distance
        (double x1, double y1, double x2, double y2) {
    double dx = x2 - x1;
    double dy = y2 - y1;
    double dsquared = dx * dx + dy * dy;
    System.out.println("dsquared is " + dsquared);
    return 0.0;  // stub
}
\end{code}

Again, you should compile and run the program at this stage and check the intermediate value, which should be 25.0.
Finally, we can use \java{Math.sqrt} to compute and return the result.

\begin{code}
public static double distance
        (double x1, double y1, double x2, double y2) {
    double dx = x2 - x1;
    double dy = y2 - y1;
    double dsquared = dx * dx + dy * dy;
    double result = Math.sqrt(dsquared);
    return result;
}
\end{code}

%In \java{main}, we can print and check the value of the result.

As you gain more experience programming, you might write and debug more than one line at a time.
%Nevertheless, incremental development can save you a lot of time debugging.
But by using incremental development, scaffolding, and testing, your code is more likely to be correct the first time.

\section{Vocabulary}

\begin{description}

% Note: expanded definition from Chapter 1
%\term{method}
%A named sequence of statements that performs a procedure or function.
%Methods may or may not take parameters, and may or may not return a value.

%\term{void}
%A special return type indicating the method does not return a value.

\term{argument}
A value that you provide when you call a method.
This value must have the type that the method expects.

\term{composition}
The ability to combine simple expressions and statements into compound expressions and statements.

\term{invoke}
To cause a method to execute.
Also known as ``calling'' a method.

\term{flow of execution}
The order in which Java executes methods and statements.
It may not necessarily be from top to bottom in the source file.

\term{parameter}
A piece of information that a method requires before it can run.
Parameters are variables: they contain values and have types.

\term{parameter passing}
The process of assigning an argument value to a parameter variable.

\term{local variable}
A variable declared inside a method.
Local variables cannot be accessed from outside their method.

\term{stack diagram}
A graphical representation of the variables belonging to each method.
The method calls are ``stacked'' from top to bottom, in the flow of execution.

\term{frame}
In a stack diagram, a representation of the variables and parameters for a method, along with their current values.

%\term{scope}
%The area of a program where a variable exists.

\term{return type}
The type of value a method returns.

\term{return value}
The value provided as the result of a method invocation.

\term{temporary variable}
A short-lived variable, often used for debugging.

\term{incremental development}
A process for creating programs by writing a few lines at a time, compiling, and testing.

\term{stub}
A placeholder for an incomplete method so that the class will compile.

\term{scaffolding}
Code that is used during program development but is not part of the final version.

\end{description}

\section{Exercises}

The code for this chapter is in the {\tt ch04} directory of {\tt ThinkJavaCode2}.
See page~\pageref{code} for instructions on how to download the repository.
Before you start the exercises, we recommend that you compile and run the examples.

If you have not already read Appendix~\ref{cltesting}, now might be a good time.
It describes an efficient way to test programs that take input from the user and display specific output.

\begin{exercise}  %%V6 Ex4.3

The purpose of this exercise is to take code from a previous exercise and redesign it as a method that takes parameters.
You should start with a working solution to Exercise~\ref{ex:date}.

\begin{enumerate}

\item Write a method called \java{printAmerican} that takes the day, date, month and year as parameters and that displays them in American format.

\item Test your method by invoking it from \java{main} and passing appropriate arguments.
The output should look something like this (except that the date might be different):

\begin{stdout}
Saturday, July 22, 2015
\end{stdout}

\item Once you have debugged \java{printAmerican}, write another method called \java{printEuropean} that displays the date in European format.

\end{enumerate}

\end{exercise}

\begin{exercise}  %%V6 Ex5.6

This exercise reviews the flow of execution through a program with multiple methods.
Read the following code and answer the questions.

\begin{code}
public static void main(String[] args) {
    zippo("rattle", 13);
}
\end{code}

\begin{code}
public static void baffle(String blimp) {
    System.out.println(blimp);
    zippo("ping", -5);
}
\end{code}

\begin{code}
public static void zippo(String quince, int flag) {
    if (flag < 0) {
        System.out.println(quince + " zoop");
    } else {
        System.out.println("ik");
        baffle(quince);
        System.out.println("boo-wa-ha-ha");
    }
}
\end{code}

\begin{enumerate}

\item Write the number {\tt 1} next to the first line of code in this program that will execute.

\item Write the number {\tt 2} next to the second line of code, and so on until the end of the program.
If a line is executed more than once, it might end up with more than one number next to it.

\item What is the value of the parameter \java{blimp} when \java{baffle} gets invoked?

\item What is the output of this program?

\end{enumerate}

\end{exercise}

\begin{exercise}  %%V6 Ex4.1

%The point of this exercise is to practice reading code and to make sure that you understand the flow of execution through a program with multiple methods.
Answer the following questions without running the program on a computer.

\begin{enumerate}

\item Draw a stack diagram that shows the state of the program the first time \java{ping} is invoked.

\item What is output by the following program?
Be precise about where there are spaces and where there are newlines.

%{\it Hint:} Start by describing in words what \java{ping} and \java{baffle} output.

%\item What happens if you invoke \java{baffle();} at the end of the \java{ping} method? (We will see why in Section~\ref{recursion}.)

\end{enumerate}

\begin{code}
public static void zoop() {
    baffle();
    System.out.print("You wugga ");
    baffle();
}
\end{code}

\begin{code}
public static void main(String[] args) {
    System.out.print("No, I ");
    zoop();
    System.out.print("I ");
    baffle();
}
\end{code}

\begin{code}
public static void baffle() {
    System.out.print("wug");
    ping();
}
\end{code}

\begin{code}
public static void ping() {
    System.out.println(".");
}
\end{code}

\end{exercise}

\begin{exercise}  %%V6 Ex6.1

If you have a question about whether something is legal, and what happens if it is not, a good way to find out is to ask the compiler.
Answer the following questions by trying them out.

\begin{enumerate}

\item What happens if you invoke a value method and don't do anything with the result; that is, if you don't assign it to a variable or use it as part of a larger expression?

\item What happens if you use a void method as part of an expression?
For example, try \java{System.out.println("boo!") + 7;}

\end{enumerate}

\end{exercise}

\begin{exercise}  %%V6 Ex5.2

Draw a stack diagram that shows the state of the program the {\it second} time \java{zoop} is invoked.
What is the complete output?

\begin{code}
public static void zoop(String fred, int bob) {
    System.out.println(fred);
    if (bob == 5) {
        ping("not ");
    } else {
        System.out.println("!");
    }
}
\end{code}

\begin{code}
public static void main(String[] args) {
    int bizz = 5;
    int buzz = 2;
    zoop("just for", bizz);
    clink(2 * buzz);
}
\end{code}

\begin{code}
public static void clink(int fork) {
    System.out.print("It's ");
    zoop("breakfast ", fork);
}
\end{code}

\begin{code}
public static void ping(String strangStrung) {
    System.out.println("any " + strangStrung + "more ");
}
\end{code}

\end{exercise}

\begin{exercise}  %%V6 Ex6.4

Many computations can be expressed more concisely using the ``multadd'' operation, which takes three operands and computes \java{a * b + c}.
Some processors even provide a hardware implementation of this operation for floating-point numbers.

\begin{enumerate}

\item Create a new program called {\tt Multadd.java}.

\item Write a method called \java{multadd} that takes three \java{doubles} as parameters and that returns \java{a * b + c}.

\item Write a \java{main} method that tests \java{multadd} by invoking it with a few simple parameters, like \java{1.0, 2.0, 3.0}.

\item Also in \java{main}, use \java{multadd} to compute the following values:
%
\begin{eqnarray*}
& \sin \frac{\pi}{4} + \frac{\cos \frac{\pi}{4}}{2} & \\
& \log 10 + \log 20 &
\end{eqnarray*}

\item Write a method called \java{expSum} that takes a double as a parameter and that uses \java{multadd} to calculate:
%
\begin{eqnarray*}
x e^{-x} + \sqrt{1 - e^{-x}}
\end{eqnarray*}
%
{\it Hint:} The method for raising $e$ to a power is \java{Math.exp}.

\end{enumerate}

In the last part of this exercise, you need to write a method that invokes another method you wrote.
Whenever you do that, it is a good idea to test the first method carefully before working on the second.
Otherwise, you might find yourself debugging two methods at the same time, which can be difficult.

One of the purposes of this exercise is to practice pattern-matching: the ability to recognize a specific problem as an instance of a general category of problems.

\end{exercise}


\chapter{Drag}

The very first computers were created to do calculations of how
artillery would fly when shot at different angles. The calculations
were similar to the ones you just did for the flying
hammer with two important differences:
\begin{itemize}
\item They were interested in two dimensions: the height and the distance across the ground.
\item Artillery flies a lot faster, so they had to worry about drag from the air.
\end{itemize}

\section{Wind resistance}

The first thing they did was put one of the shells in a wind tunnel.
They measured how much force was created when they pushed 1 m/s of
wind over the shell. Let's say it was 0.1 newtons.

One of the interesting things about the drag from the air (often
called \newterm{wind resistance}) is that it increases with the
\emph{square} of the speed. Thus, if the wind pushing on the shell is
3 m/s, instead of 1 m/s, the resistance is $3^2 \times 0.1 = 0.9$
newtons.

(Why? Intuitively, three times as many air molecules are hitting the
shell and each molecule is hitting it three times harder.)

So, if a shell is moving with the velocity vector $v$, the force
vector of the drag points in the exact opposite direction. If $\mu$ is
the force of wind resistance of the shell at 1 m/s, then the magnitude
of the drag vector is $\mu |v|^2$.

\section{Initial velocity and acceleration due to gravity}

Let's say a shell is shot out of a tube at $s$ m/s, and let's say the tube
is tilted $\theta$ radians above level.  Then, the initial velocity
will be given by the vector $[s \cos(\theta), s \sin(\theta)]$

(The velocity of the shell is actually a 3-dimensional vector, but we
are only going to worry about height and horizontal distance; we are
assuming that the operator pointed it in the right direction.)

To figure out the path of the shell, we need to compute its acceleration. We remember that

$$F = m a$$

(Note that $F$ and $a$ are vectors.)  Dividing both sides by $m$ we get:

$$a = \frac{F}{m}$$

So let's figure out the net force on the shell so that we can calculate the acceleration vector.

If the shell has a mass of $b$, the force due to gravity will be in the
downward direction with a magnitude of $9.8 b$ newtons.

To get the net force, we will need to add the force due to gravity
with the force due to wind resistance.

\section{Simulating artillery in Python}

Create a file called \filename{artillery.py}.

\begin{Verbatim}
    import numpy as np
    import matplotlib.pyplot as plt

    # Constants
    mass = 45 # kg
    start_speed = 300.0 # m/s
    theta = np.pi/5 # radians (36 degrees above level)
    time_step = 0.01 # s
    wind_resistance = 0.05 # newtons in 1 m/s wind
    force_of_gravity = np.array([0.0, -9.8 * mass]) # newtons

    # Initial state
    position = np.array([0.0, 0.0]) # [distance, height] in meters
    velocity = np.array([start_speed * np.cos(theta), start_speed * np.sin(theta)])
    time = 0.0 # seconds

    # Lists to gather data
    distances = []
    heights = []
    times = []

    # While shell is aloft
    while position[1] >= 0:
        # Record data
        distances.append(position[0])
        heights.append(position[1])
        times.append(time)

        # Calculate the next state
        time += time_step
        position += time_step * velocity

        # Calculate the net force vector
        force = force_of_gravity - wind_resistance * velocity**2

        # Calculate the current acceleration vector
        acceleration = force / mass

        # Update the velocity vector
        velocity += time_step * acceleration

    print(f"Hit the ground {position[0]:.2f} meters away at {time:.2f} seconds.")

    # Plot the data
    fig, ax = plt.subplots()
    ax.plot(distances, heights)
    ax.set_title("Distance vs. Height")
    ax.set_xlabel("Distance (m)")
    ax.set_ylabel("Height (m)")
    plt.show()
\end{Verbatim}

When you run it, you should get a message like:
\begin{Verbatim}
Hit the ground 1696.70 meters away at 20.73 seconds.
\end{Verbatim}

You should also see a plot of the shell's path:

\includegraphics[width=0.8\textwidth]{artillery.png}

\section{Terminal velocity}

If you shot the shell very, very high in the sky, it would keep accelerating
toward the ground until the force of gravity and the force of the wind resistance were equal.
The speed at which this happens is called the \newterm{terminal velocity}.  The terminal velocity of a
falling human is about 53 m/s.

\begin{Exercise}[title={Terminal velocity}, label=terminal_velocity]
    What is the terminal velocity of shell described in our example?
\end{Exercise}
\begin{Answer}[ref=terminal_velocity]
The force of gravity is $9.8 \times 45 = 441$ newtons.

At any speed $s$, the force of wind resistance is $0.05 \times s^2 = 0.05 s^2$ newtons.

At terminal velocity, $0.05 s^2 = 441$.

Solving for $s$, we get $s = \sqrt{\frac{441}{0.05}}$

Thus, terminal velocity should be about 94 m/s.

\end{Answer}


\subsection{Motivation for axioms for propositional logic}

We discussed in the previous section the ability to derive new tautologies from others using substitution and Modus Ponens.

We now aim to identify a group of axioms from which all tautologies can be derived.

\subsection{The axioms}

The first is known as "Simplification". In words, this is "if it is cloudy, then if it is a Tuesday it is also cloudy."

\(\theta \rightarrow (\gamma \rightarrow \theta )\)

The second is called "Frege".

\((\alpha \rightarrow (\beta \rightarrow \gamma ))\rightarrow ((\alpha \rightarrow \beta )\rightarrow(\alpha \rightarrow \gamma ))\)

The third is "Transposition". Consider the statement "If there are no clouds in the sky, it is not raining." If this is true then it is also true that "If it is raining there are clouds in the sky."

\((\neg \theta \rightarrow \neg \gamma )\rightarrow (\gamma \rightarrow \theta )\)

\subsection{Independence of axioms}

These axioms are independent. That is, if you take one away, you cannot derive it from the others.

These axioms are also effective. One could define all true formulae as axioms, however this is not effective.

\subsection{Soundness of axioms}

Soundness implies that all theories are true.

\(T\vdash A \Rightarrow T\vDash A \)

These axioms and the deduction rule are sound. We know that the axioms are tautologies, and we know that the inference rule is valid.

As the axioms are sound, the theories are consistent. That is, it is not possible for both \(\theta \) and \(\neg \theta \) to be theories.

\subsection{Completeness of axioms}

Completeness implies that all true formulae are theories.

\(T\vDash A \Rightarrow T\vdash A\)

\subsection{Axioms and definitions}

A definition is a conservative extension of the language. A definition statement, for example that a new symbol \(Z\) is always evaluated as false allows us to make additional statements, but it does not allow us to make additional statements in the original language.

An axiom allows us to generate additional statements in the original language, a definition does not.


\subsection{The Ideal Gas Law and Definining Temperature}
Possibly the most important equation you'll encounter in thermodynamics is the ideal gas law. It states that
\begin{equation}
    \label{eqn:(4)}
    PV=Nk_{b}T
\end{equation}
where $P$ is the pressure of the gas (in Pascals), $V$ the volume (in $m^3$), $N$ the number of molecules of gas, $T$ the temperature (in \textbf{Kelvin})\footnote{Just as a refresher, x Kelvin = x-273 Celsius, and 0 Kelvin is absolute zero.}, and $k_b$ is Boltzmann's constant ($1.381 \times 10^{-23} \textrm{ m}^2 \textrm{ kg} \textrm{ s}^{-2} \textrm{ K}^{-1}$). We can consider this relationship as this as an empirical result; essentially, it is the combination of three simple gas laws that were determined experimentally. First, we had Boyle's Law, which tells us that for fixed temperature $T$ and amount of gas $N$, the pressure $P$ is inversely proportional to the volume $V$:
\begin{equation}
    P \propto \frac{1}{V}
\end{equation}
We then have Charles' Law, which tells us that for fixed pressure $P$ and amount of gas $N$, the volume $V$ is directly proportional to the temperature $T$:
\begin{equation}
    V \propto T
\end{equation}
Finally, we have Avogadro's Law, which tells us that for constant temperature $T$ and constant pressure $P$, The volume of gas $V$ is directly proportional to the amount $N$:
\begin{equation}
    V \propto N
\end{equation}
I will leave it to you to show that combining these three leads to the ideal gas law as we have stated it!\footnote{You can fairly easily show that this version of the gas law is equivalent to $PV=nRT$, the version you might be more familiar with; see the questions section!} \\
\noindent
Now, with everything we need in place, let's finally define temperature microscopically. Substituting equation \ref{eqn:(2)} from the previous section:
\begin{align*}
    \frac{3}{2}PV=N\epsilon_{kavg}
\end{align*}
And substituting in the ideal gas law, we get:
\begin{align*}
    \frac{3}{2}Nk_bT = N\epsilon_{kavg}
\end{align*}
Cancelling the $N$s and rearranging for the temperature $T$, we obtain:
\begin{equation}
    \label{eqn:(8)}
    T = \frac{2}{3k_b}\epsilon_{kavg}
\end{equation}
which seems like a good definition of temperature! What it essentially tells us is that the faster particles are moving in a gas on average, the hotter it is (although heavy particles can make up the difference, as mass also plays into kinetic energy).\\
\noindent
The final thing I should definitely mention is the long list of assumptions that equations \ref{eqn:(2)} and \ref{eqn:(4)} make. They are, in no particular order:
\begin{enumerate}
    \item A gas is made up of point-like particles of identical mass.
    \item The particles in a gas only interact via collisions.
    \item All collisions of particles in a gas are elastic.
\end{enumerate}
The above three conditions are what it means for a gas to be ideal. For those of you who followed along with the derivation of equation \ref{eqn:(2)}, you might recognize why these assumptions were necessary to make. \\
You might be tempted to ask; if equations \ref{eqn:(2)} and \ref{eqn:(4)} only hold for ideal gases, then does our new definition of temperature only hold for ideal gases as well? Actually, no! Even though the derivation we did for it used formulas that only applies to ideal gases, it turns out that the definition holds for \textbf{all} gases.


\section{Classifying projected simplexes}
\label{sec:classifying}

%-----------------------------------------------------------------

The convex hull of a $(d-1)$ dimensional projection of a $d$-simplex
is either a $(d-1)$-simplex or a $(d-1)$ dimensional cross polytope.

\begin{Lemma}
\label{rambau-lemma}
Any set $Z$ of $(d+2)$ points whose convex hull is of dimension $d$
has exactly two triangulations denoted $T_{Z^+}$ and $T_{Z^-}$.
\end{Lemma}

See Rambau~\cite[Lemma~1.1.2]{rambau-jorg-1996}.

Let $S=(\p_0, \p_1 \ldots  \p_m)$ be an $m$-simplex in $\Reals^{n}$.
Let $\pi$ be a projection from $\Reals^{n}$ to $Q$, an $(m-1)$-dimensional
affine subspace of $\Reals^{n}$.
Assume $\pi$ is chosen so that the points
$\{\pi \p_0, \pi \p_1 \ldots  \pi \p_m\}$ are in {\it general position},
that is, any $l+1$ of the projected points spans an $l$-dimensional
affine subspace of $Q$.

By Lemma \ref{rambau-lemma},
there are two exactly triangulations of the convex hull of the projected points.
The $(m-1)$-simplexes of the triangulations are images of the $(m-1)$-simplexes of $S$,
and two triangulations correspond to a partition of $(m-1)$-simplexes of $S$
into two subsets, the "top" and "bottom" of $S$ with respect to $\pi$.

To see why this is true, and to further classify the triangulations,
consider the fact that the boundary of the convex hull of $\pi S$
must contain either $m$ or $m+1$ of the $\pi \p_i$.
(Any fewer and the points cannot be in general position.)

\begin{Theorem}
\label{one-simplex-case}
If the boundary of the convex hull of $\pi S$
contains $m$ of the $\pi \p_i$,
then it is a $(m-1)$-simplex
and the image of one of the $(m-1)$-simplexes, $F$, in $S$.
The first triangulation is just $\pi F$.
The second triangulation consists of the images of
all the remaining $(m-1)$-simplexes of $S$.
The second triangulation is itself the mutual refinement of both.
\end{Theorem}

The first 2 statements are obvious.
If we label the vertices so that $\{\pi \p_1 \ldots  \pi \p_m\}$
are on the boundary, and $\pi \p_0$ is in the interior,
then the second triangulation results from refining the first
triangulation {\it pulling}
\cite{lee-hdcg-2004} the vertex $\pi \p_0$.
The faces of the triangulation formed by pulling
are the images of the $m$ $(m-1)$-simplexes
of $S$ that contain $\p_0$, that is, all the $(m-1)$-simplexes in $S$,
other than $(\p_1 \ldots  \pi \p_m)$.

\begin{Theorem}
\label{two-simplex-case}
If the boundary of the convex hull of $\pi S$
contains all $m+1$ of the $\pi \p_i$,
then it is the image of 2 of the $(m-1)$-simplexes in $S$,
which share a common $(m-2)$-simplex.
These 2 simplexes are the first triangulation.
The second triangulation consists of the images
of the remaining $m-1$ $(m-1)$-simplexes of $S$,
which share a common $1$-simplex.
The mutual refinement is formed by splitting either
the shared $(m-2)$-simplex in the first triangulation
or the shared $1$-simplex in the second.
\end{Theorem}


\section{Examples}
\label{sec:examples}

In this section we look at several small examples which demonstrate
various points of RZ. For a serious case study from computable
mathematics see the implementation of real numbers with
RZ by Bauer and Kavkler~\cite{bauer07:_implem_rz}.

The main theme is that constructively reasonable axioms yield
computationally reasonable operations.

\subsection{Decidable sets}
\label{sec:decidable-sets}

A set $S$ is said to be decidable when, for all $x, y \in S$, $x = y$
or $\lnot (x = y)$. In classical mathematics all sets are decidable,
\iflong
because decidability of equality is just an instance of the law of
excluded middle.  But
\else
but
\fi % \iflong
RZ requires an axiom
%
\begin{source}
Parameter s : Set.
Axiom eq: \iForall x y : s, x = y \iOr \iNot (x = y).
\end{source}
%
to produce a realizer for equality
%
\begin{source}
val eq : s \iTo s \iTo [`or0 | `or1]
assertion eq : \iForall (x:\iT{s}, y:\iT{s}), (match eq x y with
                                           `or0 \iImply x \iPer{s} y
                                         | `or1 \iImply \iNot (x \iPer{s} y) )
\end{source}
%
We read this as follows: $\f{eq}$ is a function which takes
arguments~$\f{x}$ and~$\f{y}$ of type~$\f{s}$ and returns
$\mathtt{`or0}$ or $\mathtt{`or1}$. If it returns $\mathtt{`or0}$,
then $\oper{\f{s}}{\f{x}}{\f{y}}$, and if it returns
$\mathtt{`or1}$, then $\onot{(\oper{\f{s}}{\f{x}}{\f{y}})}$. In
other words $\f{eq}$ is a decision procedure%
\iflong\
which tells when
values~$\f{x}$ and~$\f{y}$ represent the same element of the modest
set.
\else % \iflong
.
\fi % \iflong

\iflong
\subsection{Examples with obligations}
\label{sec:exampl-with-oblig}

In this section we show how RZ produces obligations, is sometimes able
to optimize them away, and show the effect of hoisting.

Consider how we might define division of real numbers. Assuming the
set of real numbers~$\f{real}$, constants $\f{zero}$ and $\f{one}$, and
multiplication operation~$\f{*}$ have already been declared and
axiomatized, we might write:
%
\begin{source}
Definition nonZeroReal := \{x : real | \iNot (x = zero)\}.
Parameter inv : nonZeroReal \iTo real.
Axiom inverse : \iForall x : real, \iNot (x = zero) -> x * (inv x) = one.
Definition (/) (x : real) (y : nonZeroReal) := x * (inv y).
\end{source}
%
We have defined the set of non-zero reals $\f{nonZeroReal}$ and
the inverse operation~$\f{inv}$ on it. Division $\f{x/y}$ is defined
as $\f{x * inv\; y}$. This does \emph{not} mean that the
programmer must necessarily implement division this way, only that the
implementation of $\f{x/y}$ must be equivalent to $\f{x * inv\;y}$.

In the axiom $\f{inverse}$, RZ encounters the subexpression
$\f{inv \;x}$. Because $\f{x}$ is quantified as an element of
$\f{real}$ rather than $\f{nonZeroReal}$, the typechecking
phase inserts a coercion that makes the expression well-typed.
Translation sees $\f{inv}(\f{x} \mathbin{{:}}
\f{nonZeroReal})$ instead of $\f{inv\ x}$ and translates this to
%
\begin{source}
inv (assure u:unit, \iNot (x \iPer{real} zero) in (x, u))
\end{source}
%
If this were the final output, the programmer would have to verify
that~$\f{x}$ is not zero, and provide a trivial realizer for it. However,
in this case the thinning phase first removes the trivial realizer,
%
\iflong
\begin{source}
inv (assure \iNot (x \iPer{real} zero) in x)
\end{source}
\fi % \iflong
%
and then the optimizer determines that the obligation is not needed
because the whole expression appears under the hypothesis that~$\f{x}$ is
not zero. So in the end the programmer sees
%
\begin{source}
assertion inverse :
  \iForall (x:\iT{real}),  \iNot (x \iPer{real} zero) \iTo (x * inv x) \iPer{real} one
\end{source}
%
Assuming further that a strict linear order $<$ on~$\f{real}$ has
been axiomatized, we might proceed by relating it to $\f{inv}$:
%
\begin{source}
Axiom inv_positive: \iForall x : real, zero < x \iTo zero < inv x.
\end{source}
%
Once again $\f{inv\;x}$ appears in the input, but this time the
optimizer is unable to remove the obligation, so the output is
%
\begin{source}
assertion inv_positive: \iForall (x:\iT{real}),
   zero < x \iTo zero < inv (assure (not (x \iPer{real} zero)) in x)
\end{source}
%
Local obligations can sometimes be hard to read, but if we activate the hoisting phase
(see Section~\ref{sec:implementation}), the obligation can be moved
to the top level. As this is done, the hypotheses under which the
obligation appears are collected, and we get
%
\begin{source}
assertion inv_positive:
  assure (\iForall (x:\iT{real}),  zero < x \iTo not (x \iPer{real} zero))
    in \iForall (x:\iT{real}),  zero < x \iTo zero < inv x
\end{source}
%
Now it is easier to understand what must be checked, namely that
positive reals are not zero---an easy consequence of irreflexivity
of~$<$, but not something that the RZ optimizer is aware of.

Lastly, we could define the golden ratio as the positive solution of
$x^2 = x + 1$,
%
\begin{source}
the x : real, (zero < x \iAnd x*x = x + one)
\end{source}
%
Not surprisingly, RZ cannot determine that there is a unique such~$\f{x}$,
so it outputs an obligation:
%
\begin{source}
assure x:real,
  (x : \iT{real} \iAnd zero < x \iAnd x * x =real= x + one \iAnd
    (\iForall (x':\iT{real}),  zero < x' \iAnd x' * x' \iPer{real} x' + one \iTo x \iPer{real} x'))
  in x
\end{source}
\fi % \iflong

\iflong
\subsection{Finite sets}
\label{sec:finite-sets}

\begin{figure}[b]
\begin{source}
Definition Semilattice :=
thy
  Parameter s : Set.
  Parameter zero : s.
  Parameter join : s \iTo s \iTo s.
  Implicit Type x y z : s.
  Axiom commutative: \iForall x y,   join x y = join y x.
  Axiom associative: \iForall x y z, join (join x y) z = join x (join y z).
  Axiom idempotent:  \iForall x,     join x x = x.
  Axiom neutral:     \iForall x,     join x zero = x.
end.
\end{source}
\caption{The theory of a semilattice}
\label{fig:semilattice}
\end{figure}

\iflong
There are many characterizations of finite sets, but the one that
works best constructively is due to Kuratowski, who identified the
finite subsets of~$A$ as the least family~$K(A)$ of subsets of~$A$
that contains the empty set and is closed under unions with
singletons. This characterization relies on powersets, which are not
available in RZ. But the gist of it, namely that $K(A)$ is an
\emph{initial} structure a suitable sort, can be expressed as follows.

\else
%
The family $K(A)$ of finite subsets of a set~$A$ may be characterized
as the free $\vee$-semilattice generated by~$A$.
%
\fi
%
Recall that a \emph{$\vee$-semilattice} is a set~$S$ with a
constant~$0 \in S$ and an associative, commutative, and idempotent
operation ``join'' $\vee$ on~$S$ such that $0$ is the neutral element
for~$\vee$, see Figure~\ref{fig:semilattice} for RZ axiomatization of
semilattices.
%
The Kuratowski finite sets~$K(A)$ are the \emph{free} semilattice
generated by a set~$A$, where $\vee$ is union and $0$ is the empty
set. This is formalized in RZ as shown in Figure~\ref{fig:kuratowski}.
%
\begin{figure}
\begin{source}
Definition K (A : thy
                    Parameter a : Set.
                  end) :=
thy
  include Semilattice.
  Parameter singleton : A.a \iTo s.
  Definition fin := s.
  Definition emptyset := zero.
  Definition union := join.

  Axiom free :
    \iForall S : Semilattice, \iForall f : A.a \iTo S.s,
    \iExistsOne g : fin \iTo S.s,
      g emptyset = S.zero \iAnd
        (\iForall x : A.a, f x = g (singleton x)) \iAnd
        (\iForall u v : fin, g (union u v) = S.join (g u) (g v)).
end.
\end{source}
  \caption{Kuratowski finite sets}
  \label{fig:kuratowski}
\end{figure}
%
The theory $\f{K}$ is parameterized by a model~$\f{A}$ which contains a
set~$\f{a}$. In the first line we include the theory of semilattices.
Then we postulate an operation $\f{singleton}$ which injects the
generators into the semilattice. The three definitions are just a
convenience, so that we can refer to the parts of $\f{K(A)}$ by their
natural names, e.g., $\f{emptyset}$ instead of $\f{zero}$. The axiom
$\f{free}$ expresses the fact that $\f{K}(\f{A})$ is the free
semilattice on~$\f{A.a}$: for every semilattice $\f{S}$ and a map
$\f{f} : \f{A.a} \to \f{S.s}$ from the generators to the underlying
set of~$\f{S}$, there exists a unique semilattice homomorphism $\f{g}
: \f{fin} \to \f{S.s}$ such that $\f{f}(\f{x}) = \f{g}(\f{singleton\;
  x})$.

The output for $\f{Semilattice}$ and~$\f{K}$ specifies
values of suitable types for each declared constant and operation. All
axioms but the last one are equations and have straightforward
translations in terms of underlying pers. The output for the axiom
$\f{free}$ is shown in Figure~\ref{fig:free}.
%
\begin{figure}
  \centering
\begin{source}
module Free : functor (S : Semilattice) \iTo
sig
  val free : (A.a \iTo S.s) \iTo fin \iTo S.s
  assertion free :
    \iForall (f:\iT{A.a \iTo S.s}), let g = free f in
      g : \iT{fin \iTo S.s} \iAnd g emptyset \iPer{S.s} S.zero \iAnd
      (\iForall (x:\iT{A.a}),  f x \iPer{S.s} g (singleton x)) \iAnd
      (\iForall (u:\iT{fin}, v:\iT{fin}), g (union u v) \iPer{S.s} S.join (g u) (g v)) \iAnd
      (\iForall h:fin \iTo S.s,  h : \iT{fin \iTo S.s} \iAnd h emptyset \iPer{S.s} S.zero \iAnd
         (\iForall (x:\iT{A.a}), f x \iPer{S.s} h (singleton x)) \iAnd
         (\iForall (u:\iT{fin}, v:\iT{fin}), h (union u v) \iPer{S.s} S.join (h u) (h v)) \iTo
         \iForall x:fin, y:fin,  x \iPer{fin} y \iTo g x \iPer{S.s} h y)
end
\end{source}
  \caption{Output of axiom $\texttt{free}$.}
  \label{fig:free}
\end{figure}
%
Because the axiom quantifies over all models~$\f{S}$ of the theory
$\f{Semilattice}$ its translation is a functor~$\f{Free}$ which
accepts an implementation of a semilattice~$S$ and yields a realizer
$\f{free}$ validating the axiom. The computational meaning of
$\f{free}$ is a combination map and fold operation, taking a map
$\f{f} : \f{A.a} \to \f{S.s}$ and a finite set~$\f{u} = \set{x_1,
  \ldots, x_n}$, and return $\f{f}(x_1) \vee \cdots \vee \f{f}(x_n)$,
where $\vee$ is the join operation on the semilattice~$S$.

Applying phase-splitting to this axiom yields the even simpler
specification
%
\begin{equation*}
\mathtt{val}\ \f{free} : \alpha \to (\alpha \to \alpha \to \alpha) \to (\f{A.a}\to\alpha) \to \f{fin} \to \alpha
\end{equation*}
%
(with an appropriate assertion)
which replaces the module parameter \texttt{S} by two extra term arguments (corresponding to the module components \texttt{S.zero} and \texttt{S.join})
and a type argument $\alpha$ for the type of lattice elements (corresponding to the module input \texttt{S.s}).  This is even
more recognizable as a folding operation over the set.

It is important to note that, in contrast to \texttt{fold} operators found in typical functional
languages, \texttt{free} is only expected to work for suitable \texttt{join} arguments (e.g., idempotent and order independent).  These
sets are not the typical finite-set data structure: there is no membership predicate, nor
is there a way to compute the size of a set.  There is no
assumption that equality is decidable for set elements; this permits
finite sets of  exact real numbers, for example.  Decidable equality
is required both for membership and for detecting
whether the same element has been added twice to the same set\footnote{The natural implementation would thus
be an unordered collection of elements, possibly with duplicates.}.

Some operations are nevertheless computable.  Using \texttt{free} carefully, one
can determine whether a finite set is empty.  In the case of a set of exact
real numbers, we cannot compute the sum of a set (since there might
be duplicate elements), but we could compute maximum or minimum.

More common set implementations (e.g., the \texttt{Set} module in the OCaml standard library)
implement sets over values with decidable total order; these could also be
formalized in RZ.
\fi % \iflong

\subsection{Inductive types}
\label{sec:inductive-types}

To demonstrate the use of dependent types we show how RZ handles
general inductive types, also known as W-types or general
trees~\cite{nordstroem90:_progr_martin_type_theor}. Recall that a
W-type is a set of well-founded trees, where the branching types of
trees are described by a family of sets $B = \set{T(x)}_{x \in S}$.
Each node in a tree has a \emph{branching type}~$x \in S$, which
determines that the successors of the node are labeled by the elements
of~$T(x)$.
%
\iflong
%
For example, to get non-empty binary trees whose leaves are
labeled by natural numbers, define
%
\begin{align*}
  S &= \set{\f{cons}} \cup \set{\f{leaf}(n) \such n \in \NN}
  \\
  T(\f{cons}) &= \set{\f{left}, \f{right}}
  \\
  T(\f{leaf}(n)) &= \emptyset.
\end{align*}
%
Then a node of type $\f{cons}$ has two successors, indexed by
constants $\f{left}$ and $\f{right}$, while a node of type
$\f{leaf}(n)$ does not have any successors.
\par
%
\fi % iflong
%
Figure~\ref{fig:wtype} shows an RZ axiomatization of W-types.
%
\begin{figure}
\begin{source}
Definition Branching :=
thy
  Parameter s : Set.      (* branching types *)
  Parameter t : s -> Set. (* branch labels *)
end.

Parameter W : [B : Branching] \iTo
thy
  Parameter w : Set.
  Parameter tree : [x : B.s] \iTo (B.t x \iTo w) \iTo w.
  Axiom induction:
    \iForall M : thy Parameter p : w \iTo Prop. end,
    (\iForall x : B.s, \iForall f : B.t x \iTo w,
       ((\iForall y : B.t x, M.p (f y)) \iTo M.p (tree x f))) \iTo
    \iForall t : w, M.p t.
end.
\end{source}
\vspace{-0.5cm}
  \caption{General inductive types}
  \label{fig:wtype}
\end{figure}
%
The theory $\f{Branching}$ describes that a branching type
consists of a set~$\f{s}$ and a set~$\f{t}$ depending on~$\f{s}$. The theory~$\f{W}$ is
parameterized by a branching type~$\f{B}$. It specifies a set~$\f{w}$ of
well-founded trees and a tree-forming operation $\f{tree}$ with a
dependent type $\Pi_{\f{x} \in \f{B.s}} (\f{B.t(x)} \to \f{w}) \to \f{w}$.
%
\iflong
%
Given a
branching type~$\f{x}$ and a map $\f{f} : \f{B.t(x)} \to \f{w}$, $\f{tree}\;\f{x}\;\f{f}$
is the tree whose root has branching type~$\f{x}$ and whose successor
labeled by $\ell \in \f{B.t}(\f{x})$ is the tree~$\f{f}(\ell)$.
%
\fi
%
The inductive nature of~$\f{w}$ is expressed with the axiom
$\f{induction}$, which states that for every property $\f{M.p}$, if $\f{M.p}$
is an inductive property then every tree satisfies it. A property is
said to be \emph{inductive} if a tree $\f{tree}\;\f{x}\;\f{f}$ satisfies it
whenever all its successors satisfy it.

\iflong
In the translation (see Appendix~\ref{sec:outp-induct-types} for the
complete output) dependencies at the level of types and terms disappear.
\else
In the translation dependencies at the level of types and terms disappear.
\fi
%
A branching type is determined by a pair of non-dependent types~$\f{s}$
and~$\f{t}$ but the per $\per_{\f{t}}$ depends on~$\values{\f{s}}$. The theory~$\f{W}$
turns into a signature for a functor receiving a branching type~$\f{B}$
and returning a type~$\f{w}$, and an operation $\f{tree}$ of type
$\f{B.s} \to (\f{B.t} \to \f{w}) \to \f{w}$.  One can use phase-splitting
to translate axiom
$\f{induction}$ into a specification of a polymorphic function
%
\begin{equation*}
  \f{induction:
  (B.s \to (B.t \to w) \to (B.t \to {\alpha}) \to {\alpha}) \to w \to {\alpha}},
\end{equation*}
%
which is a form of recursion on well-founded trees. Instead of explaining $\f{induction}$, we show a surprisingly simple,
hand-written implementation of W-types in OCaml. The reader may enjoy figuring out how it works:
%
\sourcefile{wtype.ml}

\subsection{Axiom of choice}
\label{sec:axiom-choice}

RZ can help explain why a generally
accepted axiom is not constructively valid. Consider the Axiom of
Choice:
%
\begin{source}
Parameter a b : Set.
Parameter r : a \iTo b \iTo Prop.
Axiom ac: (\iForall x : a, \iExists y : b, r x y) \iTo
             (\iExists c : a \iTo b, \iForall x : a, r x (c x)).
\end{source}
%
The relevant part of the output is
%
\begin{source}
val ac : (a \iTo b * ty_r) \iTo (a \iTo b) * (a \iTo ty_r)
assertion ac :
  \iForall f:a \iTo b * ty_r,
    (\iForall (x:\iT{a}),  let (p,q) = f x in p : \iT{b} \iAnd r x p q) \iTo
    let (g,h) = ac f in
      g : \iT{a \iTo b} \iAnd (\iForall (x:\iT{a}),  r x (g x) (h x))
\end{source}
%
This requires a function $\f{ac}$ which accepts a function $\f{f}$
and computes a pair of functions $\f{(g,h)}$. The input function~$\f{f}$ takes
an $\ototal{\f{x}}{\f{a}}$ and returns a pair $\f{(p,q)}$ such that $\f{q}$ realizes
the fact that $\f{r\;x\;p}$ holds. The output functions $\f{g}$ and $\f{h}$ taking
$\ototal{\f{x}}{\f{a}}$ as input must be such that $\f{h\;x}$ realizes
$\f{r\;x\;(g\;x)}$. Crucially, the requirement $\ototal{\f{g}}{\oarrow{\f{a}}{\f{b}}}$
says that $\f{g}$ must be extensional, i.e., map equivalent realizers to
equivalent realizers. We could define~$\f{h}$ as the second component
of~$\f{f}$, but we cannot hope to implement~$\f{g}$ in general because the
first component of~$\f{f}$ is not assumed to be extensional.

The \emph{Intensional} Axiom of Choice allows the choice function to
depend on the realizers:
%
\begin{source}
Axiom iac: (\iForall x : a, \iExists y : b, r x y) \iTo
           (\iExists c : rz a \iTo b, \iForall x : rz a, r (rz x) (c x)).
\end{source}
%
Now the output is
%
\begin{source}
val iac : (a \iTo b * ty_r) \iTo (a \iTo b) * (a \iTo ty_r)
assertion iac :
  \iForall f:a \iTo b * ty_r,
    (\iForall (x:\iT{a}),  let (p,q) = f x in p : \iT{b} \iAnd r x p q) \iTo
    let (g,h) = iac f in
      (\iForall x:a, x : \iT{a} \iTo g x : \iT{b}) \iAnd (\iForall (x:\iT{a}),  r x (g x) (h x))
\end{source}
%
This is exactly the same as before \emph{except} the
troublesome requirement
\iflong $\ototal{\f{g}}{\oarrow{\f{a}}{\f{b}}}$
\fi
was weakened to
$\oforall{\f{x}}{\f{a}}{(\oimply{\ototal{\f{x}}{\f{a}}}{\ototal{\f{g\;x}}{\f{b}}})}$. We can implement $\f{iac}$ in OCaml as
%
\begin{source}
let iac f = (fun x -> fst (f x)), (fun x -> snd (f x))
\end{source}
%
The Intensional Axiom of Choice is in fact just an instance of the
usual Axiom of Choice applied to~$\irz{A}$ and~$B$. Combined with the
fact that~$\irz{A}$ covers~$A$, this establishes the validity of
\emph{Presentation Axiom}~\cite{barwise75:_admis_sets_struc}, which
states that every set is an image of one satisfying the axiom of
choice.

\subsection{Modulus of Continuity}
\label{sec:we-show-modulus-of-continuity-example}

As a last example we show how certain constructive principles require
the use of computational effects. To keep the example short, we
presume that we are already given the set of natural
numbers~$\f{nat}$ with the usual structure.

A \emph{type 2 functional} is a map $f : (\f{nat} \to \f{nat}) \to
\f{nat}$. It is said to be continuous if the output of $f(a)$ depends
only on an initial segment of the sequence~$a$. We can express the
(non-classical) axiom that all type~2 functionals are continuous in RZ
as follows:
%
\begin{source}
Axiom continuity: \iForall f : (nat \iTo nat) \iTo nat, \iForall a : nat \iTo nat,
  \iExists k, \iForall b : nat \iTo nat, (\iForall m, m \iLeq k \iTo a m = b m) \iTo f a = f b.
\end{source}
\goodbreak

The axiom says that for any $\f{f}$ and $\f{a}$ there exists $\f{k} \in
\f{nat}$ such that $\f{f(b) = f(a)}$ when sequences~$\f{a}$
and~$\f{b}$ agree on the first $\f{k}$ terms. It translate to:
%
\begin{source}
val continuity : ((nat \iTo nat) \iTo nat) \iTo (nat \iTo nat) \iTo nat
assertion continuity :
  \iForall (f:\iT{(nat \iTo nat) \iTo nat}, a:\iT{nat \iTo nat}),
    let p = continuity f a in p : \iT{nat} \iAnd
    (\iForall (b:\iT{nat \iTo nat}),
       (\iForall (m:\iT{nat}),  m \iLeq p \iTo a m \iPer{nat} b m) \iTo f a \iPer{nat} f b)
\end{source}
%
i.e., that $\f{continuity\;f\;a}$ is a number~$\f{p}$ such that
$\f{f(a) = f(b)}$ whenever $\f{a}$ and $\f{b}$ agree on the first~$\f{p}$ terms. In
other words, $\f{continuity}$ is a \emph{modulus of continuity}
functional. It cannot be implemented in a purely functional
language,\footnote{There are models of $\lambda$-calculus which validate
  the choice principle~$AC_{2,0}$, but this contradicts the
  existence of a modulus of continuity functional,
  see~\cite[9.6.10]{Troelstra:van-Dalen:88:2}.} but with the use of
store we can implement it in OCaml as
%
\begin{source}
let continuity f a = let p = ref 0 in
                     let a' n = (p := max !p n; a n) in
                       f a' ; !p
\end{source}
%
To compute a modulus for~$\f{f}$ at~$\f{a}$, the program creates a
function~$\f{a'}$ which is just like~$\f{a}$ except that it stores in~$\f{p}$ the
largest argument at which it has been called. Then $\f{f\;a'}$ is
computed, its value is discarded, and the value of~$\f{p}$ is returned.
The program works because~$\f{f}$ is assumed to be extensional and
therefore must not distinguish between extensionally equal sequences~$\f{a}$
and~$\f{a'}$.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "cie"
%%% End:


\documentclass[11pt,a4paper]{article}

% These are extra packages that you might need for writing the equations:
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{outlines}
\usepackage{mathtools}

\lstset {language=C++,
		 basicstyle=\ttfamily,
         keywordstyle=\color{blue}\ttfamily,
         stringstyle=\color{red}\ttfamily,
         commentstyle=\color{purple}\ttfamily,
         morecomment=[l][\color{magenta}]{\#},
       	 basicstyle=\tiny}

% You need the following package in order to include figures in your report:
\usepackage{graphicx}

% With this package you can set the size of the margins manually:
\usepackage[left=2cm,right=2cm,top=2cm,bottom=2cm]{geometry}

\renewcommand{\vec}[1]{\mathbf{#1}}
\newcommand{\norm}[1]{\left\lVert#1\right\rVert}

\begin{document}

% Enter the exercise number, your name and date here:
\noindent\parbox{\linewidth}{
 \parbox{.25\linewidth}{ \large ICP, Exercise 11 }\hfill
 \parbox{.5\linewidth}{\begin{center} \large Beat Hubmann \end{center}}\hfill
 \parbox{.2\linewidth}{\begin{flushright} \large Dec 07, 2018 \end{flushright}}
}
\noindent\rule{\linewidth}{2pt}

\section{Introduction}

The Jacobi relaxation method and the Gauss-Seidel method were implemented to solve
the discretized Poisson equation in two dimensions for point charges in a grounded box.
The two methods were compared with each other in terms of time to solution and number of iterations required.
Also, the time to solution was compared to a high performance library Cholesky solver.

\section{Algorithm Description}

For all cases, the two-dimensional Poisson equation(equation~\ref{eqn:1}) on $\Omega$ is
discretized using second-order central finite differences in both the x- and the y-direction (equation~\ref{eqn:2}).
Both axes share a common grid spacing of $\Delta x= \frac{1}{N+1}$ where $N$ is the number of interior points
per axis direction on the grid.
Following the established finite difference method procedure to employ natural ordering, the left-hand side of equation~\ref{eqn:2} then can be written
in form of an $N*N \times N*N$ matrix $\vec{A}$ while the values of $\phi$ on the grid get unrolled into a vector $\vec{b}$ of size $N*N$ on the right-hand side (equation~\ref{eqn:3}).\\
The resulting matrix $A$ is both sparse and block tridiagonal.

\begin{equation}
\Delta \Phi = -\phi \quad \text{on}\ \Omega = (0, 1) \times (0,1)
\label{eqn:1}
\end{equation}

\begin{equation}
4x_{i,j} - x_{i-1, j} - x_{x+1, j} - x_{i, j-1} - x_{i, j+1} = -(\Delta x)^2 \cdot \rho(x_{i,j})
\label{eqn:2}
\end{equation}

\begin{equation}
Ax = b
\label{eqn:3}
\end{equation}

\subsection{Jacobi relaxation method}
In matrix form, the Jacobi method works by decomposing the matrix $\vec{A}$ into a matrix $\vec{D}$ consisting only of $\vec{A}$'s main diagonal
and a remainder matrix $\vec{R} = \vec{A} - \vec{D}$. Starting with an initial guess for $\vec{x} = (1, 1, \ldots, 1)^{\text{T}}$, we iterate $\vec{x}^{(t+1)} = \vec{D}^{-1}(\vec{b}- \vec{R}\vec{x}^{(t)})$
until $\norm{\vec{x}^{(t+1)} - \vec{x}^{(t)}}$ becomes smaller than a chosen convergence treshold in a chosen norm.

\subsection{Gauss-Seidel method}
Similar to the Jacobi relaxation method, the matrix $\vec{A}$ is decomposed into a lower triagonal matrix $\vec{L}$ and a strictly upper triagonal matrix $\vec{U}$ such that
$\vec{A} = \vec{L} + \vec{U}$. Completely analogous to the Jacobi relaxation method, the iteration step is  $\vec{x}^{(t+1)} = \vec{L}^{-1}(\vec{b}- \vec{U}\vec{x}^{(t)})$.

\section{Results}

The program was implemented as described above and submitted with this report. \\
Both methods reached the set conversion treshold of $\norm{\vec{x}^{(t+1)} - \vec{x}^{(t)}}_{2} \le 10^{-4}$. \\
The Jacobi relaxation method took $t=3478$ iterations but on average only $\sim 45 \text{ms}$ to do so, while the Gauss-Seidel method
only took $t=1922$ iterations but $\sim 6400 \text{ms}$ to reach the same treshold. For comparison, Eigen's optimized library Cholesky method
solver obtained the reference solution in $9 \text{ms}$.\\
Both methods' solutions reached similar deviation from the reference Cholesky solution:\\
$\norm{\vec{x}^*_{\text{Jacobi}} - \vec{x}^*_{\text{Cholesky}}}_{2} \approxeq  \norm{\vec{x}^*_{\text{Gauss-Seidel}} - \vec{x}^*_{\text{Cholesky}}}_{2} \approxeq 0.05$.
The heat maps for all three solvers are shown in figures~\ref{fig:1}, \ref{fig:2} and~\ref{fig:3}.

\begin{figure}[ht]
\begin{center}
\includegraphics[scale=1.2]{figure_1.png}
\end{center}
\caption{Cholesky solver reference solution for Poisson equation with point charges at $(0.25, 0.75)$, $(0.75, 0.25)$.}
\label{fig:1}
\end{figure}

\begin{figure}[ht]
\begin{center}
\includegraphics[scale=1.2]{figure_2.png}
\end{center}
\caption{Jacobi relaxation solver solution for Poisson equation with point charges at $(0.25, 0.75)$, $(0.75, 0.25)$.}
\label{fig:2}
\end{figure}

\begin{figure}[ht]
\begin{center}
\includegraphics[scale=1.2]{figure_3.png}
\end{center}
\caption{Gauss-Seidel solver solution for Poisson equation with point charges at $(0.25, 0.75)$, $(0.75, 0.25)$.}
\label{fig:3}
\end{figure}

\section{Discussion}
The results are as expected. Further consideration should be given to investigating why the Gauss-Seidel solver
in this implementation is an order of magnitude slower than the Jacobi relaxation solver.

%\begin{thebibliography}{99}

% \bibitem{metropolis}
% Metropolis, N.,
% Rosenbluth, A.W.,
% Rosenbluth, M.N.,
% Teller, A.H.,
% Teller, E.\\
% \emph{Equations of State Calculations by Fast Computing Machines},\\
% Journal of Chemical Physics. 21 (6): 1087,\\
% 1953.

% \bibitem{herrmann}
% 	Herrmann, H. J.,
% 	Singer, H. M.,
% 	Mueller L.,
% 	Buchmann, M.-A.,\\
% 	\emph{Introduction to Computational Physics - Lecture Notes},\\
% 	ETH Zurich,\\
% 	2017.

% \bibitem{Gottschling}
% Gottschling, Peter\\
% \emph{Discovering Modern C++},\\
% Addison-Wesley,\\
% 2016.

%\end{thebibliography}

\end{document}