|
| 1 | +# Copyright 2023 DeepMind Technologies Limited |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +# you may not use this file except in compliance with the License. |
| 5 | +# You may obtain a copy of the License at |
| 6 | +# |
| 7 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +# |
| 9 | +# Unless required by applicable law or agreed to in writing, software |
| 10 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +# See the License for the specific language governing permissions and |
| 13 | +# limitations under the License. |
| 14 | +# ============================================================================== |
| 15 | +"""MLX dataclass utilities for MJX. |
| 16 | +
|
| 17 | +Ported from JAX pytree dataclasses to plain Python dataclasses with MLX array |
| 18 | +support. Instead of JAX pytree registration, we provide a `tree_map` helper |
| 19 | +that applies a function to all mlx.core.array fields in a dataclass. |
| 20 | +""" |
| 21 | + |
| 22 | +import copy |
| 23 | +import dataclasses |
| 24 | +from typing import Any, Callable, Dict, Optional, Sequence, Tuple, TypeVar |
| 25 | + |
| 26 | +import mlx.core as mx |
| 27 | +import numpy as np |
| 28 | + |
| 29 | +_T = TypeVar('_T') |
| 30 | + |
| 31 | + |
| 32 | +def _is_array_field(value: Any) -> bool: |
| 33 | + """Check if a value is an MLX array or a nested dataclass containing arrays.""" |
| 34 | + if isinstance(value, mx.array): |
| 35 | + return True |
| 36 | + if isinstance(value, np.ndarray): |
| 37 | + return False # numpy arrays are treated as metadata, not mapped over |
| 38 | + if dataclasses.is_dataclass(value) and not isinstance(value, type): |
| 39 | + return True |
| 40 | + if isinstance(value, (list, tuple)): |
| 41 | + return any(_is_array_field(v) for v in value) |
| 42 | + if isinstance(value, dict): |
| 43 | + return any(_is_array_field(v) for v in value.values()) |
| 44 | + return False |
| 45 | + |
| 46 | + |
| 47 | +def _apply_to_arrays(fn: Callable, value: Any) -> Any: |
| 48 | + """Recursively apply fn to all mx.array leaves in a nested structure.""" |
| 49 | + if isinstance(value, mx.array): |
| 50 | + return fn(value) |
| 51 | + if dataclasses.is_dataclass(value) and not isinstance(value, type): |
| 52 | + return tree_map(fn, value) |
| 53 | + if isinstance(value, tuple): |
| 54 | + mapped = tuple(_apply_to_arrays(fn, v) for v in value) |
| 55 | + # Preserve namedtuple types |
| 56 | + if hasattr(type(value), '_fields'): |
| 57 | + return type(value)(*mapped) |
| 58 | + return mapped |
| 59 | + if isinstance(value, list): |
| 60 | + return [_apply_to_arrays(fn, v) for v in value] |
| 61 | + if isinstance(value, dict): |
| 62 | + return {k: _apply_to_arrays(fn, v) for k, v in value.items()} |
| 63 | + return value |
| 64 | + |
| 65 | + |
| 66 | +def tree_map(fn: Callable, node: _T, *rest: Any) -> _T: |
| 67 | + """Apply fn to all mx.array fields in a dataclass, returning a new instance. |
| 68 | +
|
| 69 | + This is the MLX replacement for jax.tree_util.tree_map. It recursively |
| 70 | + traverses dataclass fields and applies fn to every mx.array leaf. |
| 71 | +
|
| 72 | + Args: |
| 73 | + fn: function to apply to each mx.array leaf. |
| 74 | + node: a dataclass instance to map over. |
| 75 | + *rest: additional dataclass instances to map over in parallel (like |
| 76 | + jax.tree_util.tree_map with multiple trees). |
| 77 | +
|
| 78 | + Returns: |
| 79 | + A new dataclass instance with fn applied to all array fields. |
| 80 | + """ |
| 81 | + if not dataclasses.is_dataclass(node) or isinstance(node, type): |
| 82 | + raise TypeError(f'tree_map expects a dataclass instance, got {type(node)}') |
| 83 | + |
| 84 | + if rest: |
| 85 | + # Multi-tree map: apply fn(leaf_from_node, leaf_from_rest0, ...) |
| 86 | + return _tree_map_multi(fn, node, *rest) |
| 87 | + |
| 88 | + updates = {} |
| 89 | + for field in dataclasses.fields(node): |
| 90 | + value = getattr(node, field.name) |
| 91 | + mapped = _apply_to_arrays(fn, value) |
| 92 | + if mapped is not value: |
| 93 | + updates[field.name] = mapped |
| 94 | + |
| 95 | + if updates: |
| 96 | + return dataclasses.replace(node, **updates) |
| 97 | + return node |
| 98 | + |
| 99 | + |
| 100 | +def _apply_to_arrays_multi(fn: Callable, *values: Any) -> Any: |
| 101 | + """Multi-tree version of _apply_to_arrays.""" |
| 102 | + first = values[0] |
| 103 | + if isinstance(first, mx.array): |
| 104 | + return fn(*values) |
| 105 | + if dataclasses.is_dataclass(first) and not isinstance(first, type): |
| 106 | + return _tree_map_multi(fn, *values) |
| 107 | + if isinstance(first, tuple): |
| 108 | + mapped = tuple( |
| 109 | + _apply_to_arrays_multi(fn, *(v[i] for v in values)) |
| 110 | + for i in range(len(first)) |
| 111 | + ) |
| 112 | + if hasattr(type(first), '_fields'): |
| 113 | + return type(first)(*mapped) |
| 114 | + return mapped |
| 115 | + if isinstance(first, list): |
| 116 | + return [ |
| 117 | + _apply_to_arrays_multi(fn, *(v[i] for v in values)) |
| 118 | + for i in range(len(first)) |
| 119 | + ] |
| 120 | + if isinstance(first, dict): |
| 121 | + return { |
| 122 | + k: _apply_to_arrays_multi(fn, *(v[k] for v in values)) |
| 123 | + for k in first |
| 124 | + } |
| 125 | + return first |
| 126 | + |
| 127 | + |
| 128 | +def _tree_map_multi(fn: Callable, node: _T, *rest: Any) -> _T: |
| 129 | + """Multi-tree map implementation.""" |
| 130 | + updates = {} |
| 131 | + for field in dataclasses.fields(node): |
| 132 | + values = [getattr(node, field.name)] + [ |
| 133 | + getattr(r, field.name) for r in rest |
| 134 | + ] |
| 135 | + mapped = _apply_to_arrays_multi(fn, *values) |
| 136 | + if mapped is not values[0]: |
| 137 | + updates[field.name] = mapped |
| 138 | + |
| 139 | + if updates: |
| 140 | + return dataclasses.replace(node, **updates) |
| 141 | + return node |
| 142 | + |
| 143 | + |
| 144 | +def dataclass(clz: _T) -> _T: |
| 145 | + """Create a frozen dataclass with a replace() method. |
| 146 | +
|
| 147 | + MLX port: no pytree registration needed. We just create a standard frozen |
| 148 | + dataclass and attach `replace` as a convenience method. |
| 149 | +
|
| 150 | + Args: |
| 151 | + clz: the class to register as a dataclass. |
| 152 | +
|
| 153 | + Returns: |
| 154 | + The resulting frozen dataclass. |
| 155 | + """ |
| 156 | + data_clz = dataclasses.dataclass(frozen=True)(clz) |
| 157 | + data_clz.replace = dataclasses.replace |
| 158 | + return data_clz |
| 159 | + |
| 160 | + |
| 161 | +TNode = TypeVar('TNode', bound='PyTreeNode') |
| 162 | + |
| 163 | + |
| 164 | +class PyTreeNode: |
| 165 | + """Base class for dataclasses that should act like array-carrying nodes. |
| 166 | +
|
| 167 | + MLX port of the JAX PyTreeNode. Instead of registering with JAX's pytree |
| 168 | + system, this simply creates a frozen dataclass with convenience methods. |
| 169 | + The `tree_map` function can be used to map over array fields. |
| 170 | + """ |
| 171 | + |
| 172 | + def __init_subclass__(cls, **kwargs): |
| 173 | + # Pop register_as_pytree if passed (for compatibility), but ignore it |
| 174 | + kwargs.pop('register_as_pytree', None) |
| 175 | + super().__init_subclass__(**kwargs) |
| 176 | + dataclass(cls) |
| 177 | + |
| 178 | + def __init__(self, *args, **kwargs): |
| 179 | + # stub for type checkers |
| 180 | + raise NotImplementedError |
| 181 | + |
| 182 | + def replace(self: TNode, **overrides) -> TNode: |
| 183 | + # stub for type checkers |
| 184 | + raise NotImplementedError |
| 185 | + |
| 186 | + @classmethod |
| 187 | + def fields(cls) -> Tuple[dataclasses.Field, ...]: # pylint: disable=g-bare-generic |
| 188 | + return dataclasses.fields(cls) |
| 189 | + |
| 190 | + def tree_replace( |
| 191 | + self, params: Dict[str, Optional[mx.array]] |
| 192 | + ) -> 'PyTreeNode': |
| 193 | + """Replace nested fields using dot-separated keys.""" |
| 194 | + new = self |
| 195 | + for k, v in params.items(): |
| 196 | + new = _tree_replace(new, k.split('.'), v) |
| 197 | + return new |
| 198 | + |
| 199 | + |
| 200 | +def _tree_replace( |
| 201 | + base: PyTreeNode, |
| 202 | + attr: Sequence[str], |
| 203 | + val: Optional[mx.array], |
| 204 | +) -> PyTreeNode: |
| 205 | + """Sets attributes in a dataclass with values.""" |
| 206 | + if not attr: |
| 207 | + return base |
| 208 | + |
| 209 | + # special case for List attribute |
| 210 | + if len(attr) > 1 and isinstance(getattr(base, attr[0]), list): |
| 211 | + lst = copy.deepcopy(getattr(base, attr[0])) |
| 212 | + |
| 213 | + for i, g in enumerate(lst): |
| 214 | + if not hasattr(g, attr[1]): |
| 215 | + continue |
| 216 | + v = val if not hasattr(val, '__iter__') else val[i] |
| 217 | + lst[i] = _tree_replace(g, attr[1:], v) |
| 218 | + |
| 219 | + return base.replace(**{attr[0]: lst}) |
| 220 | + |
| 221 | + if len(attr) == 1: |
| 222 | + return base.replace(**{attr[0]: val}) |
| 223 | + |
| 224 | + return base.replace( |
| 225 | + **{attr[0]: _tree_replace(getattr(base, attr[0]), attr[1:], val)} |
| 226 | + ) |
0 commit comments