0
# Field References and Lazy Computation
1

2
The FieldReference system enables dynamic field linking and lazy computation in ML Collections. This powerful feature allows you to create dependencies between configuration fields, implement computed values, and build flexible parameter relationships essential for complex ML experiment setups.
3

4
## Capabilities
5

6
### FieldReference Operations
7

8
Core functionality for creating, manipulating, and resolving field references that enable lazy computation and dynamic parameter relationships.
9

10
```python { .api }
11
class FieldReference:
12
    def __init__(self, default, field_type=None, op=None, required=False):
13
        """
14
        Create a FieldReference.
15
        
16
        Args:
17
            default: Default value or function for the reference
18
            field_type: Type of value this reference holds
19
            op: Operation for lazy computation
20
            required (bool): Whether this reference is required
21
        """
22

23
    def get(self):
24
        """
25
        Get the computed/resolved value of the reference.
26
        
27
        Returns:
28
            The resolved value of the referenced field or computation
29
        """
30

31
    def set(self, value, type_safe=True):
32
        """
33
        Set the value of the reference.
34
        
35
        Args:
36
            value: New value to assign to the referenced field
37
            type_safe (bool): Whether to enforce type safety
38
        """
39

40
    def empty(self) -> bool:
41
        """
42
        Returns True if value is None.
43
        
44
        Returns:
45
            bool: True if the reference value is None
46
        """
47

48
    def get_type(self):
49
        """
50
        Returns the field type.
51
        
52
        Returns:
53
            type: Type of the field
54
        """
55

56
    def has_cycle(self, visited=None) -> bool:
57
        """
58
        Finds cycles in reference graph.
59
        
60
        Args:
61
            visited: Set of visited references for cycle detection
62
            
63
        Returns:
64
            bool: True if cycle detected
65
        """
66

67
    def copy(self) -> FieldReference:
68
        """
69
        Create a copy of the FieldReference.
70
        
71
        Returns:
72
            FieldReference: New FieldReference instance with same computation
73
        """
74

75
    def identity(self) -> FieldReference:
76
        """
77
        Identity operation returning self.
78
        
79
        Returns:
80
            FieldReference: Self reference
81
        """
82

83
    def attr(self, attr_name: str) -> FieldReference:
84
        """
85
        Attribute access operation.
86
        
87
        Args:
88
            attr_name (str): Attribute name to access
89
            
90
        Returns:
91
            FieldReference: Reference to attribute
92
        """
93

94
    def to_int(self) -> FieldReference:
95
        """
96
        Returns reference cast to int.
97
        
98
        Returns:
99
            FieldReference: Reference with int conversion
100
        """
101

102
    def to_float(self) -> FieldReference:
103
        """
104
        Returns reference cast to float.
105
        
106
        Returns:
107
            FieldReference: Reference with float conversion
108
        """
109

110
    def to_str(self) -> FieldReference:
111
        """
112
        Returns reference cast to str.
113
        
114
        Returns:
115
            FieldReference: Reference with str conversion
116
        """
117

118
    # Mathematical operators returning new FieldReferences
119
    def __add__(self, other) -> FieldReference: ...
120
    def __sub__(self, other) -> FieldReference: ...
121
    def __mul__(self, other) -> FieldReference: ...
122
    def __truediv__(self, other) -> FieldReference: ...
123
    def __floordiv__(self, other) -> FieldReference: ...
124
    def __pow__(self, other) -> FieldReference: ...
125
    def __mod__(self, other) -> FieldReference: ...
126
    def __and__(self, other) -> FieldReference: ...
127
    def __or__(self, other) -> FieldReference: ...
128
    def __xor__(self, other) -> FieldReference: ...
129
    def __neg__(self) -> FieldReference: ...
130
    def __abs__(self) -> FieldReference: ...
131
```
132

133
### Placeholder Creation
134

135
Create placeholder references that can be resolved later, enabling flexible configuration templates and parameter injection.
136

137
```python { .api }
138
def placeholder(field_type, required=False):
139
    """
140
    Create a FieldReference placeholder with specified type and required flag.
141
    
142
    Args:
143
        field_type: Type of value that this placeholder will hold
144
        required (bool): Whether this placeholder must be filled before use
145
        
146
    Returns:
147
        FieldReference: Placeholder reference that can be resolved later
148
    """
149

150
def required_placeholder(field_type):
151
    """
152
    Create a required FieldReference placeholder.
153
    
154
    Args:
155
        field_type: Type of value that this placeholder will hold
156
    
157
    Returns:
158
        FieldReference: Required placeholder that must be filled before use
159
    """
160
```
161

162
Usage examples:
163

164
```python
165
from ml_collections import ConfigDict
166
from ml_collections.config_dict import placeholder, required_placeholder
167

168
# Create config with placeholders
169
config = ConfigDict()
170
config.model_name = required_placeholder(str)
171
config.learning_rate = placeholder(float)  # Type-specified placeholder
172
config.batch_size = placeholder(int)
173

174
# Set required values
175
config.model_name = 'resnet50'
176

177
# Optional placeholders use defaults if not set
178
print(config.learning_rate)  # 0.001
179

180
# Set optional placeholder
181
config.batch_size = 32
182
print(config.batch_size)  # 32
183
```
184

185
### Dynamic Field Relationships
186

187
Create computed fields that automatically update based on other configuration values, enabling complex parameter dependencies.
188

189
```python
190
from ml_collections import ConfigDict, FieldReference
191

192
config = ConfigDict()
193
config.epochs = 100
194
config.steps_per_epoch = 1000
195

196
# Create computed field using get_ref
197
config.total_steps = config.get_ref('epochs') * config.get_ref('steps_per_epoch')
198

199
print(config.total_steps)  # 100000
200

201
# Changes propagate automatically
202
config.epochs = 200
203
print(config.total_steps)  # 200000
204
```
205

206
### Advanced Reference Patterns
207

208
Complex computation patterns and reference chains for sophisticated ML experiment configurations.
209

210
```python
211
# Multi-level dependencies
212
config = ConfigDict()
213
config.base_lr = 0.1
214
config.warmup_epochs = 5
215
config.total_epochs = 100
216

217
# Learning rate schedule with dependencies
218
config.warmup_lr = FieldReference(lambda: config.base_lr * 0.1)
219
config.peak_lr = FieldReference(lambda: config.base_lr)
220
config.final_lr = FieldReference(lambda: config.base_lr * 0.01)
221

222
# Compute warmup steps based on other parameters
223
config.steps_per_epoch = 1000
224
config.warmup_steps = FieldReference(
225
    lambda: config.warmup_epochs * config.steps_per_epoch
226
)
227

228
# Complex conditional logic
229
config.use_scheduler = True
230
config.current_lr = FieldReference(
231
    lambda: config.peak_lr if config.use_scheduler else config.base_lr
232
)
233
```
234

235
### Reference Resolution and Copying
236

237
Resolve reference chains and create independent copies of configurations with computed values.
238

239
```python
240
# Using ConfigDict method to resolve all references
241
config_with_references = ConfigDict()
242
config_with_references.a = 10
243
config_with_references.b = FieldReference(lambda: config_with_references.a * 2)
244
config_with_references.c = FieldReference(lambda: config_with_references.b + 5)
245

246
# Create resolved copy
247
resolved_config = config_with_references.copy_and_resolve_references()
248
print(resolved_config.a)  # 10
249
print(resolved_config.b)  # 20  
250
print(resolved_config.c)  # 25
251

252
# Individual reference operations
253
ref = config_with_references.get_ref('b')
254
print(ref.get())  # 20
255

256
# Copy reference for reuse
257
ref_copy = ref.copy()
258
```
259

260
### Error Handling
261

262
Understand and handle errors that can occur with field references and placeholders.
263

264
```python
265
from ml_collections.config_dict import RequiredValueError
266

267
config = ConfigDict()
268
config.required_field = required_placeholder()
269

270
# This raises RequiredValueError
271
try:
272
    value = config.required_field
273
except RequiredValueError as e:
274
    print(f"Required field not set: {e}")
275

276
# Set the required value
277
config.required_field = "model_name"
278
print(config.required_field)  # "model_name"
279
```
280

281
## Types
282

283
```python { .api }
284
class RequiredValueError(ValueError):
285
    """Raised when a required placeholder value is not provided."""
286

287
class _Op:
288
    """Internal operation representation for lazy computation."""
289
```