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
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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 modelsUserSessionandUserInteraction.
🛠️ Requirements & Setup
Environment Prerequisites
As per local rule, the virtual environment is installed locally:
- Python 3.10+ (tested on Python 3.13)
- Local venv:
/Users/stergios/.venvs/digitalED_gd_3d
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
No comments to display
No comments to display