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 Github:Euclid ML on Github PyPI:Euclid ML on PyPI

---

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

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.