Programming Assignment 1 Checklist: Percolation


Frequently Asked Questions (Percolation)

What are the goals of this assignment?

Can I add (or remove) methods to (or from) Percolation or PercolationStats? No. You must implement the APIs exactly as specified, with the identical set of public methods and signatures (or you will receive a substantial deduction). However, you are encouraged to add private methods that enhance the readability, maintainability, and modularity of your program.

What is unit testing? In your main() you are expected to show any testing you did of your code. At a minimum this includes calling all constructors and methods in the class. Any testing you did to debug your program should also be shown here. The autograder will not call it but you will fail the API check if it is not there.

Why is it so important to implement the prescribed API? Writing to an API is an important skill to master because it is an essential component of modular programming, whether you are developing software by yourself or as part of a group. When you develop a module that properly implements an API, anyone using that module (including yourself, perhaps at some later time) does not need to revisit the details of the code for that module when using it. This approach greatly simplifies writing large programs, developing software as part of a group, or developing software for use by others.

Most important, when you properly implement an API, others can write software to use your module or to test it. We do this regularly when grading your programs. For example, your PercolationStats client should work with our Percolation data type and vice versa. If you add an extra public method to Percolation and call them from PercolationStats, then your client won't work with our Percolation data type. Conversely, our PercolationStats client may not work with your Percolation data type if you remove a public method.

How many lines of code should my program be? You should strive for clarity and efficiency. Our reference solution for Percolation.java is about 80 lines, plus a test client. Our PercolationStats.java client is about 60 lines. If you are re-implementing the union-find data structure (instead of reusing the implementations provided), you are on the wrong track.

What should stddev() return if T equals 1? The sample standard deviation is undefined. We recommend returning Double.NaN but we will not test this case.

After the system has percolated, PercolationVisualizer colors in light blue all sites connected to open sites on the bottom (in addition to those connected to open sites on the top). Is this "backwash" acceptable? Yes. While allowing backwash does not strictly conform to the Percolation API, it requires quite a bit of ingenuity to fix. It is extra credit if you are able to implement a solution that meets the performance requirements and has no backwash.

   % java-algs4 PercolationVisualizer input10.txt
Percolation backwash

How do I generate a site uniformly at random among all blocked sites for use in PercolationStats? Pick a site at random (by using StdRandom to generate two integers between 0 (inclusive) and n (exclusive) and use this site if it is blocked; if not, repeat.

I don't get reliable timing information in PercolationStats when n = 200. What should I do? Increase the size of n (say to 400, 800, and 1600), until the mean running time exceeds its standard deviation.


Testing

Testing. We provide two clients that serve as large-scale visual traces. We highly recommend using them for testing and debugging your Percolation implementation.

Visualization client. PercolationVisualizer.java animates the results of opening sites in a percolation system specified by a file by performing the following steps:

The program should behave as in this movie and the following snapshots when used with input20.txt.

   % more input20.txt
   20
    6 10
   17 10
   11  4
    8  4
    4  8
    0  0
   ...

% java-algs4 PercolationVisualizer input20.txt
      Percolation 50 sites
50 open sites
Percolation 100 sites
100 open sites
Percolation 150 sites
150 open sites
Percolation 204 sites
204 open sites
Percolation 250 sites
250 open sites

Sample data files. The directory percolation contains some sample files for use with the visualization client. Associated with most input .txt file is an output .png file that contains the desired graphical output at the end of the visualization.

InteractiveVisualization client. InteractivePercolationVisualizer.java is similar to the first test client except that the input comes from a mouse (instead of from a file). It takes a command-line integer n that specifies the grid size. As a bonus, it writes to standard output the sequence of sites opened in the same format used by PercolationVisualizer, so you can use it to prepare interesting files for testing. If you design an interesting data file, feel free to share it with us and your classmates by posting it in the discussion forums.


Possible Progress Steps

These are purely suggestions for how you might make progress. You do not have to follow these steps.