0
# Parameter System
1

2
Type-safe parameter management system with validation, default values, and JSON serialization support. Essential for configuring ML algorithms and components with runtime safety and persistence capabilities.
3

4
## Capabilities
5

6
### Params Class
7

8
Core parameter container that provides type-safe parameter storage with JSON serialization.
9

10
```java { .api }
11
/**
12
 * Map-like container for parameters with type safety and serialization
13
 * Supports validation, default values, and JSON persistence
14
 */
15
public class Params implements Serializable, Cloneable {
16
    
17
    /** Get number of parameters stored */
18
    public int size();
19
    
20
    /** Remove all parameters */
21
    public void clear();
22
    
23
    /** Check if container is empty */
24
    public boolean isEmpty();
25
    
26
    /** Get parameter value with default handling */
27
    public <V> V get(ParamInfo<V> info);
28
    
29
    /** Set parameter value with type safety */
30
    public <V> Params set(ParamInfo<V> info, V value);
31
    
32
    /** Remove specific parameter */
33
    public <V> void remove(ParamInfo<V> info);
34
    
35
    /** Check if parameter exists */
36
    public <V> boolean contains(ParamInfo<V> info);
37
    
38
    /** Serialize all parameters to JSON */
39
    public String toJson();
40
    
41
    /** Load parameters from JSON string */
42
    public void loadJson(String json);
43
    
44
    /** Merge with another Params instance */
45
    public Params merge(Params otherParams);
46
    
47
    /** Create deep copy of parameters */
48
    public Params clone();
49
}
50
```
51

52
**Usage Examples:**
53

54
```java
55
import org.apache.flink.ml.api.misc.param.Params;
56
import org.apache.flink.ml.api.misc.param.ParamInfo;
57

58
// Create parameter definitions
59
ParamInfo<Integer> MAX_ITER = ParamInfoFactory
60
    .createParamInfo("maxIter", Integer.class)
61
    .setDescription("Maximum number of iterations")
62
    .setHasDefaultValue(100)
63
    .build();
64

65
ParamInfo<Double> LEARNING_RATE = ParamInfoFactory
66
    .createParamInfo("learningRate", Double.class)
67
    .setDescription("Learning rate for optimization")
68
    .setRequired()
69
    .build();
70

71
// Create and populate parameters
72
Params params = new Params();
73
params.set(MAX_ITER, 200);
74
params.set(LEARNING_RATE, 0.01);
75

76
// Check parameter existence and get values
77
if (params.contains(LEARNING_RATE)) {
78
    double lr = params.get(LEARNING_RATE);
79
    System.out.println("Learning rate: " + lr);
80
}
81

82
// Get value with default fallback
83
int maxIter = params.get(MAX_ITER); // Returns 200, or 100 if not set
84

85
// Serialize and deserialize
86
String json = params.toJson();
87
Params loaded = new Params();
88
loaded.loadJson(json);
89

90
// Merge parameters
91
Params otherParams = new Params().set(MAX_ITER, 300);
92
Params merged = params.merge(otherParams);
93
```
94

95
### ParamInfo Class
96

97
Parameter metadata and definition class that provides type information, validation, and default values.
98

99
```java { .api }
100
/**
101
 * Parameter definition with metadata, validation, and default values
102
 * @param <V> The parameter value type
103
 */
104
public class ParamInfo<V> {
105
    
106
    /** Get parameter name identifier */
107
    public String getName();
108
    
109
    /** Get parameter aliases for backward compatibility */
110
    public String[] getAlias();
111
    
112
    /** Get human-readable parameter description */
113
    public String getDescription();
114
    
115
    /** Check if parameter is optional */
116
    public boolean isOptional();
117
    
118
    /** Check if parameter has a default value */
119
    public boolean hasDefaultValue();
120
    
121
    /** Get default value if available */
122
    public V getDefaultValue();
123
    
124
    /** Get parameter validator */
125
    public ParamValidator<V> getValidator();
126
    
127
    /** Get parameter value class */
128
    public Class<V> getValueClass();
129
}
130
```
131

132
### ParamInfoFactory Class
133

134
Factory for creating ParamInfo instances with builder pattern support.
135

136
```java { .api }
137
/**
138
 * Factory for creating ParamInfo instances with fluent builder pattern
139
 */
140
public class ParamInfoFactory {
141
    
142
    /** Create builder for parameter definition */
143
    public static <V> ParamInfoBuilder<V> createParamInfo(String name, Class<V> valueClass);
144
}
145
```
146

147
### ParamInfoBuilder Class
148

149
Builder for constructing ParamInfo instances with validation and metadata.
150

151
```java { .api }
152
/**
153
 * Builder for constructing ParamInfo instances
154
 * @param <V> The parameter value type
155
 */
156
public static class ParamInfoBuilder<V> {
157
    
158
    /** Set parameter aliases for backward compatibility */
159
    public ParamInfoBuilder<V> setAlias(String[] alias);
160
    
161
    /** Set human-readable description */
162
    public ParamInfoBuilder<V> setDescription(String description);
163
    
164
    /** Mark parameter as optional */
165
    public ParamInfoBuilder<V> setOptional();
166
    
167
    /** Mark parameter as required */
168
    public ParamInfoBuilder<V> setRequired();
169
    
170
    /** Set default value for parameter */
171
    public ParamInfoBuilder<V> setHasDefaultValue(V defaultValue);
172
    
173
    /** Set validation function */
174
    public ParamInfoBuilder<V> setValidator(ParamValidator<V> validator);
175
    
176
    /** Build final ParamInfo instance */
177
    public ParamInfo<V> build();
178
}
179
```
180

181
**Usage Example:**
182

183
```java
184
// Create comprehensive parameter definition
185
ParamInfo<String> ALGORITHM = ParamInfoFactory
186
    .createParamInfo("algorithm", String.class)
187
    .setDescription("Algorithm type for classification")
188
    .setAlias(new String[]{"algo", "method"})
189
    .setHasDefaultValue("logistic")
190
    .setValidator(value -> 
191
        Arrays.asList("logistic", "svm", "tree").contains(value))
192
    .build();
193

194
// Create required parameter with validation
195
ParamInfo<Integer> NUM_FEATURES = ParamInfoFactory
196
    .createParamInfo("numFeatures", Integer.class)
197
    .setDescription("Number of input features")
198
    .setRequired()
199
    .setValidator(value -> value > 0)
200
    .build();
201
```
202

203
### ParamValidator Interface
204

205
Interface for implementing parameter value validation.
206

207
```java { .api }
208
/**
209
 * Interface for parameter value validation
210
 * @param <V> The parameter value type to validate
211
 */
212
public interface ParamValidator<V> extends Serializable {
213
    
214
    /** Validate parameter value, return true if valid */
215
    boolean validate(V value);
216
}
217
```
218

219
**Usage Examples:**
220

221
```java
222
// Range validator
223
ParamValidator<Double> rangeValidator = value -> value >= 0.0 && value <= 1.0;
224

225
// Enum validator  
226
ParamValidator<String> enumValidator = value -> 
227
    Arrays.asList("auto", "manual", "hybrid").contains(value);
228

229
// Custom complex validator
230
ParamValidator<Integer[]> arrayValidator = value -> {
231
    if (value == null || value.length == 0) return false;
232
    return Arrays.stream(value).allMatch(v -> v > 0);
233
};
234
```
235

236
### WithParams Interface
237

238
Common interface for classes that use the parameter system.
239

240
```java { .api }
241
/**
242
 * Common interface for parameter handling
243
 * @param <T> The implementing class type for method chaining
244
 */
245
public interface WithParams<T> {
246
    
247
    /** Get all parameters */
248
    Params getParams();
249
    
250
    /** Set parameter value with type safety and method chaining */
251
    <V> T set(ParamInfo<V> info, V value);
252
    
253
    /** Get parameter value with default handling */
254
    <V> V get(ParamInfo<V> info);
255
}
256
```
257

258
**Implementation Example:**
259

260
```java
261
public class MyEstimator implements WithParams<MyEstimator> {
262
    private Params params = new Params();
263
    
264
    // Parameter definitions
265
    public static final ParamInfo<Integer> MAX_ITER = ParamInfoFactory
266
        .createParamInfo("maxIter", Integer.class)
267
        .setHasDefaultValue(100)
268
        .build();
269
    
270
    public static final ParamInfo<Double> TOLERANCE = ParamInfoFactory
271
        .createParamInfo("tolerance", Double.class)
272
        .setHasDefaultValue(1e-6)
273
        .build();
274
    
275
    @Override
276
    public Params getParams() {
277
        return params;
278
    }
279
    
280
    @Override
281
    public <V> MyEstimator set(ParamInfo<V> info, V value) {
282
        params.set(info, value);
283
        return this;
284
    }
285
    
286
    @Override
287
    public <V> V get(ParamInfo<V> info) {
288
        return params.get(info);
289
    }
290
    
291
    // Convenience methods
292
    public MyEstimator setMaxIter(int maxIter) {
293
        return set(MAX_ITER, maxIter);
294
    }
295
    
296
    public int getMaxIter() {
297
        return get(MAX_ITER);
298
    }
299
    
300
    public MyEstimator setTolerance(double tolerance) {
301
        return set(TOLERANCE, tolerance);
302
    }
303
    
304
    public double getTolerance() {
305
        return get(TOLERANCE);
306
    }
307
}
308
```
309

310
### ExtractParamInfosUtil Utility
311

312
Utility for extracting parameter information from WithParams classes.
313

314
```java { .api }
315
/**
316
 * Utility for extracting ParamInfo instances from WithParams classes
317
 */
318
public class ExtractParamInfosUtil {
319
    
320
    /** Extract all ParamInfo instances from a WithParams object */
321
    public static List<ParamInfo> extractParamInfos(WithParams s);
322
}
323
```
324

325
**Usage Example:**
326

327
```java
328
MyEstimator estimator = new MyEstimator();
329
List<ParamInfo> paramInfos = ExtractParamInfosUtil.extractParamInfos(estimator);
330

331
// Inspect available parameters
332
for (ParamInfo info : paramInfos) {
333
    System.out.println("Parameter: " + info.getName());
334
    System.out.println("Description: " + info.getDescription());
335
    System.out.println("Optional: " + info.isOptional());
336
    System.out.println("Default: " + info.getDefaultValue());
337
    System.out.println();
338
}
339
```
340

341
## Parameter System Benefits
342

343
The parameter system provides several key advantages:
344

345
1. **Type Safety**: Compile-time type checking prevents parameter type errors
346
2. **Validation**: Runtime validation ensures parameter values are valid
347
3. **Default Values**: Automatic fallback to sensible defaults
348
4. **Serialization**: JSON persistence for saving/loading configurations
349
5. **Documentation**: Built-in parameter descriptions and metadata
350
6. **Method Chaining**: Fluent API for configuration
351
7. **Backward Compatibility**: Alias support for parameter name changes