Placed online: September 17
20 points, ~2% of final grade
Due: no later than 11 pm, Thursday, September 25
General Assignment Requirements

1. to practice implementing a stand alone class
2. to work with two dimensional arrays
3. To learn to use the jar tool. Important Note. On this assignment you will turn in 3 files archived into a single file. The archive tool we use in the class is called jar. (Java ARchive) I strongly recommend learning to use that tool well before the due date. In the past students have had trouble turning in the assignment on time because they did not allow enough time to learn to use jar. jar can be used to create executable Java programs and to archive multiple files into a single file. You will be using jar to create an archive, not to create an executable, so there is no need to include the .class files.
   
   If you do not turn in the correct files in your jar file you will either get a 0 on the assignment or use slip days correcting the problem, thus it is important not to wait until the last minute to learn how to create jar files.

Implement a class that represents a mathematical matrix.

Mathematical matrices are used  to solve systems of linear equations. Matrices are used in applications such as physics, engineering, probability and statistics, economics, biology, and computer science. (especially in the area of computer graphics) 

Matrices appear in the following form:

These matrices represent this system of linear equations:

  x +  5y + 10z + 5w =   4
 6x +  4y + 12z + 4w =   5
10x +  5y + 12z + 11w = 12
 5x + 11y + 23z + 9w  =  7

The above matrix has 4 rows and 4 columns, but the number of rows and columns do not have to be equal. In other words mathematical matrices do not need to be square, but they must be rectangular. Each entry can be an integer or real number. For this assignment you will only deal with matrices of integers. You will implement a class, MathMatrix, that models a mathematical matrix and supports various operations on matrices. See this page for an explanation of the mathematical operations you are implementing. The Wikipedia article may also be useful. After calculus, most students then take a course entitled Matrices and Matrix Calculations.

The provided source file MathMatrix.java contains a skeleton implementation of a class for modeling mathematical matrices. MathMatrix.java

Implement all of the methods in MathMatrix.java under the constraints of the general requirements.

• You may use any classes and methods from the Java standard library you wish on this assignment. The Arrays class has many useful methods for dealing with arrays.

• add assertions to methods to check preconditions

• You must use a "native" two dimensional array of ints as your underlying storage container in the matrix class:

  private int[][] myCells; 
  // or myNums or cells or some other appropriate name
  // DO NOT USE myMathMatrix. That is much too confusing.
   

• The first row of a MathMatrix is numbered 0. The first column of a MathMatrix is numbered 0.

• The provided source file, MathMatrixTester.java contains various tests for the MathMatrix class. Some of these tests may be incorrect. You must find and fix any incorrect tests. Your MathMatrix class must pass the included tests. I encourage you to use the class listserv to identify incorrect tests.

• Add many more tests to this class. I encourage you to share you tests with others via the class listserv.

•  Include the code that conducts the experiments described below, but comment the code out in the version of the assignment you turn in..

• You are encouraged to create private helper methods and use other public methods in the MathMatrix class when completing methods in the MathMatrix class if this simplifies the solution.

• Note, once a MathMatrix object is created there are no methods to alters its size, except for calling the transpose method. So unlike the IntList we are doing in class it doesn't make sense to have extra capacity. The size of the 2d array of ints will be the same size as the Mathematical Matrix we are representing. (And if the transpose method gets called then you will have to create a new 2d array for the MathMatrix.)

The provided source file, Stopwatch.java, is a class for measuring the execution time of parts of programs. Do not alter this file.

In addition to completing the MathMatrix.java class and adding tests to the MathMatrixTester.java class, perform the following experiments and answer the following questions. Your results and answers will be placed in a text file, A3Exp.txt. The code that conducts the experiments is to be included in the MathMatrixTester.java class, but commented out.

Use the Stopwatch class to record the time it takes to perform various operations on MathMatrix objects.

Stopwatch s = new Stopwatch();
s.start();
//code to time
s.stop();

The Stopwatch class can show the elapsed time in seconds or nanoseconds. See the Stopwatch class documentation for more details.

Experiment 1:

• Create 2 square matrix objects. (The number of rows equals the number of columns.) Fill the matrix objects with random values.

• Use the Stopwatch class to record the time it takes to add the 2 MathMatrix objects together.

• Repeat the experiment 100 times and record the average time in milliseconds it takes to add the 2 MathMatrix objects together.

• You must choose a value for the number of rows and columns so that all of the 100 tests give a result of at least 10 milliseconds elapsed time. (10 millisecond is 0.01 seconds) You may, of course, automate these 100 repetitions.

  On my computer a MathMatrix dimension equal to 800 (So the MathMatrix was 800 by 800, 640,000 total elements) led to all measured times being greater than 10 milliseconds. Your results will vary based on the speed of the computer you run the test on.
   

• Record the dimension of the matrix and the average time it took for the add operation based on 100 repetitions.

• Now double the dimension of the matrix and repeat the experiment. In my example the original MathMatrix was 800 by 800. In this step the size would be increased to 1600 by 1600.

• Record the dimension of the matrix and the average time it took for the add operation on the larger matrix based on 100 repetitions.

Experiment 2:

• Perform the same basic experiment as experiment 1, but use the multiply method instead of the add method.

• You can use a much smaller dimension than in experiment 1 and still avoid measured times of less than 1 millisecond. You must choose a size that results in at least 10 milliseconds for the experiment. On my computer a dimension of 200 (a 200 by 200 matrix. 40,000 elements) avoided any times below 10 milliseconds.

Questions. Answer the following questions. Place your answers at the bottom of your A3Exp.txt file.

1. Based on the results of experiment 1, how long would you expect the add method to take if you doubled the dimension size of the MathMatrix objects again?

2. Based on the results of experiment 2, how long would you expect the multiply method to take if you doubled the dimension size of the MathMatrix objects again?

3. How large a matrix can you create before your program runs out of heap memory? Estimate the amount of memory your program is given based on the largest possible matrix object it can create successfully. (Recall, an int in Java takes up 4 bytes.)

4. The logic of the add and subtract methods of the MathMatrix class are very similar. Code so similar should make you want to generalize it into a method. You are not required to do this on the assignment, but what do you think could be done to generalize the add and subtract methods?

Fill in the header for MathMatrix.java and MathMatrixTester.java. Replace <NAME> with your name. Note, you are stating, on your honor, that you did the assignment on your own, as required.

When finished turn in a jar file named A3.jar that contains the following files: MathMatrix.java, MathMatrixTester.java, and A3Exp.txt. Use the turnin program to turn the file in.

jar is a program included in the standard edition of Java loaded on the computers in the Microlab and that you have on your computer if you downloaded Java. See Sun's page for using jar and my tips for using jar. Some IDEs provide the ability to create jar files. Here is a link to how to create jar files in Eclipse. Recall you are not creating an executable, only archiving the necessary files.

• review and follow the general assignment requirements?
• work on the assignment individually?
• fill in the headers in your files?
• implement the required methods?
• ensure your program does not suffer a compile error or runtime error?
• find and fix any incorrect tests in MathMatrixTester?
• ensure your program passes the tests in MathMatrixTesert?
• add your own tests to the main method of MathMatrixTester?
• if possible use other methods from the class instead of repeating code?
• complete the experiments and place you answers in a file named A3Exp.txt?
• turn in your jar file named A3.jar (that contains all appropriate files) to the proper account in the Microlab via the turnin program before 11 pm, Thursday, September 25?

1. Be clear on the difference between MathMatrix objects and the 2d array of ints that serves as the storage container for the ints that make up a MathMatrix object.
   
   Assume the 2d array of int that is the instance variable for each MathMatrix object is named myCells.
   
   public MathMatrix add(MathMatrix rightHandSide)
   {   MathMatrix result = new MathMatrix(numRows(), numCols(), 0);
       int valueFromThisMathMatrix = myCells[0][0];
       int valueFromRightHandSide = rightHandSide.myCells[0][0];
       int valueFromResult = result.myCells[0][0];
   
       // following line results in syntax error
       // valueFromRightHandSide = rightHandSide[0][0];
    
2. Familiarize yourself with the concept of deep copying. (As opposed to shallow copying.) One of the constructors requires you make a deep copy of a 2d array. Here is the Wikipedia article on object copying.
    
3. If possible use other methods from the MathMatrix class instead of repeating code.
    
4. There are two methods involving transposing a matrix, a mutator and an accessor. One of these is necessary, but we are providing both as a convenience to the users of our class.
    
5. When coding your methods write assert statements to check preconditions.
    

6. An explanation of the requirements for the toString method.

   In the String that is returned from the toString method the space for each "cell" is equal to the longest value in the matrix plus 1. (Don't forget to consider a minus sign in on of the values.) All cell entries are right justified with newline characters  between rows. The last row does not end in a newline character. For example, given the following MathMatrix.

   10	100	101	-1000
   1000	10	55	4
   1	-1	4	0

   You should return a String that would appear like this. Use newline characters ("\n") to create line breaks.
   
       10   100   101 -1000
     1000    10    55     4
        1    -1     4     0
   
   In example above it can be hard to tell how many spaces there are between numbers. In this example the spaces have been replaced by periods to the number of "spaces" is more clearly shown.
    
   ....10...100...101.-1000
   ..1000....10....55.....4
   .....1....-1.....4.....0
   
   Please note, the last line does not include a newline character. (Every time I give this assignment some poor soul spends a couple hours trying to figure out why they don't pass the toString test. The cause is usually because they have added a newline character to the last row when they shouldn't have.)

   One way of finding the length of an int is to convert it to a String and find the length of the String. Here is an example:

   int x;
   //code to give x a value.
   String s = "" + x;
   int lengthOfInt = s.length();
   
   //or more simply given an int x
   int lengthOfX = ("" + x).length();

   Doing the toString method using just loops and Strings and if statements is actually a very interesting exercise. Or you can learn how to use the format method from the String class and formatting string syntax.
    

7. The isUpperTriangular method determines if the MathMatrix is an upper triangular matrix. A matrix is upper triangular if it is a square matrix and all values below the main diagonal are 0. The main diagonal is all the cells whose row and column are equal. The values of the elements on the main diagonal don't have to be zero, just the ones below it. A 1 by 1 matrix is considered upper triangular.