DigitalED | 3D Gradient Descent Gamified Lab

DigitalED | 3D Gradient Descent Gamified Lab

An interactive, gamified 3D and 2D laboratory designed to teach the mathematics and intuition of Gradient Descent algorithms in machine learning. Built as a full-stack Django application with Three.js WebGL graphics and 100% client-side computation.


🚀 Key Features

  1. Split-Screen Ergonomic Layout:

    • Narrow Left Column (≤ 25% max width): Sleek glassmorphic control center with gamification scoreboard, mission challenges, surface selector, hyperparameter sliders, optimizer switches, and step controls.
    • 3D Visualizer Canvas (75% right area): Full-viewport WebGL canvas with real-time camera controls, dynamic height colormaps, animated ball physics, glowing trajectory path ribbons, and vector field quiver plots.
  2. Gamified Educational Missions:

    • Level 1: The Parabolic Valley: Smooth convex bowl $f(x, y) = 0.5(x^2 + 2y^2)$. Tune learning rate $\alpha$ to reach the target in minimum steps.
    • Level 2: Saddle Point Pass: Hyperbolic paraboloid $f(x, y) = 0.4(x^2 - y^2)$. Demonstrates how standard GD stalls at saddle plateaus and how Momentum or Adam accelerates past.
    • Level 3: Rosenbrock Banana Trench: The famous non-convex ravine $f(x, y) = 0.08((1-x)^2 + 10(y-x^2)^2)$. Demonstrates wall oscillations vs smooth ravine navigation.
    • Level 4: Multi-Modal Peaks (Himmelblau): Landscapes with multiple local and global minima. Teaches how stochastic mini-batch noise escapes shallow basins.
    • Level 5: Rastrigin Ripple Field: Dozens of ripple barriers where pure GD gets trapped and momentum glides through.
    • 🎲 Procedural Random Landscapes: Generates random 3D surfaces dynamically.
  3. Hover Educational Explanations:

    • Hovering over any parameter reveals rich educational cards with the mathematical equation, core concept intuition, physical analogies (e.g. friction, ball inertia, stride length), and "Too Low" vs "Too High" consequences.
  4. 3D Perspective ⇄ 2D Contour Map Toggle:

    • Seamlessly switch between the 3D perspective surface and an orthographic top-down 2D contour map with isobar level curves and gradient direction vectors.
  5. Ball Drop Physics & Interactive Surface Click:

    • The ball drops from the sky onto the surface, bouncing on impact and rolling along the exact gradient descent trajectory.
    • Click anywhere on the 3D surface mesh to drop the ball at that exact coordinate.
  6. 100% Client-Side Compute:

    • All surface functions, analytical and numerical gradients ($\partial f/\partial x, \partial f/\partial y$), optimizer updates (GD, Polyak Momentum, RMSprop, Adam), stochastic noise, and WebGL rendering run completely in the browser for instant, lag-free 60fps interaction.
  7. Invisible Unique Session Tracking & Telemetry:

    • Every visitor is automatically assigned a unique persistent UUID via Django middleware.
    • User inputs, hyperparameter configurations, and simulation outcomes are asynchronously posted to /api/record-input/ and recorded in SQLite database models UserSession and UserInteraction.

🛠️ Requirements & Setup

Environment Prerequisites

As per local rule, the virtual environment is installed locally:

Installation

# If creating a fresh local environment:
python3 -m venv ~/.venvs/digitalED_gd_3d
source ~/.venvs/digitalED_gd_3d/bin/activate

# Install dependencies:
pip install -r requirements.txt

Running with Django Dev Server

python manage.py migrate
python manage.py runserver 127.0.0.1:8000

Then open http://127.0.0.1:8000 in your web browser.

Running with uWSGI (Production Mode)

A production-ready uwsgi.ini is located at the project root:

uwsgi --ini uwsgi.ini

This launches a master process with 4 worker threads serving the application and static files at http://0.0.0.0:8000.


📂 Project Architecture

digitalED_gradient_descent_3d/
├── requirements.txt            # Project dependencies (Django, uWSGI, etc.)
├── uwsgi.ini                   # Production uWSGI configuration at root
├── manage.py                   # Django management script
├── config/
│   ├── settings.py             # Settings, DB config, middleware, staticfiles
│   ├── urls.py                 # Root URL configuration
│   └── wsgi.py                 # WSGI entrypoint
├── visualizer/
│   ├── models.py               # UserSession & UserInteraction models
│   ├── middleware.py           # Invisible session tracking middleware
│   ├── views.py                # Views: index, record_input API, session_stats API
│   ├── urls.py                 # App URLs
│   └── admin.py                # Django Admin integration
├── templates/
│   └── visualizer/
│       └── index.html          # Semantic HTML5 layout, HUD, popovers
└── static/
    ├── css/
    │   └── styles.css          # Dark glassmorphism, 25% sidebar layout, HUD
    └── js/
        ├── surfaces.js         # Mathematical surfaces & random procedural generator
        ├── optimizers.js       # Client-side GD, Momentum, RMSprop, Adam solvers
        ├── visualizer3d.js     # Three.js 3D/2D renderer, ball drop & trajectory
        ├── audio.js            # Procedural Web Audio API sound synthesizer
        └── app.js              # Coordinator, UI binding & telemetry reporting

Site: gradient.stergios.ch


Revision #1
Created 2026-10-07 19:16:03 UTC by Stergios
Updated 2026-10-07 19:16:03 UTC by Stergios