0
# Configuration Flags
1

2
Integration with absl.flags for loading configurations from files, defining command-line overrides, and managing parameterized experiment configurations. This module bridges ML Collections with command-line argument parsing, enabling flexible experiment management and configuration overrides.
3

4
## Capabilities
5

6
### File-based Configuration Loading
7

8
Load configurations from Python files containing a `get_config()` function, enabling organized experiment configuration management.
9

10
```python { .api }
11
def DEFINE_config_file(
12
    name: str,
13
    default: Optional[str] = None,
14
    help_string: str = "path to config file.",
15
    flag_values = FLAGS,
16
    lock_config: bool = True,
17
    accept_new_attributes: bool = False,
18
    sys_argv: Optional[List[str]] = None,
19
    **kwargs
20
):
21
    """
22
    Define a flag that loads configuration from a Python file.
23
    
24
    Args:
25
        name (str): Name of the flag
26
        default (str, optional): Default config file path
27
        help_string (str): Help text for the flag
28
        flag_values: FlagValues instance to register with (default: FLAGS)
29
        lock_config (bool): Whether to lock config after loading (default: True)
30
        accept_new_attributes (bool): Allow new attributes in overrides (default: False)
31
        sys_argv (List[str], optional): Alternative sys.argv for parsing
32
        **kwargs: Additional arguments passed to absl.flags
33
        
34
    Returns:
35
        Flag object for the configuration file
36
    """
37
```
38

39
Usage example:
40

41
```python
42
from absl import app, flags
43
from ml_collections import config_flags
44

45
# Define config file flag
46
FLAGS = flags.FLAGS
47
config_flags.DEFINE_config_file('config', default='configs/default.py')
48

49
def main(argv):
50
    config = FLAGS.config
51
    print(f"Model: {config.model}")
52
    print(f"Learning rate: {config.learning_rate}")
53

54
if __name__ == '__main__':
55
    app.run(main)
56
```
57

58
Example config file (`configs/default.py`):
59

60
```python
61
from ml_collections import ConfigDict
62

63
def get_config():
64
    config = ConfigDict()
65
    config.model = 'resnet50'
66
    config.learning_rate = 0.001
67
    config.batch_size = 32
68
    config.optimizer = ConfigDict()
69
    config.optimizer.name = 'adam'
70
    config.optimizer.beta1 = 0.9
71
    return config
72
```
73

74
### Direct ConfigDict Flags
75

76
Define flags that accept ConfigDict objects directly, useful for programmatic configuration setup.
77

78
```python { .api }
79
def DEFINE_config_dict(
80
    name: str,
81
    config: ConfigDict,
82
    help_string: str = "ConfigDict instance.",
83
    flag_values = FLAGS,
84
    lock_config: bool = True,
85
    accept_new_attributes: bool = False,
86
    sys_argv: Optional[List[str]] = None,
87
    **kwargs
88
):
89
    """
90
    Define a flag that accepts a ConfigDict directly.
91
    
92
    Args:
93
        name (str): Name of the flag
94
        config (ConfigDict): Default ConfigDict value
95
        help_string (str): Help text for the flag
96
        flag_values: FlagValues instance to register with (default: FLAGS)
97
        lock_config (bool): Whether to lock config after loading (default: True)
98
        accept_new_attributes (bool): Allow new attributes in overrides (default: False)
99
        sys_argv (List[str], optional): Alternative sys.argv for parsing
100
        **kwargs: Additional arguments passed to absl.flags
101
        
102
    Returns:
103
        Flag object for the ConfigDict
104
    """
105
```
106

107
### Dataclass Configuration Integration
108

109
Define flags for dataclass-based configurations, providing type-safe alternatives to dictionary-based configs.
110

111
```python { .api }
112
def DEFINE_config_dataclass(
113
    name: str,
114
    config_class,
115
    help_string: str = "Dataclass configuration.",
116
    flag_values = FLAGS,
117
    sys_argv: Optional[List[str]] = None,
118
    parse_fn: Optional[Callable[[Any], Any]] = None,
119
    **kwargs
120
):
121
    """
122
    Define a flag for dataclass-based configurations.
123
    
124
    Args:
125
        name (str): Name of the flag
126
        config_class: Dataclass type for the configuration
127
        help_string (str): Help text for the flag
128
        flag_values: FlagValues instance to register with (default: FLAGS)
129
        sys_argv (List[str], optional): Alternative sys.argv for parsing
130
        parse_fn (Callable, optional): Custom parse function for dataclass fields
131
        **kwargs: Additional arguments passed to absl.flags
132
        
133
    Returns:
134
        Flag object for the dataclass configuration
135
    """
136
```
137

138
### Configuration File Utilities
139

140
Access metadata and override information from configuration flags.
141

142
```python { .api }
143
def get_config_filename(flag_name: str) -> Optional[str]:
144
    """
145
    Return the filename of a config file flag.
146
    
147
    Args:
148
        flag_name (str): Name of the config file flag
149
        
150
    Returns:
151
        str or None: Path to the config file, or None if not set
152
    """
153

154
def get_override_values(flag_name: str) -> Dict[str, Any]:
155
    """
156
    Return dictionary of override values from command line.
157
    
158
    Args:
159
        flag_name (str): Name of the config flag
160
        
161
    Returns:
162
        dict: Dictionary containing all override values applied
163
    """
164

165
def is_config_flag(flag) -> bool:
166
    """
167
    Type checking utility for ConfigFlags.
168
    
169
    Args:
170
        flag: Flag object to check
171
        
172
    Returns:
173
        bool: True if flag is a config flag type
174
    """
175
```
176

177
### Command-line Override System
178

179
Override nested configuration values directly from the command line using dot notation.
180

181
Command-line usage:
182

183
```bash
184
# Override nested values with dot notation
185
python train.py --config=configs/resnet.py \
186
    --config.learning_rate=0.01 \
187
    --config.model.num_layers=50 \
188
    --config.optimizer.name=sgd
189

190
# Override with complex types
191
python train.py --config=configs/base.py \
192
    --config.data.image_size="(224, 224)" \
193
    --config.augmentation.enabled=True
194
```
195

196
### Custom Type Parsers
197

198
Register custom parsers for specialized types in configuration overrides.
199

200
```python { .api }
201
def register_flag_parser_for_type(type_name, parser_fn):
202
    """
203
    Register a parser for a specific type.
204
    
205
    Args:
206
        type_name: Type to register parser for
207
        parser_fn: Function that parses string to the type
208
    """
209

210
def register_flag_parser(*, parser: flags.ArgumentParser):
211
    """
212
    Decorator to register custom flag parsers for types.
213
    
214
    Args:
215
        parser: ArgumentParser instance for the type
216
        
217
    Returns:
218
        Decorator function for parser registration
219
    """
220
```
221

222
Usage example:
223

224
```python
225
from ml_collections import config_flags
226
from absl import flags
227
import numpy as np
228

229
# Register custom parser for numpy arrays
230
@config_flags.register_flag_parser(parser=flags.ArgumentParser())
231
def parse_numpy_array(value):
232
    # Parse string representation to numpy array
233
    return np.array(eval(value))
234

235
# Now you can override numpy array fields from command line
236
# --config.weights="[1.0, 2.0, 3.0]"
237
```
238

239
### Parameterized Configuration Files
240

241
Pass parameters to config files for dynamic configuration generation.
242

243
Config file with parameters (`configs/parameterized.py`):
244

245
```python
246
from ml_collections import ConfigDict
247

248
def get_config(model_size='base'):
249
    config = ConfigDict()
250
    
251
    if model_size == 'small':
252
        config.hidden_size = 256
253
        config.num_layers = 6
254
    elif model_size == 'base':
255
        config.hidden_size = 512
256
        config.num_layers = 12
257
    elif model_size == 'large':
258
        config.hidden_size = 1024
259
        config.num_layers = 24
260
    
261
    config.learning_rate = 0.001
262
    return config
263
```
264

265
Usage:
266

267
```bash
268
# Pass parameters to config function
269
python train.py --config=configs/parameterized.py \
270
    --config.model_size=large
271
```
272

273
### Supported Override Types
274

275
ML Collections supports command-line overrides for the following types:
276

277
- **Basic types**: `int`, `float`, `bool`, `str`
278
- **Collections**: `tuple`, `list` (converted to tuples)
279
- **Enums**: `enum.Enum` values
280
- **Nested structures**: Arbitrary depth with dot notation
281
- **Complex tuples**: Mixed types within tuples
282

283
Examples:
284

285
```bash
286
# Basic types
287
--config.learning_rate=0.01
288
--config.enabled=True
289
--config.model_name="resnet50"
290

291
# Tuples and nested structures  
292
--config.image_size="(224, 224)"
293
--config.data.train_split=0.8
294
--config.optimizer.params.beta1=0.9
295

296
# Complex nested overrides
297
--config.model.layers.0.filters=64
298
--config.scheduler.milestones="[30, 60, 90]"
299
```
300

301
### Special Dataclass Values
302

303
For dataclass configurations, ML Collections supports special values for optional fields:
304

305
- **`build`/`True`/`1`**: Create default instance of the dataclass
306
- **`none`/`False`/`0`**: Set field to None (for Optional fields)
307

308
Example:
309
```bash
310
# Create default instance
311
python train.py --config.model=build
312

313
# Set to None
314
python train.py --config.optional_field=none
315
```
316

317
### Backward Compatibility
318

319
ML Collections provides backward compatibility exports for legacy code:
320

321
```python { .api }
322
from ml_collections.config_flags import GetValue, GetType, SetValue
323

324
# Legacy functions (deprecated)
325
GetValue = config_path.get_value
326
GetType = config_path.get_type  
327
SetValue = config_path.set_value
328
```
329

330
### Advanced Features
331

332
#### Flag Properties
333

334
Config flags provide additional properties for introspection:
335

336
```python
337
# Access config filename (including parameterization)
338
config_filename = FLAGS.config.config_filename
339

340
# Get all override values as flat dictionary
341
override_values = FLAGS.config.override_values
342
```
343

344
#### Enum Support
345

346
ML Collections supports enum fields with case-insensitive parsing:
347

348
```python
349
from enum import Enum
350

351
class ModelType(Enum):
352
    RESNET = "resnet"
353
    EFFICIENTNET = "efficientnet"
354

355
# Command line: --config.model_type=RESNET or --config.model_type=resnet
356
```
357

358
#### Tuple Multi-flag Support
359

360
Tuple fields support repeated flags for building sequences:
361

362
```bash
363
# Build tuple from multiple flags
364
python train.py --config.layers 64 --config.layers 128 --config.layers 256
365
```
366

367
## Types
368

369
```python { .api }
370
class UnsupportedOperationError(Exception):
371
    """Raised for unsupported flag operations."""
372

373
class FlagOrderError(ValueError):
374
    """Raised when flags are accessed in wrong order."""
375

376
class UnparsedFlagError(ValueError):
377
    """Raised when flags haven't been parsed."""
378
```