ML Collections

1.1.0 · active · verified Sat Apr 11

ML Collections is a library of Python collections designed for ML use cases. It provides dict-like data structures, primarily `ConfigDict` and `FrozenConfigDict`, which offer dot-based access, type safety, and other features useful for managing experiment configurations in a structured way. The library is actively maintained, with its current version being 1.1.0, and receives regular updates.

Warnings

gotcha Using `config_dict.get_ref()` creates a bidirectional dependency. If you change the referenced value, the original value also changes. For one-way references, use `config_dict.get_oneway_ref()` instead.
Fix: Replace `cfg.get_ref('field')` with `cfg.get_oneway_ref('field')` when a one-way dependency is desired.
gotcha ConfigDicts are largely type-safe: once a field is set with a particular type, reassigning a value of an incompatible type (e.g., `int` to a `str` field) will raise a `TypeError`. An exception is made for `int` values being assigned to `float` fields, which are automatically converted.
Fix: Ensure that assigned values match the initial type of the field, or explicitly cast them if a compatible conversion is desired (e.g., `str(integer_value)`).
gotcha When using `ml_collections.config_flags` to override boolean values from the command line, the syntax is specific: `--config.boolean_field` sets it to `True`, and `--noconfig.boolean_field` sets it to `False`. Standard `--config.boolean_field=value` (with 'true', 'false', 'True', 'False') is also supported.
Fix: Adhere to the `absl.flags`-like syntax for boolean overrides or use explicit `key=value` assignment.
breaking Initializing a `ConfigDict` with an `initial_dictionary` that contains lists or tuples with nested dictionaries, `ConfigDict`s, or `FieldReference`s directly can lead to errors. The internal reference structure must form a Directed Acyclic Graph (DAG).
Fix: Avoid nesting mutable dict-like structures directly within lists/tuples during initial `ConfigDict` construction or ensure a DAG structure. Consider creating nested `ConfigDict` instances explicitly for complex structures.

Install

pip install ml-collections Install with pip

Imports

ConfigDict
```
from ml_collections import config_dict
```
FrozenConfigDict
```
from ml_collections import config_dict
```
FieldReference
```
from ml_collections import config_dict
```
DEFINE_config_dict
```
from ml_collections import config_flags
```
DEFINE_config_file
```
from ml_collections import config_flags
```

Quickstart

This example demonstrates how to create a `ConfigDict`, assign and access values using dot notation, and illustrates its type-safe behavior. It also shows the exception for assigning integers to float fields.

from ml_collections import config_dict

# Create a ConfigDict
cfg = config_dict.ConfigDict()

# Assign values with dot notation
cfg.learning_rate = 0.001
cfg.optimizer = 'Adam'
cfg.model = config_dict.ConfigDict()
cfg.model.name = 'ResNet50'
cfg.model.num_layers = 50

# Access values
print(f"Learning rate: {cfg.learning_rate}")
print(f"Model name: {cfg.model.name}")

# ConfigDicts are type-safe (mostly)
try:
    cfg.learning_rate = 'high' # This will raise a TypeError
except TypeError as e:
    print(f"Caught expected error: {e}")

# Integer can be assigned to float fields
cfg.weight_decay = 1e-5
cfg.weight_decay = 0 # This works as int -> float conversion is allowed
print(f"Weight decay: {cfg.weight_decay}")

view raw JSON →