0
# Parameter System
1

2
Type-safe parameter management system providing validation, default values, and automatic usage string generation for all configurable components. The system ensures consistent parameter handling across inputs, algorithms, and outputs.
3

4
## Capabilities
5

6
### Core Parameter Interfaces
7

8
Base interfaces that define the parameter system contract.
9

10
```java { .api }
11
/**
12
 * Base interface for all configurable components
13
 */
14
public interface Parameterized {
15
    /** Unique component identifier */
16
    String getName();
17
    
18
    /** Command-line usage documentation */
19
    String getUsage();
20
    
21
    /** Configure component from command-line parameters */
22
    void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
23
}
24

25
/**
26
 * Individual parameter interface for type-safe value handling
27
 * @param <T> Parameter value type
28
 */
29
public interface Parameter<T> {
30
    /** Parameter usage string for help generation */
31
    String getUsage();
32
    
33
    /** Whether parameter is hidden from usage documentation */
34
    boolean isHidden();
35
    
36
    /** Configure parameter value from command-line tool */
37
    void configure(ParameterTool parameterTool);
38
    
39
    /** Get configured parameter value */
40
    T getValue();
41
}
42
```
43

44
### Parameter Base Classes
45

46
Base implementations providing common parameter functionality.
47

48
```java { .api }
49
/**
50
 * Base class for parameterized components with automatic parameter management
51
 */
52
public abstract class ParameterizedBase implements Parameterized {
53
    /** Default component name based on class simple name */
54
    public String getName();
55
    
56
    /** Auto-generated usage string from registered parameters */
57
    public String getUsage();
58
    
59
    /** Configure all registered parameters from command-line */
60
    public void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
61
}
62

63
/**
64
 * Base class for typed parameters with common functionality
65
 * @param <T> Parameter value type
66
 */
67
public abstract class SimpleParameter<T> implements Parameter<T> {
68
    /** Set default value for parameter */
69
    public SimpleParameter<T> setDefaultValue(T defaultValue);
70
    
71
    /** Get configured value or default if not set */
72
    public T getValue();
73
    
74
    /** Generate usage string for this parameter */
75
    public String getUsage();
76
    
77
    /** Check if parameter should be hidden from help */
78
    public boolean isHidden();
79
}
80
```
81

82
## Parameter Types
83

84
### Boolean Parameters
85

86
Boolean flag parameters for enabling/disabling features.
87

88
```java { .api }
89
/**
90
 * Boolean flag parameter
91
 */
92
public class BooleanParameter extends SimpleParameter<Boolean> {
93
    /** Create boolean parameter with specified name */
94
    public BooleanParameter(Parameterized parent, String name);
95
    
96
    /** Set default value (default: false) */
97
    public BooleanParameter setDefaultValue(Boolean defaultValue);
98
}
99
```
100

101
**Usage Examples:**
102

103
```java
104
// Define boolean parameters
105
BooleanParameter enableFeature = new BooleanParameter(this, "enable_feature");
106
BooleanParameter verbose = new BooleanParameter(this, "verbose").setDefaultValue(false);
107

108
// Command-line usage
109
--enable_feature        // Sets to true
110
--verbose false         // Explicitly sets to false
111
```
112

113
### Numeric Parameters
114

115
#### Long Parameters
116

117
Integer parameters with optional bounds validation.
118

119
```java { .api }
120
/**
121
 * Long integer parameter with bounds checking
122
 */
123
public class LongParameter extends SimpleParameter<Long> {
124
    /** Create long parameter with specified name */
125
    public LongParameter(Parameterized parent, String name);
126
    
127
    /** Set minimum allowed value */
128
    public LongParameter setMinimumValue(long minimumValue);
129
    
130
    /** Set maximum allowed value */
131
    public LongParameter setMaximumValue(long maximumValue);
132
    
133
    /** Set default value */
134
    public LongParameter setDefaultValue(Long defaultValue);
135
}
136
```
137

138
**Usage Examples:**
139

140
```java
141
// Define long parameters with bounds
142
LongParameter vertexCount = new LongParameter(this, "vertex_count")
143
    .setMinimumValue(1)
144
    .setMaximumValue(1000000)
145
    .setDefaultValue(1000L);
146

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

151
// Command-line usage
152
--vertex_count 5000
153
--iterations 20
154
```
155

156
#### Double Parameters
157

158
Floating-point parameters with bounds validation and precision control.
159

160
```java { .api }
161
/**
162
 * Double floating-point parameter with bounds checking
163
 */
164
public class DoubleParameter extends SimpleParameter<Double> {
165
    /** Create double parameter with specified name */
166
    public DoubleParameter(Parameterized parent, String name);
167
    
168
    /** Set minimum value with inclusion control */
169
    public DoubleParameter setMinimumValue(double min, boolean inclusive);
170
    
171
    /** Set maximum value with inclusion control */
172
    public DoubleParameter setMaximumValue(double max, boolean inclusive);
173
    
174
    /** Set default value */
175
    public DoubleParameter setDefaultValue(Double defaultValue);
176
}
177
```
178

179
**Usage Examples:**
180

181
```java
182
// Define double parameters with bounds
183
DoubleParameter dampingFactor = new DoubleParameter(this, "damping_factor")
184
    .setMinimumValue(0.0, false)  // Exclusive minimum
185
    .setMaximumValue(1.0, true)   // Inclusive maximum
186
    .setDefaultValue(0.85);
187

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

192
// Command-line usage
193
--damping_factor 0.9
194
--threshold 0.0001
195
```
196

197
### String Parameters
198

199
Text parameters with optional validation and formatting.
200

201
```java { .api }
202
/**
203
 * String parameter for text values
204
 */
205
public class StringParameter extends SimpleParameter<String> {
206
    /** Create string parameter with specified name */
207
    public StringParameter(Parameterized parent, String name);
208
    
209
    /** Set default value */
210
    public StringParameter setDefaultValue(String defaultValue);
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
// Define string parameters
218
StringParameter filename = new StringParameter(this, "filename");
219
StringParameter format = new StringParameter(this, "format").setDefaultValue("csv");
220

221
// Command-line usage
222
--filename "graph_data.csv"
223
--format "tsv"
224
```
225

226
### Choice Parameters
227

228
Parameters that allow selection from predefined options.
229

230
```java { .api }
231
/**
232
 * Choice parameter for selecting from predefined options
233
 */
234
public class ChoiceParameter extends SimpleParameter<String> {
235
    /** Create choice parameter with specified name */
236
    public ChoiceParameter(Parameterized parent, String name);
237
    
238
    /** Add visible choices to selection */
239
    public ChoiceParameter addChoices(String... choices);
240
    
241
    /** Add hidden choices (not shown in help but still valid) */
242
    public ChoiceParameter addHiddenChoices(String... hiddenChoices);
243
    
244
    /** Set default choice */
245
    public ChoiceParameter setDefaultValue(String defaultValue);
246
}
247
```
248

249
**Usage Examples:**
250

251
```java
252
// Define choice parameters
253
ChoiceParameter algorithm = new ChoiceParameter(this, "algorithm")
254
    .addChoices("pagerank", "connected_components", "triangle_listing")
255
    .setDefaultValue("pagerank");
256

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

262
// Command-line usage
263
--algorithm connected_components
264
--output_format json
265
```
266

267
## Advanced Parameter Types
268

269
### Iteration Convergence
270

271
Specialized parameter for controlling iterative algorithms.
272

273
```java { .api }
274
/**
275
 * Iteration convergence control with multiple termination criteria
276
 */
277
public class IterationConvergence extends ParameterizedBase {
278
    /** Maximum number of iterations */
279
    LongParameter iterations;
280
    
281
    /** Convergence threshold for early termination */
282
    DoubleParameter convergenceThreshold;
283
    
284
    /** Enable convergence threshold checking */
285
    BooleanParameter convergenceEnabled;
286
}
287
```
288

289
**Usage Examples:**
290

291
```java
292
// Define iteration control
293
IterationConvergence convergence = new IterationConvergence(this, "convergence");
294

295
// Command-line usage
296
--iterations 50 --convergence_threshold 0.001 --convergence_enabled
297
```
298

299
### Graph Simplification
300

301
Parameters for graph preprocessing and simplification.
302

303
```java { .api }
304
/**
305
 * Graph simplification parameters for preprocessing
306
 */
307
public class Simplify extends ParameterizedBase {
308
    /** Remove self-loops from graph */
309
    BooleanParameter removeSelfLoops;
310
    
311
    /** Remove duplicate edges */
312
    BooleanParameter removeDuplicateEdges;
313
    
314
    /** Remove isolated vertices */
315
    BooleanParameter removeIsolatedVertices;
316
}
317
```
318

319
## Parameter Utilities
320

321
### Parameter Utility Functions
322

323
Helper functions for parameter processing and validation.
324

325
```java { .api }
326
/**
327
 * Utility functions for parameter processing
328
 */
329
public class Util {
330
    /** Parse numeric ranges and validate bounds */
331
    public static List<Long> parseRange(String range);
332
    
333
    /** Format parameter values for display */
334
    public static String formatValue(Object value);
335
    
336
    /** Validate parameter combinations */
337
    public static void validateParameterCombination(Parameter<?>... parameters);
338
}
339
```
340

341
## Usage Patterns
342

343
### Basic Parameter Definition
344

345
```java
346
public class MyAlgorithm extends ParameterizedBase implements Driver {
347
    // Define parameters as class fields
348
    private LongParameter iterations = new LongParameter(this, "iterations")
349
        .setMinimumValue(1)
350
        .setDefaultValue(10L);
351
    
352
    private DoubleParameter threshold = new DoubleParameter(this, "threshold")
353
        .setMinimumValue(0.0, false)
354
        .setDefaultValue(0.001);
355
    
356
    private BooleanParameter verbose = new BooleanParameter(this, "verbose");
357
    
358
    @Override
359
    public DataSet plan(Graph graph) throws Exception {
360
        // Use parameter values
361
        long maxIterations = iterations.getValue();
362
        double convergenceThreshold = threshold.getValue();
363
        boolean enableVerbose = verbose.getValue();
364
        
365
        // Algorithm implementation
366
        return null;
367
    }
368
}
369
```
370

371
### Parameter Configuration
372

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

378
MyAlgorithm algorithm = new MyAlgorithm();
379
algorithm.configure(parameterTool);
380

381
// Access configured values
382
System.out.println("Iterations: " + algorithm.iterations.getValue());
383
System.out.println("Threshold: " + algorithm.threshold.getValue());
384
System.out.println("Verbose: " + algorithm.verbose.getValue());
385
```
386

387
### Usage String Generation
388

389
```java
390
// Automatic usage string generation
391
MyAlgorithm algorithm = new MyAlgorithm();
392
System.out.println(algorithm.getUsage());
393

394
// Output:
395
// --iterations <long> : Maximum iterations (default: 10, minimum: 1)
396
// --threshold <double> : Convergence threshold (default: 0.001, minimum: 0.0 exclusive)
397
// --verbose : Enable verbose output (default: false)
398
```
399

400
### Parameter Validation
401

402
```java
403
// Validation happens automatically during configure()
404
try {
405
    algorithm.configure(parameterTool);
406
} catch (ProgramParametrizationException e) {
407
    System.err.println("Parameter validation failed: " + e.getMessage());
408
    // Examples of validation errors:
409
    // "iterations must be at least 1, got: 0"
410
    // "threshold must be greater than 0.0, got: 0.0"
411
    // "Unknown parameter: invalid_param"
412
}
413
```
414

415
### Hidden Parameters
416

417
```java
418
// Define hidden parameters for internal use
419
private StringParameter debugMode = new StringParameter(this, "__debug_mode") {
420
    @Override
421
    public boolean isHidden() {
422
        return true;  // Hidden from usage documentation
423
    }
424
}.setDefaultValue("off");
425
```