lucid-dl 2.11.0__tar.gz → 2.11.3__tar.gz

{lucid_dl-2.11.0/lucid_dl.egg-info → lucid_dl-2.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lucid-dl
-Version: 2.11.0
+Version: 2.11.3
 Summary: Lumerico's Comprehensive Interface for Deep Learning
 Home-page: https://github.com/ChanLumerico/lucid
 Author: ChanLumerico
@@ -8,7 +8,7 @@ Author-email: greensox284@gmail.com
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.12
+Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
@@ -33,7 +33,7 @@ Dynamic: summary
 [![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)
+![Lines of Code](https://img.shields.io/badge/dynamic/json?label=Lines%20of%20Code&color=purple&url=https%3A%2F%2Fraw.githubusercontent.com%2FChanLumerico%2Flucid%2Fmain%2Floc%2Floc_badge.json&query=%24.linesOfCode&cacheSeconds=3600)
 
 **Lucid** is a minimalist deep learning framework built entirely from scratch in Python. It offers a pedagogically rich environment to explore the foundations of modern deep learning systems, including autodiff, neural network modules, and GPU acceleration — all while staying lightweight, readable, and free of complex dependencies.
 
@@ -48,24 +48,19 @@ Whether you're a student, educator, or an advanced researcher seeking to demysti
 
 ### 🔥 What's New
 
-- Now supports [**`Safetensors`**](https://github.com/huggingface/safetensors) for Lucid neural module porting along with the legacy `.lcd` format
+- Added additional `nn.Module` hooks for richer introspection during training:
 
-- Branched a Stand-alone Autograd Engine as `lucid.autograd`
+  ```python
+  def register_forward_pre_hook(self, hook: Callable, *, with_kwargs: bool = False)
 
-  - 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
-    ```
+  def register_forward_hook(self, hook: Callable, *, with_kwargs: bool = False)
 
-- 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)
-  - Uses heuristic thresholds to avoid fusion overhead on small tensors
-  - Disabled by default on GPU paths to ensure stable performance
+  def register_backward_hook(self, hook: Callable)
+
+  def register_full_backward_pre_hook(self, hook: Callable)
+
+  def register_full_backward_hook(self, hook: Callable)
+  ```
 
 ## 🔧 How to Install
 

{lucid_dl-2.11.0 → lucid_dl-2.11.3}/README.md

@@ -5,7 +5,7 @@
 [![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)
+![Lines of Code](https://img.shields.io/badge/dynamic/json?label=Lines%20of%20Code&color=purple&url=https%3A%2F%2Fraw.githubusercontent.com%2FChanLumerico%2Flucid%2Fmain%2Floc%2Floc_badge.json&query=%24.linesOfCode&cacheSeconds=3600)
 
 **Lucid** is a minimalist deep learning framework built entirely from scratch in Python. It offers a pedagogically rich environment to explore the foundations of modern deep learning systems, including autodiff, neural network modules, and GPU acceleration — all while staying lightweight, readable, and free of complex dependencies.
 
@@ -20,24 +20,19 @@ Whether you're a student, educator, or an advanced researcher seeking to demysti
 
 ### 🔥 What's New
 
-- Now supports [**`Safetensors`**](https://github.com/huggingface/safetensors) for Lucid neural module porting along with the legacy `.lcd` format
+- Added additional `nn.Module` hooks for richer introspection during training:
 
-- Branched a Stand-alone Autograd Engine as `lucid.autograd`
+  ```python
+  def register_forward_pre_hook(self, hook: Callable, *, with_kwargs: bool = False)
 
-  - 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
-    ```
+  def register_forward_hook(self, hook: Callable, *, with_kwargs: bool = False)
 
-- 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)
-  - Uses heuristic thresholds to avoid fusion overhead on small tensors
-  - Disabled by default on GPU paths to ensure stable performance
+  def register_backward_hook(self, hook: Callable)
+
+  def register_full_backward_pre_hook(self, hook: Callable)
+
+  def register_full_backward_hook(self, hook: Callable)
+  ```
 
 ## 🔧 How to Install
 

{lucid_dl-2.11.0 → lucid_dl-2.11.3}/lucid/__init__.py

@@ -64,9 +64,11 @@ inf = math.inf
 
 Int = types.Int
 Int8, Int16, Int32, Int64 = (types.Int8, types.Int16, types.Int32, types.Int64)
+Char, Short, Long = (Int8, Int16, Int64)
 
 Float = types.Float
 Float16, Float32, Float64 = (types.Float16, types.Float32, types.Float64)
+Half, Double = (Float16, Float64)
 
 Complex = types.Complex
 Complex64 = types.Complex64
@@ -306,9 +308,9 @@ def register_model(func: _ModuleReturnFunc) -> _ModuleReturnFunc:
 
 
 def _conv_view_limit_mb() -> int:
-    from lucid._backend import conv as _conv_backend
+    from lucid._kernel import conv as _conv_kernel
 
-    return _conv_backend.get_conv_view_limit_mb()
+    return _conv_kernel.get_conv_view_limit_mb()
 
 
 def __getattr__(name: str) -> Any:

{lucid_dl-2.11.0 → lucid_dl-2.11.3}/lucid/_backend/core.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Callable, Tuple, ClassVar
+from typing import Callable, Self, Tuple, ClassVar
 import functools
 import weakref
 
@@ -37,6 +37,7 @@ def func_op(
             requires_grad = False
             is_free = True
             dtype_hint: _BuiltinNumeric | Numeric | None = None
+            inplace_target: _TensorLike | None = None
 
             if n_in is None:
                 tensor_args = args
@@ -68,8 +69,42 @@ def func_op(
                             + f"('{type(op_self).__name__}')."
                         )
 
+            if op_self._inplace:
+                if n_ret != 1:
+                    raise ValueError("inplace op must have a single return value.")
+                if not (0 <= op_self._inplace_target < len(tensors)):
+                    raise ValueError("inplace_target is out of range.")
+
+                target = tensors[op_self._inplace_target]
+                if lucid.grad_enabled() and target.requires_grad and target.is_leaf:
+                    raise RuntimeError(
+                        "A leaf tensor with 'requires_grad=True' "
+                        "cannot be subjected to inplace operations."
+                    )
+                inplace_target = target
+
+                proxy = target.new_tensor()
+                proxy._op = target._op
+                proxy._prev = list(target._prev)
+                proxy._backward_op = target._backward_op
+                proxy._backward_hooks = list(target._backward_hooks)
+                proxy.grad = None
+                proxy._version = target._version
+
+                if hasattr(target, "_is_free"):
+                    proxy._is_free = target._is_free
+                if hasattr(target, "_is_bool_tensor"):
+                    proxy._is_bool_tensor = target._is_bool_tensor
+
+                tensors = (
+                    tensors[: op_self._inplace_target]
+                    + (proxy,)
+                    + tensors[op_self._inplace_target + 1 :]
+                )
+
             non_tensor_args = args[n_in:] if n_in is not None else ()
             new_args = (*tensors, *non_tensor_args)
+
             func_return_pairs = forward_func(op_self, *new_args, **kwargs)
 
             tensor_refs = tuple(weakref.ref(t) for t in tensors)
@@ -92,6 +127,25 @@ def func_op(
 
             if num_returns == 1:
                 func_return_pairs: _FuncOpReturnType = (func_return_pairs,)
+            elif op_self._inplace:
+                raise ValueError("inplace op must have a single return value.")
+
+            if op_self._inplace:
+                (ret_value, grad_func) = func_return_pairs[0]
+                target = inplace_target
+                if target is None:
+                    raise RuntimeError("Missing inplace target tensor.")
+                target.data = ret_value.data
+
+                if ret_value.dtype is bool:
+                    target._is_bool_tensor = True
+                    target.dtype = bool
+                else:
+                    target._is_bool_tensor = False
+                    target.dtype = ret_value.dtype
+
+                target._version += 1
+                func_return_pairs = ((target, grad_func),)
 
             results: Tuple[_TensorLike, ...] = tuple()
             for result, grad_func in func_return_pairs:
@@ -113,6 +167,7 @@ def func_op(
                         forward_op_ref=weakref.ref(op_self),
                         grad_func=grad_func,
                         tensor_refs=tensor_refs,
+                        versions=tuple(t._version for t in tensors),
                         device=device,
                     )
 
@@ -138,15 +193,15 @@ def func_op(
 
 
 def unary_func_op(has_gradient: bool = True, device: _DeviceType = "cpu") -> Callable:
-    return func_op(1, 1, has_gradient=has_gradient, device=device)
+    return func_op(1, 1, has_gradient, device)
 
 
 def binary_func_op(has_gradient: bool = True, device: _DeviceType = "cpu") -> Callable:
-    return func_op(2, 1, has_gradient=has_gradient, device=device)
+    return func_op(2, 1, has_gradient, device)
 
 
 def poly_func_op(has_gradient: bool = True, device: _DeviceType = "cpu") -> Callable:
-    return func_op(None, 1, has_gradient=has_gradient, device=device)
+    return func_op(None, 1, has_gradient, device)
 
 
 class Operation(ABC):
@@ -154,11 +209,18 @@ class Operation(ABC):
 
     def __init__(self) -> None:
         self.result: _TensorLike | tuple[_TensorLike, ...] | None = None
+        self._inplace: bool = False
+        self._inplace_target: int = 0
         self._flops: int | None = None
 
     def clear(self) -> None:
         self.result = None
 
+    def inplace(self, target: int = 0) -> Self:
+        self._inplace = True
+        self._inplace_target = target
+        return self
+
     @abstractmethod
     def cpu(self, *args, **kwargs) -> _FuncOpReturnType: ...
 
@@ -201,12 +263,14 @@ class BackwardOperation:
         forward_op_ref: weakref.ref[Operation] | None,
         grad_func: _GradFuncType | None,
         tensor_refs: tuple[weakref.ref[_TensorLike]],
+        versions: tuple[int, ...] = (),
         device: _DeviceType | None = "cpu",
         custom_closure: Callable[[], None] | None = None,
     ) -> None:
         self.forward_op_ref = forward_op_ref
         self.grad_func = grad_func
         self.tensor_refs = tensor_refs
+        self.versions = versions
         self.device = device
 
         self.custom_closure = custom_closure
@@ -215,18 +279,36 @@ class BackwardOperation:
         if self.grad_func is None and self.custom_closure is None:
             raise ValueError("Either 'grad_func' or 'custom_closure' must be provided.")
 
+        if len(tensor_refs) != len(versions):
+            raise ValueError("Numbers of 'tensor_refs' and 'versions' do not match.")
+
     def override_grad_func(self, new_grad_func: _GradFuncType) -> None:
         if self.custom_closure is not None:
             return
         self.grad_func = new_grad_func
 
     def override_tensor_refs(
-        self, new_tensor_refs: tuple[weakref.ref[_TensorLike]]
+        self,
+        new_tensor_refs: tuple[weakref.ref[_TensorLike]],
+        new_versions: tuple[int, ...] | None = None,
     ) -> None:
         self.tensor_refs = new_tensor_refs
         self.num_inputs = len(new_tensor_refs)
+        if new_versions is not None:
+            if len(new_versions) != len(new_tensor_refs):
+                raise ValueError(
+                    "Numbers of 'tensor_refs' and 'versions' do not match."
+                )
+            self.versions = new_versions
 
     def __call__(self) -> None:
+        live_tensors = tuple(ref() for ref in self.tensor_refs)
+        if not live_tensors or any(t is None for t in live_tensors):
+            return
+
+        if any(ver != t._version for ver, t in zip(self.versions, live_tensors)):
+            raise RuntimeError(f"Tensor version mismatch detected.")
+
         if self.custom_closure is not None:
             self.custom_closure()
             return
@@ -240,16 +322,14 @@ class BackwardOperation:
         if self.num_inputs == 1 or not isinstance(grads, tuple):
             grads = (grads,)
 
-        live_tensors = tuple(ref() for ref in self.tensor_refs)
-        if any(t is None for t in live_tensors):
-            return
-
         if len(grads) != len(live_tensors):
             raise ValueError(
                 f"Expected {len(live_tensors)} gradients, got {len(grads)}."
             )
 
         for tensor, grad in zip(live_tensors, grads):
+            if not tensor.requires_grad and grad is None:
+                continue
             new_grad = lucid._match_grad_shape(tensor.data, grad, device=self.device)
             lucid._set_tensor_grad(tensor, new_grad)
 

{lucid_dl-2.11.0 → lucid_dl-2.11.3}/lucid/_backend/metal.py

@@ -4,6 +4,8 @@ import platform
 
 import numpy as np
 
+from lucid.types import _TensorLike
+
 try:
     import mlx.core as mx
 except ModuleNotFoundError as e:
@@ -105,7 +107,9 @@ def parse_mlx_indexing(index: Any) -> Any:
     return index
 
 
-def post_step_eval(param: Any, state: Mapping[str, Any] | None = None) -> None:
+def post_step_eval(
+    param: _TensorLike | Any, state: Mapping[str, Any] | None = None
+) -> None:
     is_gpu = False
     if hasattr(param, "is_gpu"):
         try:

{lucid_dl-2.11.0 → lucid_dl-2.11.3}/lucid/_func/__init__.py

@@ -34,18 +34,50 @@ def add(a: Tensor, b: Tensor, /) -> Tensor:
     return bfunc.add()(a, b)
 
 
+def add_(a: Tensor, b: Tensor) -> Tensor:
+    return bfunc.add().inplace()(a, b)
+
+
 def sub(a: Tensor, b: Tensor, /) -> Tensor:
     return bfunc.sub()(a, b)
 
 
+def sub_(a: Tensor, b: Tensor, /) -> Tensor:
+    return bfunc.sub().inplace()(a, b)
+
+
 def multiply(a: Tensor, b: Tensor, /) -> Tensor:
     return bfunc.multiply()(a, b)
 
 
+def mul_(a: Tensor, b: Tensor, /) -> Tensor:
+    return bfunc.multiply().inplace()(a, b)
+
+
 def div(a: Tensor, b: Tensor, /, floor: bool = False) -> Tensor:
     return bfunc.truediv()(a, b) if not floor else bfunc.floordiv()(a, b)
 
 
+def div_(a: Tensor, b: Tensor, /, floor: bool = False) -> Tensor:
+    return (
+        bfunc.truediv().inplace()(a, b)
+        if not floor
+        else bfunc.floordiv().inplace()(a, b)
+    )
+
+
+def minimum_(a: Tensor, b: Tensor, /) -> Tensor:
+    return bfunc.minimum().inplace()(a, b)
+
+
+def maximum_(a: Tensor, b: Tensor, /) -> Tensor:
+    return bfunc.maximum().inplace()(a, b)
+
+
+def power_(a: Tensor, b: Tensor, /) -> Tensor:
+    return bfunc.power().inplace()(a, b)
+
+
 def _equal(a: Tensor, b: Tensor, /) -> Tensor:
     return bfunc._equal()(a, b)
 
@@ -237,6 +269,92 @@ def cube(a: Tensor, /) -> Tensor:
     return ufunc.cube()(a)
 
 
+def neg_(a: Tensor, /) -> Tensor:
+    return ufunc._neg().inplace()(a)
+
+
+def exp_(a: Tensor, /) -> Tensor:
+    return ufunc.exp().inplace()(a)
+
+
+def log_(a: Tensor, /) -> Tensor:
+    return ufunc.log().inplace()(a)
+
+
+def log2_(a: Tensor, /) -> Tensor:
+    return ufunc.log2().inplace()(a)
+
+
+def sqrt_(a: Tensor, /) -> Tensor:
+    return ufunc.sqrt().inplace()(a)
+
+
+def sin_(a: Tensor, /) -> Tensor:
+    return ufunc.sin().inplace()(a)
+
+
+def cos_(a: Tensor, /) -> Tensor:
+    return ufunc.cos().inplace()(a)
+
+
+def tan_(a: Tensor, /) -> Tensor:
+    return ufunc.tan().inplace()(a)
+
+
+def arcsin_(a: Tensor, /) -> Tensor:
+    return ufunc.arcsin().inplace()(a)
+
+
+def arccos_(a: Tensor, /) -> Tensor:
+    return ufunc.arccos().inplace()(a)
+
+
+def arctan_(a: Tensor, /) -> Tensor:
+    return ufunc.arctan().inplace()(a)
+
+
+def sinh_(a: Tensor, /) -> Tensor:
+    return ufunc.sinh().inplace()(a)
+
+
+def cosh_(a: Tensor, /) -> Tensor:
+    return ufunc.cosh().inplace()(a)
+
+
+def tanh_(a: Tensor, /) -> Tensor:
+    return ufunc.tanh().inplace()(a)
+
+
+def clip_(
+    a: Tensor, /, min_value: _Scalar | None = None, max_value: _Scalar | None = None
+) -> Tensor:
+    if min_value is None:
+        min_value = lucid.min(a).item()
+    if max_value is None:
+        max_value = lucid.max(a).item()
+    return ufunc.clip(min_value, max_value).inplace()(a)
+
+
+def abs_(a: Tensor, /) -> Tensor:
+    return ufunc._abs().inplace()(a)
+
+
+def sign_(a: Tensor, /) -> Tensor:
+    return ufunc.sign().inplace()(a)
+
+
+def reciprocal_(a: Tensor, /) -> Tensor:
+    return ufunc.reciprocal().inplace()(a)
+
+
+def square_(a: Tensor, /) -> Tensor:
+    return ufunc.square().inplace()(a)
+
+
+def cube_(a: Tensor, /) -> Tensor:
+    return ufunc.cube().inplace()(a)
+
+
 @property
 def _T(a: Tensor, /) -> Tensor:
     return ufunc._T()(a)
@@ -301,6 +419,18 @@ def ceil(a: Tensor) -> Tensor:
     return ufunc.ceil()(a)
 
 
+def round_(a: Tensor, /, decimals: int = 0) -> Tensor:
+    return ufunc.round(decimals).inplace()(a)
+
+
+def floor_(a: Tensor) -> Tensor:
+    return ufunc.floor().inplace()(a)
+
+
+def ceil_(a: Tensor) -> Tensor:
+    return ufunc.ceil().inplace()(a)
+
+
 def cumprod(a: Tensor, axis: int = -1) -> Tensor:
     return ufunc.cumprod(axis)(a)
 
@@ -595,3 +725,35 @@ Tensor.swapaxes = swapaxes
 Tensor.round = round
 Tensor.floor = floor
 Tensor.ceil = ceil
+
+Tensor.add_ = add_
+Tensor.sub_ = sub_
+Tensor.mul_ = mul_
+Tensor.div_ = div_
+Tensor.minimum_ = minimum_
+Tensor.maximum_ = maximum_
+Tensor.power_ = power_
+
+Tensor.neg_ = neg_
+Tensor.exp_ = exp_
+Tensor.log_ = log_
+Tensor.log2_ = log2_
+Tensor.sqrt_ = sqrt_
+Tensor.sin_ = sin_
+Tensor.cos_ = cos_
+Tensor.tan_ = tan_
+Tensor.arcsin_ = arcsin_
+Tensor.arccos_ = arccos_
+Tensor.arctan_ = arctan_
+Tensor.sinh_ = sinh_
+Tensor.cosh_ = cosh_
+Tensor.tanh_ = tanh_
+Tensor.clip_ = clip_
+Tensor.abs_ = abs_
+Tensor.sign_ = sign_
+Tensor.reciprocal_ = reciprocal_
+Tensor.square_ = square_
+Tensor.cube_ = cube_
+Tensor.round_ = round_
+Tensor.floor_ = floor_
+Tensor.ceil_ = ceil_

lucid_dl-2.11.0/lucid/_tensor/tensor_ops.py → lucid_dl-2.11.3/lucid/_tensor/base.py

@@ -133,3 +133,67 @@ class _TensorBase:
     def nonzero(self) -> Self: ...
 
     def diagonal(self, offset: int = 0, axis1: int = 0, axis2: int = 1) -> Self: ...
+
+
+class _TensorInplace:
+    def add_(self, other: Self) -> Self: ...
+
+    def sub_(self, other: Self) -> Self: ...
+
+    def mul_(self, other: Self) -> Self: ...
+
+    def div_(self, other: Self, /, floor: bool = False) -> Self: ...
+
+    def minimum_(self, other: Self) -> Self: ...
+
+    def maximum_(self, other: Self) -> Self: ...
+
+    def power_(self, other: Self) -> Self: ...
+
+    def neg_(self) -> Self: ...
+
+    def exp_(self) -> Self: ...
+
+    def log_(self) -> Self: ...
+
+    def log2_(self) -> Self: ...
+
+    def sqrt_(self) -> Self: ...
+
+    def sin_(self) -> Self: ...
+
+    def cos_(self) -> Self: ...
+
+    def tan_(self) -> Self: ...
+
+    def arcsin_(self) -> Self: ...
+
+    def arccos_(self) -> Self: ...
+
+    def arctan_(self) -> Self: ...
+
+    def sinh_(self) -> Self: ...
+
+    def cosh_(self) -> Self: ...
+
+    def tanh_(self) -> Self: ...
+
+    def clip_(
+        self, min_value: _Scalar | None = None, max_value: _Scalar | None = None
+    ) -> Self: ...
+
+    def abs_(self) -> Self: ...
+
+    def sign_(self) -> Self: ...
+
+    def reciprocal_(self) -> Self: ...
+
+    def square_(self) -> Self: ...
+
+    def cube_(self) -> Self: ...
+
+    def round_(self, decimals: int = 0) -> Self: ...
+
+    def floor_(self) -> Self: ...
+
+    def ceil_(self) -> Self: ...