ClumsyGrad

A Simple Automatic Differentiation Library built on top of NumPy

Contents:

• 1. Quick Start Guide
• 2. Tutorial
• 3. Examples
• 4. Internals
• 5. API Reference
  • 5.1. clumsygrad.tensor
  • 5.2. clumsygrad.random
  • 5.3. clumsygrad.math
  • 5.4. clumsygrad.activation
  • 5.5. clumsygrad.loss
  • 5.6. clumsygrad.optimizer
  • 5.7. clumsygrad.grad
  • 5.8. clumsygrad.gradcheck

Key Features

• Lightweight Design

  Minimal dependencies - built primarily on NumPy.

• Minimalist Architecture

  Easy to understand and modify for experimentation.

Quick Start Example

from clumsygrad.tensor import Tensor, TensorType
from clumsygrad.loss import mse_loss

# Create tensors with gradient tracking
x = Tensor([[1.0, 2.0]], tensor_type=TensorType.INPUT)
W = Tensor([[3.0], [4.0]], tensor_type=TensorType.PARAMETER)
b = Tensor([5.0], tensor_type=TensorType.PARAMETER)
target = Tensor([15.0], tensor_type=TensorType.INPUT)

# Forward pass: linear transformation
output = x @ W + b  # Matrix multiplication + bias

# Compute loss
loss = mse_loss(output, target)

# Backward pass: automatic differentiation
loss.backward()

# Gradients are now available
print(f"W gradient: {W.grad}")
print(f"b gradient: {b.grad}")
print(f"Loss: {loss.data}")

Installation

To install ClumsyGrad, you can use pip:

pip install clumsygrad

Note

ClumsyGrad requires Python 3.14+ and NumPy 2.5+.

Performance Notes

Warning

ClumsyGrad is mainly designed by me for educational purposes, and may not be completely optimized for performance.

Acknowledgments

• Inspired by PyTorch (obviously!) and other automatic differentiation frameworks.