the demo

The black hole demo, explained like a human

This page explains what the demo actually does, in plain words. There is real physics here, but you don't need any of it to build your own sim today. Read it for the ideas and the vocabulary. The few formulas that appear are guests, not the hosts.

download the demo (Python, any OS) ↓unzip, then double-click run.bat (Windows) or run sh run.sh (Mac). It finds or fetches a compatible Python for you. GPU recommended.

1 · The one idea everything hangs on

Newton said gravity is a force: things pull on each other. Einstein said no: mass bends space and time around itself, and everything (including light) just travels in the straightest possible line through that bent space. The classic picture is a bowling ball on a trampoline. A marble rolling past doesn't get "pulled", it follows the dip in the surface.

A black hole is the extreme case: so much mass in so little space that close to it, the bending is total. There's a point of no return, the event horizon. Light that crosses it doesn't come back, which is the entire reason the thing looks black.

In 1916, Karl Schwarzschild solved Einstein's equations for a non-spinning black hole, while serving in World War I. It took until 1963 for Roy Kerr to crack the spinning version. Real black holes all spin, so the spinning solution, the Kerr metric, is the equation for the real thing, and it's what this demo computes. That's the whole reason for the name.

2 · How the picture gets made: ray tracing, backwards

My old sims moved particles around and drew a dark circle in the middle. This demo draws nothing by hand. Instead, for every single pixel of the window, it fires a ray of light backwards: out of the camera, into space. Einstein's equations bend the ray as it travels. Then the pixel simply shows whatever its ray ended up hitting:

One ray per pixel, fired backwards from the camera. Where the ray ends up decides the pixel's color. The window is about a million pixels, so: a million of these, every frame.

Why backwards? Because a star sprays light in every direction and almost none of it enters your camera. Tracing forwards wastes almost every ray. Tracing backwards from the camera means every ray you compute is one that matters. Every serious renderer works this way, including the ones at Pixar; the only difference here is that gravity gets a vote on where each ray goes.

Bending the ray is done by solving a small set of differential equations, step by step, with a standard numerical method (called RK4; up to ~400 tiny steps per ray). That phrase, "solving equations step by step because there's no shortcut formula", is basically the definition of a simulation. Your sim today will do the same thing, just with simpler equations.

3 · What you're actually seeing on screen

Here's the part I find genuinely insane: nobody drew ANY of the features you see. They all emerge from the light-bending math on their own.

The black circle ("the shadow"). Pixels whose rays fell in. The math makes it about 2.6 times wider than the horizon itself, and that's exactly the size of the dark patch in the real Event Horizon Telescope photos from 2019.
The thin bright ring hugging the shadow. Light that did a full lap (or two, or three) around the black hole before escaping to the camera. Photons doing orbits.
The glow arcing over the top ("the Interstellar look"). That's the back half of the disk, which is physically behind the hole. Its light bends up and over the top, so you see behind the black hole. Same math the Interstellar VFX team used.
One side of the disk is brighter. The gas orbits at a decent fraction of the speed of light. The side racing toward you gets brightness-boosted (this is called relativistic beaming), the side racing away gets dimmed. The real telescope images have the same lopsided glow.
The colors. No artist picked that orange. The gas gets hotter closer in (friction), and each ring glows with the actual color a thing at that temperature glows, like iron in a forge going red, then orange, then white. Physicists call that blackbody color.
Drag the spin slider and the shadow goes D-shaped. A spinning black hole drags space itself around with it, like a spoon spinning in honey. This is frame dragging, and it's the signature difference between Schwarzschild and Kerr. The slider also moves the disk's inner edge: closer to the hole the faster it spins, another straight prediction of the math.

Verify it, don't trust it

Run python kerr_blackhole.py --check. It fires test rays and compares the results against exact numbers physicists have worked out on paper (the shadow size, the innermost stable orbit, the spin asymmetry). If the physics were faked, these tests could not pass. Demand this of your own sims: every real simulation has some known answer it can be checked against.

4 · A taste of the actual math (optional, skippable)

You can close this section and lose nothing. But if you want to see what "real physics in the code" literally looks like, here are the two numbers doing the most work.

Where the horizon is. The spin of the hole is a number $a$ between 0 (not spinning) and 1 (spinning as fast as physics allows). The point of no return sits at

r_+ = 1 + \sqrt{1 - a^2}

Read it out loud: for a non-spinning hole ( $a=0$ ) the horizon radius is 2 units; spin it up to the max ( $a=1$ ) and the horizon shrinks to 1. One tiny formula, and it's wired straight to the demo's spin slider.

The color-and-brightness number. When a ray hits the disk, the code computes one number $g$ : the ratio of the photon's energy when it reaches you to its energy when it left the gas. Climbing out of the gravity well drains the photon (gravitational redshift), and the gas rushing toward or away from you shifts it again (the Doppler effect, same reason an ambulance siren changes pitch as it passes). Both effects collapse into that single $g$ . Then: brightness gets multiplied by $g^4$ , and color shifts by $g$ . That one number is carrying all of Einstein on its back, and it's maybe six lines of Python.

The honest version

What's deliberately simplified in the demo: the disk is infinitely thin, its turbulence is a noise texture rather than real fluid dynamics, and the background stars aren't redshifted. Everything about where light goes and what color it arrives is exact. Knowing precisely which parts of your sim are real and which are decoration is the difference between simulating and decorating. Say it in your README and nobody can touch you.

5 · Where each idea lives in the code

The demo is one Python file, about 500 lines. The physics is maybe 80 of them:

The idea	Function in `kerr_blackhole.py`
How curved space bends each ray (Kerr, 1963)	`geodesic_rhs`
Stepping the ray forward, ~400 small steps	`rk4_step`
Turning a pixel into a ray direction	`camera_ray`
Where the disk's inner edge sits (moves with spin)	`isco_radius`
The g number: redshift + Doppler + beaming	`shade_disk`
How hot the gas is at each radius	`disk_temperature`
Temperature → glow color	`blackbody_rgb`
The self-tests	`run_checks` (run with `--check`)

There's also a SHOW_physics.py in the download: the physics core copied onto one screen with plain-English comments, for reading.

6 · Your ladder: what to build yourself

You do NOT need any of the above for the hackathon. Black hole sims come in levels, every level is legitimate, and honesty about your level beats faking a higher one:

Level 1: Newton. Particles pulled by the school formula $F = GMm/r^2$ , a capture radius where they vanish, color by speed. Far from the hole, Newton is within a percent of Einstein, so say that in your README and your sim is honest. This is what the workshop master prompt builds, and it can look great.
Level 2: bend some light. One famous equation bends light rays around a non-spinning hole in 2D. Ask your AI: "add gravitational lensing using the real geodesic equation for a Schwarzschild black hole, and explain the equation to me before you code it." Real lensing, about 20 lines.
Level 3: what the demo does. Full spinning-black-hole ray tracing. The recipe is this page, and the annotated code is in the download.

The actual point of the demo

Anyone can prompt an AI into "a black hole simulation." The difference between decorative and real is knowing which ideas must be inside (bent light paths, the g number) and how to check they're really being computed (the self-tests, the known numbers). Specifying and verifying: that's the skill that makes you dangerous with AI tools instead of dependent on them.

back to the workshop →see all sim ideas