Live server: The web version runs at humandescent.net on an RTX 4090 GPU. Expect instability if many people connect simultaneously.
Human Descent opens the door for you to explore neural network optimization in high-dimensional weight space using the MNIST dataset. Manipulate everyday controllers (keyboard, xbox, DJ MIDI), each corresponding to a random direction in high dimensional weight space, to gain intuitive insights into the dynamics and complexities of neural network training.
- 3D landscape (default): renders three coupled loss surfaces that update in real time while you explore six random directions.
- 1D slices (experimental): renders six fast-updating loss curves, one per dimension. Launch with
?mode=1d(e.g.http://localhost:5173/?mode=1d) or use the View toggle in the header to switch between modes. - Team lobby (desktop only): open
?lobby=1or choose Lobby on desktop. Captains create and name teams, invite up to two teammates, and start a team speed run or challenge another team. Unequal teams are supported. Each player controls one landscape; everyone shares the team's model, batch and loss. New Dimensions advances once everyone votes, with green borders showing the current votes. Mobile supports solo play only. See multiplayer architecture and testing.
The visualizations in this project rely on a custom set of layers found in hudes/model_first/model_first_nn.py. These helpers wrap familiar PyTorch modules (linear, convolution, pooling, flatten, sequential) so that every forward pass accepts not just a minibatch of data, but also a batch of parameter tensors. Key pieces include:
get_param_moduleandMFSequential, which convert a standard model definition into its batch-parameterized twin.MFConv2dandMFLinear, which reshape weights and biases on the fly to evaluate many parameter sets in parallel using grouped convolutions and batched einsum calls.- Lightweight utilities like
MFMaxPool2dandUnsqueezethat preserve the extra parameter dimension without copying data.
Because these modules keep the parameter batch dimension throughout the network, we can sweep across hundreds of points on the loss surface with a single forward pass. That efficiency is what makes the interactive loss-landscape exploration in the browser viable.
git clone https://github.com/misko/human_descent.git # clone the repo
python3 -m venv hudes_env # create a virual enviornment
source hudes_env/bin/activate
cd human_descent
pip install . # install human descent and its dependencies in the virtual env
bash run.sh # download mnist, run the server, and then run the client!
The aim of this repository is to build an interactive tool to allow humans to directly optimize high dimension problems such as neural network training. Inspired by Measuring the Intrinsic Dimension of Objective Landscapes, (Chunyuan Li and Heerad Farkhoor and Rosanne Liu and Jason Yosinski)
A can use any of the ineractive inputs (Xtouch mini midi mixer, Xbox like controllers, keyboard, etc..) to control a random n-dimensional subspace of parameter space at a time.
Iteratively selecting between new training batches and different random subspaces this allows you to optimize a very high dimensional weight space.
For example its possible to train a 26,000 parameter MNIST model using a 6 dimensional keyboard input in about 10 minutes.
- Run frontend units with
cd web && npm run test:unit. Browser tests require a compatible Python environment or the test container described below. - Run multiplayer browser tests with
cd web && HUDES_TEST_IMAGE=hudes-test npm run test:multiplayer. These use real sockets and services with a deterministic inference engine; separate Python tests exercise real PyTorch inference. - When iterating on the speed-run or highscores flows, capture deterministic Playwright logs with:
cd web
(npm run -s test:e2e:chromium -- tests/speedrun.spec.mjs) 2>&1 3>&1 | tee /tmp/play-speedrun.log >/dev/null
This preserves browser/server output under /tmp/play-speedrun.log for later debugging. See the multiplayer testing guide for the separate unit, wire, service, browser and numerical checks.
The production container uses Ubuntu 26.04 LTS, Python 3.14.9 and PyTorch 2.14.1
with CUDA 12.6.
Python 3.14 is the newest version supported by the current native ML wheels.
Node 26.12.1 is required for the web build. Install browser packages with
cd web && npm ci; the checked-in lockfile fixes the dependency graph.
Build the server with docker build --target runtime -t human-descent ..
For CPU tests, pass --target test --build-arg TORCH_BACKEND=cpu --build-arg TORCH_REQUIREMENTS=requirements-cpu.lock. Python dependencies are
installed from hashed locks. Production images omit pip; rebuild the image to
update dependencies.
The system and certifi CA bundles share the corrected OS trust store, with the affected emSign G1/G3 roots disabled. Build-time assertions check both trust paths; Requests, HTTPX and pip also receive explicit CA bundle settings.
The runtime builds PCRE2 10.49 from its pinned upstream source digest and runs the upstream test suite before packaging the library. It uses Ubuntu's GNU coreutils provider to avoid the affected Rust coreutils implementation. These changes apply to the container; they do not replace host operating system tools. The shared Expat library also uses verified upstream 2.9.0 with its test suite run during the build, matching the version already bundled by CPython. The upstream XML complexity issue remains open; this update does not clear that remaining finding. The Xrender library uses verified upstream 0.9.13, fixing CVE-2026-88807 in X11 reply parsing. Its build reuses the graphics headers already needed by Pygame; compilers and development headers stay outside the runtime image.
Keep ports 10000 (WebSocket) and 10001 (HTTP API) on loopback at the host and
forward them through the TLS proxy. Persist the MNIST data and high score database
under /data. Set HIGH_SCORES_PATH if using a different database location.
Deleting high scores requires an Authorization: Bearer header matching
HUDES_ADMIN_TOKEN. When that environment variable is absent, deletion is disabled.
Store the token in a private environment file; never include it in a web build.
Public game input has bounded message, client, dimension and SGD limits.
Disconnected resume sessions expire after HUDES_RESUME_TTL (120 seconds by
default), and their inference state is released. Tensor caches also evict old
batches and dimension vectors so repeated navigation cannot grow them indefinitely. HTTP headers have a read timeout
and size limit. Invalid tensor types and nonfinite numeric values are rejected
before shared inference work is scheduled.
Browser tests allocate isolated ports and a separate high score database, and wait for
the connection to be ready before sending game controls. They never terminate a
production listener. HUDES_BACKEND_COMMAND can supply a containerized GPU server
for testing, while HUDES_PYTHON selects the protobuf compiler's interpreter.
A dependency refresh does not by itself certify the operating system. Retain container scan evidence and review unfixed distribution advisories before public cutover. Trivy reports no critical/high findings using Ubuntu's vendor priorities; some vendor-medium entries have higher CVSS base scores. Remaining distribution findings stay in the raw audit report, including stale PCRE2 records for versions older than the installed upstream security release. Public cutover still requires resolution of the proxy's end of life Ubuntu installation. The affected emSign G1/G3 trust anchors are explicitly disabled in the container system store; certifi 2026.10.19 links to the corrected system bundle.
