0
# ML Collections
1

2
ML Collections is a library of Python collections designed specifically for machine learning use cases. It provides specialized configuration dictionaries with dot-based access, type safety, locking mechanisms, lazy computation, and human-readable YAML serialization - essential features for managing complex ML experiment configurations and model parameters.
3

4
## Package Information
5

6
- **Package Name**: ml-collections
7
- **Language**: Python
8
- **Installation**: `pip install ml-collections`
9
- **Python Requirement**: >=3.10
10

11
## Core Imports
12

13
```python
14
import ml_collections
15
from ml_collections import ConfigDict, FieldReference, FrozenConfigDict
16
```
17

18
Individual imports:
19

20
```python
21
from ml_collections.config_dict import (
22
    ConfigDict, FrozenConfigDict, FieldReference,
23
    create, placeholder, required_placeholder, recursive_rename,
24
    MutabilityError, RequiredValueError, JSONDecodeError, CustomJSONEncoder
25
)
26
from ml_collections.config_flags import (
27
    DEFINE_config_file, DEFINE_config_dict, DEFINE_config_dataclass,
28
    get_config_filename, get_override_values, is_config_flag,
29
    register_flag_parser, register_flag_parser_for_type,
30
    UnsupportedOperationError, FlagOrderError, UnparsedFlagError
31
)
32
```
33

34
## Basic Usage
35

36
```python
37
from ml_collections import ConfigDict, FieldReference, FrozenConfigDict
38

39
# Create a mutable configuration dictionary
40
config = ConfigDict()
41
config.model = 'resnet50'
42
config.learning_rate = 0.001
43
config.batch_size = 32
44

45
# Nested configurations with dot access
46
config.optimizer = ConfigDict()
47
config.optimizer.name = 'adam'
48
config.optimizer.beta1 = 0.9
49
config.optimizer.beta2 = 0.999
50

51
# Access fields with dot notation
52
print(config.learning_rate)  # 0.001
53
print(config.optimizer.name)  # 'adam'
54

55
# Create immutable configuration for reproducibility
56
frozen_config = FrozenConfigDict(config)
57
print(hash(frozen_config))  # Hashable for caching
58

59
# Field references for dynamic linking
60
config.steps_per_epoch = 1000
61
config.epochs = 10
62
config.total_steps = config.get_ref('epochs') * config.get_ref('steps_per_epoch')
63
print(config.total_steps)  # 10000
64
```
65

66
## Architecture
67

68
ML Collections follows a layered architecture:
69

70
- **ConfigDict/FrozenConfigDict**: Core dictionary classes with ML-specific enhancements
71
- **FieldReference System**: Lazy computation and dynamic field linking
72
- **Type Safety Layer**: Runtime type checking and validation
73
- **Locking Mechanism**: Configuration structure protection
74
- **Serialization Layer**: YAML-compatible human-readable output
75
- **Command-line Integration**: absl.flags integration for experiment management
76

77
This design enables reproducible ML experiments while maintaining flexibility for complex parameter configurations and nested model settings.
78

79
## Capabilities
80

81
### Configuration Dictionaries
82

83
Core ConfigDict and FrozenConfigDict classes providing dot-based access, type safety, locking mechanisms, and ML-specific features for managing experiment configurations.
84

85
```python { .api }
86
class ConfigDict:
87
    def __init__(self, initial_dictionary=None, type_safe=True): ...
88
    def lock(self) -> None: ...
89
    def unlock(self) -> None: ...
90
    def get_ref(self, key: str) -> FieldReference: ...
91

92
class FrozenConfigDict:
93
    def __init__(self, initial_dictionary=None): ...
94
    def as_configdict(self) -> ConfigDict: ...
95
```
96

97
[Configuration Dictionaries](./config-dict.md)
98

99
### Field References and Lazy Computation
100

101
Dynamic field linking system enabling lazy computation, parameter dependencies, and flexible configuration relationships for complex ML experiment setups.
102

103
```python { .api }
104
class FieldReference:
105
    def get(self): ...
106
    def set(self, value): ...
107
    def copy(self) -> FieldReference: ...
108

109
def placeholder(fn_or_value=None, *, required=False): ...
110
def required_placeholder(): ...
111
```
112

113
[Field References](./field-references.md)
114

115
### Command-line Configuration Flags
116

117
Integration with absl.flags for loading configurations from files, defining command-line overrides, and managing parameterized experiment configurations.
118

119
```python { .api }
120
def DEFINE_config_file(
121
    name: str,
122
    default: Optional[str] = None,
123
    help_string: str = "path to config file.",
124
    **kwargs
125
): ...
126

127
def DEFINE_config_dict(
128
    name: str, 
129
    config: ConfigDict,
130
    help_string: str = "ConfigDict instance.",
131
    **kwargs
132
): ...
133
```
134

135
[Configuration Flags](./config-flags.md)
136

137
## Types
138

139
```python { .api }
140
class RequiredValueError(ValueError):
141
    """Raised when a required placeholder value is not provided."""
142

143
class MutabilityError(AttributeError):
144
    """Raised when attempting to modify locked or immutable structures."""
145

146
class JSONDecodeError(ValueError):
147
    """Raised when JSON decoding fails."""
148

149
class CustomJSONEncoder:
150
    """JSON encoder for ML Collections objects."""
151

152
class UnsupportedOperationError(Exception):
153
    """Raised for unsupported flag operations."""
154

155
class FlagOrderError(ValueError):
156
    """Raised when flags are accessed in wrong order."""
157

158
class UnparsedFlagError(ValueError):
159
    """Raised when flags haven't been parsed."""
160
```