lucid-dl 0.1.0__tar.gz

lucid_dl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chan Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lucid_dl-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.1
+Name: lucid-dl
+Version: 0.1.0
+Summary: Lumerico's Comprehensive Interface for Deep Learning
+Home-page: https://github.com/ChanLumerico/lucid
+Author: ChanLumerico
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+
+# Lucid 💎
+
+**Lucid** is an educational deep learning framework developed to help users understand 
+the underlying mechanics of deep learning models and tensor operations. 
+
+It is designed to provide a simple yet powerful environment to experiment with neural networks, 
+optimization, and backpropagation using only **`NumPy`**. 
+
+Lucid is ideal for those who want to learn about the inner workings of deep learning 
+algorithms and operations without the complexity of high-level frameworks.
+
+*Latest version: **0.1.0***
+
+[📑 Lucid Documentation](https://chanlumerico.github.io/lucid/build/html/index.html)
+
+## Overview
+
+Lucid provides core functionality for building and training deep learning models. 
+By utilizing `NumPy` arrays as the fundamental data structure (referred to as **Tensors**), 
+Lucid allows for the construction of layers, models, and operations commonly found in neural networks. 
+
+It offers automatic differentiation (autodiff) for computing gradients and performing backpropagation, 
+enabling efficient optimization of model parameters.
+
+## Key Features
+
+- **Tensors**: Tensors are the main data structure in Lucid, 
+  similar to arrays in `NumPy` but with additional features such as automatic gradient tracking.
+
+- **Autodiff**: Lucid computes gradients automatically using reverse-mode differentiation, 
+  making it possible to train models through backpropagation.
+
+- **Modularity**: Lucid is designed with modularity in mind, allowing users to build and 
+  customize layers, models, and operations with ease.
+
+- **Gradient Tracking**: Support for tracking gradients through Tensors, 
+  enabling automatic backpropagation during training.
+
+- **Educational Focus**: Lucid is a minimalistic library designed to be intuitive and provide 
+  a deeper understanding of the mechanics of deep learning.
+
+## Core Components
+
+### Tensors
+
+Tensors are the primary data structure in Lucid, similar to `NumPy` arrays but with additional capabilities, 
+such as the ability to track gradients. 
+
+Operations performed on tensors are automatically tracked, allowing for efficient backpropagation.
+
+- **Tensor Operations**: Basic operations like addition, subtraction, multiplication, 
+  and division are supported, with automatic gradient computation for supported operations.
+
+- **Gradient Tracking**: When constructing Tensors, 
+  users can specify if they require gradients for backpropagation.
+
+- **Shape Management**: Lucid supports reshaping, transposing, and other tensor manipulation 
+  operations to allow for flexible model design.
+
+### Neural Networks (`lucid.nn`)
+
+Lucid provides a framework for defining and training neural networks. 
+Models are built by subclassing the **nn.Module** class, which allows users to define layers, 
+forward passes, and backward passes (gradient computations) for the model.
+
+- **Layer Definitions**: Layers can be constructed using basic operations, like matrix multiplication, 
+  activation functions, and loss functions.
+
+- **Forward and Backward Passes**: Users define the computation graph in the `forward` method, 
+  and Lucid handles backpropagation automatically by tracking operations performed on tensors.
+
+### Linear Algebra Operations (`lucid.linalg`)
+
+Lucid includes basic linear algebra operations, such as matrix multiplication, 
+inverse, determinant calculation, and more.
+
+- **Matrix Operations**: These operations are essential for building and manipulating neural networks, 
+  particularly for tasks like transforming data in the forward pass.
+
+### Optimization
+
+Lucid supports optimization routines like Stochastic Gradient Descent (SGD), 
+which allow for the training of models by minimizing a loss function.
+
+- **Autodiff and Backpropagation**: Lucid's autodiff capabilities make it easy to compute 
+  gradients and optimize model parameters using backpropagation.
+
+## Example Usage
+
+The following example demonstrates how to define and train a simple neural network using Lucid.
+
+```python
+# Example of a Simple Model
+
+import lucid
+import lucid.nn as nn
+import lucid.nn.functional as F
+
+# Define a simple model class
+class SimpleModel(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.dense1 = nn.Linear(3, 5)
+        self.dense2 = nn.Linear(5, 1)
+    
+    def forward(self, x):
+        x = self.dense1(x)
+        x = F.relu(x)
+        x = self.dense2(x)
+        return x
+
+# Create an instance of the model
+model = SimpleModel()
+
+# Create a sample input tensor
+input_tensor = lucid.Tensor([[1.0, 2.0, 3.0]])
+
+# Forward pass
+output = model(input_tensor)
+
+print(output)
+```
+
+In the above example, we define a simple model with two dense layers,
+apply a ReLU activation, and perform a forward pass using an input tensor.
+
+This showcases how easy it is to define models and run computations with Lucid.
+
+## Notes
+
+Lucid is built for learning and experimenting with deep learning concepts,
+allowing users to see how operations like backpropagation, optimization,
+and activation functions are implemented at a low level.
+
+Lucid is lightweight, with no external dependencies beyond `NumPy`,
+making it easy to install and use without complex setups or specialized hardware.
+
+## Limitations
+
+Lucid does not aim to provide the high-level functionalities of production-ready frameworks.
+Instead, it focuses on educational value and understanding how deep
+learning models are built from scratch.
+
+Performance optimizations that are available in specialized libraries may not be as
+efficient in Lucid, as it is not optimized for production workloads.
+
+## Conclusion
+
+Lucid provides a minimalistic, educational environment to learn about deep learning using only `NumPy`.
+It gives users the tools to experiment with neural networks, automatic differentiation,
+optimization, and other essential components of deep learning, all while providing insight into how
+these operations are implemented at the core level.
+
+For further information and usage details, refer to the documentation of specific modules like
+lucid.nn and lucid.linalg.

lucid_dl-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Lucid 💎
+
+**Lucid** is an educational deep learning framework developed to help users understand 
+the underlying mechanics of deep learning models and tensor operations. 
+
+It is designed to provide a simple yet powerful environment to experiment with neural networks, 
+optimization, and backpropagation using only **`NumPy`**. 
+
+Lucid is ideal for those who want to learn about the inner workings of deep learning 
+algorithms and operations without the complexity of high-level frameworks.
+
+*Latest version: **0.1.0***
+
+[📑 Lucid Documentation](https://chanlumerico.github.io/lucid/build/html/index.html)
+
+## Overview
+
+Lucid provides core functionality for building and training deep learning models. 
+By utilizing `NumPy` arrays as the fundamental data structure (referred to as **Tensors**), 
+Lucid allows for the construction of layers, models, and operations commonly found in neural networks. 
+
+It offers automatic differentiation (autodiff) for computing gradients and performing backpropagation, 
+enabling efficient optimization of model parameters.
+
+## Key Features
+
+- **Tensors**: Tensors are the main data structure in Lucid, 
+  similar to arrays in `NumPy` but with additional features such as automatic gradient tracking.
+
+- **Autodiff**: Lucid computes gradients automatically using reverse-mode differentiation, 
+  making it possible to train models through backpropagation.
+
+- **Modularity**: Lucid is designed with modularity in mind, allowing users to build and 
+  customize layers, models, and operations with ease.
+
+- **Gradient Tracking**: Support for tracking gradients through Tensors, 
+  enabling automatic backpropagation during training.
+
+- **Educational Focus**: Lucid is a minimalistic library designed to be intuitive and provide 
+  a deeper understanding of the mechanics of deep learning.
+
+## Core Components
+
+### Tensors
+
+Tensors are the primary data structure in Lucid, similar to `NumPy` arrays but with additional capabilities, 
+such as the ability to track gradients. 
+
+Operations performed on tensors are automatically tracked, allowing for efficient backpropagation.
+
+- **Tensor Operations**: Basic operations like addition, subtraction, multiplication, 
+  and division are supported, with automatic gradient computation for supported operations.
+
+- **Gradient Tracking**: When constructing Tensors, 
+  users can specify if they require gradients for backpropagation.
+
+- **Shape Management**: Lucid supports reshaping, transposing, and other tensor manipulation 
+  operations to allow for flexible model design.
+
+### Neural Networks (`lucid.nn`)
+
+Lucid provides a framework for defining and training neural networks. 
+Models are built by subclassing the **nn.Module** class, which allows users to define layers, 
+forward passes, and backward passes (gradient computations) for the model.
+
+- **Layer Definitions**: Layers can be constructed using basic operations, like matrix multiplication, 
+  activation functions, and loss functions.
+
+- **Forward and Backward Passes**: Users define the computation graph in the `forward` method, 
+  and Lucid handles backpropagation automatically by tracking operations performed on tensors.
+
+### Linear Algebra Operations (`lucid.linalg`)
+
+Lucid includes basic linear algebra operations, such as matrix multiplication, 
+inverse, determinant calculation, and more.
+
+- **Matrix Operations**: These operations are essential for building and manipulating neural networks, 
+  particularly for tasks like transforming data in the forward pass.
+
+### Optimization
+
+Lucid supports optimization routines like Stochastic Gradient Descent (SGD), 
+which allow for the training of models by minimizing a loss function.
+
+- **Autodiff and Backpropagation**: Lucid's autodiff capabilities make it easy to compute 
+  gradients and optimize model parameters using backpropagation.
+
+## Example Usage
+
+The following example demonstrates how to define and train a simple neural network using Lucid.
+
+```python
+# Example of a Simple Model
+
+import lucid
+import lucid.nn as nn
+import lucid.nn.functional as F
+
+# Define a simple model class
+class SimpleModel(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.dense1 = nn.Linear(3, 5)
+        self.dense2 = nn.Linear(5, 1)
+    
+    def forward(self, x):
+        x = self.dense1(x)
+        x = F.relu(x)
+        x = self.dense2(x)
+        return x
+
+# Create an instance of the model
+model = SimpleModel()
+
+# Create a sample input tensor
+input_tensor = lucid.Tensor([[1.0, 2.0, 3.0]])
+
+# Forward pass
+output = model(input_tensor)
+
+print(output)
+```
+
+In the above example, we define a simple model with two dense layers,
+apply a ReLU activation, and perform a forward pass using an input tensor.
+
+This showcases how easy it is to define models and run computations with Lucid.
+
+## Notes
+
+Lucid is built for learning and experimenting with deep learning concepts,
+allowing users to see how operations like backpropagation, optimization,
+and activation functions are implemented at a low level.
+
+Lucid is lightweight, with no external dependencies beyond `NumPy`,
+making it easy to install and use without complex setups or specialized hardware.
+
+## Limitations
+
+Lucid does not aim to provide the high-level functionalities of production-ready frameworks.
+Instead, it focuses on educational value and understanding how deep
+learning models are built from scratch.
+
+Performance optimizations that are available in specialized libraries may not be as
+efficient in Lucid, as it is not optimized for production workloads.
+
+## Conclusion
+
+Lucid provides a minimalistic, educational environment to learn about deep learning using only `NumPy`.
+It gives users the tools to experiment with neural networks, automatic differentiation,
+optimization, and other essential components of deep learning, all while providing insight into how
+these operations are implemented at the core level.
+
+For further information and usage details, refer to the documentation of specific modules like
+lucid.nn and lucid.linalg.

lucid_dl-0.1.0/lucid/__init__.py

@@ -0,0 +1,55 @@
+"""
+# `Lucid `
+
+**Lucid** is an educational deep learning framework developed to help users understand 
+the underlying mechanics of deep learning models and tensor operations. 
+
+It is designed to provide a simple yet powerful environment to experiment with neural networks, 
+optimization, and backpropagation using only `NumPy`. 
+
+Lucid is ideal for those who want to learn about the inner workings of deep learning 
+algorithms and operations without the complexity of high-level frameworks.
+
+[📑 Lucid Documentation](https://chanlumerico.github.io/lucid/build/html/index.html)
+"""
+
+from contextlib import contextmanager
+from typing import Any, Generator
+import numpy as np
+
+from lucid._tensor import Tensor
+from lucid._func import *
+from lucid._util import *
+
+from lucid.types import _ArrayOrScalar
+
+import lucid.linalg as linalg
+import lucid.random as random
+import lucid.nn as nn
+
+_grad_enabled: bool = True
+
+newaxis = np.newaxis
+
+
+def tensor(
+    data: Tensor | _ArrayOrScalar, requires_grad: bool = False, dtype: Any = np.float32
+) -> Tensor:
+    if isinstance(data, Tensor):
+        data = data.data
+    return Tensor(data, requires_grad, dtype)
+
+
+@contextmanager
+def no_grad() -> Generator:
+    global _grad_enabled
+    prev_state = _grad_enabled
+    _grad_enabled = False
+    try:
+        yield
+    finally:
+        _grad_enabled = prev_state
+
+
+def grad_enabled() -> bool:
+    return _grad_enabled

lucid_dl-0.1.0/lucid/_backend/__init__.py

@@ -0,0 +1,6 @@
+from lucid._backend.func_op import (
+    _FuncOpReturnType,
+    create_func_op,
+    create_bfunc_op,
+    create_ufunc_op,
+)

lucid_dl-0.1.0/lucid/_backend/func_op.py

@@ -0,0 +1,104 @@
+import functools
+from typing import Callable, Tuple
+
+import numpy as np
+
+import lucid
+from lucid._tensor import Tensor
+from lucid.types import _NumPyArray, _ArrayOrScalar
+
+_GradFuncType = Callable[[None], _NumPyArray | Tuple[_NumPyArray, ...]]
+
+_ReturnGradFuncPair = Tuple[Tensor, _GradFuncType]
+
+_FuncOpReturnType = _ReturnGradFuncPair | Tuple[_ReturnGradFuncPair, ...]
+
+
+def _set_tensor_grad(tensor: Tensor, grad: _NumPyArray) -> None:
+    if tensor.requires_grad:
+        if tensor.grad is None:
+            tensor.grad = grad
+        else:
+            tensor.grad = tensor.grad + grad
+
+
+def _check_is_tensor(any: Tensor | _ArrayOrScalar) -> Tensor:
+    if not isinstance(any, Tensor):
+        return Tensor(any)
+    return any
+
+
+def _match_grad_shape(data: _NumPyArray, grad: _NumPyArray) -> _NumPyArray:
+    if data.shape == grad.shape:
+        return grad
+
+    if data.size == grad.size:
+        reshaped_grad = grad
+    elif data.size < grad.size:
+        axis = []
+        if data.ndim == 0:
+            axis.extend(range(grad.ndim))
+        else:
+            for ax in range(data.ndim):
+                if data.shape[ax] != grad.shape[ax] and data.shape[ax] == 1:
+                    axis.append(ax)
+
+        reshaped_grad = np.sum(grad, axis=tuple(axis)).reshape(data.shape)
+    else:
+        reshaped_grad = np.broadcast_to(grad, data.shape)
+
+    return reshaped_grad
+
+
+def create_func_op(n_in: int, n_ret: int, has_gradient: bool = True) -> callable:
+
+    def decorator(func: Callable[..., _FuncOpReturnType]) -> callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> tuple[Tensor, ...]:
+            tensors: tuple[Tensor] = tuple()
+            requires_grad = False
+
+            for arg in args[:n_in]:
+                tensor = _check_is_tensor(arg)
+                tensors += (tensor,)
+                requires_grad = requires_grad or tensor.requires_grad
+
+            new_args = (*tensors, *args[n_in:])
+            func_return_pairs = func(*new_args, **kwargs)
+
+            if n_ret == 1:
+                func_return_pairs = (func_return_pairs,)
+
+            results: tuple[Tensor] = tuple()
+            for result, compute_grad in func_return_pairs:
+                result.requires_grad = requires_grad and has_gradient
+                results += (result,)
+
+                def _backward_op(*, _func: callable = compute_grad) -> None:
+                    grads = _func()
+                    if n_in == 1:
+                        grads = (grads,)
+
+                    for tensor, grad in zip(tensors, grads, strict=True):
+                        new_grad = _match_grad_shape(tensor.data, grad)
+                        _set_tensor_grad(tensor, new_grad)
+
+                if not lucid.grad_enabled():
+                    continue
+
+                result._backward_op = _backward_op
+                result._prev = tensors
+
+            return results if n_ret > 1 else results[0]
+
+        return wrapper
+
+    return decorator
+
+
+def create_bfunc_op(has_gradient: bool = True) -> callable:
+    return create_func_op(n_in=2, n_ret=1, has_gradient=has_gradient)
+
+
+def create_ufunc_op(has_gradient: bool = True) -> callable:
+    return create_func_op(n_in=1, n_ret=1, has_gradient=has_gradient)