Metadata-Version: 2.4
Name: euclid-ml
Version: 0.9.9
Summary: A simple deep learning framework built on top of numpy/cupy.
Author: Dra3don
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Euclid ML

**Euclid ML** is a lightweight deep learning framework built entirely in **Python**, using **NumPy** for CPU computation and **CuPy** for GPU acceleration.

Euclid was created to make the internals of modern neural networks understandable and accessible. Rather than relying on large compiled frameworks, Euclid implements core deep learning functionality from the ground up, including automatic differentiation, tensors, neural network layers, convolutional networks, Transformer architectures, optimizers, and GPU computation.

Euclid has also been used to build and experiment with multiple machine learning projects, including **CNNs, Transformers, language models, neural image compression, and neural chess evaluation**.

---

## Features

### Core

* Automatic differentiation (Autograd)
* Computational graphs
* Tensor operations and gradient tracking
* CPU backend using NumPy
* GPU backend using CuPy
* Memory-efficient autograd
* Automatic computational graph cleanup
* Modular and extensible architecture

### Neural Network Layers

* Dense / Linear
* Conv2D
* ConvTranspose2D
* MaxPool2D
* Flatten
* Dropout
* Transformer blocks
* Multi-head self-attention
* Feed-forward networks

### Activation Functions

* ReLU
* Sigmoid
* Tanh
* Softmax

### Loss Functions

* Cross Entropy
* Mean Squared Error (MSE)
* Huber Loss

### Optimizers

* SGD
* RMSProp
* Adam

---

## Architectures

Euclid can be used to build a variety of neural network architectures, including:

* Fully connected neural networks
* Convolutional neural networks (CNNs)
* Encoder-decoder networks
* Transformer-based models
* Language models
* Custom neural network architectures

Euclid has been used for projects including:

* MNIST image classification
* Neural image compression
* Transformer language models
* Knowledge distillation
* Neural chess evaluation
* Other machine learning experiments

---

## Performance

Euclid is designed primarily for **understanding and experimentation**, but performance has also been an important focus of the project.

The framework includes:

* Vectorized tensor operations
* Vectorized convolution using `im2col`
* Vectorized pooling
* GPU acceleration through CuPy
* Memory-efficient autograd
* Automatic cleanup of computational graphs
* Reduced intermediate tensor allocations

These optimizations allow Euclid to go beyond small educational examples and train substantially larger neural networks.

---

## Computer Vision

Euclid supports convolutional neural networks through layers such as `Conv2D`, `ConvTranspose2D`, `MaxPool2D`, and `Flatten`.

The convolution implementation uses vectorized operations such as **im2col**, allowing convolutional networks to be trained using NumPy or CuPy.

Euclid has been used to train a CNN on **MNIST**, reaching approximately **99% test accuracy**.

Euclid also supports **transposed convolutions**, making it possible to build encoder-decoder architectures for tasks such as neural image compression.

---

## Neural Image Compression

One of the projects built with Euclid is a neural image compression system using an **encoder-decoder architecture**.

The encoder compresses an image into a much smaller latent representation, while the decoder reconstructs the image from that representation. The model uses convolutional layers and transposed convolutional layers to perform the encoding and reconstruction.

The system has been tested at extremely high compression ratios, including approximately **48x compression**, demonstrating how neural networks can learn compact representations of images.

---

## Transformers

Euclid includes the building blocks required to experiment with Transformer architectures, including:

* Multi-head self-attention
* Feed-forward networks
* Transformer blocks
* Positional information
* Configurable model dimensions
* Configurable attention heads
* Configurable sequence lengths

These components have been used to build and train small language models and experiment with **Transformer-based language modeling and knowledge distillation**.

Euclid has also been used to build a substantially larger experimental Transformer with multiple Transformer blocks, attention heads, and a large feed-forward dimension.

---

## GPU Support

Euclid supports both CPU and GPU computation.

| Backend | Library |
| ------- | ------- |
| CPU     | NumPy   |
| GPU     | CuPy    |

The framework is designed to keep the API consistent between the two backends, allowing the same model code to run on different hardware with minimal changes.

---

## Example

```python
import euclid as Euclid

model = Euclid.networks.Sequential([
    Euclid.layers.Dense(784, 128),
    Euclid.layers.ReLU(),
    Euclid.layers.Dense(128, 10),
    Euclid.layers.Softmax(),
])

optimizer = Euclid.optimizers.Adam(
    model.parameters(),
    learning_rate=1e-3
)

loss = Euclid.losses.CrossEntropy()
```

The same general API can be used when experimenting with more advanced architectures.

---

## Why Euclid?

Euclid was created to answer a simple question:

> **How do modern deep learning frameworks actually work under the hood?**

Rather than treating deep learning as a black box, Euclid provides an implementation where the underlying mechanisms are accessible.

You can inspect the autograd system, see how gradients propagate, modify layers, experiment with optimizers, implement new architectures, and run the framework on either CPU or GPU.

Euclid is not intended to replace frameworks such as PyTorch or TensorFlow.

It is intended to help you **understand them by building the underlying ideas yourself**.

---

## Philosophy

Euclid focuses on:

* **Readable source code**
* **Minimal dependencies**
* **Understanding neural networks internally**
* **Easy experimentation**
* **Extensibility**
* **Performance where practical**

Instead of hiding everything behind highly optimized compiled code, Euclid keeps the core implementation visible and editable.

Want to implement a new layer? You can.

Want to experiment with a new activation function? You can.

Want to modify the attention mechanism of a Transformer? You can.

Want to build your own neural network architecture from the underlying components? You can.

**That's the point of Euclid.**

---

## Roadmap

* [x] Automatic differentiation
* [x] Tensor system
* [x] Dense layers
* [x] Convolutional neural networks
* [x] Conv2D
* [x] ConvTranspose2D
* [x] GPU backend
* [x] Vectorized convolution
* [x] Vectorized pooling
* [x] Optimizers
* [x] Transformer architecture
* [x] Multi-head self-attention
* [x] Memory-efficient autograd
* [x] Language model experiments
* [x] Knowledge distillation experiments
* [x] Neural image compression
* [ ] Recurrent neural networks
* [ ] Mixed precision training
* [ ] Model serialization
* [ ] Distributed training

---

## Contributing

Contributions, bug reports, feature requests, and discussions are welcome.

If you'd like to contribute, feel free to open an issue or submit a pull request.

---

## License

This project is licensed under the **MIT License**.
