Algorithm Drivers

/**
 * A driver for one or more graph algorithms and/or analytics
 * Coordinates algorithm execution with input graphs
 */
public interface Driver<K, VV, EV> extends Parameterized {
  /**
   * A one-line description presented in algorithm listings
   * @return Short description of the algorithm
   */
  String getShortDescription();
  
  /**
   * A multi-line description presented in algorithm usage help
   * @return Detailed description of the algorithm
   */
  String getLongDescription();
  
  /**
   * Execute algorithms and analytics on the input graph
   * The execution plan is finalized in the output methods
   * @param graph Input graph to process
   * @throws Exception if algorithm execution fails
   */
  void plan(Graph<K, VV, EV> graph) throws Exception;
}

/**
 * PageRank algorithm driver using iterative computation
 * Scores vertices based on link structure and random walk model
 */
public class PageRank<K, VV, EV> extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Print {
  
  public String getName();
  public String getShortDescription(); // "score vertices by the number and quality of incoming links"
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void print(String executionName) throws Exception;
}

--algorithm PageRank --dampingFactor 0.9 --iterationConvergence "20;0.001"

/**
 * Connected Components algorithm driver using GSA implementation
 * Identifies connected components by propagating minimum vertex IDs
 * Requires vertex type to be Comparable for minimum ID computation
 */
public class ConnectedComponents<K extends Comparable<K>, VV, EV> 
    extends ParameterizedBase 
    implements Driver<K, VV, EV>, CSV, Hash, Print {
  
  public String getName();
  public String getShortDescription(); // "ConnectedComponents"
  public String getLongDescription(); // "ConnectedComponents"
  public void plan(Graph<K, VV, EV> graph) throws Exception;
  public void hash(String executionName) throws Exception;
  public void print(String executionName) throws Exception;
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
}

--algorithm ConnectedComponents

/**
 * HITS algorithm driver using iterative computation
 * Computes hub and authority scores based on link structure
 */
public class HITS<K, VV, EV> extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Print {
  
  public String getName();
  public String getShortDescription(); // "score vertices as hubs and authorities"
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void print(String executionName) throws Exception;
}

--algorithm HITS --iterationConvergence "15;0.0001"

/**
 * Adamic-Adar similarity algorithm driver
 * Computes similarity scores weighted by centerpoint degree
 */
public class AdamicAdar<K extends CopyableValue<K>, VV, EV> 
    extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Print {
  
  public String getName();
  public String getShortDescription(); // "similarity score weighted by centerpoint degree"
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void print(String executionName) throws Exception;
}

--algorithm AdamicAdar --minRatio 0.1 --minScore 0.5 --littleParallelism 1

/**
 * Clustering Coefficient algorithm driver
 * Computes local clustering coefficient for each vertex
 */
public class ClusteringCoefficient<K extends CopyableValue<K>, VV, EV> 
    extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Print {
  
  public String getName();
  public String getShortDescription();
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void print(String executionName) throws Exception;
}

/**
 * Jaccard Index similarity algorithm driver
 * Computes Jaccard similarity coefficient between vertex pairs
 */
public class JaccardIndex<K extends CopyableValue<K>, VV, EV> 
    extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Print {
  
  public String getName();
  public String getShortDescription();
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void print(String executionName) throws Exception;
}

/**
 * Triangle Listing algorithm driver
 * Enumerates all triangles in the input graph
 */
public class TriangleListing<K extends CopyableValue<K>, VV, EV> 
    extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Hash, Print {
  
  public String getName();
  public String getShortDescription();
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void hash(String executionName) throws Exception;
  public void print(String executionName) throws Exception;
}

/**
 * Graph Metrics algorithm driver
 * Computes vertex and edge metrics for graph analysis
 */
public class GraphMetrics<K extends Comparable<K>, VV, EV> 
    extends ParameterizedBase 
    implements Driver<K, VV, EV>, Hash, Print {
  
  public String getName();
  public String getShortDescription(); // "compute vertex and edge metrics"
  public String getLongDescription();
  public void plan(Graph<K, VV, EV> graph) throws Exception;
  public void hash(String executionName) throws Exception;
  public void print(String executionName) throws Exception;
}

--algorithm GraphMetrics --order directed

/**
 * Edge List driver for graph output
 * Outputs the input graph as a simple edge list
 */
public class EdgeList<K, VV, EV> extends SimpleDriver<K, VV, EV, Result<K>> 
    implements CSV, Hash, Print {
  
  public String getName();
  public String getShortDescription();
  public String getLongDescription();
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
  public void hash(String executionName) throws Exception;
  public void print(String executionName) throws Exception;
}

/**
 * Base driver class for algorithms producing a single result DataSet
 * Provides common functionality for result handling and output formatting
 * Implements standard output interfaces for CSV, Print, and Hash operations
 */
public abstract class SimpleDriver<K, VV, EV, R extends PrintableResult> 
    extends ParameterizedBase implements Driver<K, VV, EV> {
  
  /**
   * Abstract method for algorithm-specific graph processing logic
   * Subclasses implement their specific algorithm here
   * @param graph Input graph to process
   * @return DataSet containing algorithm results
   * @throws Exception if algorithm execution fails
   */
  protected abstract DataSet<R> simplePlan(Graph<K, VV, EV> graph) throws Exception;
  
  /**
   * Get the result DataSet from the last algorithm execution
   * @return DataSet containing algorithm results, or null if not executed
   */
  protected DataSet<R> getResult();
  
  /**
   * Implementation of Driver interface - coordinates algorithm execution
   * Calls simplePlan() and stores result for output operations
   * @param graph Input graph to process
   * @throws Exception if algorithm execution fails
   */
  public void plan(Graph<K, VV, EV> graph) throws Exception;
  
  /**
   * Compute and print hash of algorithm results for verification
   * @param executionName Name to display with hash output
   * @throws Exception if hash computation fails
   */
  public void hash(String executionName) throws Exception;
  
  /**
   * Print algorithm results to console for inspection
   * @param executionName Name to display with printed output
   * @throws Exception if printing fails
   */
  public void print(String executionName) throws Exception;
  
  /**
   * Write algorithm results to CSV file with configurable formatting
   * @param filename Output file path
   * @param lineDelimiter Line separator (e.g., "\n")
   * @param fieldDelimiter Field separator (e.g., ",")
   * @throws Exception if file writing fails
   */
  public void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
}

/**
 * Base class for parameterized components
 * Provides common parameter parsing and validation functionality
 */
public abstract class ParameterizedBase implements Parameterized {
  
  public String getName();
  public String getUsage();
  public void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
  
  // Protected methods for parameter management
  protected void addParameter(Parameter parameter);
  protected String getParametersListing();
}

// Result wrapper for algorithm outputs
class Result<K> {
  // Contains algorithm-specific result data
}

// Output format interfaces
interface CSV {
  void writeCSV(String filename, String lineDelimiter, String fieldDelimiter) throws Exception;
}

interface Print {
  void print(String executionName) throws Exception;
}

interface Hash {
  void hash(String executionName) throws Exception;
}

// Type constraints for certain algorithms
interface CopyableValue<T> extends Value {
  void copyTo(T target);
  T copy();
}

interface Comparable<T> {
  int compareTo(T other);
}