lucid-dl 2.10.0__py3-none-any.whl → 2.11.0__py3-none-any.whl

lucid/__init__.py

@@ -49,6 +49,7 @@ import lucid.random as random
 import lucid.einops as einops
 import lucid.nn as nn
 import lucid.types as types
+import lucid.autograd as autograd
 
 from lucid._fusion import ENABLE_FUSION
 

lucid/_tensor/tensor.py

@@ -140,110 +140,9 @@ class Tensor(_TensorBase):
         return self
 
     def backward(self, retain_grad: bool = False, retain_graph: bool = False) -> None:
-        if self.grad is None:
-            self.grad = (
-                np.ones_like(self.data) if self.is_cpu() else mx.ones_like(self.data)
-            )
-        visited = set()
-        topo_order: list[Self] = []
-        stack = [self]
-        ops_to_clear = set()
-
-        while stack:
-            tensor = stack[-1]
-            if tensor in visited:
-                stack.pop()
-                topo_order.append(tensor)
-                continue
-
-            visited.add(tensor)
-            for parent in tensor._prev:
-                if parent not in visited:
-                    stack.append(parent)
-
-        if lucid.ENABLE_FUSION and self.is_cpu():
-            self._try_backward_fusion(topo_order)
-
-        for tensor in reversed(topo_order):
-            try:
-                tensor._backward_op()
-            except Exception as e:
-                raise lucid.BackwardError(shape=tensor.shape, op=tensor._op) from e
-
-            for hook in tensor._backward_hooks:
-                hook(tensor, tensor.grad)
-
-            if tensor._op is not None:
-                ops_to_clear.add(tensor._op)
-
-            if not (tensor.is_leaf or retain_grad or tensor.keep_grad):
-                tensor.grad = None
-
-        if not retain_graph:
-            for tensor in topo_order:
-                tensor.clear_node()
-            for op in ops_to_clear:
-                try:
-                    op.clear()
-                except Exception:
-                    try:
-                        op.result = None
-                    except Exception:
-                        pass
-
-    def _try_backward_fusion(self, topo_order: list[Self]) -> None:
-        consumer_of: dict[int, Self] = {}
-        multi_consumer: set[int] = set()
-
-        for consumer in topo_order:
-            for parent in consumer._prev:
-                pid = id(parent)
-                if pid in multi_consumer:
-                    continue
-
-                prev_consumer = consumer_of.get(pid)
-                if prev_consumer is None:
-                    consumer_of[pid] = consumer
-                else:
-                    multi_consumer.add(pid)
-                    consumer_of.pop(pid, None)
-
-        if not consumer_of:
-            return
-
-        from lucid._fusion import match_fusion_table
-
-        for pid, v in list(consumer_of.items()):
-            p = next((t for t in v._prev if id(t) == pid), None)
-            if p is None:
-                continue
-            if p._op is None or v._op is None:
-                continue
-
-            fused_backward_op = match_fusion_table(p._op, v._op)
-            if fused_backward_op is None:
-                continue
-            if v.size < fused_backward_op.heuristic_thresh:
-                continue
-
-            # NOTE (fusion limitation): --- IGNORE ---
-            # TEMP: only fuse simple unary chains p -> v.
-            # If v has multiple parents (e.g., binary ops), a fused grad func would
-            # need to account for all inputs; skip for now.
-            if len(v._prev) != 1 or v._prev[0] is not p:
-                continue
-
-            p_parents = tuple(p._prev)
-            v._prev.remove(p)
-            v._prev.extend(p_parents)
-            p.clear_node(clear_op=False)
-
-            v._backward_op.override_tensor_refs(tuple(weakref.ref(t) for t in v._prev))
-            v._backward_op.override_grad_func(
-                fused_backward_op.get_fused_grad_func(
-                    inputs=p_parents, results=v, device=v.device
-                )
-            )
+        import lucid.autograd as autograd
+
+        autograd.backward(self, retain_grad=retain_grad, retain_graph=retain_graph)
 
     def register_hook(self, hook: _HookType) -> Callable:
         self._backward_hooks.append(hook)

lucid/autograd/__init__.py

@@ -0,0 +1,219 @@
+from typing import Iterable, Sequence
+import weakref
+
+import numpy as np
+
+from lucid._backend.metal import mx
+from lucid.error import BackwardError
+from lucid.types import _MLXArray, _NumPyArray, _TensorLike, _Scalar, _Gradient
+
+
+__all__ = ["grad", "backward"]
+
+
+def _as_tuple(value: _TensorLike | Sequence[_TensorLike]) -> tuple[_TensorLike, ...]:
+    if isinstance(value, (tuple, list)):
+        return tuple(value)
+    return (value,)
+
+
+def _coerce_grad_output(
+    output: _TensorLike, grad_output: _TensorLike | _Gradient | _Scalar
+) -> _Gradient:
+    if grad_output is None:
+        if output.is_cpu():
+            return np.ones_like(output.data)
+        return mx.ones_like(output.data)
+
+    if isinstance(grad_output, _TensorLike):
+        grad_output = grad_output.data
+
+    if isinstance(grad_output, _NumPyArray):
+        if output.is_gpu():
+            grad_output = mx.array(grad_output)
+        return grad_output
+
+    if isinstance(grad_output, _MLXArray):
+        if output.is_cpu():
+            grad_output = np.array(grad_output)
+        return grad_output
+
+    if output.is_cpu():
+        return np.ones_like(output.data) * grad_output
+    return mx.ones_like(output.data) * grad_output
+
+
+def grad(
+    outputs: _TensorLike | Iterable[_TensorLike],
+    inputs: _TensorLike | Iterable[_TensorLike],
+    grad_outputs: _TensorLike | Iterable[_TensorLike] | Iterable[_Scalar] | None = None,
+    retain_graph: bool = False,
+    allow_unused: bool = False,
+) -> tuple[_Gradient, ...] | _Gradient:
+    out_tensors = _as_tuple(outputs)
+    in_tensors = _as_tuple(inputs)
+
+    if grad_outputs is None:
+        grad_outs = (None,) * len(out_tensors)
+    else:
+        grad_outs = _as_tuple(grad_outputs)
+        if len(grad_outs) != len(out_tensors):
+            raise ValueError("grad_outputs length must match outputs length.")
+
+    for tensor in out_tensors:
+        if not isinstance(tensor, _TensorLike):
+            raise TypeError("All outputs must be _TensorLike instances.")
+
+    for tensor in in_tensors:
+        if not isinstance(tensor, _TensorLike):
+            raise TypeError("All inputs must be _TensorLike instances.")
+
+    prev_grads = {tensor: tensor.grad for tensor in in_tensors}
+    prev_out_grads = {tensor: tensor.grad for tensor in out_tensors}
+    prev_keep = {tensor: tensor.keep_grad for tensor in in_tensors}
+
+    for tensor in in_tensors:
+        tensor.grad = None
+        tensor.keep_grad = True
+
+    try:
+        for i, (output, grad_output) in enumerate(zip(out_tensors, grad_outs)):
+            if not output.requires_grad:
+                if allow_unused:
+                    continue
+                raise RuntimeError("All outputs must require gradients.")
+
+            coerced = _coerce_grad_output(output, grad_output)
+            if coerced.shape != output.shape:
+                raise ValueError("grad_output shape must match output shape.")
+
+            output.grad = coerced
+            output.backward(
+                retain_grad=True,
+                retain_graph=(i < len(out_tensors) - 1) or retain_graph,
+            )
+
+        grads = tuple(tensor.grad for tensor in in_tensors)
+        if not allow_unused and any(grad is None for grad in grads):
+            raise RuntimeError(
+                "Some inputs did not receive gradients. Set allow_unused=True."
+            )
+
+        if len(grads) == 1:
+            return grads[0]
+        return grads
+    finally:
+        for tensor, grad in prev_out_grads.items():
+            tensor.grad = grad
+        for tensor in in_tensors:
+            tensor.grad = prev_grads[tensor]
+            tensor.keep_grad = prev_keep[tensor]
+
+
+def backward(
+    tensor: _TensorLike, retain_grad: bool = False, retain_graph: bool = False
+) -> None:
+    if tensor.grad is None:
+        tensor.grad = (
+            np.ones_like(tensor.data) if tensor.is_cpu() else mx.ones_like(tensor.data)
+        )
+
+    visited = set()
+    topo_order: list[_TensorLike] = []
+    stack = [tensor]
+    ops_to_clear = set()
+
+    while stack:
+        node = stack[-1]
+        if node in visited:
+            stack.pop()
+            topo_order.append(node)
+            continue
+
+        visited.add(node)
+        for parent in node._prev:
+            if parent not in visited:
+                stack.append(parent)
+
+    from lucid._fusion import ENABLE_FUSION
+
+    if ENABLE_FUSION and tensor.is_cpu():
+        _try_backward_fusion(topo_order)
+
+    for node in reversed(topo_order):
+        try:
+            node._backward_op()
+        except Exception as e:
+            raise BackwardError(shape=node.shape, op=node._op) from e
+
+        for hook in node._backward_hooks:
+            hook(node, node.grad)
+
+        if node._op is not None:
+            ops_to_clear.add(node._op)
+
+        if not (node.is_leaf or retain_grad or node.keep_grad):
+            node.grad = None
+
+    if not retain_graph:
+        for node in topo_order:
+            node.clear_node()
+        for op in ops_to_clear:
+            try:
+                op.clear()
+            except Exception:
+                try:
+                    op.result = None
+                except Exception:
+                    pass
+
+
+def _try_backward_fusion(topo_order: list[_TensorLike]) -> None:
+    from lucid._fusion import match_fusion_table
+
+    consumer_of: dict[int, _TensorLike] = {}
+    multi_consumer: set[int] = set()
+
+    for consumer in topo_order:
+        for parent in consumer._prev:
+            pid = id(parent)
+            if pid in multi_consumer:
+                continue
+
+            prev_consumer = consumer_of.get(pid)
+            if prev_consumer is None:
+                consumer_of[pid] = consumer
+            else:
+                multi_consumer.add(pid)
+                consumer_of.pop(pid, None)
+
+    if not consumer_of:
+        return
+
+    for pid, v in list(consumer_of.items()):
+        p = next((t for t in v._prev if id(t) == pid), None)
+        if p is None:
+            continue
+        if p._op is None or v._op is None:
+            continue
+
+        fused_backward_op = match_fusion_table(p._op, v._op)
+        if fused_backward_op is None:
+            continue
+        if v.size < fused_backward_op.heuristic_thresh:
+            continue
+
+        if len(v._prev) != 1 or v._prev[0] is not p:
+            continue
+
+        p_parents = tuple(p._prev)
+        v._prev.remove(p)
+        v._prev.extend(p_parents)
+        p.clear_node(clear_op=False)
+
+        v._backward_op.override_tensor_refs(tuple(weakref.ref(t) for t in v._prev))
+        v._backward_op.override_grad_func(
+            fused_backward_op.get_fused_grad_func(
+                inputs=p_parents, results=v, device=v.device
+            )
+        )

lucid/types.py

@@ -46,15 +46,30 @@ class _TensorLike(Protocol):
     device: _DeviceType
     shape: Any
     data: Any
+    grad: Any
+    keep_grad: bool
+    is_leaf: bool
+    size: Any
 
     _op: object | None
     _prev: list[_TensorLike]
     _backward_op: Any
+    _backward_hooks: Any
 
     def to(self, device: _DeviceType) -> None: ...
 
     def free(self) -> None: ...
 
+    def is_cpu(self) -> bool: ...
+
+    def is_gpu(self) -> bool: ...
+
+    def clear_node(self, clear_op: bool = True) -> None: ...
+
+    def backward(
+        self, retain_grad: bool = False, retain_graph: bool = False
+    ) -> None: ...
+
 
 class Numeric:
     def __init__(

{lucid_dl-2.10.0.dist-info → lucid_dl-2.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lucid-dl
-Version: 2.10.0
+Version: 2.11.0
 Summary: Lumerico's Comprehensive Interface for Deep Learning
 Home-page: https://github.com/ChanLumerico/lucid
 Author: ChanLumerico
@@ -28,9 +28,9 @@ Dynamic: summary
 
 # Lucid² 💎
 
-![PyPI - Version](https://img.shields.io/pypi/v/lucid-dl?color=red)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/lucid-dl.svg)
-![PyPI - Total Downloads](https://img.shields.io/badge/total%20downloads-34.0k-yellow.svg)
+![PyPI Version](https://img.shields.io/pypi/v/lucid-dl?color=red)
+![PyPI Downloads](https://img.shields.io/pypi/dm/lucid-dl.svg)
+[![PyPI Total Downloads](https://static.pepy.tech/personalized-badge/lucid-dl?period=total&units=NONE&left_color=GRAY&right_color=yellow&left_text=total%20downloads)](https://pepy.tech/projects/lucid-dl)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ChanLumerico/lucid.svg)
 ![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)
 ![Lines of Code](https://img.shields.io/badge/lines%20of%20code-27.7k-purple.svg)
@@ -50,6 +50,17 @@ Whether you're a student, educator, or an advanced researcher seeking to demysti
 
 - Now supports [**`Safetensors`**](https://github.com/huggingface/safetensors) for Lucid neural module porting along with the legacy `.lcd` format
 
+- Branched a Stand-alone Autograd Engine as `lucid.autograd`
+
+  - Provides a generalized API of computing gradients:
+    
+    ```python
+    import lucid.autograd as autograd
+    x = lucid.Tensor([1., 2.], requires_grad=True)
+    y = (x ** 2).sum()
+    autograd.grad(y, x)  # ∂y/∂x
+    ```
+
 - Introduced **Backward Fusion** for CPU execution:
   - Automatically fuses selected operation patterns during backpropagation to reduce graph overhead
   - Supports identity/unary fusion (e.g. `log∘exp`, double negation, and view-like ops such as reshape/squeeze)

{lucid_dl-2.10.0.dist-info → lucid_dl-2.11.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-lucid/__init__.py,sha256=aqui9d7CMjxCcb0txpd68amluwuMwNTbTOxVuuS4N6Y,9055
+lucid/__init__.py,sha256=Rd4OF5hgSNFuSzeB4--gfkRrrQpSEhYJ10-vV93YShk,9089
 lucid/error.py,sha256=qnTiVuZm3c5-DIt-OOyobZ7RUm7E1K4NR0j998LG1ug,709
 lucid/port.py,sha256=Kt1YaSWef_eKF4KRj-UFhirvFC5urEESfYQ_BSlBZGE,3811
-lucid/types.py,sha256=n225G0mVm0im3r9jZi2YY0hMfhOgsJroRlHZiqT_Sn4,3981
+lucid/types.py,sha256=7mkE4_kAn6I8bToqoNb4E5IKwVOjYMQ_kMXZB7O_KeA,4310
 lucid/_backend/__init__.py,sha256=n1bnYdeb_bNDBKASWGywTRa0Ne9hMAkal3AuVZJgovI,5
 lucid/_backend/conv.py,sha256=EkU_AbNcSFJWwLzk7tY4OBaA5RUh44CgDcVGviH_AZA,16641
 lucid/_backend/core.py,sha256=TYuLbv5V-H3sxhgTjwUO2iPxJ6TIJjsYx8EugpUGJ2g,8531
@@ -15,10 +15,11 @@ lucid/_fusion/__init__.py,sha256=SVzLiFzs4m1mMOpefKDLFkYqV0zV5FGwFd9hEbUZtSo,68
 lucid/_fusion/base.py,sha256=d6nWuPjYxkie9Xrtbj3JVusnIN61PIoSFFSthJNm9os,3821
 lucid/_fusion/func.py,sha256=9tXzB-QNrx_AvNJiPto807faXKlzjuMG4o9gRgI5usc,1659
 lucid/_tensor/__init__.py,sha256=wFWAMhTnQwThNiBEIT4fcw4ryIm8A4AoR-m9KDhklOQ,40
-lucid/_tensor/tensor.py,sha256=uRz7bNveY2e5ET0kIvGP_Ml7n0ZPMsjETOQCET1JVZs,16939
+lucid/_tensor/tensor.py,sha256=kccMHLPi2aGpkjwzEb7SBpp3Hhbe1TZv3VUDUSOv2ik,13570
 lucid/_tensor/tensor_ops.py,sha256=5XtqcPbrkOb87pVTSOMNaje9K78tgLpsNdV8XXnbpHc,3991
 lucid/_util/__init__.py,sha256=NgOleItHJGVLdJlKHKfpzuSl3vofzJpNsZByHAYJmKs,6838
 lucid/_util/func.py,sha256=ZODVlGdAejMTJnwEls7yMCI5WJ9Thkb3RIq1WwQCS4E,44239
+lucid/autograd/__init__.py,sha256=uKuGXUUSF8rBx7iEuVA6a_AhY9wfkC82TPmc1AKbay4,6675
 lucid/data/__init__.py,sha256=qrDIQsnix5ZUEa0yrtomaaWbNJyJ3xEr2gdhRvg70_8,118
 lucid/data/_base.py,sha256=RM8xpBl8qFhm19n7eER_jOsRaxkL3rbOkwUvn6VetSE,5921
 lucid/data/_util.py,sha256=UsbliOrGmM0f1vqppoBPn3RSx53PIqcVx_yVOlHZB6A,1985
@@ -126,8 +127,8 @@ lucid/visual/__init__.py,sha256=6TuFDfmXTwpLyHl7_KqBfdzW6zqHjGzIFvymjFPlvjI,21
 lucid/visual/graph.py,sha256=YjpIDM_lloZARw3sCBiXPl_hT5A2gTk2fEHvwvJWXTk,4599
 lucid/weights/__init__.py,sha256=z1AikA3rOEeckWGkYWlcZkxNlJo9Xwa39PL6ly3hWnc,8801
 lucid/weights/__init__.pyi,sha256=lFonYC3cUx2Idolf3AEPnjFcyqcn3UDU84oJlZafqLY,3013
-lucid_dl-2.10.0.dist-info/licenses/LICENSE,sha256=vxRFYnVD1IeYtsvw-KmoElfqrjxKHv1h9YTvsG54loQ,1065
-lucid_dl-2.10.0.dist-info/METADATA,sha256=WpXt6J0ErHy2z-Kl0W7lKcEcJ5n6CNypk1HYv_TNIm8,11756
-lucid_dl-2.10.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lucid_dl-2.10.0.dist-info/top_level.txt,sha256=uzP_qBx9iNWIHKJRlElYcBLYVqMpdm9Q1Ma63QPYbFc,6
-lucid_dl-2.10.0.dist-info/RECORD,,
+lucid_dl-2.11.0.dist-info/licenses/LICENSE,sha256=vxRFYnVD1IeYtsvw-KmoElfqrjxKHv1h9YTvsG54loQ,1065
+lucid_dl-2.11.0.dist-info/METADATA,sha256=_wOx1Pjq_HgSvzL_4eMHGMsHz8cOwpvU9EpiFhYglco,12159
+lucid_dl-2.11.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lucid_dl-2.11.0.dist-info/top_level.txt,sha256=uzP_qBx9iNWIHKJRlElYcBLYVqMpdm9Q1Ma63QPYbFc,6
+lucid_dl-2.11.0.dist-info/RECORD,,