0
# Input Sources
1

2
Flexible input system supporting both file-based graph data and algorithmic graph generation. All inputs implement the standardized Input interface for consistent parameter handling and graph creation.
3

4
## Capabilities
5

6
### Input Interface
7

8
Base interface that all graph input sources must implement.
9

10
```java { .api }
11
/**
12
 * Base interface for all graph input sources
13
 * @param <K> Vertex key type
14
 * @param <VV> Vertex value type
15
 * @param <EV> Edge value type
16
 */
17
public interface Input<K, VV, EV> extends Parameterized {
18
    /** Human-readable identifier for the input source */
19
    String getIdentity();
20
    
21
    /** Create the input graph using Flink execution environment */
22
    Graph<K, VV, EV> create(ExecutionEnvironment env) throws Exception;
23
}
24
```
25

26
### Input Base Class
27

28
Base implementation providing common functionality for input sources.
29

30
```java { .api }
31
/**
32
 * Base class for input implementations with common parameter handling
33
 */
34
public abstract class InputBase<K, VV, EV> extends ParameterizedBase implements Input<K, VV, EV> {
35
    /** Input generation or reading parallelism */
36
    LongParameter parallelism;
37
}
38
```
39

40
## File-Based Inputs
41

42
### CSV Input
43

44
Reads graph data from CSV files with configurable format and field mappings.
45

46
```java { .api }
47
/**
48
 * CSV file input for reading graph data from comma-separated files
49
 */
50
public class CSV extends InputBase<K, VV, EV> {
51
    /** Path to input CSV file */
52
    StringParameter inputFilename;
53
    
54
    /** Field separator character (default: comma) */
55
    StringParameter fieldDelimiter;
56
    
57
    /** Skip header row in CSV file */
58
    BooleanParameter skipHeader;
59
}
60
```
61

62
**Usage Examples:**
63

64
```bash
65
# Basic CSV input
66
--input CSV --input_filename graph.csv
67

68
# CSV with custom delimiter and header
69
--input CSV --input_filename data.tsv --field_delimiter "\t" --skip_header
70
```
71

72
**CSV Format Examples:**
73

74
```csv
75
# Edge list format (source, target)
76
1,2
77
2,3
78
3,1
79

80
# Edge list with weights (source, target, weight)
81
1,2,0.5
82
2,3,1.0
83
3,1,0.8
84

85
# Vertex and edge data (source, target, source_value, target_value, edge_value)
86
1,2,Alice,Bob,friend
87
2,3,Bob,Charlie,colleague
88
```
89

90
## Graph Generators
91

92
### Generated Graph Base Classes
93

94
Base classes for algorithmically generated graphs with common parameters.
95

96
```java { .api }
97
/**
98
 * Base class for algorithmically generated graphs
99
 */
100
public abstract class GeneratedGraph extends InputBase<K, VV, EV> {
101
    /** Number of vertices in generated graph */
102
    LongParameter vertexCount;
103
    
104
    /** Random seed for reproducible generation */
105
    LongParameter seed;
106
}
107

108
/**
109
 * Base class for generated graphs that may have multiple edges between vertices
110
 */
111
public abstract class GeneratedMultiGraph extends GeneratedGraph {
112
    /** Whether to allow multiple edges between same vertex pair */
113
    BooleanParameter allowMultipleEdges;
114
}
115
```
116

117
### Complete Graph
118

119
Generates complete graphs where every vertex is connected to every other vertex.
120

121
```java { .api }
122
/**
123
 * Complete graph generator - all vertices connected to all others
124
 */
125
public class CompleteGraph extends GeneratedGraph {
126
    // Inherits vertexCount and seed from GeneratedGraph
127
    // Generates (n * (n-1)) / 2 edges for n vertices
128
}
129
```
130

131
**Usage Examples:**
132

133
```bash
134
# Generate complete graph with 1000 vertices
135
--input CompleteGraph --vertex_count 1000
136

137
# Complete graph with specific seed for reproducibility  
138
--input CompleteGraph --vertex_count 500 --seed 12345
139
```
140

141
### Grid Graph
142

143
Generates regular grid graphs with configurable dimensions.
144

145
```java { .api }
146
/**
147
 * Grid graph generator for regular lattice structures
148
 */
149
public class GridGraph extends GeneratedGraph {
150
    /** Grid dimensions (e.g., "10x10" for 2D, "5x5x5" for 3D) */
151
    StringParameter dimensions;
152
    
153
    /** Include diagonal connections in grid */
154
    BooleanParameter includeDiagonals;
155
}
156
```
157

158
**Usage Examples:**
159

160
```bash
161
# 2D grid graph
162
--input GridGraph --dimensions "10x10"
163

164
# 3D grid with diagonals
165
--input GridGraph --dimensions "5x5x5" --include_diagonals
166
```
167

168
### Star Graph
169

170
Generates star graphs with one central vertex connected to all others.
171

172
```java { .api }
173
/**
174
 * Star graph generator - one central vertex connected to all others
175
 */
176
public class StarGraph extends GeneratedGraph {
177
    // Generates 1 central vertex + (n-1) leaf vertices
178
    // Total edges: n-1
179
}
180
```
181

182
**Usage Examples:**
183

184
```bash
185
# Star graph with 1000 vertices (1 center + 999 leaves)
186
--input StarGraph --vertex_count 1000
187
```
188

189
### Cycle Graph
190

191
Generates cycle graphs where vertices form a ring structure.
192

193
```java { .api }
194
/**
195
 * Cycle graph generator - vertices connected in a ring
196
 */
197
public class CycleGraph extends GeneratedGraph {
198
    // Each vertex connected to exactly 2 neighbors
199
    // Total edges: n (for n vertices)
200
}
201
```
202

203
### Path Graph
204

205
Generates path graphs where vertices form a linear chain.
206

207
```java { .api }
208
/**
209
 * Path graph generator - vertices connected in a line
210
 */
211
public class PathGraph extends GeneratedGraph {
212
    // Vertices connected in sequence: 1-2-3-...-n
213
    // Total edges: n-1
214
}
215
```
216

217
### R-MAT Graph
218

219
Generates R-MAT (Recursive Matrix) graphs using probabilistic edge placement for realistic network structures.
220

221
```java { .api }
222
/**
223
 * R-MAT graph generator for realistic network topologies
224
 * Uses recursive matrix model with configurable probabilities
225
 */
226
public class RMatGraph extends GeneratedMultiGraph {
227
    /** Graph scale - generates 2^scale vertices */
228
    LongParameter scale;
229
    
230
    /** Edge factor - multiplier for number of edges */
231
    LongParameter edgeFactor;
232
    
233
    /** R-MAT matrix probability parameters (must sum to 1.0) */
234
    DoubleParameter a, b, c; // d = 1 - a - b - c
235
    
236
    /** Enable noise in edge placement */
237
    BooleanParameter noiseEnabled;
238
    
239
    /** Noise level for edge placement randomization */
240
    DoubleParameter noise;
241
}
242
```
243

244
**Usage Examples:**
245

246
```bash
247
# Basic R-MAT graph (scale=10 gives 1024 vertices)
248
--input RMatGraph --scale 10 --edge_factor 4
249

250
# R-MAT with custom probabilities
251
--input RMatGraph --scale 12 --edge_factor 8 --a 0.45 --b 0.25 --c 0.15
252

253
# R-MAT with noise
254
--input RMatGraph --scale 8 --edge_factor 2 --noise_enabled --noise 0.1
255
```
256

257
### Hypercube Graph
258

259
Generates hypercube graphs of specified dimensions.
260

261
```java { .api }
262
/**
263
 * Hypercube graph generator for n-dimensional hypercube structures
264
 */
265
public class HypercubeGraph extends GeneratedGraph {
266
    /** Hypercube dimension */
267
    LongParameter dimensions;
268
    // Generates 2^dimensions vertices
269
}
270
```
271

272
### Circulant Graph
273

274
Generates circulant graphs with configurable connection patterns.
275

276
```java { .api }
277
/**
278
 * Circulant graph generator with configurable offset patterns
279
 */
280
public class CirculantGraph extends GeneratedGraph {
281
    /** Connection offsets (e.g., "1,2" connects each vertex to +1 and +2 neighbors) */
282
    StringParameter offsets;
283
}
284
```
285

286
**Usage Examples:**
287

288
```bash
289
# Circulant graph with offset pattern
290
--input CirculantGraph --vertex_count 100 --offsets "1,2,5"
291
```
292

293
### Utility Generators
294

295
#### Empty Graph
296

297
Generates graphs with vertices but no edges.
298

299
```java { .api }
300
/**
301
 * Empty graph generator - vertices with no edges
302
 */
303
public class EmptyGraph extends GeneratedGraph {
304
    // Generates n isolated vertices
305
}
306
```
307

308
#### Singleton Edge Graph
309

310
Generates graphs with single edges between vertex pairs.
311

312
```java { .api }
313
/**
314
 * Singleton edge graph generator - ensures single edges between pairs
315
 */
316
public class SingletonEdgeGraph extends GeneratedGraph {
317
    /** Target edge count */
318
    LongParameter edgeCount;
319
}
320
```
321

322
#### Echo Graph
323

324
Utility input for testing and debugging that echoes input parameters.
325

326
```java { .api }
327
/**
328
 * Echo graph for testing - outputs parameter information
329
 */
330
public class EchoGraph extends InputBase<K, VV, EV> {
331
    // Used for debugging parameter passing and configuration
332
}
333
```
334

335
## Usage Patterns
336

337
**Basic Graph Generation:**
338

339
```java
340
// Create complete graph generator
341
CompleteGraph generator = new CompleteGraph();
342
generator.configure(ParameterTool.fromArgs(new String[]{
343
    "--vertex_count", "1000",
344
    "--seed", "12345"
345
}));
346

347
// Generate graph
348
Graph<LongValue, NullValue, NullValue> graph = generator.create(env);
349
```
350

351
**File Input:**
352

353
```java
354
// Configure CSV input
355
CSV csvInput = new CSV();
356
csvInput.configure(ParameterTool.fromArgs(new String[]{
357
    "--input_filename", "graph.csv",
358
    "--field_delimiter", ",",
359
    "--skip_header"
360
}));
361

362
// Read graph from file
363
Graph<LongValue, NullValue, DoubleValue> graph = csvInput.create(env);
364
```
365

366
**Input Selection by Name:**
367

368
```java
369
// Get input from factory
370
ParameterizedFactory<Input> factory = createInputFactory();
371
Input input = factory.get("CompleteGraph");
372

373
if (input != null) {
374
    input.configure(parameters);
375
    Graph graph = input.create(env);
376
}
377
```