multilayer-perceptron-from-scratch 0.1.2

A clean and educational implementation of a Multilayer Perceptron from scratch using NumPy

Multilayer Perceptron (MLP) from Scratch 🧠

Multilayer Perceptron from Scratch is a lightweight, educational, and high-performance implementation of a feedforward artificial neural network built entirely from scratch using NumPy.

A lightweight, educational, and high-performance implementation of a Multilayer Perceptron neural network, built entirely from scratch using NumPy.

This project implements the fundamental mathematics of deep learning—including Backpropagation and Stochastic Gradient Descent (SGD) with data shuffling—without the overhead of heavy frameworks like PyTorch or TensorFlow.

---

✨ Key Features

• 🎯 Pure NumPy: Zero dependencies for the core engine (only numpy).

• 🔄 Stochastic Gradient Descent (SGD): Includes automatic data shuffling every epoch for better convergence.

• 🏗️ Flexible Architecture: Custom-define any number of hidden layers and neurons.

• 📉 Matrix-Based Backpropagation: Efficient implementation using the four fundamental equations of backpropagation.

• 🎓 Educational Design: Clean, commented code ideal for learning how neural networks actually work "under the hood."

---

📦 Installation

You can install the package directly from PyPI:

pip install multilayer-perceptron-from-scratch

---

📓 Interactive Jupyter Notebooks (.ipynb)

For a richer, visual, and hands-on experience, the repository includes ready-to-run Jupyter Notebooks featuring complex non-linear classification tasks. Each demo captures dynamic metrics like Loss progression and Accuracy scores, culminating in detailed decision boundary plots using matplotlib.

---

🌕 DEMO 1: Moons Dataset Boundary

• Description: A classic, non-linear benchmarking problem. This demo uses a hidden layer of 16 neurons to smoothly separate two intertwining mathematical half-circles.
• Key Components: sklearn.datasets.make_moons, matplotlib.pyplot contour plotting.
• Performance: Reaches 100% accuracy in less than 1000 epochs.
• 🔗 Run in Cloud:

---

🌀 DEMO 2: Wide-Gap 6-Arm Spiral

• Description: A highly complex geometric distribution designed to test the network's ability to capture sharp, twisting transitions. By leveraging a deeper architecture ([2, 10, 10, 1]) and a higher learning rate ($\eta = 0.2$), the model maps the intricate spiral arms perfectly.
• Key Components: Custom synthetic spiral generator with a wide center gap.
• Performance: Successfully untangles all 6 arms, achieving 99.8%+ accuracy by epoch 2000.
• 🔗 Run in Cloud:

---

📊 DEMO 3: Continuous Cosine vs. Interrupted Sine

• Description: A sophisticated phase and amplitude classification task. The network is challenged to classify a completely continuous blue Cosine wave against a red Sine wave that gets intentionally interrupted at intersection points to avoid mathematical overlapping.
• Key Components: Custom hybrid mathematical wave simulation, matplotlib.lines.Line2D advanced legends.
• Performance: Demonstrates exceptional decision-boundary fitting with 98.6% accuracy.
• 🔗 Run in Cloud:

---

🚀 Quick Start (XOR Example)

The following example demonstrates how to solve the classic XOR problem using the Network class.

import numpy as np
from multilayer_perceptron import Network

# 1. Define Architecture: [Input (2), Hidden (20), Output (1)]
net = Network([2, 20, 1])

# 2. Prepare Training Data (XOR)
# Format: List of tuples (input_vector, target_vector)
training_data = [
    (np.array([[0], [0]]), np.array([[0]])),
    (np.array([[0], [1]]), np.array([[1]])),
    (np.array([[1], [0]]), np.array([[1]])),
    (np.array([[1], [1]]), np.array([[0]]))
]

# 3. Train using SGD
# Parameters: data, epochs, learning_rate
print("Starting Training...")
net.SGD(training_data, epochs=3000, learning_rate=0.2)

# 4. Test the model
print("\nResults:")
for x, y in training_data:
    output, _, _ = net.feedforward(x)
    prediction = 1 if output >= 0.5 else 0
    print(f"Input: {x.flatten()} | Target: {int(y[0][0])} | Predicted: {prediction}")

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Created with ❤️ by Nehorai Yosef