Parameter System

/**
 * Base interface for all configurable components
 */
public interface Parameterized {
    /** Unique component identifier */
    String getName();
    
    /** Command-line usage documentation */
    String getUsage();
    
    /** Configure component from command-line parameters */
    void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
}

/**
 * Individual parameter interface for type-safe value handling
 * @param <T> Parameter value type
 */
public interface Parameter<T> {
    /** Parameter usage string for help generation */
    String getUsage();
    
    /** Whether parameter is hidden from usage documentation */
    boolean isHidden();
    
    /** Configure parameter value from command-line tool */
    void configure(ParameterTool parameterTool);
    
    /** Get configured parameter value */
    T getValue();
}

/**
 * Base class for parameterized components with automatic parameter management
 */
public abstract class ParameterizedBase implements Parameterized {
    /** Default component name based on class simple name */
    public String getName();
    
    /** Auto-generated usage string from registered parameters */
    public String getUsage();
    
    /** Configure all registered parameters from command-line */
    public void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
}

/**
 * Base class for typed parameters with common functionality
 * @param <T> Parameter value type
 */
public abstract class SimpleParameter<T> implements Parameter<T> {
    /** Set default value for parameter */
    public SimpleParameter<T> setDefaultValue(T defaultValue);
    
    /** Get configured value or default if not set */
    public T getValue();
    
    /** Generate usage string for this parameter */
    public String getUsage();
    
    /** Check if parameter should be hidden from help */
    public boolean isHidden();
}

/**
 * Boolean flag parameter
 */
public class BooleanParameter extends SimpleParameter<Boolean> {
    /** Create boolean parameter with specified name */
    public BooleanParameter(Parameterized parent, String name);
    
    /** Set default value (default: false) */
    public BooleanParameter setDefaultValue(Boolean defaultValue);
}

// Define boolean parameters
BooleanParameter enableFeature = new BooleanParameter(this, "enable_feature");
BooleanParameter verbose = new BooleanParameter(this, "verbose").setDefaultValue(false);

// Command-line usage
--enable_feature        // Sets to true
--verbose false         // Explicitly sets to false

/**
 * Long integer parameter with bounds checking
 */
public class LongParameter extends SimpleParameter<Long> {
    /** Create long parameter with specified name */
    public LongParameter(Parameterized parent, String name);
    
    /** Set minimum allowed value */
    public LongParameter setMinimumValue(long minimumValue);
    
    /** Set maximum allowed value */
    public LongParameter setMaximumValue(long maximumValue);
    
    /** Set default value */
    public LongParameter setDefaultValue(Long defaultValue);
}

// Define long parameters with bounds
LongParameter vertexCount = new LongParameter(this, "vertex_count")
    .setMinimumValue(1)
    .setMaximumValue(1000000)
    .setDefaultValue(1000L);

LongParameter iterations = new LongParameter(this, "iterations")
    .setMinimumValue(1)
    .setDefaultValue(10L);

// Command-line usage
--vertex_count 5000
--iterations 20

/**
 * Double floating-point parameter with bounds checking
 */
public class DoubleParameter extends SimpleParameter<Double> {
    /** Create double parameter with specified name */
    public DoubleParameter(Parameterized parent, String name);
    
    /** Set minimum value with inclusion control */
    public DoubleParameter setMinimumValue(double min, boolean inclusive);
    
    /** Set maximum value with inclusion control */
    public DoubleParameter setMaximumValue(double max, boolean inclusive);
    
    /** Set default value */
    public DoubleParameter setDefaultValue(Double defaultValue);
}

// Define double parameters with bounds
DoubleParameter dampingFactor = new DoubleParameter(this, "damping_factor")
    .setMinimumValue(0.0, false)  // Exclusive minimum
    .setMaximumValue(1.0, true)   // Inclusive maximum
    .setDefaultValue(0.85);

DoubleParameter threshold = new DoubleParameter(this, "threshold")
    .setMinimumValue(0.0, true)
    .setDefaultValue(0.001);

// Command-line usage
--damping_factor 0.9
--threshold 0.0001

/**
 * String parameter for text values
 */
public class StringParameter extends SimpleParameter<String> {
    /** Create string parameter with specified name */
    public StringParameter(Parameterized parent, String name);
    
    /** Set default value */
    public StringParameter setDefaultValue(String defaultValue);
}

// Define string parameters
StringParameter filename = new StringParameter(this, "filename");
StringParameter format = new StringParameter(this, "format").setDefaultValue("csv");

// Command-line usage
--filename "graph_data.csv"
--format "tsv"

/**
 * Choice parameter for selecting from predefined options
 */
public class ChoiceParameter extends SimpleParameter<String> {
    /** Create choice parameter with specified name */
    public ChoiceParameter(Parameterized parent, String name);
    
    /** Add visible choices to selection */
    public ChoiceParameter addChoices(String... choices);
    
    /** Add hidden choices (not shown in help but still valid) */
    public ChoiceParameter addHiddenChoices(String... hiddenChoices);
    
    /** Set default choice */
    public ChoiceParameter setDefaultValue(String defaultValue);
}

// Define choice parameters
ChoiceParameter algorithm = new ChoiceParameter(this, "algorithm")
    .addChoices("pagerank", "connected_components", "triangle_listing")
    .setDefaultValue("pagerank");

ChoiceParameter outputFormat = new ChoiceParameter(this, "output_format")
    .addChoices("csv", "json")
    .addHiddenChoices("debug")  // Hidden option for internal use
    .setDefaultValue("csv");

// Command-line usage
--algorithm connected_components
--output_format json

/**
 * Iteration convergence control with multiple termination criteria
 */
public class IterationConvergence extends ParameterizedBase {
    /** Maximum number of iterations */
    LongParameter iterations;
    
    /** Convergence threshold for early termination */
    DoubleParameter convergenceThreshold;
    
    /** Enable convergence threshold checking */
    BooleanParameter convergenceEnabled;
}

// Define iteration control
IterationConvergence convergence = new IterationConvergence(this, "convergence");

// Command-line usage
--iterations 50 --convergence_threshold 0.001 --convergence_enabled

/**
 * Graph simplification parameters for preprocessing
 */
public class Simplify extends ParameterizedBase {
    /** Remove self-loops from graph */
    BooleanParameter removeSelfLoops;
    
    /** Remove duplicate edges */
    BooleanParameter removeDuplicateEdges;
    
    /** Remove isolated vertices */
    BooleanParameter removeIsolatedVertices;
}

/**
 * Utility functions for parameter processing
 */
public class Util {
    /** Parse numeric ranges and validate bounds */
    public static List<Long> parseRange(String range);
    
    /** Format parameter values for display */
    public static String formatValue(Object value);
    
    /** Validate parameter combinations */
    public static void validateParameterCombination(Parameter<?>... parameters);
}

public class MyAlgorithm extends ParameterizedBase implements Driver {
    // Define parameters as class fields
    private LongParameter iterations = new LongParameter(this, "iterations")
        .setMinimumValue(1)
        .setDefaultValue(10L);
    
    private DoubleParameter threshold = new DoubleParameter(this, "threshold")
        .setMinimumValue(0.0, false)
        .setDefaultValue(0.001);
    
    private BooleanParameter verbose = new BooleanParameter(this, "verbose");
    
    @Override
    public DataSet plan(Graph graph) throws Exception {
        // Use parameter values
        long maxIterations = iterations.getValue();
        double convergenceThreshold = threshold.getValue();
        boolean enableVerbose = verbose.getValue();
        
        // Algorithm implementation
        return null;
    }
}

// Configure from command-line arguments
String[] args = {"--iterations", "20", "--threshold", "0.0001", "--verbose"};
ParameterTool parameterTool = ParameterTool.fromArgs(args);

MyAlgorithm algorithm = new MyAlgorithm();
algorithm.configure(parameterTool);

// Access configured values
System.out.println("Iterations: " + algorithm.iterations.getValue());
System.out.println("Threshold: " + algorithm.threshold.getValue());
System.out.println("Verbose: " + algorithm.verbose.getValue());

// Automatic usage string generation
MyAlgorithm algorithm = new MyAlgorithm();
System.out.println(algorithm.getUsage());

// Output:
// --iterations <long> : Maximum iterations (default: 10, minimum: 1)
// --threshold <double> : Convergence threshold (default: 0.001, minimum: 0.0 exclusive)
// --verbose : Enable verbose output (default: false)

// Validation happens automatically during configure()
try {
    algorithm.configure(parameterTool);
} catch (ProgramParametrizationException e) {
    System.err.println("Parameter validation failed: " + e.getMessage());
    // Examples of validation errors:
    // "iterations must be at least 1, got: 0"
    // "threshold must be greater than 0.0, got: 0.0"
    // "Unknown parameter: invalid_param"
}

// Define hidden parameters for internal use
private StringParameter debugMode = new StringParameter(this, "__debug_mode") {
    @Override
    public boolean isHidden() {
        return true;  // Hidden from usage documentation
    }
}.setDefaultValue("off");