Metadata-Version: 2.4
Name: euclid-ml
Version: 0.9.9.1
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 because I wanted to see how machine learning libraries worked under the surface.

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

TinyGPT:[TinyGPT](https://pypi.org/project/)
Github:[Euclid ML on Github](https://pypi.org/project/euclid-ml/0.9.9/)
PyPI:[Euclid ML on PyPI](https://pypi.org/project/euclid-ml/0.9.9/)

---

## 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

### Reinforcement Learning

* PPO
* Environments
---

## 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
* GANs
* 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.

But also it is not very fast because it is built entirely in python

---

## 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(
    
    learning_rate=1e-3
)
optimizer.set_parameters(model.parameters())

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 (don't its kinda bad), 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.

It is also pretty easy to understand because it is completely in python.

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

## What's Next

My next goal is to build another library on top of this one more comparable to tenserflow, with reinforcement learning support.

## 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**.
