0
# Parameter System
1

2
The parameter system provides type-safe command-line argument parsing and validation for algorithms, input sources, and other configurable components. It supports various parameter types with bounds checking, default values, and automatic usage generation.
3

4
## Capabilities
5

6
### Parameterized Interface
7

8
Base interface for all configurable components that accept command-line parameters.
9

10
```java { .api }
11
/**
12
 * A configurable command-line choice, such as an input or algorithm
13
 * Provides standardized parameter handling across all components
14
 */
15
public interface Parameterized {
16
  /**
17
   * Unique, human-readable identifier presented as a selectable choice
18
   * @return Parameter name used in command-line arguments
19
   */
20
  String getName();
21
  
22
  /**
23
   * Human-readable format for command-line usage documentation
24
   * @return Command-line documentation string showing all options
25
   */
26
  String getUsage();
27
  
28
  /**
29
   * Read parameter values from command-line arguments
30
   * @param parameterTool Parameter parser containing command-line arguments
31
   * @throws ProgramParametrizationException when configuration is invalid
32
   */
33
  void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
34
}
35
```
36

37
### ParameterizedBase
38

39
Base implementation providing common parameter management functionality.
40

41
```java { .api }
42
/**
43
 * Base class for parameterized components providing common functionality
44
 * Handles parameter registration, parsing, and usage generation
45
 */
46
public abstract class ParameterizedBase implements Parameterized {
47
  
48
  public String getName(); // defaults to class simple name
49
  public String getUsage(); // generated from registered parameters
50
  public void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
51
  
52
  /**
53
   * Add a parameter to this component for parsing and usage generation
54
   * @param parameter Parameter to register
55
   */
56
  protected void addParameter(Parameter parameter);
57
  
58
  /**
59
   * Generate formatted listing of all registered parameters
60
   * @return Formatted parameter documentation string
61
   */
62
  protected String getParametersListing();
63
}
64
```
65

66
### Parameter Types
67

68
#### Parameter Base Interface
69

70
Base interface for all parameter types.
71

72
```java { .api }
73
/**
74
 * Base interface for typed parameters with validation and parsing
75
 * Provides consistent parameter handling across different data types
76
 */
77
public interface Parameter {
78
  /**
79
   * Get the parameter name used in command-line arguments
80
   * @return Parameter name string
81
   */
82
  String getName();
83
  
84
  /**
85
   * Get human-readable usage description for this parameter
86
   * @return Usage string describing the parameter
87
   */
88
  String getUsage();
89
  
90
  /**
91
   * Parse and validate parameter value from command-line arguments
92
   * @param parameterTool Parameter parser
93
   * @throws ProgramParametrizationException if parsing or validation fails
94
   */
95
  void configure(ParameterTool parameterTool) throws ProgramParametrizationException;
96
}
97
```
98

99
#### LongParameter
100

101
Parameter type for long integer values with optional bounds and defaults.
102

103
```java { .api }
104
/**
105
 * Long integer parameter with optional minimum/maximum bounds and default values
106
 * Supports validation and automatic usage generation
107
 */
108
public class LongParameter extends SimpleParameter {
109
  /**
110
   * Create a long parameter with name and default value
111
   * @param name Parameter name for command-line usage
112
   * @param defaultValue Default value if not specified
113
   */
114
  public LongParameter(String name, long defaultValue);
115
  
116
  /**
117
   * Set minimum allowed value for validation
118
   * @param minimum Minimum allowed value (inclusive)
119
   * @return This parameter for method chaining
120
   */
121
  public LongParameter setMinimum(long minimum);
122
  
123
  /**
124
   * Set maximum allowed value for validation  
125
   * @param maximum Maximum allowed value (inclusive)
126
   * @return This parameter for method chaining
127
   */
128
  public LongParameter setMaximum(long maximum);
129
  
130
  /**
131
   * Get the current parameter value after configuration
132
   * @return Current long value
133
   */
134
  public long getValue();
135
}
136
```
137

138
**Usage Examples:**
139
```java
140
// Simple long parameter with default
141
LongParameter vertexCount = new LongParameter("vertex_count", 100);
142

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

146
// Long parameter with both bounds
147
LongParameter iterations = new LongParameter("iterations", 10)
148
    .setMinimum(1).setMaximum(1000);
149
```
150

151
#### DoubleParameter
152

153
Parameter type for double-precision floating-point values with optional bounds.
154

155
```java { .api }
156
/**
157
 * Double-precision floating-point parameter with bounds validation
158
 * Supports inclusive and exclusive bounds checking
159
 */
160
public class DoubleParameter extends SimpleParameter {
161
  /**
162
   * Create a double parameter with name and default value
163
   * @param name Parameter name for command-line usage
164
   * @param defaultValue Default value if not specified
165
   */
166
  public DoubleParameter(String name, double defaultValue);
167
  
168
  /**
169
   * Set minimum allowed value (inclusive)
170
   * @param minimum Minimum allowed value
171
   * @param inclusive Whether minimum is inclusive (true) or exclusive (false)
172
   * @return This parameter for method chaining
173
   */
174
  public DoubleParameter setMinimum(double minimum, boolean inclusive);
175
  
176
  /**
177
   * Set maximum allowed value (inclusive)
178
   * @param maximum Maximum allowed value
179
   * @param inclusive Whether maximum is inclusive (true) or exclusive (false)
180
   * @return This parameter for method chaining
181
   */
182
  public DoubleParameter setMaximum(double maximum, boolean inclusive);
183
  
184
  /**
185
   * Get the current parameter value after configuration
186
   * @return Current double value
187
   */
188
  public double getValue();
189
}
190
```
191

192
**Usage Examples:**
193
```java
194
// Damping factor between 0.0 and 1.0 (exclusive bounds)
195
DoubleParameter dampingFactor = new DoubleParameter("dampingFactor", 0.85)
196
    .setMinimum(0.0, false).setMaximum(1.0, false);
197

198
// Noise level from 0.0 to 2.0 (inclusive bounds)  
199
DoubleParameter noise = new DoubleParameter("noise", 0.1)
200
    .setMinimum(0.0, true).setMaximum(2.0, true);
201
```
202

203
#### BooleanParameter
204

205
Parameter type for boolean flag values.
206

207
```java { .api }
208
/**
209
 * Boolean parameter for true/false command-line flags
210
 * Supports presence-based and explicit value parsing
211
 */
212
public class BooleanParameter extends SimpleParameter {
213
  /**
214
   * Create a boolean parameter with name and default value
215
   * @param name Parameter name for command-line usage
216
   * @param defaultValue Default boolean value if not specified
217
   */
218
  public BooleanParameter(String name, boolean defaultValue);
219
  
220
  /**
221
   * Get the current parameter value after configuration
222
   * @return Current boolean value
223
   */
224
  public boolean getValue();
225
}
226
```
227

228
**Usage Examples:**
229
```java
230
// Noise enabled flag (default false)
231
BooleanParameter noiseEnabled = new BooleanParameter("noise_enabled", false);
232

233
// Command-line usage: --noise_enabled true or --noise_enabled false
234
```
235

236
#### StringParameter
237

238
Parameter type for string values with optional requirements.
239

240
```java { .api }
241
/**
242
 * String parameter with optional default values and requirement validation
243
 * Can be configured as required or optional
244
 */
245
public class StringParameter extends SimpleParameter {
246
  /**
247
   * Create a string parameter with name (required by default)
248
   * @param name Parameter name for command-line usage
249
   */
250
  public StringParameter(String name);
251
  
252
  /**
253
   * Create a string parameter with name and default value (optional)
254
   * @param name Parameter name for command-line usage
255
   * @param defaultValue Default string value if not specified
256
   */
257
  public StringParameter(String name, String defaultValue);
258
  
259
  /**
260
   * Get the current parameter value after configuration
261
   * @return Current string value
262
   */
263
  public String getValue();
264
}
265
```
266

267
**Usage Examples:**
268
```java
269
// Required filename parameter
270
StringParameter inputFilename = new StringParameter("input_filename");
271

272
// Optional comment prefix with default
273
StringParameter commentPrefix = new StringParameter("comment_prefix", "#");
274
```
275

276
#### ChoiceParameter
277

278
Parameter type for selecting from a predefined set of options.
279

280
```java { .api }
281
/**
282
 * Choice parameter for selecting from predefined options
283
 * Validates input against allowed choices and provides usage help
284
 */  
285
public class ChoiceParameter extends SimpleParameter {
286
  /**
287
   * Create a choice parameter with name, choices, and default
288
   * @param name Parameter name for command-line usage
289
   * @param defaultChoice Default choice if not specified
290
   * @param choices Array of allowed choice strings
291
   */
292
  public ChoiceParameter(String name, String defaultChoice, String... choices);
293
  
294
  /**
295
   * Get the current selected choice after configuration
296
   * @return Current choice string
297
   */
298
  public String getValue();
299
}
300
```
301

302
**Usage Examples:**
303
```java
304
// Graph type choice (directed vs undirected)
305
ChoiceParameter order = new ChoiceParameter("order", "directed", 
306
    "directed", "undirected");
307

308
// Vertex ID type choice
309
ChoiceParameter type = new ChoiceParameter("type", "integer",
310
    "integer", "long", "string");
311
```
312

313
#### IterationConvergence
314

315
Specialized parameter for controlling iterative algorithms with maximum iterations and convergence thresholds.
316

317
```java { .api }
318
/**
319
 * Specialized parameter for iterative algorithm control
320
 * Combines maximum iterations with convergence threshold in a single parameter
321
 */
322
public class IterationConvergence extends SimpleParameter {
323
  /**
324
   * Create iteration convergence parameter with default iterations
325
   * @param name Parameter name for command-line usage
326
   * @param defaultIterations Default maximum iterations
327
   */
328
  public IterationConvergence(String name, int defaultIterations);
329
  
330
  /**
331
   * Get the maximum iterations value
332
   * @return Maximum number of iterations
333
   */
334
  public int getIterations();
335
  
336
  /**
337
   * Get the convergence threshold value (if specified)
338
   * @return Convergence threshold or null if not specified
339
   */
340
  public Double getConvergenceThreshold();
341
}
342
```
343

344
**Parameter Format:** `"<iterations>[;<threshold>]"`
345
- `iterations`: Maximum number of iterations (required)  
346
- `threshold`: Convergence threshold (optional)
347

348
**Usage Examples:**
349
```java
350
// Iteration convergence with default 10 iterations
351
IterationConvergence iterationConvergence = 
352
    new IterationConvergence("iterationConvergence", 10);
353

354
// Command-line usage:
355
// --iterationConvergence "20"           (20 iterations, no threshold)
356
// --iterationConvergence "50;0.001"     (50 iterations, threshold 0.001)
357
```
358

359
#### Simplify Parameter
360

361
Specialized parameter for graph simplification options to remove parallel edges and self-loops.
362

363
```java { .api }
364
/**
365
 * Graph simplification parameter for removing parallel edges and self-loops
366
 * Supports directed/undirected simplification modes
367
 */
368
public class Simplify extends ParameterizedBase implements Parameter<Simplify.Value> {
369
  
370
  /**
371
   * Create simplify parameter with given name
372
   * @param owner The parameterized component that owns this parameter
373
   * @param name Parameter name for command-line usage
374
   */
375
  public Simplify(Parameterized owner, String name);
376
  
377
  /**
378
   * Apply simplification to the given graph based on configured options
379
   * @param graph Input graph to simplify
380
   * @return Simplified graph with parallel edges/self-loops removed
381
   * @throws Exception if simplification fails
382
   */
383
  public <K, VV, EV> Graph<K, VV, EV> simplify(Graph<K, VV, EV> graph) throws Exception;
384
  
385
  /**
386
   * Get abbreviated description of simplification settings
387
   * @return Short string describing simplification (e.g., "undirected", "simple")
388
   */
389
  public String getShortString();
390
  
391
  /**
392
   * Get the parsed simplification configuration
393
   * @return Value object containing simplification options
394
   */
395
  public Simplify.Value getValue();
396
  
397
  /**
398
   * Value class containing simplification configuration
399
   */
400
  public static class Value {
401
    /** Remove parallel edges in directed mode */
402
    public final boolean directed;
403
    /** Remove parallel edges in undirected mode */  
404
    public final boolean undirected;
405
    
406
    /**
407
     * Create simplification value with mode flags
408
     * @param directed Enable directed simplification
409
     * @param undirected Enable undirected simplification
410
     */
411
    public Value(boolean directed, boolean undirected);
412
  }
413
}
414
```
415

416
**Usage Examples:**
417
```java
418
// Graph simplification parameter
419
Simplify simplify = new Simplify(this, "simplify");
420

421
// Command-line usage:
422
// --simplify "directed"     (remove parallel edges in directed mode)
423
// --simplify "undirected"   (remove parallel edges in undirected mode)  
424
// --simplify "simple"       (remove both parallel edges and self-loops)
425
```
426

427
### Parameter Utilities
428

429
#### Simplify Interface
430

431
Interface for parameters that support value simplification or transformation.
432

433
```java { .api }
434
/**
435
 * Interface for parameters that can simplify or transform their values
436
 * Used for post-processing parameter values after parsing
437
 */
438
public interface Simplify {
439
  /**
440
   * Simplify or transform the parameter value
441
   * Called after configuration to post-process the value
442
   */  
443
  void simplify();
444
}
445
```
446

447
#### Util Class
448

449
Utility methods for parameter processing, validation, and formatting.
450

451
```java { .api }
452
/**
453
 * Utility methods for parameter processing and value formatting
454
 * Provides common functionality for parameter implementations
455
 */
456
public class Util {
457
  
458
  /**
459
   * Validate a parameter condition and throw exception if false
460
   * Provides consistent error reporting across parameter implementations
461
   * @param condition Boolean condition that must be true
462
   * @param message Error message to display if condition fails
463
   * @throws ProgramParametrizationException if condition is false
464
   */  
465
  public static void checkParameter(boolean condition, String message) 
466
      throws ProgramParametrizationException;
467
  
468
  /**
469
   * Format numeric value with appropriate precision for display
470
   * @param value Numeric value to format
471
   * @return Formatted string representation
472
   */
473
  public static String formatNumeric(double value);
474
  
475
  /**
476
   * Parse boolean value from string with flexible input handling
477
   * @param value String representation of boolean
478
   * @return Parsed boolean value
479
   * @throws ProgramParametrizationException if parsing fails
480
   */
481
  public static boolean parseBoolean(String value) throws ProgramParametrizationException;
482
}
483
```
484

485
### Usage Patterns
486

487
#### Basic Parameter Setup
488

489
```java
490
public class MyAlgorithm extends ParameterizedBase {
491
  private LongParameter iterations = new LongParameter("iterations", 10);
492
  private DoubleParameter threshold = new DoubleParameter("threshold", 0.001);
493
  private BooleanParameter verbose = new BooleanParameter("verbose", false);
494
  
495
  public MyAlgorithm() {
496
    addParameter(iterations);
497
    addParameter(threshold);  
498
    addParameter(verbose);
499
  }
500
  
501
  // Parameter values accessible via iterations.getValue(), etc.
502
}
503
```
504

505
#### Dynamic Parameter Configuration
506

507
```java  
508
public class GridGraph extends GeneratedGraph<LongValue> {
509
  @Override
510
  public void configure(ParameterTool parameterTool) throws ProgramParametrizationException {
511
    super.configure(parameterTool);
512
    
513
    // Parse dynamic dimension parameters (dim0, dim1, dim2, ...)
514
    for (String key : parameterTool.toMap().keySet()) {
515
      if (key.startsWith("dim")) {
516
        String dimValue = parameterTool.get(key);
517
        // Parse format "size:wrap" and store dimension configuration
518
      }
519
    }
520
  }
521
}
522
```
523

524
## Types
525

526
```java { .api }
527
// Parameter parsing and validation
528
class ParameterTool {
529
  public static ParameterTool fromArgs(String[] args);
530
  public String get(String key);
531
  public String getRequired(String key) throws RuntimeException;
532
  public boolean has(String key);
533
  public Map<String, String> toMap();
534
}
535

536
class ProgramParametrizationException extends Exception {
537
  public ProgramParametrizationException(String message);
538
}
539

540
// Base parameter classes
541
abstract class SimpleParameter implements Parameter {
542
  // Common functionality for simple parameter types
543
}
544

545
abstract class Parameter {
546
  // Core parameter interface methods
547
}
548
```