krnl 0.1.0__tar.gz

krnl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adhavan Yuvaraj
+
+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.

krnl-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: krnl
+Version: 0.1.0
+Summary: A lightweight educational tensor and automatic differentiation library with CPU and OpenCL GPU support
+Author-email: Adhavan <helloadhavan@gmaim.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs==26.1.0
+Requires-Dist: Automat==25.4.16
+Requires-Dist: constantly==23.10.4
+Requires-Dist: construct==2.10.70
+Requires-Dist: hyperlink==21.0.0
+Requires-Dist: idna==3.20
+Requires-Dist: Incremental==24.11.0
+Requires-Dist: Mako==1.4.3
+Requires-Dist: MarkupSafe==3.0.4
+Requires-Dist: numpy==2.5.4
+Requires-Dist: packaging==26.3
+Requires-Dist: platformdirs==4.13.5
+Requires-Dist: protobuf==7.36.2
+Requires-Dist: psutil==7.2.2
+Requires-Dist: pyasn1==0.6.4
+Requires-Dist: pyopencl==2026.1.4
+Requires-Dist: pysnmp==7.1.30
+Requires-Dist: pytools==2026.1.1
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: siphash24==1.9
+Requires-Dist: Twisted==26.4.0
+Requires-Dist: typing_extensions==4.16.0
+Requires-Dist: zope.interface==8.7
+Dynamic: license-file
+
+# krnl
+
+`krnl` is a lightweight, educational machine learning library built in Python on top of NumPy, with experimental OpenCL support for device-aware tensor computation. The project is designed to help understand the core ideas behind modern deep learning frameworks: tensors, autograd, computational graphs, layers, losses, and optimization.
+
+This library aims to stay small and readable rather than production-focused. It is intentionally useful for learning how neural networks and training loops work under the hood.
+
+## Highlights
+
+- Tensor-based autograd engine
+- NumPy-backed CPU execution
+- OpenCL backend experiments for GPU-style computation
+- Basic neural network building blocks
+- Optimizer implementations for training
+- Common loss functions for regression and learning tasks
+- Simple, traceable code for educational use
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/helloadhavan/krnl.git
+cd krnl
+```
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Optional OpenCL setup
+
+To use the OpenCL backend, make sure your system has a compatible OpenCL runtime and drivers installed.
+
+## Quick start
+
+```python
+from backends.backends.tensor import Tensor
+
+x = Tensor(2.0)
+w = Tensor(3.0, requires_grad=True)
+b = Tensor(4.0, requires_grad=True)
+
+y = x * w + b
+loss = (y - 10.0) ** 2
+
+loss.backward()
+
+print(y.data)
+print(w.grad)
+print(b.grad)
+```
+
+This example creates a small computational graph, computes a scalar loss, and backpropagates gradients through the graph.
+
+## Core concepts
+
+### Tensor
+
+The `Tensor` class is the foundation of the project. It stores numeric data, tracks computation history, and supports differentiation through custom arithmetic and autograd operations.
+
+Key features include:
+
+- scalar and array arithmetic
+- forward pass tracking
+- backward gradient propagation
+- device awareness for CPU/GPU execution
+- support for differentiable operations used in model training
+
+### Device abstraction
+
+The `Device` abstraction allows the library to reason about whether computation should happen on CPU or a GPU-like backend. This keeps the design simple while making it easier to experiment with accelerator-backed operations.
+
+### OpenCL backend
+
+The OpenCL path uses PyOpenCL to move arrays to an accelerator, execute simple kernels, and support basic tensor operations. It is useful for experimentation and understanding how low-level device execution fits into a training loop.
+
+## Neural network utilities
+
+The library includes a minimal `nn` module with building blocks for simple models.
+
+### Module and Parameter
+
+`Module` is the base class for neural network components. It provides a simple interface for registering trainable parameters.
+
+`Parameter` wraps a tensor and marks it as trainable so that it participates in gradient-based optimization.
+
+### Layers
+
+The library includes a few basic layer types:
+
+- `Linear`: a dense layer implementing `y = xW^T + b`
+- `ReLU`: elementwise rectified linear activation
+- `Sigmoid`: elementwise sigmoid activation
+
+Example:
+
+```python
+from nn.model_utils import Linear, ReLU
+from backends.backends.tensor import Tensor
+
+layer1 = Linear(in_features=4, out_features=8)
+activation = ReLU()
+
+x = Tensor([[1.0, 2.0, 3.0, 4.0]])
+y = activation(layer1(x))
+```
+
+## Loss functions
+
+The project includes a small set of regression-style loss implementations in `nn`.
+
+### MSELoss
+
+Mean Squared Error:
+
+```python
+(predicted - target) ** 2
+```
+
+This computes the squared error across the prediction and is commonly used for regression tasks.
+
+### MAELoss
+
+Mean Absolute Error:
+
+```python
+abs(predicted - target)
+```
+
+This is useful when you want the average magnitude of the prediction error without squaring it.
+
+### HuberLoss
+
+A smooth piecewise loss that behaves like squared error for small residuals and absolute error for larger residuals. It is often used to reduce sensitivity to outliers.
+
+Example:
+
+```python
+from nn import MSELoss, MAELoss, HuberLoss
+
+criterion = MSELoss()
+loss = criterion(predictions, targets)
+```
+
+## Optimizers
+
+The library includes several optimization strategies in `nn`.
+
+### SGD
+
+Stochastic Gradient Descent updates parameters by moving them in the direction opposite the gradient:
+
+```python
+parameter = parameter - learning_rate * gradient
+```
+
+This is the simplest gradient-based optimizer and is useful for understanding the basics of training.
+
+### Adam
+
+Adam combines momentum and adaptive learning rates using first and second moment estimates. It is one of the most common modern optimizers and is useful when training neural networks more stably than plain SGD.
+
+### Muon
+
+Muon is a momentum-based optimizer with an orthogonalized update direction. It introduces a more structure-aware update strategy and is included as an experimental optimizer in the library.
+
+### MuonAdam
+
+This optimizer combines Muon-style orthogonal updates with Adam-like moment estimates, making it a hybrid approach for experimentation and learning.
+
+Example:
+
+```python
+from nn.optim import SGD, Adam, Muon, MuonAdam
+
+sgd = SGD(parameters=model_parameters, learning_rate=0.01)
+adam = Adam(parameters=model_parameters, learning_rate=0.001)
+muon = Muon(parameters=model_parameters, learning_rate=0.02)
+muon_adam = MuonAdam(parameters=model_parameters, learning_rate=0.02)
+```
+
+## Training workflow
+
+A typical training loop looks like this:
+
+```python
+from nn import MSELoss
+from nn.optim import SGD
+
+model = ...
+criterion = MSELoss()
+optimizer = SGD(model._parameters.values(), learning_rate=0.01)
+
+for batch_x, batch_y in data:
+    predictions = model(batch_x)
+    loss = criterion(predictions, batch_y)
+
+    loss.backward()
+    optimizer.step()
+    optimizer.zero_grad()
+```
+
+## Repository structure
+
+```text
+krnl/
+├── README.md
+├── __init__.py
+├── requirements.txt
+├── version.txt
+├── src/
+│   ├── backends/
+│   │   ├── GPU_processer.py
+│   │   ├── __init__.py
+│   │   ├── device.py
+│   │   ├── kernels.py
+│   │   └── tensor.py
+│   ├── nn/
+│   │   ├── __init__.py
+│   │   ├── loss.py
+│   │   ├── model_utils.py
+│   │   └── optim.py
+│   └── tests/
+│       ├── test_opencl_backend.py
+│       ├── test_simple_model_implementation.py
+│       └── test_tensor.py
+└── .gitignore
+```
+
+## Running tests
+
+From the project root:
+
+```bash
+python src/tests/test_tensor.py
+python src/tests/test_opencl_backend.py
+```
+
+The OpenCL tests require a valid OpenCL installation and compatible device support.
+
+## Project status
+
+`krnl` is an educational framework for understanding the internals of deep learning systems. It is not intended to replace established libraries such as PyTorch or TensorFlow.
+
+Current focus areas include:
+
+- tensor arithmetic and autograd
+- gradient-based optimization
+- CPU execution with NumPy
+- GPU/OpenCL experimentation
+- small neural network primitives
+
+## Contributing
+
+Contributions are welcome in areas such as:
+
+- more layer types
+- additional loss functions
+- more optimization algorithms
+- clearer documentation
+- stronger tests
+- device and performance improvements
+
+The project remains intentionally simple and readable so it can serve as a learning tool.
+
+## License
+
+This repository does not currently include a license file. If you plan to distribute or publish it publicly, consider adding a license such as MIT or Apache 2.0.
+
+## Acknowledgements
+
+This project is built for experimentation and education in tensor math, computational graphs, optimization, and device-aware execution.

krnl-0.1.0/README.md

@@ -0,0 +1,281 @@
+# krnl
+
+`krnl` is a lightweight, educational machine learning library built in Python on top of NumPy, with experimental OpenCL support for device-aware tensor computation. The project is designed to help understand the core ideas behind modern deep learning frameworks: tensors, autograd, computational graphs, layers, losses, and optimization.
+
+This library aims to stay small and readable rather than production-focused. It is intentionally useful for learning how neural networks and training loops work under the hood.
+
+## Highlights
+
+- Tensor-based autograd engine
+- NumPy-backed CPU execution
+- OpenCL backend experiments for GPU-style computation
+- Basic neural network building blocks
+- Optimizer implementations for training
+- Common loss functions for regression and learning tasks
+- Simple, traceable code for educational use
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/helloadhavan/krnl.git
+cd krnl
+```
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Optional OpenCL setup
+
+To use the OpenCL backend, make sure your system has a compatible OpenCL runtime and drivers installed.
+
+## Quick start
+
+```python
+from backends.backends.tensor import Tensor
+
+x = Tensor(2.0)
+w = Tensor(3.0, requires_grad=True)
+b = Tensor(4.0, requires_grad=True)
+
+y = x * w + b
+loss = (y - 10.0) ** 2
+
+loss.backward()
+
+print(y.data)
+print(w.grad)
+print(b.grad)
+```
+
+This example creates a small computational graph, computes a scalar loss, and backpropagates gradients through the graph.
+
+## Core concepts
+
+### Tensor
+
+The `Tensor` class is the foundation of the project. It stores numeric data, tracks computation history, and supports differentiation through custom arithmetic and autograd operations.
+
+Key features include:
+
+- scalar and array arithmetic
+- forward pass tracking
+- backward gradient propagation
+- device awareness for CPU/GPU execution
+- support for differentiable operations used in model training
+
+### Device abstraction
+
+The `Device` abstraction allows the library to reason about whether computation should happen on CPU or a GPU-like backend. This keeps the design simple while making it easier to experiment with accelerator-backed operations.
+
+### OpenCL backend
+
+The OpenCL path uses PyOpenCL to move arrays to an accelerator, execute simple kernels, and support basic tensor operations. It is useful for experimentation and understanding how low-level device execution fits into a training loop.
+
+## Neural network utilities
+
+The library includes a minimal `nn` module with building blocks for simple models.
+
+### Module and Parameter
+
+`Module` is the base class for neural network components. It provides a simple interface for registering trainable parameters.
+
+`Parameter` wraps a tensor and marks it as trainable so that it participates in gradient-based optimization.
+
+### Layers
+
+The library includes a few basic layer types:
+
+- `Linear`: a dense layer implementing `y = xW^T + b`
+- `ReLU`: elementwise rectified linear activation
+- `Sigmoid`: elementwise sigmoid activation
+
+Example:
+
+```python
+from nn.model_utils import Linear, ReLU
+from backends.backends.tensor import Tensor
+
+layer1 = Linear(in_features=4, out_features=8)
+activation = ReLU()
+
+x = Tensor([[1.0, 2.0, 3.0, 4.0]])
+y = activation(layer1(x))
+```
+
+## Loss functions
+
+The project includes a small set of regression-style loss implementations in `nn`.
+
+### MSELoss
+
+Mean Squared Error:
+
+```python
+(predicted - target) ** 2
+```
+
+This computes the squared error across the prediction and is commonly used for regression tasks.
+
+### MAELoss
+
+Mean Absolute Error:
+
+```python
+abs(predicted - target)
+```
+
+This is useful when you want the average magnitude of the prediction error without squaring it.
+
+### HuberLoss
+
+A smooth piecewise loss that behaves like squared error for small residuals and absolute error for larger residuals. It is often used to reduce sensitivity to outliers.
+
+Example:
+
+```python
+from nn import MSELoss, MAELoss, HuberLoss
+
+criterion = MSELoss()
+loss = criterion(predictions, targets)
+```
+
+## Optimizers
+
+The library includes several optimization strategies in `nn`.
+
+### SGD
+
+Stochastic Gradient Descent updates parameters by moving them in the direction opposite the gradient:
+
+```python
+parameter = parameter - learning_rate * gradient
+```
+
+This is the simplest gradient-based optimizer and is useful for understanding the basics of training.
+
+### Adam
+
+Adam combines momentum and adaptive learning rates using first and second moment estimates. It is one of the most common modern optimizers and is useful when training neural networks more stably than plain SGD.
+
+### Muon
+
+Muon is a momentum-based optimizer with an orthogonalized update direction. It introduces a more structure-aware update strategy and is included as an experimental optimizer in the library.
+
+### MuonAdam
+
+This optimizer combines Muon-style orthogonal updates with Adam-like moment estimates, making it a hybrid approach for experimentation and learning.
+
+Example:
+
+```python
+from nn.optim import SGD, Adam, Muon, MuonAdam
+
+sgd = SGD(parameters=model_parameters, learning_rate=0.01)
+adam = Adam(parameters=model_parameters, learning_rate=0.001)
+muon = Muon(parameters=model_parameters, learning_rate=0.02)
+muon_adam = MuonAdam(parameters=model_parameters, learning_rate=0.02)
+```
+
+## Training workflow
+
+A typical training loop looks like this:
+
+```python
+from nn import MSELoss
+from nn.optim import SGD
+
+model = ...
+criterion = MSELoss()
+optimizer = SGD(model._parameters.values(), learning_rate=0.01)
+
+for batch_x, batch_y in data:
+    predictions = model(batch_x)
+    loss = criterion(predictions, batch_y)
+
+    loss.backward()
+    optimizer.step()
+    optimizer.zero_grad()
+```
+
+## Repository structure
+
+```text
+krnl/
+├── README.md
+├── __init__.py
+├── requirements.txt
+├── version.txt
+├── src/
+│   ├── backends/
+│   │   ├── GPU_processer.py
+│   │   ├── __init__.py
+│   │   ├── device.py
+│   │   ├── kernels.py
+│   │   └── tensor.py
+│   ├── nn/
+│   │   ├── __init__.py
+│   │   ├── loss.py
+│   │   ├── model_utils.py
+│   │   └── optim.py
+│   └── tests/
+│       ├── test_opencl_backend.py
+│       ├── test_simple_model_implementation.py
+│       └── test_tensor.py
+└── .gitignore
+```
+
+## Running tests
+
+From the project root:
+
+```bash
+python src/tests/test_tensor.py
+python src/tests/test_opencl_backend.py
+```
+
+The OpenCL tests require a valid OpenCL installation and compatible device support.
+
+## Project status
+
+`krnl` is an educational framework for understanding the internals of deep learning systems. It is not intended to replace established libraries such as PyTorch or TensorFlow.
+
+Current focus areas include:
+
+- tensor arithmetic and autograd
+- gradient-based optimization
+- CPU execution with NumPy
+- GPU/OpenCL experimentation
+- small neural network primitives
+
+## Contributing
+
+Contributions are welcome in areas such as:
+
+- more layer types
+- additional loss functions
+- more optimization algorithms
+- clearer documentation
+- stronger tests
+- device and performance improvements
+
+The project remains intentionally simple and readable so it can serve as a learning tool.
+
+## License
+
+This repository does not currently include a license file. If you plan to distribute or publish it publicly, consider adding a license such as MIT or Apache 2.0.
+
+## Acknowledgements
+
+This project is built for experimentation and education in tensor math, computational graphs, optimization, and device-aware execution.

krnl-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "krnl"
+version = "0.1.0"
+description = "A lightweight educational tensor and automatic differentiation library with CPU and OpenCL GPU support"
+readme = "README.md"
+requires-python = ">=3.11"
+
+authors = [
+    { name = "Adhavan", email = "helloadhavan@gmaim.com" },
+]
+
+dependencies = [
+    "attrs==26.1.0",
+    "Automat==25.4.16",
+    "constantly==23.10.4",
+    "construct==2.10.70",
+    "hyperlink==21.0.0",
+    "idna==3.20",
+    "Incremental==24.11.0",
+    "Mako==1.4.3",
+    "MarkupSafe==3.0.4",
+    "numpy==2.5.4",
+    "packaging==26.3",
+    "platformdirs==4.13.5",
+    "protobuf==7.36.2",
+    "psutil==7.2.2",
+    "pyasn1==0.6.4",
+    "pyopencl==2026.1.4",
+    "pysnmp==7.1.30",
+    "pytools==2026.1.1",
+    "PyYAML==6.0.3",
+    "siphash24==1.9",
+    "Twisted==26.4.0",
+    "typing_extensions==4.16.0",
+    "zope.interface==8.7",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

krnl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+