ps-neuralnetwork 0.1.0

A minimal neural network framework with automatic differentiation built from scratch

ps-neuralnetwork

A minimal neural network framework built from scratch in pure Python, featuring a custom automatic-differentiation Value class, multi-layer perceptron (Neural_Network), training loop, and decision boundary visualization. Perfect for educational purposes and quick experimentation with 2D classification tasks.

---

Features

• Automatic Differentiation via a custom Value class
• Multi-Layer Perceptron with configurable hidden layers and tanh activations
• Training Utility with Mean Squared Error loss and manual gradient descent
• Decision Boundary Visualization for 2D datasets using Matplotlib

---

Installation

git clone https://github.com/yourusername/ps-neuralnetwork.git
cd ps-neuralnetwork
pip install -e .

This installs the package in “editable” mode so you can modify the source and immediately test changes.

---

Quick Start

# 1. Import training helper and network
from ps_neuralnetwork.training import training
from ps_neuralnetwork.nn_scratch import Neural_Network

# 2. Generate 2D classification data
from sklearn.datasets import make_moons
import matplotlib.pyplot as plt

X, y = make_moons(n_samples=100, noise=0.1)
y = y * 2 - 1  # Convert labels from {0,1} to {-1,+1}

# 3. Visualize raw data
plt.figure(figsize=(5,5))
plt.scatter(X[:,0], X[:,1], c=y, s=20, cmap='jet')
plt.title("Make Moons Dataset")
plt.show()

# 4. Create and configure Neural Network
net = Neural_Network(input_size=2, layer_sizes=[4, 3, 5, 2, 1])

# 5. Train the network
learning_rate = 0.001
num_epochs     = 500
trainer = training(net, X, y, learning_rate, num_epochs)

# Run training
trainer()

# 6. Plot training progress and decision boundary
trainer.plot(smoothness=0.05)

---

API Reference

ps_neuralnetwork.nn_scratch.Neural_Network(input_size, layer_sizes)

• input_size: Number of input features (e.g., 2 for 2D data)
• layer_sizes: List of neuron counts for each hidden and output layer (e.g., [4,3,1])

Creates a feed-forward network with tanh activations.

---

ps_neuralnetwork.training.training(net, X, y, learning_rate, num_epochs)

• net: Instance of Neural_Network
• X: Feature array of shape (n_samples, input_size)
• y: Label array of shape (n_samples,) with values -1 or +1
• learning_rate: Step size for gradient descent (e.g., 0.001)
• num_epochs: Number of training epochs (e.g., 500)

Returns a trainer object with:

• Callable: trainer() to start training
• trainer.plot(smoothness): Visualizes decision boundary and loss over epochs
  • smoothness controls contour resolution

---

Package Structure

ps-neuralnetwork/
├── src/
│   └── ps_neuralnetwork/
│       ├── __init__.py
│       ├── value.py        # Automatic differentiation engine
│       ├── network.py      # Multi-layer perceptron
│       └── training.py     # Training loop and visualization
├── README.md              # This file
├── LICENSE                # MIT License
└── pyproject.toml         # Build and metadata

---

License

This project is released under the MIT License. See the LICENSE file for details.

---

Acknowledgements

• Built with NumPy, Matplotlib, and scikit-learn
• Inspired by “neural networks from scratch” tutorials and micro-autograd implementations

The Value class was adapted from Andrej Karpathy’s micrograd project (https://github.com/karpathy/micrograd), MIT License.

Happy experimenting! 🎉