Handwired

Handwired is a library that rewrites ordinary JavaScript programs (made of if‑else, loops, and simple arithmetic) into a fully differentiable computation expressed only with matrix multiplication and the ReLU activation. Because the resulting program uses only these two primitives, it can be executed on the CPU, WebGPU, or any other hardware that accelerates matrix ops, and the whole computation remains differentiable without any training‑time weight learning.

How it works

Parse the source – Handwired analyses the control‑flow of a JavaScript function.
Replace branches with arithmetic – Conditional statements are expressed as linear combinations using the ReLU trick (Math.max(0, x)), e.g. a > 4 becomes a value that is 1 when true and 0 when false.
Collect operations – All additions, multiplications, and ReLUs are gathered into a single large matrix‑multiply expression.
Execute – The resulting matrix program can be run directly in JavaScript or dispatched to WebGPU for GPU‑accelerated execution.

Because the transformation is exact (no approximation) and the “weights” are just the constants that were already present in the original code, the program is differentiable out‑of‑the‑box.

Why it matters

End‑to‑end differentiability of legacy JavaScript logic enables gradient‑based experiments (e.g., fine‑tuning the constants, or attaching the program to a learnable neural network).
GPU‑level parallelism for code that was originally single‑threaded, making it possible to run massive searches (the repo demonstrates a JSON‑search over 100 k documents in milliseconds).
No training required – the “weights” are the original numeric literals, so you get a functional model instantly.

Example

// Original code
const a = 5
const result = (a > 4) ? 10 : 12

Handwired rewrites it to:

const a = 5
// ReLU‑based branch selector
const above4 = Math.max(0, a - 4) - Math.max(0, a - 5)
// Both branches are computed, then blended
const result = above4 * 10 + (1 - above4) * 12

All operations are now linear + ReLU, ready for matrix‑multiplication execution.

Getting started

# Clone the repo and install dependencies (uses bun)
git clone https://github.com/chenglou/handwired.git
cd handwired
bun install

# Run the demo server locally
bun start

The live demos are also hosted at https://chenglou.me/handwired/.
Explore the source in src/, documentation in docs/, and template projects in template/.
Older experimental code lives in the lab/ folder.

Use‑case ideas

Unfreeze and train the constants to see what gradients can achieve.
Hybrid models: attach a Handwired‑converted program to a trainable neural net (e.g., a tiny GPT) and train the whole system end‑to‑end.
High‑performance search: run traditional JavaScript logic (like JSON filtering) at GPU speed for large datasets.

License & Contributions

The repository is open‑source; see the LICENSE file for details. Contributions are welcome via pull requests.

chenglou/handwired