ML Collections

A FieldReference allows multiple fields to point to the same underlying value. If the value of the reference changes, all fields pointing to it will reflect the change.

• placeholder(type): A shortcut to create a FieldReference with a None default value and a specific type constraint.
• Indirection Note: If you assign a FieldReference to another field via standard assignment (e.g., cfg.field2 = cfg.field1), the indirection is lost and it becomes a standard value field. To maintain the link, ensure you are working with the reference object itself.

To change the value of a FieldReference, use .set(value). To retrieve the actual value, use .get().

from ml_collections import config_dict

placeholder = config_dict.FieldReference(0)
cfg = config_dict.ConfigDict()
cfg.placeholder = placeholder
cfg.optional = config_dict.placeholder(int)

cfg.optional = 1555
cfg.placeholder = 1  # Changes the value for all fields tied to this placeholder

You can perform lazy computations by using FieldReference objects within operations. This allows values to be re-calculated automatically when the underlying reference changes.

Using FieldReferences directly

When you perform an operation (like + or *) on a FieldReference, the result is a new FieldReference that represents the computation.

• Use .get() to execute the operation and get the result.
• Use .set() on the original reference to update the entire computation chain.

Using ConfigDict.get_ref()

Within a ConfigDict, you can trigger lazy evaluation of specific fields using .get_ref('field_name').

• get_ref(name): Creates a bi-directional dependency. Changing the referenced field will update the computed field, but changing the computed field will also change the referenced field (one-way reference gotcha).
• get_oneway_ref(name): Creates a one-way dependency. Changing the computed field will not affect the original referenced field.

Warning on Cycles: You cannot create cycles. Attempting to assign a computed field back to one of its own dependencies will raise a config_dict.MutabilityError.

from ml_collections import config_dict

config = config_dict.ConfigDict()
config.integer_field = 2
config.float_field = 2.5

# Standard assignment (not lazy)
config.no_lazy = config.integer_field * config.float_field

# Lazy evaluation using get_ref
config.lazy_integer = config.get_ref('integer_field') * config.float_field

config.integer_field = 3
print(config.no_lazy)     # 5.0 (uses original value)
print(config.lazy_integer) # 7.5 (re-evaluated)

The ConfigDict class provides a "dict-like" data structure with dot-based access to nested elements. It is designed for expressing configurations for models and experiments.

Key features include:

• Dot-based access: Access nested fields using cfg.field.subfield.
• Type safety: Assigning a value of an incompatible type raises a TypeError (e.g., assigning a string to an integer field).
• Type conversion exception: int values can be assigned to float fields and will be automatically converted.
• Locking: Use .lock() to prevent adding or deleting fields, which helps catch spelling mistakes.
• Human-readable printing: Prints in a valid YAML format.
• Keyword argument support: Fields can be passed using the ** operator.

from ml_collections import config_dict

cfg = config_dict.ConfigDict()
cfg.float_field = 12.6
cfg.integer_field = 123
cfg.nested = config_dict.ConfigDict()
cfg.nested.string_field = 'tom'

print(cfg.integer_field)  # 123
print(cfg['integer_field'])  # 123

A FrozenConfigDict is an immutable and hashable version of ConfigDict. It is useful when you want to ensure a configuration cannot be modified after creation.

When initializing a FrozenConfigDict with a dictionary containing lists or sets, it automatically converts them to immutable types (e.g., lists become tuples, sets become frozensets).

Converting between types:

• To turn a FrozenConfigDict back into a mutable ConfigDict, use .as_configdict() or pass the frozen object to the ConfigDict() constructor.
• To create a FrozenConfigDict from an existing ConfigDict, pass the ConfigDict instance to the FrozenConfigDict() constructor.

from ml_collections import config_dict

initial_dictionary = {
    'int': 1,
    'list': [1, 2],
}

cfg = config_dict.ConfigDict(initial_dictionary)
frozen_dict = config_dict.FrozenConfigDict(initial_dictionary)

# FrozenConfigDict is immutable
try:
  frozen_dict.int = 2
except AttributeError as e:
  print(e)

# Converting back to mutable
thawed_cfg = frozen_dict.as_configdict()