Parameter System

/**
 * A configurable command-line choice, such as an input or algorithm
 * Provides standardized parameter handling across all components
 */
public interface Parameterized {
  /**
   * Unique, human-readable identifier presented as a selectable choice
   * @return Parameter name used in command-line arguments
   */
  String getName();
  
  /**
   * Human-readable format for command-line usage documentation
   * @return Command-line documentation string showing all options
   */
  String getUsage();
  
  /**
   * Read parameter values from command-line arguments
   * @param parameterTool Parameter parser containing command-line arguments
   * @throws ProgramParametrizationException when configuration is invalid
   */
  void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
}

/**
 * Base class for parameterized components providing common functionality
 * Handles parameter registration, parsing, and usage generation
 */
public abstract class ParameterizedBase implements Parameterized {
  
  public String getName(); // defaults to class simple name
  public String getUsage(); // generated from registered parameters
  public void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
  
  /**
   * Add a parameter to this component for parsing and usage generation
   * @param parameter Parameter to register
   */
  protected void addParameter(Parameter parameter);
  
  /**
   * Generate formatted listing of all registered parameters
   * @return Formatted parameter documentation string
   */
  protected String getParametersListing();
}

/**
 * Base interface for typed parameters with validation and parsing
 * Provides consistent parameter handling across different data types
 */
public interface Parameter {
  /**
   * Get the parameter name used in command-line arguments
   * @return Parameter name string
   */
  String getName();
  
  /**
   * Get human-readable usage description for this parameter
   * @return Usage string describing the parameter
   */
  String getUsage();
  
  /**
   * Parse and validate parameter value from command-line arguments
   * @param parameterTool Parameter parser
   * @throws ProgramParametrizationException if parsing or validation fails
   */
  void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
}

/**
 * Long integer parameter with optional minimum/maximum bounds and default values
 * Supports validation and automatic usage generation
 */
public class LongParameter extends SimpleParameter {
  /**
   * Create a long parameter with name and default value
   * @param name Parameter name for command-line usage
   * @param defaultValue Default value if not specified
   */
  public LongParameter(String name, long defaultValue);
  
  /**
   * Set minimum allowed value for validation
   * @param minimum Minimum allowed value (inclusive)
   * @return This parameter for method chaining
   */
  public LongParameter setMinimum(long minimum);
  
  /**
   * Set maximum allowed value for validation  
   * @param maximum Maximum allowed value (inclusive)
   * @return This parameter for method chaining
   */
  public LongParameter setMaximum(long maximum);
  
  /**
   * Get the current parameter value after configuration
   * @return Current long value
   */
  public long getValue();
}

// Simple long parameter with default
LongParameter vertexCount = new LongParameter("vertex_count", 100);

// Long parameter with minimum bound
LongParameter scale = new LongParameter("scale", 10).setMinimum(1);

// Long parameter with both bounds
LongParameter iterations = new LongParameter("iterations", 10)
    .setMinimum(1).setMaximum(1000);

/**
 * Double-precision floating-point parameter with bounds validation
 * Supports inclusive and exclusive bounds checking
 */
public class DoubleParameter extends SimpleParameter {
  /**
   * Create a double parameter with name and default value
   * @param name Parameter name for command-line usage
   * @param defaultValue Default value if not specified
   */
  public DoubleParameter(String name, double defaultValue);
  
  /**
   * Set minimum allowed value (inclusive)
   * @param minimum Minimum allowed value
   * @param inclusive Whether minimum is inclusive (true) or exclusive (false)
   * @return This parameter for method chaining
   */
  public DoubleParameter setMinimum(double minimum, boolean inclusive);
  
  /**
   * Set maximum allowed value (inclusive)
   * @param maximum Maximum allowed value
   * @param inclusive Whether maximum is inclusive (true) or exclusive (false)
   * @return This parameter for method chaining
   */
  public DoubleParameter setMaximum(double maximum, boolean inclusive);
  
  /**
   * Get the current parameter value after configuration
   * @return Current double value
   */
  public double getValue();
}

// Damping factor between 0.0 and 1.0 (exclusive bounds)
DoubleParameter dampingFactor = new DoubleParameter("dampingFactor", 0.85)
    .setMinimum(0.0, false).setMaximum(1.0, false);

// Noise level from 0.0 to 2.0 (inclusive bounds)  
DoubleParameter noise = new DoubleParameter("noise", 0.1)
    .setMinimum(0.0, true).setMaximum(2.0, true);

/**
 * Boolean parameter for true/false command-line flags
 * Supports presence-based and explicit value parsing
 */
public class BooleanParameter extends SimpleParameter {
  /**
   * Create a boolean parameter with name and default value
   * @param name Parameter name for command-line usage
   * @param defaultValue Default boolean value if not specified
   */
  public BooleanParameter(String name, boolean defaultValue);
  
  /**
   * Get the current parameter value after configuration
   * @return Current boolean value
   */
  public boolean getValue();
}

// Noise enabled flag (default false)
BooleanParameter noiseEnabled = new BooleanParameter("noise_enabled", false);

// Command-line usage: --noise_enabled true or --noise_enabled false

/**
 * String parameter with optional default values and requirement validation
 * Can be configured as required or optional
 */
public class StringParameter extends SimpleParameter {
  /**
   * Create a string parameter with name (required by default)
   * @param name Parameter name for command-line usage
   */
  public StringParameter(String name);
  
  /**
   * Create a string parameter with name and default value (optional)
   * @param name Parameter name for command-line usage
   * @param defaultValue Default string value if not specified
   */
  public StringParameter(String name, String defaultValue);
  
  /**
   * Get the current parameter value after configuration
   * @return Current string value
   */
  public String getValue();
}

// Required filename parameter
StringParameter inputFilename = new StringParameter("input_filename");

// Optional comment prefix with default
StringParameter commentPrefix = new StringParameter("comment_prefix", "#");

/**
 * Choice parameter for selecting from predefined options
 * Validates input against allowed choices and provides usage help
 */  
public class ChoiceParameter extends SimpleParameter {
  /**
   * Create a choice parameter with name, choices, and default
   * @param name Parameter name for command-line usage
   * @param defaultChoice Default choice if not specified
   * @param choices Array of allowed choice strings
   */
  public ChoiceParameter(String name, String defaultChoice, String... choices);
  
  /**
   * Get the current selected choice after configuration
   * @return Current choice string
   */
  public String getValue();
}

// Graph type choice (directed vs undirected)
ChoiceParameter order = new ChoiceParameter("order", "directed", 
    "directed", "undirected");

// Vertex ID type choice
ChoiceParameter type = new ChoiceParameter("type", "integer",
    "integer", "long", "string");

/**
 * Specialized parameter for iterative algorithm control
 * Combines maximum iterations with convergence threshold in a single parameter
 */
public class IterationConvergence extends SimpleParameter {
  /**
   * Create iteration convergence parameter with default iterations
   * @param name Parameter name for command-line usage
   * @param defaultIterations Default maximum iterations
   */
  public IterationConvergence(String name, int defaultIterations);
  
  /**
   * Get the maximum iterations value
   * @return Maximum number of iterations
   */
  public int getIterations();
  
  /**
   * Get the convergence threshold value (if specified)
   * @return Convergence threshold or null if not specified
   */
  public Double getConvergenceThreshold();
}

// Iteration convergence with default 10 iterations
IterationConvergence iterationConvergence = 
    new IterationConvergence("iterationConvergence", 10);

// Command-line usage:
// --iterationConvergence "20"           (20 iterations, no threshold)
// --iterationConvergence "50;0.001"     (50 iterations, threshold 0.001)

/**
 * Graph simplification parameter for removing parallel edges and self-loops
 * Supports directed/undirected simplification modes
 */
public class Simplify extends ParameterizedBase implements Parameter<Simplify.Value> {
  
  /**
   * Create simplify parameter with given name
   * @param owner The parameterized component that owns this parameter
   * @param name Parameter name for command-line usage
   */
  public Simplify(Parameterized owner, String name);
  
  /**
   * Apply simplification to the given graph based on configured options
   * @param graph Input graph to simplify
   * @return Simplified graph with parallel edges/self-loops removed
   * @throws Exception if simplification fails
   */
  public <K, VV, EV> Graph<K, VV, EV> simplify(Graph<K, VV, EV> graph) throws Exception;
  
  /**
   * Get abbreviated description of simplification settings
   * @return Short string describing simplification (e.g., "undirected", "simple")
   */
  public String getShortString();
  
  /**
   * Get the parsed simplification configuration
   * @return Value object containing simplification options
   */
  public Simplify.Value getValue();
  
  /**
   * Value class containing simplification configuration
   */
  public static class Value {
    /** Remove parallel edges in directed mode */
    public final boolean directed;
    /** Remove parallel edges in undirected mode */  
    public final boolean undirected;
    
    /**
     * Create simplification value with mode flags
     * @param directed Enable directed simplification
     * @param undirected Enable undirected simplification
     */
    public Value(boolean directed, boolean undirected);
  }
}

// Graph simplification parameter
Simplify simplify = new Simplify(this, "simplify");

// Command-line usage:
// --simplify "directed"     (remove parallel edges in directed mode)
// --simplify "undirected"   (remove parallel edges in undirected mode)  
// --simplify "simple"       (remove both parallel edges and self-loops)

/**
 * Interface for parameters that can simplify or transform their values
 * Used for post-processing parameter values after parsing
 */
public interface Simplify {
  /**
   * Simplify or transform the parameter value
   * Called after configuration to post-process the value
   */  
  void simplify();
}

/**
 * Utility methods for parameter processing and value formatting
 * Provides common functionality for parameter implementations
 */
public class Util {
  
  /**
   * Validate a parameter condition and throw exception if false
   * Provides consistent error reporting across parameter implementations
   * @param condition Boolean condition that must be true
   * @param message Error message to display if condition fails
   * @throws ProgramParametrizationException if condition is false
   */  
  public static void checkParameter(boolean condition, String message) 
      throws ProgramParametrizationException;
  
  /**
   * Format numeric value with appropriate precision for display
   * @param value Numeric value to format
   * @return Formatted string representation
   */
  public static String formatNumeric(double value);
  
  /**
   * Parse boolean value from string with flexible input handling
   * @param value String representation of boolean
   * @return Parsed boolean value
   * @throws ProgramParametrizationException if parsing fails
   */
  public static boolean parseBoolean(String value) throws ProgramParametrizationException;
}

public class MyAlgorithm extends ParameterizedBase {
  private LongParameter iterations = new LongParameter("iterations", 10);
  private DoubleParameter threshold = new DoubleParameter("threshold", 0.001);
  private BooleanParameter verbose = new BooleanParameter("verbose", false);
  
  public MyAlgorithm() {
    addParameter(iterations);
    addParameter(threshold);  
    addParameter(verbose);
  }
  
  // Parameter values accessible via iterations.getValue(), etc.
}

public class GridGraph extends GeneratedGraph<LongValue> {
  @Override
  public void configure(ParameterTool parameterTool) throws ProgramParametrizationException {
    super.configure(parameterTool);
    
    // Parse dynamic dimension parameters (dim0, dim1, dim2, ...)
    for (String key : parameterTool.toMap().keySet()) {
      if (key.startsWith("dim")) {
        String dimValue = parameterTool.get(key);
        // Parse format "size:wrap" and store dimension configuration
      }
    }
  }
}

// Parameter parsing and validation
class ParameterTool {
  public static ParameterTool fromArgs(String[] args);
  public String get(String key);
  public String getRequired(String key) throws RuntimeException;
  public boolean has(String key);
  public Map<String, String> toMap();
}

class ProgramParametrizationException extends Exception {
  public ProgramParametrizationException(String message);
}

// Base parameter classes
abstract class SimpleParameter implements Parameter {
  // Common functionality for simple parameter types
}

abstract class Parameter {
  // Core parameter interface methods
}