0
# Runner Framework
1

2
The Runner framework provides a unified command-line interface for executing graph algorithms with configurable inputs and outputs. It serves as the main entry point for the flink-gelly-examples library and coordinates algorithm execution through a consistent parameter-driven approach.
3

4
## Capabilities
5

6
### Main Execution Entry Point
7

8
The primary entry point for command-line execution of graph algorithms.
9

10
```java { .api }
11
/**
12
 * Main class that executes Flink graph processing drivers
13
 * Coordinates input sources, algorithms, and output formatters
14
 */
15
public class Runner {
16
  /**
17
   * Command-line entry point for executing graph algorithms
18
   * @param args Command-line arguments specifying algorithm, input, and output
19
   * @throws Exception if execution fails or parameters are invalid
20
   */
21
  public static void main(String[] args) throws Exception;
22
}
23
```
24

25
**Usage Pattern:**
26
```bash
27
flink run flink-gelly-examples_2.10-1.3.3.jar \
28
  --algorithm <algorithm_name> [algorithm_options] \
29
  --input <input_name> [input_options] \
30
  --output <output_name> [output_options]
31
```
32

33
**Available Commands:**
34
- List algorithms: `flink run flink-gelly-examples_2.10-1.3.3.jar` (no parameters)
35
- Algorithm help: `flink run flink-gelly-examples_2.10-1.3.3.jar --algorithm <name>`
36

37
### Algorithm Registry
38

39
The Runner maintains registries of available algorithms and input sources through parameterized factories.
40

41
```java { .api }
42
/**
43
 * Factory for creating parameterized instances by name
44
 * Provides iteration over available implementations
45
 */
46
private static class ParameterizedFactory<T extends Parameterized> 
47
    implements Iterable<T> {
48
  
49
  /**
50
   * Add a class to the factory registry
51
   * @param cls Class extending T to register
52
   * @return this factory for method chaining
53
   */
54
  public ParameterizedFactory<T> addClass(Class<? extends T> cls);
55
  
56
  /**
57
   * Get an instance by name
58
   * @param name String matching getName() of registered class
59
   * @return Instance of the named class or null if not found
60
   */
61
  public T get(String name);
62
}
63
```
64

65
### Supported Algorithms
66

67
The Runner framework supports the following graph algorithms:
68

69
- **AdamicAdar**: Similarity score weighted by centerpoint degree
70
- **ClusteringCoefficient**: Local clustering coefficient computation
71
- **ConnectedComponents**: Connected component detection using GSA
72
- **EdgeList**: Simple graph edge list output
73
- **GraphMetrics**: Comprehensive graph metrics computation
74
- **HITS**: Hub and authority scoring algorithm
75
- **JaccardIndex**: Jaccard similarity coefficient computation
76
- **PageRank**: Link analysis ranking algorithm
77
- **TriangleListing**: Triangle enumeration in graphs
78

79
**Usage Examples:**
80

81
```bash
82
# Run PageRank with damping factor 0.9 and 20 iterations
83
flink run flink-gelly-examples_2.10-1.3.3.jar \
84
  --algorithm PageRank \
85
  --dampingFactor 0.9 \
86
  --iterationConvergence "20;0.001" \
87
  --input CompleteGraph --vertex_count 1000 \
88
  --output print
89

90
# Run Connected Components on CSV data
91
flink run flink-gelly-examples_2.10-1.3.3.jar \
92
  --algorithm ConnectedComponents \
93
  --input CSV --input_filename edges.csv --type long \
94
  --output csv --output_filename components.csv
95
```
96

97
### Supported Input Sources
98

99
The Runner framework supports various graph input sources:
100

101
- **CSV**: Read graphs from CSV files with configurable delimiters and key types
102
- **CirculantGraph**: Generate circulant graphs with offset ranges
103
- **CompleteGraph**: Generate complete graphs (all vertices connected)
104
- **CycleGraph**: Generate cycle/ring graphs
105
- **EchoGraph**: Generate echo graphs with specified vertex degree
106
- **EmptyGraph**: Generate graphs with vertices but no edges
107
- **GridGraph**: Generate multi-dimensional grid graphs
108
- **HypercubeGraph**: Generate N-dimensional hypercube graphs
109
- **PathGraph**: Generate linear path graphs
110
- **RMatGraph**: Generate R-MAT scale-free random graphs
111
- **SingletonEdgeGraph**: Generate graphs with singleton edges
112
- **StarGraph**: Generate star topology graphs
113

114
**Usage Examples:**
115

116
```bash
117
# Use R-MAT generator with 2^12 vertices and edge factor 8
118
--input RMatGraph --scale 12 --edge_factor 8 --seed 12345
119

120
# Use CSV input with string keys and custom delimiters
121
--input CSV --input_filename graph.txt --type string \
122
  --input_field_delimiter ";" --comment_prefix "//"
123

124
# Use 3D grid graph with wrapped endpoints
125
--input GridGraph --dim0 "10:true" --dim1 "10:false" --dim2 "5:true"
126
```
127

128
### Supported Output Formats
129

130
The Runner framework supports multiple output formats depending on algorithm capabilities:
131

132
- **CSV**: Write results to CSV files with configurable delimiters
133
- **Print**: Output results to console for inspection
134
- **Hash**: Compute and display hash of results for verification
135

136
**Output Examples:**
137

138
```bash
139
# CSV output with custom delimiters
140
--output csv --output_filename results.csv \
141
  --output_line_delimiter "\n" --output_field_delimiter ","
142

143
# Console output
144
--output print
145

146
# Hash verification
147
--output hash
148
```
149

150
### Error Handling and Help
151

152
The Runner provides comprehensive error handling and usage help:
153

154
```java { .api }
155
/**
156
 * List available algorithms with descriptions
157
 * @return Formatted string listing all registered algorithms
158
 */
159
private static String getAlgorithmsListing();
160

161
/**
162
 * Display usage for a specific algorithm including compatible inputs and outputs
163
 * @param algorithmName Name of the algorithm to show usage for
164
 * @return Formatted usage string with all options
165
 */
166
private static String getAlgorithmUsage(String algorithmName);
167
```
168

169
**Error Conditions:**
170
- Missing required parameters throw `ProgramParametrizationException`
171
- Invalid algorithm names throw `ProgramParametrizationException`
172
- Invalid input types throw `ProgramParametrizationException`
173
- Unsupported output formats throw `ProgramParametrizationException`
174

175
**Help Usage:**
176
```bash
177
# List all available algorithms
178
flink run flink-gelly-examples_2.10-1.3.3.jar
179

180
# Show help for specific algorithm
181
flink run flink-gelly-examples_2.10-1.3.3.jar --algorithm PageRank
182

183
# Invalid parameters show usage automatically
184
flink run flink-gelly-examples_2.10-1.3.3.jar --algorithm InvalidAlgorithm
185
```
186

187
## Types
188

189
```java { .api }
190
// Core execution interfaces
191
interface Driver<K, VV, EV> extends Parameterized {
192
  String getShortDescription();
193
  String getLongDescription(); 
194
  void plan(Graph<K, VV, EV> graph) throws Exception;
195
}
196

197
interface Input<K, VV, EV> extends Parameterized {
198
  String getIdentity();
199
  Graph<K, VV, EV> create(ExecutionEnvironment env) throws Exception;
200
}
201

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

207
interface Print {
208
  void print(String executionName) throws Exception;
209
}
210

211
interface Hash {
212
  void hash(String executionName) throws Exception;
213
}
214

215
// Parameter parsing and validation
216
class ParameterTool {
217
  public static ParameterTool fromArgs(String[] args);
218
  public String get(String key);
219
  public String getRequired(String key) throws RuntimeException;
220
  public boolean has(String key);
221
}
222

223
class ProgramParametrizationException extends Exception {
224
  public ProgramParametrizationException(String message);
225
}
226
```