/**
 * This interface encapsulates what a class used in Percolation Threshold
 * simulations should support. By varying the implementations you can
 * experiment with different approaches in analyzing not only what the 
 * Percolation Threshold constants are for different grids, but how efficiently
 * these constants can be determined via simulation.
 * 
 * @author Owen Astrachan
 * @date March, 2008
 * @date September, 2008
 */

public interface IPercolate {

    /**
     * Classes may implement draw as a 'no op', meaning no drawing is done. If
     * this method is implemented, some visualization of the percolation
     * simulation will occur, either via a graphics/visualization library or
     * by printing to standard out, logging statistics, etc.
     */
    public abstract void draw();

    /**
     * Choose an open site in the simulated grid and 'mark' it as occupied, no
     * checks are done to determine if there is an open site. This method 
     * modifies internal state of an IPercolate implementation so that
     * calls to to the <code>percolates</code> method will return results
     * that reflect the change-of-state in the simulation implementation.
     */
    public abstract void step();

    /**
     * Returns true if the simulated percolation actually percolates. What it means to
     * percolate could depend on the system being simulated, but returning true
     * typically means there's a connected path from begining-to-end, from source-to-sink,
     * from top-to-bottom, etc.
     * @return true iff the simulated system percolates
     */
    public abstract boolean percolates();

}