Manu Martínez-Almeida — Writing

NoiseLang: Where N = 5 is a Dirac delta

Manu Martínez-Almeida — Mon, 06 Jul 2026 00:00:00 GMT

During my telecommunications degree I took a course on signals and noise, I spent a lot of evenings writing probability by hand: expectations, variances, the odds of two random variables landing in some region. It always sucked, when I tried to run it on a computer, so much boilerplate.

That wish became NoiseLang. I started it about nine years ago, however, I never finished it. Only recently, I brought it back thanks to AI tools and something far more ambitious than what I could have built alone the first time.

Everything is a distribution

The whole language hangs on one idea, that every value is a probability distribution. A plain number is a Dirac spike, a distribution with all its weight on a single value. Since constants and random variables are the same kind of object, every operator in the language maps distributions to distributions.

Purists will tell you that the Dirac delta belongs to continuous densities and has no business on a six-sided die, and they are right. What I mean is the Dirac measure, all the weight on one point, which works fine on a die. Noise never evaluates a density anyway, it draws samples. And a constant collapses back to a plain integer in the graph, so 5 costs nothing.

A name always refers to one fixed node, the same way X is the same X across a whole page of math. So X + X is 2X and X - X is exactly 0. If you want variable independence you write separate draws, ie, using ~ multiple times, or ~[N] to draw N independent variables into a vector.

X ~ unif_int(1, 6)
Y ~ unif_int(1, 6)
X + Y                 # two independent dice, a real 2d6 distribution

Nothing runs until you ask for some results, for example, P(X + Y < 10), at that moment it forces the runtime to run millions of simulations (across all cores, if available) and return an estimate with a standard error attached.

Bday = unif_int(1, 365)
days ~[23] Bday          # 23 people in a room
P(has_duplicates(days))  # the birthday paradox, about 0.507

This is much easier to watch than to describe, so I built some cool demos!

Why it sat for nine years

The design was never the hard part, because a parser and a tree-walking interpreter for this language is a weekend of work. The problem was everything else, writing an efficient Monte Carlo runtime, instead of a naive interpreter, conditional bayesian inference, and more.

Current version is a compiler with a GPU backend (WGSL through wgpu), a WASM backend, and a pile of careful numerical code, so for a cute-weekend project it stayed permanently out of reach.

Building the ambitious version with an agent

At my day job and side projects, I am experimenting with the boundaries of what today’s AI agents can do. For example, I am also porting a game I built 15 years ago for iOS, in archaic Objective-C to a modern game engine (with relative success).

With NoiseLang, I realized, AI is great at building the JIT parts, the runtime parts, the numerical parts, but it sucks at coming up with good language design ideas, many times overriding existing language features for different purposes, or coming up with different syntax for non-orthogonal features.

One IR, three backends

The first plan was to compile the graph into WASM and let a WASM runtime JIT it for me, because that runtime was surely going to optimize better than any compiler I could write myself. While exploring that, I realized I could reach for the JIT optimizer directly and skip the WASM step, so the first native backend was a Cranelift JIT, a killer library for a project like this, NoiseLang ran at native speed and I barely wrote any compiler. That JIT is gone now. Keep reading, because the reason it left is my favorite part of the whole project.

~ and the distribution constructors build an append-only DAG called the RvGraph. This graph is the single source of truth, which is later converted into three different code paths:

a columnar batch interpreter that works everywhere and acts as the correctness oracle;
a WGSL emitter that fuses a whole expression into one GPU compute shader;
a WASM emitter that does the same fused kernel for the browser’s CPU.

flowchart LR
  src["X ~ unif(1, 6)"] --> ir["RvGraph"]
  ir --> interp["batch interpreter"]
  ir --> wgsl["WGSL emitter (GPU)"]
  ir --> wasm["WASM emitter"]
  wgsl -. fallback .-> interp
  wasm -. fallback .-> interp

One shared module defines what the graph means, so the two code generators stay thin and cannot drift apart. Anything a backend can’t successfully compile falls back to the interpreter, and the results stay identical across backends and core counts. All tests run in all three code paths and compared to be bit-identical.

The engine picks the path per query, the same way a SQL query planner picks an execution plan: a cost model keeps the small queries on the vectorized interpreter, fans the medium ones out across every core with a work-stealing reducer, and sends the heavy ones to the GPU as one fused compute shader. You write P(...), the planner does the rest.

Making the Monte Carlo loop cheap

All the performance work is about one loop: draw a few million samples, evaluate the expression on each, and reduce the results. A handful of techniques carry most of it, while keeping the results deterministic (that was the hard part).

Kernel fusion keeps every intermediate value in registers, so an arithmetic-heavy expression stays in registers. The PRNG compiles into the kernel, and the ln, sin, and cos become inline polynomial approximations, speeding up the kernel by a factor of 2.

My favorite trick used to be in the RNG. The original generator (xoshiro256++) is a serial dependency chain, so instead of fighting that, the kernel ran four independent streams at once and let the out-of-order core overlap them. That trick is retired now, and the reason is better than the trick: the RNG became counter-based (squares64), a middle-square hash where every draw is a pure function of (seed, lane, source). No state to thread through the loop means any slice of the sample space can run on any core, or any GPU thread, and land bit-identical. And it is not a random pick (pun intended), the exact bit stream the engine consumes passed 1 TB of PractRand with zero anomalies.

On my 14-core M4 Pro, a one-line P(...) sustains around 5.8 billion samples per second and scales about 9.6× from one core to all of them. Per core, the JIT kernel ran within about 1.15× of hand-written Rust compiled by LLVM, which told me the CPU codegen had hit its ceiling. The same fused loop, emitted as WASM, runs at roughly half to three-quarters of native speed inside V8.

The GPU ate the JIT

A few weeks after I published this article, I deleted the JIT. The idea clicked when I noticed that a Monte Carlo query is already shaped like a compute shader: one pure kernel evaluated over millions of independent lanes, then a reduce to fold them down. That is exactly the GPU compute model, so the RvGraph got a WGSL lowering, and thanks to wgpu the same emitter reaches Metal, Vulkan and DirectX 12 on native, and WebGPU in the browser. One GPU backend to maintain, instead of one per platform.

Then I measured the full example corpus on the M4 Pro:

backend	corpus total	speedup
interpreter	3854 ms	1.00×
Cranelift JIT	3274 ms	1.18×
GPU	923 ms	4.17×
JIT + GPU	843 ms	4.57×

Once the GPU exists, everything the JIT adds is 80 ms, and it only ever worked on native. So it went, 1,834 lines and four dependencies deleted, and the shipped CLI jumped from the interpreter to the GPU by default. Deleting a backend was the fastest release I ever cut!

The heavy examples are where it gets fun. A quantization example that draws random rotation matrices went from 1474 ms to 55 ms (26×). The 100-prisoners simulation needed real compiler work first: by the time the emitter sees the graph, a for loop is unrolled into ~15,000 data-dependent reads, and the Metal shader compiler takes 2.2 seconds to chew on that. The fix was to capture the loop as a single node at eval time and emit it back as an actual WGSL loop, and the simulation dropped from 59 ms to 2.8 ms.

Where Noise sits

NoiseLang is a toy language, you probably should not use it for anything serious, however I wish this language existed during my university days.

For a language nerd, it’s a small expression-based language over a static random-variable algebra, with forward Monte Carlo and rejection-based conditioning.

You might ask, how does it compare to NumPy or Stan? NumPy makes you write the simulation yourself, and Stan makes you declare a model and wait for a sampler. Noise lets you write the probability as math while running Monte Carlo under the hood to get the answer.

Stan and PyMC beat Noise at the thing they’re built for, fitting a posterior to lots of continuous data with their HMC/NUTS samplers, and NumPy beats it at raw array crunching. Conditioning in Noise is rejection-based, so it works great for a handful of discrete observations but becomes useless for ten thousand continuous measurements, and there is no stateful simulation yet (no Markov chains yet). Noise wins when you have a probability question and you wanna know the answer without much hassle.

So use Noise for the whiteboard stage of a problem, when you want to run the math you just wrote, and move to Stan or PyMC when you need a real posterior, or to NumPy and JAX when you need to go to production.

Back to signals and noise

Going back to my university days, there was this subject called “Señales Aleatorias Y Ruido”, which is a spanish translation of “Random Signals and Noise”.

The textbook, in all its glory.

This subject was the nightmare of many students, including myself, in fact, I failed it. Truth be told, I didn’t put enough effort into it during the first year, but it changed when I had the take the same subject again in the second year. The professor was great, and made the subject interesting. The things that blew my mind was how he could model why FM survives a noisy channel when AM doesn’t.

So, here is my tribute to the subject, a one-screen Noise program that models why FM survives a noisy channel when AM doesn’t.

One caveat, and roger_ on Hacker News caught it before I did. The program above modulates phase, not frequency, so technically it is PM. For the single tone I am sending, PM and FM are the same thing up to a scale factor and a shift, so the demo still shows what I want it to show, but real FM would differentiate the message before it goes into the phase. Now I want to write that version, because FM should pull even further ahead once the message stops being a single tone.

Run NoiseLang in the browser

Everything above runs on @noiselang/core, thanks to the Rust engine compiled to WebAssembly.

npm install @noiselang/core



const result = await run(`
  X ~ rand::unif(-1, 1);
  Y ~ rand::unif(-1, 1);
  4 * P(X^2 + Y^2 < 1)
`);

console.log(result.value); // "3.1415…" — the last statement's value
console.log(result.output); // everything Print(...) emitted

run never throws, failures come back on result.error with a source span. There is also runWithIntrospection, the API behind the variable inspector at noiselang.com.

And when the page has WebGPU available, the heavy queries run on your GPU with the same WGSL shaders as native. Everything else stays on the WASM kernel, so nothing breaks on browsers that don’t have it.

NoiseLang is playable in the browser at noiselang.com. Open it, type X ~ unif(-1, 1); Y ~ unif(-1, 1); 4 * P(X^2 + Y^2 < 1), and watch a few million draws estimate π from your browser tab.

Appendix: prior art

I posted this on Hacker News and the thread turned into a reading list, which is the best thing that can happen to you when you ship a toy language. NoiseLang is not the first language to treat probability as a first-class value, not even close, so here is what people pointed me to:

monad-bayes, a Haskell library where the same “everything is a distribution” idea falls out of the monad, courtesy of bradrn. I had no idea Haskell could express this so directly.
webppl, Anglican, Stan and PyMC, the real probabilistic programming languages, suggested by chrisra. If you have an actual model to fit, go there, not here.
diceplots.com by qdotme, which keeps the distributions exactly analytical at every step and never samples. The opposite trade-off to mine, and a fun one.
“General Purpose Convolution Algorithm in S4-Classes by means of FFT” by Ruckdeschel and Kohl, sent by data-ottawa. It is the paper behind the R package distr, and it overloads +, -, *, / on distributions by computing the convolutions with an FFT instead of sampling them. Exactly the operator algebra I wanted, arrived at from the other direction.
kccqzy’s work on probabilistic program inference, which handles loops without Monte Carlo at all. He also asked the question I was hoping nobody would ask, which is how NoiseLang handles loops, and the answer is that it does not.

Big thanks also to RossBencina and thrtythreeforty, who pushed on the RNG trick until I understood my own benchmark better, and to roger_, who noticed that my FM demo is really doing phase modulation. This is why you post your toys!

This article has interactive figures — read it on manualmeida.dev.

Qwik: Resumability That Feels Like React

Manu Martínez-Almeida — Tue, 09 May 2023 00:00:00 GMT

Performance is a human problem, not a technology one

The thing I came to believe working on Qwik is that the web’s performance problem isn’t a technology problem. It’s a design and developer-experience problem. Developers, like water, follow the path of least resistance, and in most frameworks the easy way to build something is also the way that ships a slow site. We then tell people to go optimize it afterward, as a chore, trading off capabilities or DX or their weekend to claw the performance back.

I find it more honest to stop blaming developers and fix the path instead. A framework should be designed so the path of least resistance lands you on a fast site by default. You shouldn’t have to be a performance expert to ship a fast page; you should have to work to ship a slow one.

And the thing worth optimizing is almost always JavaScript. Most sites already handle their images and CSS reasonably well, so there’s little left on the table there. JavaScript is where the big wins hide. The difference between a sluggish page and a snappy one is often tens of points of Lighthouse score, and for anyone running an e-commerce or consumer site, that gap is revenue. Resumability is the lever Qwik pulls on exactly that.

The idea: resume, don’t rebuild

Every mainstream framework hydrates. The server renders HTML, then the browser downloads the whole component tree as JavaScript, re-executes it, and reattaches event listeners to reconstruct state the server already had. You pay, in bytes and CPU, to rebuild something you were handed seconds ago.

Islands and partial hydration, the approach Astro popularized, make this better by only hydrating the interactive bits. But each island still has to download and execute its JavaScript before it’s ready, and someone has to draw and maintain those island boundaries by hand.

Resumability skips the rebuild entirely. The server serializes the application’s state and its event wiring into the HTML itself. The browser ships almost no JavaScript up front. Conceptually the app becomes a hashmap: an event on an element points at the one chunk of code that handles it. When you click a button, Qwik reads an attribute on that element, fetches that small chunk, restores the state it captured, and runs it. There’s no global “boot the app” step, because there’s no app to boot.

There’s a neat way to see the flip. In a hydrated app, event handlers are the last thing to become ready, after the whole tree has downloaded and executed. In a resumable app they’re the first. The page is interactive the moment it arrives.

The first version worked; writing it was the hard part

Proving resumability was one thing. The developer experience was another. In that early version the philosophy leaked all the way into the API. You split your code into many small files by hand, you referenced lazy-loadable symbols by name, and you wrote a lot of ceremony to tell the runtime how the pieces fit together. It worked, and it asked too much of the person typing.

My bet was that all of that ceremony could become the compiler’s job. A developer should write something that looks like ordinary React, with components, event handlers, and local state, and the build step should do the hard work of making it resumable. The point of the whole project, after all, was to make the fast path the easy path, and an API that demanded this much manual wiring was the opposite of that.

Making it feel like React

In the design I led, you write a component with handlers and hooks, the way you already think. The magic lives in the compiler.

export const Counter = component$(() => {
  const count = useSignal(0);
  // looks like an ordinary closure; the compiler will extract it
  return <button onClick$={() => count.value++}>{count.value}</button>;
});

The compiler reads the AST, finds every $-marked boundary (a component$, an onClick$), and pulls that closure out into its own module with no dependencies except the variables it closed over. Those captured variables get serialized straight into the HTML. When the user clicks, the runtime loads that one module, restores the state it captured, and runs the handler. Nothing else downloads.

The captured state can be a live signal, so the handler reads and updates a reactive count and the DOM follows along. useSignal lets the runtime make a surgical update to exactly the text node that changed, with no component re-render in the browser. The signal model drew on Solid’s reactivity. The result reads like React and behaves like a resumable app, with none of the manual wiring the first version demanded.

One thing I like about this model over React Server Components: a Qwik component is universal. The same component runs on the server or the client, and the developer doesn’t annotate the boundary. With RSC it’s easy to reach for use client everywhere out of convenience and quietly opt back into shipping everything. In Qwik there’s no boundary to get wrong, because the compiler is the one deciding what crosses it.

Rust and SWC

The optimizer that does all this is written in Rust, on top of SWC. It runs on every build and across large codebases, so it had to stay fast enough to disappear into the dev loop. Rust kept the AST passes quick as projects grew, which matters when the entire premise is that the compiler, and not the developer, carries the complexity.

QwikCity

Later, with Adam Bradley (co-creator of Ionic and Stencil), I worked on the design of QwikCity, the meta-framework that sits on top: routing, data loading, and the conventions that make Qwik a way to build whole sites. That part was a close back-and-forth between the two of us.

Credit where it’s due

I want to be precise about this. The resumability concept, and much of how it works under the hood, including the runtime and the Solid-inspired signals, came from Miško Hevery, the creator of Angular. What I led was the developer-facing redesign and the compiler beneath it: turning closures into independent, serializable modules and working out the reachability analysis that decides what to ship.

The throughline to the rest of my work is that compiler. Make the source look ordinary, push the hard analysis to build time, and let the runtime stay lazy, so the path of least resistance is also the fast one. I’d wired the same instinct into Gin’s router years earlier, and I’d reach for it again tomorrow. If you’re designing a framework, that’s where I’d spend the effort: on the compiler that lets people write the easy thing while you quietly ship the simple one.

If you want the longer version of this argument, I gave a talk on it.

This article has interactive figures — read it on manualmeida.dev.

Releasing OpenView

Manu Martínez-Almeida — Sat, 02 Apr 2022 00:00:00 GMT

Originally published on the set.health blog, April 2, 2022.

Today we are happy to announce the OpenView initiative, a non-profit project that deeply connects with our vision of global healthcare.

Figure 1. Screenshot of Open View health.

Let’s stop for a minute and think! Imagine you had a ski accident. Now you can’t stand up, there’s an intense pain in your knee. You are worried about your leg, generally you like doing sports. In the local hospital your leg was examined in an MRI and you have to face the fact that you probably need to go through surgery because your ACL (anterior cruciate ligament) is injured, and your knee keeps swallowing. You are trying very hard to imagine what is going on in your leg and want to ask another doctor to give you a secondary opinion. Let’s say you have a CD or a stick with your MRI images in hands and you visit a different orthopedist. He says his software is not able to open your image, so you two need to find another way how to open the images. Very complicated and time consuming. So many steps until the physician gets to the point to check your medical data.

Scenario 2: your MRI images are in a fully anonymized link, you can securely share with anyone. You can easily ask for a secondary opinion about your condition. Additionally you are able to see it in 3D so everything is clear not only to the doctor, but to you as well. Less fear, faster recovery.

OpenView was built for 3 reasons and I’m going to lead you through these crucial points.

I. User friendly technology

Having surgery no matter what, is a big deal. I think we all can agree on that, right?! We built the app with privacy in mind. We know, not everyone is a hardtech genius, so we kept it as simple as possible. People need a diagnosis. They have the right to access their medical data and to share it with their loved ones or to ask for a secondary opinion.

II. Fully anonymized

We built this app with privacy in mind. We know, most people have unanswered questions and doubts about the web. So let me write it out “loud”: it cannot be safer!

This is an open source project
We don’t track any users
All data is encrypted end-to-end
Added data is anonymized following HIPAA and GDPR guidelines
All data and processing remains offline, until the user decides to share it
Decentralised storage

III. Decentralised and non-profit

OpenView will never make a business out of patients’ data and we took extraordinary measure to ensure that. The data is stored using IPFS (Interplanetary Filesystem), a distributed network of storage servers owned by individuals, universities and companies. IPFS supports other projects such as the WebArchive, and massive datasets of medical images. We are looking for partnerships with universities and institutions that are willing to donate storage resources to power the network. Then, medical datasets will be publically available for anyone instered from big companies to students for free, 100% public domain.

OpenView is powered by set.health Core, our commercial product to help companies to build better healthcare products. Our business model is licensing our API for developers and consulting, not selling data. Additionally you can donate your own data.

Do you have an app and want to boost it?

Reach out to us!

Frontend solutions
First class support
We are experts of custom medical imaging and DICOM solutions
Our code has 0 dependencies

Do you want to be part of the project?

If you are a developer, feel free to open an issue or a pull request in Github.
If you are a patient. Just feel free to use the app, and donate your data anonymously.
If you are a university, we want to heard from you! We need your help to connect the data into actual research and progress. Please drop us an email to team@set.health.

Open OpenView app

OpenView and set.health are no longer online, and team@set.health no longer reaches anyone — the links above go to how the app looked the week this was published. The source is still on GitHub.

How Breaking My Leg Gave Me Time to Stop and Think

Manu Martínez-Almeida — Wed, 20 May 2020 00:00:00 GMT

Today I’m incredibly excited to show off a project I’ve been working on, but first a quick back story.

Figure 1. Ray tracing of my ankle using set.health tech. The loose fragments along the right are the displaced pieces of the break.

I have been writing software since I was 10 years old. Back then, I barely knew what I was doing, gluing together parts of different videogame websites I loved.

I do remember though the first moment my brain clicked and realized that programming was more than putting things together, but gives you the opportunity to build new things from the ground up. Since then, it was all about the product, building new things.

When the first iPhone was released, I was fascinated with the idea of building something that could be used by thousands of people. So I joined an open-source project to build videogames. I learned a lot! Computer graphics, teamwork, and how a game engine works under the hood, someone could say I got my CS “degree” during that time.

This allowed me to build and ship a couple of games, one of them very successful, I worked tirelessly polishing the gameplay, the design of every little aspect, adjusting the difficulty and the controls obsessively. It was all about the product, I didn’t care much about the code, it was a mere tool to accomplish something, but then I fell in love.

I fell in love with software engineering, I rediscovered the complexity of building software, the software itself. The developer experience of people using my code, how an API will be able to scale and be future proof, optimizing processes so more developers can work without stepping on each other. Since then, I have worked building SDKs and APIs, created Gin, and Ionic and Stencil using web technologies.

During all this time I had no time to stop and think, not a single week without coding, week after week, then year after year. Thinking more about the “Why”, rather than the “How”. However, back in October 2019 something happened. One night some friends and I went out for drinks close to my office in Kreuzberg, a vibrant district of Berlin.

That night I broke my ankle.

Suddenly, everything I was doing, I was working on stopped abruptly. For 14 days I “lived” in that hospital of Kreuzberg, waiting for a surgery until the swelling shrinks. When I was able to calm down, it was not that bad, I found time to read those books I always wanted to, and books I would have never read, reconnected with people, wrote more, designed a tattoo for my ankle and even learned some German: “Ich möchte gerne einen Kaffee mit Milch ohne Zucker”. A time to think and disconnect the autopilot.

The worst was to come, even though the doctors assured the surgery went well, I had the feeling something was not good. After dealing with a very stressful process, I managed to get my health data onto a CD, bought an external CD reader on Amazon and asked for a second opinion.

I was told to come back immediately to Spain (where my family is from). Indeed, there were problems, the articular space was not respected, nerve damage because of the suture, an unrepaired tendon and the syndesmosis screw not placed in the optimal position. I was scared, tired, and depressed, but after the second surgery I was able to find some peace again.

Without deadlines, I opened my laptop and remembered those old days where I used to write game engines and build things. After some research, I tried to visualize my health data, writing all the software from scratch.

It was a lot of fun, but how could I connect the dots?

I decided it was time to think again in terms of product, something I would love to build and feel passionate about.

Figure 2. Tech demo showcasing my very own ankle.

Rendering gigabytes of voxels in a browser

A CT scan is a 3D grid of density samples, often hundreds of slices deep, which adds up to gigabytes. You can’t download all of it before drawing anything, and you can’t fit all of it in GPU memory. Yet a radiologist expects to spin and re-window the volume with no lag.

The rendering itself is ray casting through a 3D texture. For each pixel on screen, march a ray into the volume, sample density along the way, map each sample to color and opacity, and composite front to back until the pixel goes opaque.

// simplified: march a ray through the CT volume and accumulate color + opacity
vec4 raymarch(vec3 origin, vec3 dir) {
  vec4 acc = vec4(0.0);
  for (int i = 0; i < STEPS; i++) {
    vec3 p = origin + dir * (float(i) * stepSize);
    float density = texture(volume, p).r;    // sample one voxel
    vec4 s = transfer(density);              // density -> color + alpha
    acc.rgb += (1.0 - acc.a) * s.a * s.rgb;  // front-to-back compositing
    acc.a   += (1.0 - acc.a) * s.a;
    if (acc.a > 0.99) break;                 // early ray termination
  }
  return acc;
}

Three decisions made it run in real time on WebGL. We split each volume into smaller blocks, so the GPU only ever held the parts in view and could skip the empty space between them. We quantized the data, including the normal vectors used for shading, to shrink what had to live in texture memory. And we loaded progressively, coarse first and detail as you leaned in, so the first frame appeared fast even on a multi-gigabyte study.

Figure 3. OpenView Health, the free viewer we built on the set.health SDK. Slices and the 3D render stay in sync, and you can measure, window, and annotate straight in the browser.

Keeping the data safe by never seeing it

Medical data raises the stakes on security, so we ran end-to-end encryption on the client. A scan never left the device in the clear, which meant we couldn’t read it, and that was the point. The data we never held unencrypted is data we could never leak. That one decision collapsed a large amount of compliance and liability surface into something we could reason about.

Announcing set.health

Healthcare is not a commodity, at least it’s not for me, so building a health product requires a strong ethical filter to discard bad ideas. Once you realize that patients are the true owners of the data, but still they can’t access it easily, you can see there is a problem. People need a diagnosis to feel safe and well-informed, to be able to access and share their data and even having access to a Wifi hotspot is critically important so they can connect with their loved ones in the emergency room.

Today I am announcing set.health, my bottom-up approach to solve this problem by helping companies build better software and health products: patient apps, custom implant companies to ship faster, health platforms to communicate better, securing the medical data, funneling anonymized medical data into truly open datasets… and ultimately serve as a product for patients to understand and share their medical data.

There are quite a few companies that also try to solve this problem under different approaches, and I love it!

Figure 4. Technical demo of a COVID19 case using set.health directly from a browser.

What it became

set.health shipped as an SDK and a compliant backend across iOS, Android, and the web, and it ran until 2026. The use case that clicked was custom prosthetics. A doctor could shape an implant against a patient’s real anatomy, an engineer could validate it, and the two could hold a precise conversation inside the same 3D view, all running on our SDK.

Figure 5. A custom-implant planning and ordering tool a partner built on the SDK: plan plates, screws, and surgical guides against a real fracture, leave notes, and order the printed parts. The tool is no longer online.

2020 is being a complicated year for all of us, but It Gets Worse Before It Gets Better. Today, I can say that breaking my ankle might be one of the 5 best things that happened in my life, just time will say in which position exactly.

Please take a look, and send me an email if you wanna know more, I would love to heard from you!

set.health is no longer online — those links go to how the site looked the week I published this.

Tschüss 👋

Building Gin: Simple Over Easy

Manu Martínez-Almeida — Tue, 30 Jun 2026 00:00:00 GMT

In 2014 I came back from San Francisco with no plan. I spent a year building SDKs at Joypad and TinySpark after shipping one of my first games, and that year gave me a good sense of what small software teams need from their tools. Back in Spain, about to start Telecommunications Engineering, I had to decide what to build next.

The answer was Fyve, a social network built around people’s interests. I chose Go for the backend because the language felt plain in the right way, and Gin started as the web framework for that product. The code still lives at gin-gonic/gin.

Fyve never took off. Gin, the tool I built along the way, is still going twelve years later.

Simple over easy

At the time, the Go web framework people kept pointing me to was Martini. I understood why immediately. The README was small, the middleware model felt elegant, and you could get a route responding in minutes.

Martini used reflection-based dependency injection to wire handlers together, which made the first demo feel smooth but also moved important behavior out of sight. Services appeared in your handlers without any visible wiring, so when something misbehaved the control flow was hard to trace. And all of that reflection ran on every single request.

Around then I watched Rob Pike’s Simplicity is Complicated, and it gave me vocabulary for what bothered me about Martini. What stuck with me was the idea that simple software often takes more work from the person building it so that it can take less work from the person using it.

That became the design brief for Gin. Easy is about how good the first example looks, and Martini’s first example looked great. Simple is about how many moving parts you have to understand, and how many exceptions you have to remember, once the codebase is old enough to surprise you.

Finding the middle ground

Aristotle’s version of virtue was the middle ground: not too much, not too little. That was the shape of the framework problem too.

Martini gave you too much magic. Plain net/http gives you full control and no surprises, but it helps you with almost nothing, so you end up writing the same plumbing for route params, request parsing, validation, and responses in handler after handler. None of it is hard, but it makes the code noisy.

Gin was my attempt at the point between the two. The request path stays explicit, nothing on it uses reflection, and the repetitive plumbing lives in a single object called the Context.

r := gin.Default()
r.GET("/users/:id", func(c *gin.Context) {
    id := c.Param("id")          // path params, no reflection
    c.JSON(200, gin.H{"id": id}) // response rendering, one call
})
r.Run(":8080")

That *gin.Context carries the request, the response writer, path parameters, validation helpers, and rendering, so it’s the only thing you pass around. The common operations sit one method call away, and behind them is plain Go code you can step into when production gets weird.

Funny enough, gin.Context shipped in 2014, two years before the standard library’s context.Context existed. When the standard one arrived we kept our name and made gin.Context satisfy the new interface, so every existing program kept compiling and you could pass a gin.Context anywhere a context.Context was expected.

That instinct came from the SDK years. When the convenient way to do something is also the right way, people write better code without noticing.

A router built around a radix tree

The router is where the simple-over-easy line became concrete. Martini matched requests by walking a list of regular expressions and asking each one whether it matched. Regexes are flexible, since you can make a route match only numbers or hide extra rules inside the pattern, but they’re also a second language living inside your framework.

Gin’s route language is smaller. You get static segments, named parameters, and catch-alls, and that restriction is exactly what lets the router use a radix tree, the same approach httprouter made popular in Go. It also had a side effect I came to appreciate. Since the route language gives you nothing to be clever with, routes written for Gin tend to be regular and boring.

Matching /blog/42/comments walks /blog/ down to the :slug node, binds 42, and continues into /comments. The cost of a lookup depends on the length of the URL, and it stays the same whether the app has ten routes registered or ten thousand. Routes that share a prefix also share nodes, so a big route table stays compact in memory.

For a router holding $n$ routes and a request path of length $k$, a radix-tree lookup runs in

$$ T_\text{match}(k) = O(k), \quad \text{independent of } n, $$

while checking a list of $n$ regexes costs $O(n \cdot m)$ for patterns of length $m$. The tree trades the per-request scan for a single walk down the shared prefix.

The allocations follow the same thinking. Path parameters go into a preallocated slice, and Context objects come out of a sync.Pool and get reset between requests, so the garbage collector has less junk to clean up and latency has fewer reasons to wobble.

I trust this kind of performance work because the speed comes from doing fewer things, and doing fewer things also leaves the person reading the code with less to understand.

Designing for zero breaking changes

The other constraint I gave myself was backward compatibility. Go had made a compatibility promise for the language itself, and I wanted Gin to offer its users the same deal.

That constraint changes how you design. Before anything goes into the public API you ask whether you’d be happy maintaining it for ten years, because removing it later is off the table. You learn to reject the clever rename that saves five characters, and to treat every exported function as something a stranger might have built a company on.

The constraint held. Some of the first programs ever written against Gin still compile and run today, more than a decade later, and I’m prouder of that than of any benchmark.

Hacker News, and then growth

I released Gin on Hacker News at the right moment. Go was getting attention there, and a framework that fit in one README and benchmarked well was easy for people to try.

The growth after that was steady. People used it, filed issues, sent patches, and put it in real services, and today Gin sits around 88k stars with more than 290k projects depending on it.

Stars are a vanity metric, and I mostly treat them that way. The dependency count is the number I care about, because each of those projects is a bet that the API won’t break underneath them, and that bet has kept paying off long after Fyve disappeared.

Letting it graduate

A few years in, I stepped back and handed Gin to maintainers who kept improving it without me. I think of that as the project graduating. Special kudos to Bo-Yi Wu and Javier Provecho, who carried it forward and kept the bar high.

That’s the part of open source I respect most, when a project stops needing its author. Gin has since absorbed years of other people’s use cases, priorities, and taste, and it came out better for it.

If you’re building a library, that’s the bar I’d aim for. Design an API you can imagine keeping for ten years, and make it simple underneath even when that costs more than making it easy, because with any luck the thing will outgrow you.

I tried to do the same thing a few years later on a compiler, which is the story of Qwik.

This article has interactive figures — read it on manualmeida.dev.

Half-Truths

Manu Martínez-Almeida — Tue, 28 Jun 2022 00:00:00 GMT

On writing as little as possible

Software is best without classes, or functions, or code. But if you must, write as little as possible.
The only thing that really matters in software is KISS.
That is classic over-abstraction.
When in doubt, add setTimeout.
No hack is complete without .replace().
try/catch is for cowards.

On shipping

Never merge a PR.
If you’re afraid to release on Friday, the problem isn’t Friday.
If you can’t release fast, you have tech debt to solve.
Precommit hooks are the root of all evil.
The difference between a hobby and a job is that you don’t write documentation for the former.

On things one if-statement away from disaster

Almost all software is one if-statement away from disaster.
If you code just to make things work, one day suddenly nothing will work.
Dependencies are the root of all evil.
Developers will always find unexpected ways to use your API.
There are two hard things in computer science: cache invalidation and symlinks.

On knowing better

Debugging skills are underrated.
You are only an expert in a given technology when you know when not to use it.
A good engineer balances not underestimating apparently simple tasks against not overengineering apparently complex ones.
An experienced developer is the one who knows when to be volatile and when to be stable. (I figured it out, by the way: a stable is someone who installs linting build scripts, and a volatile is someone who disables them.)
I love monorepos, but I hate lerna.

If you got this far looking for a coherent philosophy, I’m sorry. The honest version is that good engineering is mostly knowing which of these to ignore today.

Disclaimer: a good number of these were forged in long, unhinged rants with Adam Bradley. I’ll take half the blame and none of the credit.