tessl/pypi-ml-collections

ML Collections is a library of Python collections designed for ML usecases.

—

Pending

Overview

Eval results

Files

Field References and Lazy Computation

Name: tessl/pypi-ml-collections
Author: tessl

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.

Capabilities

FieldReference Operations

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

class FieldReference:
    def __init__(self, default, field_type=None, op=None, required=False):
        """
        Create a FieldReference.
        
        Args:
            default: Default value or function for the reference
            field_type: Type of value this reference holds
            op: Operation for lazy computation
            required (bool): Whether this reference is required
        """

    def get(self):
        """
        Get the computed/resolved value of the reference.
        
        Returns:
            The resolved value of the referenced field or computation
        """

    def set(self, value, type_safe=True):
        """
        Set the value of the reference.
        
        Args:
            value: New value to assign to the referenced field
            type_safe (bool): Whether to enforce type safety
        """

    def empty(self) -> bool:
        """
        Returns True if value is None.
        
        Returns:
            bool: True if the reference value is None
        """

    def get_type(self):
        """
        Returns the field type.
        
        Returns:
            type: Type of the field
        """

    def has_cycle(self, visited=None) -> bool:
        """
        Finds cycles in reference graph.
        
        Args:
            visited: Set of visited references for cycle detection
            
        Returns:
            bool: True if cycle detected
        """

    def copy(self) -> FieldReference:
        """
        Create a copy of the FieldReference.
        
        Returns:
            FieldReference: New FieldReference instance with same computation
        """

    def identity(self) -> FieldReference:
        """
        Identity operation returning self.
        
        Returns:
            FieldReference: Self reference
        """

    def attr(self, attr_name: str) -> FieldReference:
        """
        Attribute access operation.
        
        Args:
            attr_name (str): Attribute name to access
            
        Returns:
            FieldReference: Reference to attribute
        """

    def to_int(self) -> FieldReference:
        """
        Returns reference cast to int.
        
        Returns:
            FieldReference: Reference with int conversion
        """

    def to_float(self) -> FieldReference:
        """
        Returns reference cast to float.
        
        Returns:
            FieldReference: Reference with float conversion
        """

    def to_str(self) -> FieldReference:
        """
        Returns reference cast to str.
        
        Returns:
            FieldReference: Reference with str conversion
        """

    # Mathematical operators returning new FieldReferences
    def __add__(self, other) -> FieldReference: ...
    def __sub__(self, other) -> FieldReference: ...
    def __mul__(self, other) -> FieldReference: ...
    def __truediv__(self, other) -> FieldReference: ...
    def __floordiv__(self, other) -> FieldReference: ...
    def __pow__(self, other) -> FieldReference: ...
    def __mod__(self, other) -> FieldReference: ...
    def __and__(self, other) -> FieldReference: ...
    def __or__(self, other) -> FieldReference: ...
    def __xor__(self, other) -> FieldReference: ...
    def __neg__(self) -> FieldReference: ...
    def __abs__(self) -> FieldReference: ...

Placeholder Creation

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

def placeholder(field_type, required=False):
    """
    Create a FieldReference placeholder with specified type and required flag.
    
    Args:
        field_type: Type of value that this placeholder will hold
        required (bool): Whether this placeholder must be filled before use
        
    Returns:
        FieldReference: Placeholder reference that can be resolved later
    """

def required_placeholder(field_type):
    """
    Create a required FieldReference placeholder.
    
    Args:
        field_type: Type of value that this placeholder will hold
    
    Returns:
        FieldReference: Required placeholder that must be filled before use
    """

Usage examples:

from ml_collections import ConfigDict
from ml_collections.config_dict import placeholder, required_placeholder

# Create config with placeholders
config = ConfigDict()
config.model_name = required_placeholder(str)
config.learning_rate = placeholder(float)  # Type-specified placeholder
config.batch_size = placeholder(int)

# Set required values
config.model_name = 'resnet50'

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

# Set optional placeholder
config.batch_size = 32
print(config.batch_size)  # 32

Dynamic Field Relationships

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

from ml_collections import ConfigDict, FieldReference

config = ConfigDict()
config.epochs = 100
config.steps_per_epoch = 1000

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

print(config.total_steps)  # 100000

# Changes propagate automatically
config.epochs = 200
print(config.total_steps)  # 200000

Advanced Reference Patterns

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

# Multi-level dependencies
config = ConfigDict()
config.base_lr = 0.1
config.warmup_epochs = 5
config.total_epochs = 100

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

# Compute warmup steps based on other parameters
config.steps_per_epoch = 1000
config.warmup_steps = FieldReference(
    lambda: config.warmup_epochs * config.steps_per_epoch
)

# Complex conditional logic
config.use_scheduler = True
config.current_lr = FieldReference(
    lambda: config.peak_lr if config.use_scheduler else config.base_lr
)

Reference Resolution and Copying

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

# Using ConfigDict method to resolve all references
config_with_references = ConfigDict()
config_with_references.a = 10
config_with_references.b = FieldReference(lambda: config_with_references.a * 2)
config_with_references.c = FieldReference(lambda: config_with_references.b + 5)

# Create resolved copy
resolved_config = config_with_references.copy_and_resolve_references()
print(resolved_config.a)  # 10
print(resolved_config.b)  # 20  
print(resolved_config.c)  # 25

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

# Copy reference for reuse
ref_copy = ref.copy()

Error Handling

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

from ml_collections.config_dict import RequiredValueError

config = ConfigDict()
config.required_field = required_placeholder()

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

# Set the required value
config.required_field = "model_name"
print(config.required_field)  # "model_name"

Types

class RequiredValueError(ValueError):
    """Raised when a required placeholder value is not provided."""

class _Op:
    """Internal operation representation for lazy computation."""

Install with Tessl CLI