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

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

• Automatic differentiation
• Tensor system
• Dense layers
• Convolutional neural networks
• Conv2D
• ConvTranspose2D
• GPU backend
• Vectorized convolution
• Vectorized pooling
• Optimizers
• Transformer architecture
• Multi-head self-attention
• Memory-efficient autograd
• Language model experiments
• Knowledge distillation experiments
• 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.