Eli Bendersky's website

watgo - a WebAssembly Toolkit for Go

2026-04-09T19:28:00-07:00

I'm happy to announce the general availability of watgo - the WebAssembly Toolkit for Go. This project is similar to wabt (C++) or wasm-tools (Rust), but in pure, zero-dependency Go.

watgo comes with a CLI and a Go API to parse WAT (WebAssembly Text), validate it, and encode it into WASM binaries; it also supports decoding WASM from its binary format.

At the center of it all is wasmir - a semantic representation of a WebAssembly module that users can examine (and manipulate). This diagram shows the functionalities provided by watgo:

Parse: a parser from WAT to wasmir
Validate: uses the official WebAssembly validation semantics to check that the module is well formed and safe
Encode: emits wasmir into WASM binary representation
Decode: read WASM binary representation into wasmir

CLI use case

watgo comes with a CLI, which you can install by issuing this command:

go install github.com/eliben/watgo/cmd/watgo@latest

The CLI aims to be compatible with wasm-tools [1], and I've already switched my wasm-wat-samples projects to use it; e.g. a command to parse a WAT file, validate it and encode it into binary format:

watgo parse stack.wat -o stack.wasm

API use case

wasmir semantically represents a WASM module with an API that's easy to work with. Here's an example of using watgo to parse a simple WAT program and do some analysis:

package main

import (
  "fmt"

  "github.com/eliben/watgo"
  "github.com/eliben/watgo/wasmir"
)

const wasmText = `
(module
  (func (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )
  (func (param f32 i32) (result i32)
    local.get 1
    i32.const 1
    i32.add
    drop
    i32.const 0
  )
)`

func main() {
  m, err := watgo.ParseWAT([]byte(wasmText))
  if err != nil {
    panic(err)
  }

  i32Params := 0
  localGets := 0
  i32Adds := 0

  // Module-defined functions carry a type index into m.Types. The function
  // body itself is a flat sequence of wasmir.Instruction values.
  for _, fn := range m.Funcs {
    sig := m.Types[fn.TypeIdx]
    for _, param := range sig.Params {
      if param.Kind == wasmir.ValueKindI32 {
        i32Params++
      }
    }

    for _, instr := range fn.Body {
      switch instr.Kind {
      case wasmir.InstrLocalGet:
        localGets++
      case wasmir.InstrI32Add:
        i32Adds++
      }
    }
  }

  fmt.Printf("module-defined funcs: %d\n", len(m.Funcs))
  fmt.Printf("i32 params: %d\n", i32Params)
  fmt.Printf("local.get instructions: %d\n", localGets)
  fmt.Printf("i32.add instructions: %d\n", i32Adds)
}

One important note: the WAT format supports several syntactic niceties that are flattened / canonicalized when lowered to wasmir. For example, all folded instructions are lowered to unfolded ones (linear form), function & type names are resolved to numeric indices, etc. This matches the validation and execution semantics of WASM and its binary representation.

These syntactic details are present in watgo in the textformat package (which parses WAT into an AST) and are removed when this is lowered to wasmir. The textformat package is kept internal at this time, but in the future I may consider exposing it publicly - if there's interest.

Testing strategy

Even though it's still early days for watgo, I'm reasonably confident in its correctness due to a strategy of very heavy testing right from the start.

WebAssembly comes with a large official test suite, which is perfect for end-to-end testing of new implementations. The core test suite includes almost 200K lines of WAT files that carry several modules with expected execution semantics and a variety of error scenarios exercised. These live in specially designed .wast files and leverage a custom spec interpreter.

watgo hijacks this approach by using the official test suite for its own testing. A custom harness parses .wast files and uses watgo to convert the WAT in them to binary WASM, which is then executed by Node.js [2]; this harness is a significant effort in itself, but it's very much worth it - the result is excellent testing coverage. watgo passes the entire WASM spec core test suite.

Similarly, we leverage wabt's interp test suite which also includes end-to-end tests, using a simpler Node-based harness to test them against watgo.

Finally, I maintain a collection of realistic program samples written in WAT in the wasm-wat-samples repository; these are also used by watgo to test itself.

[1]	Though not all of wasm-tools's functionality is supported yet.

[2]	To stick to a pure-Go approach also for testing, I originally tried using wazero for this, but had to give up because wazero doesn't support some of the recent WASM proposals that have already made it into the standard (most notably Garbage Collection).

Summary of reading: January - March 2026

2026-03-31T17:34:00-07:00

"Intellectuals and Society" by Thomas Sowell - a collection of essays in which Sowell criticizes "intellectuals", by which he mostly means left-leaning thinkers and opinions. Interesting, though certainly very biased. This book is from 2009 and focuses mostly on early and mid 20th century; yes, history certainly rhymes.
"The Hacker and the State: Cyber Attacks and the New Normal of Geopolitics" by Ben Buchanan - a pretty good overview of some of the the major cyber-attacks done by states in the past 15 years. It doesn't go very deep because it's likely just based on the bits and pieces that leaked to the press; for the same reason, the coverage is probably very partial. Still, it's an interesting and well-researched book overall.
"A Primate's Memoir: A Neuroscientist’s Unconventional Life Among the Baboons" by Robert Sapolsky - an account of the author's years spent researching baboons in Kenya. Only about a quarter of the book is really about baboons, though; mostly, it's about the author's adventures in Africa (some of them surely inspired by an intense death wish) and his interaction with the local peoples. I really liked this book overall - it's engaging, educational and funny. Should try more books by this author.
"Seeing Like a State" by James C. Scott - the author attempts to link various events in history to discuss "Why do well-intentioned plans for improving the human condition go tragically awry?"; discussing large state plans like scientific forest management, building pre-planned cities and mono-culture agriculture. Some of the chapters are interesting, but overall I'm not sure I'm sold on the thesis. Specifically, the author mixes in private enterprises (like industrial agriculture in the West) with state-driven initiatives in puzzling ways.
"Karate-Do: My Way of Life" by Gichin Funakoshi - short autobiography from the founder of modern Shotokan Karate. It's really interesting to find out how recent it all is - prior to WWII, Karate was an obscure art practiced mostly in Okinawa and a bit in other parts of Japan. The author played a critical role in popularizing Karate and spreading it out of Okinawa in the first half of the 20th century. The writing is flowing and succinct - I really liked this book.
"A Tale of a Ring" by Ilan Sheinfeld (read in Hebrew) - a multi-generational fictional saga of two families who moved from Danzig (today Gdansk in Poland) to Buenos Aires in late 19th century, with a touch of magic. Didn't like this one very much.
"The Wide Wide Sea: Imperial Ambition, First Contact and the Fateful Final Voyage of Captain James Cook" by Hampton Sides - a very interesting account of Captain Cook's last voyage (the one tasked with finding a northwest passage around Canada). The book has a strong focus on his interaction with Polynesian peoples along the way, especially on Hawaii (which he was the first European to visit).
"The Suitcase" by Sergei Dovlatov - (read in Russian) a collection of short stories in Dovlatov's typical humorist style. Very nice little book.
"The Second Chance Convenience Store" by Kim Ho-Yeon - a collection of connected stories centered around a convenience store in Seoul, and an unusual new employee that began working night shifts there. Short and sweet fiction, I enjoyed it.
"A History of the Bible: The Story of the World's Most Influential Book" by John Barton - a very detailed history of the Bible, covering both the old and new testaments in many aspects. Some parts of the book are quite tedious; it's not an easy read. Even though the author tries to maintain a very objective and scientific approach, it's apparent (at least for an atheist) that he skirts as close as possible to declaring it all nonsense, given that he's a priest!
"Rust Atomics and Locks: Low-Level Concurrency in Practice" by Mara Bos - an overview of low-level concurrency topics using Rust. It's a decent book for people not too familiar with the subject; I personally didn't find it too captivating, but I do see the possibility of referring to it in the future if I get to do some lower-level Rust hacking. A comment on the code samples: it would be nice if the accompanying repository had test harnesses to observe how the code behaves, and some benchmarks. Without this, many claims made in the book feel empty without real data to back them up, and it's challenging to play with the code and see it perform in real life.
"Hot Chocolate on Thursday" by Michiko Aoyama - a bit similar to "What You Are Looking for Is in the Library" by the same author: connected short stories about ordinary people living their life in Japan (with one detour to Australia). Slightly worse than the previous book, but still pretty good.
"The Silmarillion" by J.R.R. Tolkien - even though I'm a big LOTR fan, I've never gotten myself to read this one, due to its reputation for being difficult. What changed things eventually (25 years after my first read through of LOTR) is my kids! They liked LOTR so much that they went straight ahead to Silmarillion and burned through it as well, so I couldn't stay behind. What can I say, this book is pretty amazing. The amazing thing is how a book can be both epic and borderline unreadable at the same time :) Tolkien really let himself go with the names here (3-4 new names introduced per page, on average), names for characters, names for natural features like forests and rivers, names for all kinds of magical paraphernalia; names that change in time, different names given to the same thing by different peoples, and on and on. The edition I was reading has a helpful name index at the end (42 pages long!) which was very helpful, but it still made the task only marginally easier. Names aside though, the book is undoubtedly monumental; the language is outstanding. It's a whole new mythology, Bible-like in scope, all somehow more-or-less consistent (if you remember who is who, of course); it's an injustice to see this just as a prelude to the LOTR books. Compared to the scope of the Silmarillion, LOTR is just a small speck of a quest told in detail; The Silmarillion - among other things - includes brief tellings of at least a dozen stories of similar scope. Many modern book (or TV) series build whole "universes" with their own rules, history and aesthetic. The Silmarillion must be considered the OG of this.

Re-reads:

"Travels with Charley in Search of America" by John Steinbeck
"Deep Work" by Cal Newport
"The Philadelphia chromosome" by Jessica Wapner
"The Price of Privilege" by Madeline Levine

Notes on Lagrange Interpolating Polynomials

2026-02-28T18:58:00-08:00

Polynomial interpolation is a method of finding a polynomial function that fits a given set of data perfectly. More concretely, suppose we have a set of n+1 distinct points [1]:

\[(x_0,y_0), (x_1, y_1), (x_2, y_2)\cdots(x_n, y_n)\]

And we want to find the polynomial coefficients {a_0\cdots a_n} such that:

\[p(x)=a_0 + a_1 x + a_2 x^2 + \cdots + a_n x^n\]

Fits all our points; that is p(x_0)=y_0, p(x_1)=y_1 etc.

This post discusses a common approach to solving this problem, and also shows why such a polynomial exists and is unique.

Showing existence using linear algebra

When we assign all points (x_i, y_i) into the generic polynomial p(x), we get:

\[\begin{aligned} p(x_0)&=a_0 + a_1 x_0 + a_2 x_0^2 + \cdots a_n x_0^n = y_0\\ p(x_1)&=a_0 + a_1 x_1 + a_2 x_1^2 + \cdots a_n x_1^n = y_1\\ p(x_2)&=a_0 + a_1 x_2 + a_2 x_2^2 + \cdots a_n x_2^n = y_2\\ \cdots \\ p(x_n)&=a_0 + a_1 x_n + a_2 x_n^2 + \cdots a_n x_n^n = y_n\\ \end{aligned}\]

We want to solve for the coefficients a_i. This is a linear system of equations that can be represented by the following matrix equation:

\[{\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & x_0 & x_0^2 & \dots & x_0^n\\ 1 & x_1 & x_1^2 & \dots & x_1^n\\ 1 & x_2 & x_2^2 & \dots & x_2^n\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 1 & x_n & x_n^2 & \dots & x_n^n \end{bmatrix} \begin{bmatrix} a_0\\ a_1\\ a_2\\ \vdots\\ a_n\\ \end{bmatrix}= \begin{bmatrix} y_0\\ y_1\\ y_2\\ \vdots\\ y_n\\ \end{bmatrix} }\]

The matrix on the left is called the Vandermonde matrix. This matrix is known to be invertible (see Appendix for a proof); therefore, this system of equations has a single solution that can be calculated by inverting the matrix.

In practice, however, the Vandermonde matrix is often numerically ill-conditioned, so inverting it isn’t the best way to calculate exact polynomial coefficients. Several better methods exist.

Lagrange Polynomial

Lagrange interpolation polynomials emerge from a simple, yet powerful idea. Let’s define the Lagrange basis functions l_i(x) (i \in [0, n]) as follows, given our points (x_i, y_i):

\[l_i(x) = \begin{cases} 1 & x = x_i \\ 0 & x = x_j \quad \forall j \neq i \end{cases}\]

In words, l_i(x) is constrained to 1 at and to 0 at all other x_j. We don’t care about its value at any other point.

The linear combination:

\[p(x)=\sum_{i=0}^{n}y_i l_i(x)\]

is then a valid interpolating polynomial for our set of n+1 points, because it’s equal to at each (take a moment to convince yourself this is true).

How do we find l_i(x)? The key insight comes from studying the following function:

\[l'_i(x)=(x-x_0)\cdot (x-x_1)\cdots (x-x_{i-1}) \cdot (x-x_{i+1})\cdots (x-x_n)= \prod_{\substack{0\leq j \leq n \\ j \neq i}}(x-x_j)\]

This function has terms (x-x_j) for all j\neq i. It should be easy to see that l'_i(x) is 0 at all x_j when j\neq i.

What about its value at , though? We can just assign into l'_i(x) to get:

\[l'_i(x_i)=\prod_{\substack{0\leq j \leq n \\ j \neq i}}(x_i-x_j)\]

And then normalize l'_i(x), dividing it by this (constant) value. We get the Lagrange basis function l_i(x):

\[l_i(x)=\frac{l'_i(x)}{l'_i(x_i)}=\prod_{\substack{0\leq j \leq n \\ j \neq i}}\frac{x-x_j}{x_i-x_j}\]

Let’s use a concrete example to visualize this. Suppose we have the following set of points we want to interpolate: (1,4), (2,2), (3,3). We can calculate l'_0(x), l'_1(x) and l'_2(x), and get the following:

Note where each l'_i(x) intersects the axis. These functions have the right values at all x_{j\neq i}. If we normalize them to obtain l_i(x), we get these functions:

Note that each polynomial is 1 at the appropriate and 0 at all the other x_{j\neq i}, as required.

With these l_i(x), we can now plot the interpolating polynomial p(x)=\sum_{i=0}^{n}y_i l_i(x), which fits our set of input points:

Polynomial degree and uniqueness

We’ve just seen that the linear combination of Lagrange basis functions:

\[p(x)=\sum_{i=0}^{n}y_i l_i(x)\]

is a valid interpolating polynomial for a set of n+1 distinct points (x_i, y_i). What is its degree?

Since the degree of each l_i(x) is , then the degree of p(x) is at most . We’ve just derived the first part of the Polynomial interpolation theorem:

Polynomial interpolation theorem: for any n+1 data points (x_0,y_0), (x_1, y_1)\cdots(x_n, y_n) \in \mathbb{R}^2 where no two x_j are the same, there exists a unique polynomial p(x) of degree at most that interpolates these points.

We’ve demonstrated existence and degree, but not yet uniqueness. So let’s turn to that.

We know that p(x) interpolates all n+1 points, and its degree is . Suppose there’s another such polynomial q(x). Let’s construct:

\[r(x)=p(x)-q(x)\]

That do we know about r(x)? First of all, its value is 0 at all our , so it has n+1 roots. Second, we also know that its degree is at most (because it’s the difference of two polynomials of such degree). These two facts are a contradiction. No non-zero polynomial of degree \leq n can have n+1 roots (a basic algebraic fact related to the Fundamental theorem of algebra). So r(x) must be the zero polynomial; in other words, our p(x) is unique \blacksquare.

Note the implication of uniqueness here: given our set of n+1 distinct points, there’s only one polynomial of degree \leq n that interpolates it. We can find its coefficients by inverting the Vandermonde matrix, by using Lagrange basis functions, or any other method [2].

Lagrange polynomials as a basis for P_n(\mathbb{R})

The set P_n(\mathbb{R}) consists of all real polynomials of degree \leq n. This set - along with addition of polynomials and scalar multiplication - forms a vector space.

We called l_i(x) the "Lagrange basis" previously, and they do - in fact - form an actual linear algebra basis for this vector space. To prove this claim, we need to show that Lagrange polynomials are linearly independent and that they span the space.

Linear independence: we have to show that

\[s(x)=\sum_{i=0}^{n}a_i l_i(x)=0\]

implies a_i=0 \quad \forall i. Recall that l_i(x) is 1 at , while all other l_j(x) are 0 at that point. Therefore, evaluating s(x) at , we get:

\[s(x_i)=a_i = 0\]

Similarly, we can show that a_i is 0, for all \blacksquare.

Span: we’ve already demonstrated that the linear combination of l_i(x):

\[p(x)=\sum_{i=0}^{n}y_i l_i(x)\]

is a valid interpolating polynomial for any set of n+1 distinct points. Using the polynomial interpolation theorem, this is the unique polynomial interpolating this set of points. In other words, for every q(x)\in P_n(\mathbb{R}), we can identify any set of n+1 distinct points it passes through, and then use the technique described in this post to find the coefficients of q(x) in the Lagrange basis. Therefore, the set l_i(x) spans the vector space \blacksquare.

Interpolation matrix in the Lagrange basis

Previously we’ve seen how to use the \{1, x, x^2, \dots x^n\} basis to write down a system of linear equations that helps us find the interpolating polynomial. This results in the Vandermonde matrix.

Using the Lagrange basis, we can get a much nicer matrix representation of the interpolation equations.

Recall that our general polynomial using the Lagrange basis is:

\[p(x)=\sum_{i=0}^{n}a_i l_i(x)\]

Let’s build a system of equations for each of the n+1 points (x_i,y_i). For :

\[p(x_0)=\sum_{i=0}^{n}a_i l_i(x_0)\]

By definition of the Lagrange basis functions, all l_i(x_0) where i\neq 0 are 0, while l_0(x_0) is 1. So this simplifies to:

\[p(x_0)=a_0\]

But the value at node is , so we’ve just found that a_0=y_0. We can produce similar equations for the other nodes as well, p(x_1)=a_1, etc. In matrix form:

\[{\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & 0 & 0 & \dots & 0\\ 0 & 1 & 0 & \dots & 0\\ 0 & 0 & 1 & \dots & 0\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 0 & 0 & 0 & \dots & 1 \end{bmatrix} \begin{bmatrix} a_0\\ a_1\\ a_2\\ \vdots\\ a_n\\ \end{bmatrix}= \begin{bmatrix} y_0\\ y_1\\ y_2\\ \vdots\\ y_n\\ \end{bmatrix} }\]

We get the identity matrix; this is another way to trivially show that a_0=y_0, a_1=y_1 and so on.

Appendix: Vandermonde matrix

Given some numbers \{x_0 \dots x_n\} a matrix of this form:

\[V= {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & x_0 & x_0^2 & \dots & x_0^n\\ 1 & x_1 & x_1^2 & \dots & x_1^n\\ 1 & x_2 & x_2^2 & \dots & x_2^n\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 1 & x_n & x_n^2 & \dots & x_n^n \end{bmatrix} }\]

Is called the Vandermonde matrix. What’s special about a Vandermonde matrix is that we know it’s invertible when are distinct. This is because its determinant is known to be non-zero. Moreover, its determinant is [3]:

\[\det(V) = \prod_{0 \le i < j \le n} (x_j - x_i)\]

Here’s why.

To get some intuition, let’s consider some small-rank Vandermonde matrices. Starting with a 2-by-2:

\[\det(V)=\det\begin{bmatrix} 1 & x_0 \\ 1 & x_1 \\ \end{bmatrix}=x_1-x_0\]

Let’s try 3-by-3 now:

\[\det(V)=\det {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & x_0 & x_0^2 \\ 1 & x_1 & x_1^2 \\ 1 & x_2 & x_2^2 \\ \end{bmatrix} }\]

We can use the standard way of calculating determinants to expand from the first row:

\[\begin{aligned} \det(V)&=1\cdot(x_1 x_2^2 - x_2 x_1^2)-x_0(x_2^2-x_1^2)+x_0^2(x_2 - x_1)\\ &=x_1 x_2^2 - x_2 x_1^2 - x_0 x_2^2+x_0 x_1^2+x_0^2 x_2 - x_0^2 x_1\\ \end{aligned}\]

Using some algebraic manipulation, it’s easy to show this is equivalent to:

\[\det(V)=(x_2-x_1)(x_2-x_0)(x_1-x_0)\]

For the full proof, let’s look at the generalized n+1-by-n+1 matrix again:

Recall that subtracting a multiple of one column from another doesn’t change a matrix’s determinant. For each column k>1, we’ll subtract the value of column k-1 multiplied by from it (this is done on all columns simultaneously). The idea is to make the first row all zeros after the very first element:

\[V= {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & 0 & 0 & \dots & 0\\ 1 & x_1 - x_0 & x_1^2 - x_1 x_0& \dots & x_1^n - x_1^{n-1} x_0\\ 1 & x_2 - x_0 & x_2^2 - x_2 x_0& \dots & x_2^n - x_2^{n-1} x_0\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 1 & x_n - x_0 & x_n^2 - x_n x_0& \dots & x_n^n - x_n^{n-1} x_0\\ \end{bmatrix} }\]

Now we factor out x_1-x_0 from the second row (after the first element), x_2-x_0 from the third row and so on, to get:

\[V= {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & 0 & 0 & \dots & 0\\ 1 & x_1 - x_0 & x_1(x_1 - x_0)& \dots & x_1^{n-1}(x_1 - x_0)\\ 1 & x_2 - x_0 & x_2(x_2 - x_0)& \dots & x_2^{n-1}(x_2 - x_0)\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 1 & x_n - x_0 & x_n(x_n - x_0)& \dots & x_n^{n-1}(x_n - x_0)\\ \end{bmatrix} }\]

Imagine we erase the first row and first column of . We’ll call the resulting matrix .

\[W= {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} x_1 - x_0 & x_1(x_1 - x_0)& \dots & x_1^{n-1}(x_1 - x_0)\\ x_2 - x_0 & x_2(x_2 - x_0)& \dots & x_2^{n-1}(x_2 - x_0)\\ \vdots & \vdots & \ddots &\vdots \\ x_n - x_0 & x_n(x_n - x_0)& \dots & x_n^{n-1}(x_n - x_0)\\ \end{bmatrix} }\]

Because the first row of is all zeros except the first element, we have:

\[\det(V)=\det(W)\]

Note that the first row of has a common factor of x_1-x_0, so when calculating \det(W), we can move this common factor out. Same for the common factor x_2-x_0 of the second row, and so on. Overall, we can write:

\[\det(W)=(x_1-x_0)(x_2-x_0)\cdots(x_n-x_0)\cdot \det {\renewcommand{\arraystretch}{1.5}\begin{bmatrix} 1 & x_1 & x_1^2 & \dots & x_1^{n-1}\\ 1 & x_2 & x_2^2 & \dots & x_2^{n-1}\\ \vdots & \vdots & \vdots & \ddots &\vdots \\ 1 & x_n & x_n^2 & \dots & x_n^{n-1} \end{bmatrix} }\]

But the smaller matrix is just the Vandermonde matrix for \{x_1 \dots x_{n}\}. If we continue this process by induction, we’ll get:

\[\det(V) = \prod_{0 \le i < j \le n} (x_j - x_i)\]

If you’re interested, the Wikipedia page for the Vandermonde matrix has a couple of additional proofs.

[1]	The -es here are called nodes and the -s are called values.

[2]	Newton polynomials is also an option, and there are many other approaches.

[3]	Note that this means the product of all differences between x_j and where is strictly smaller than j. That is, for n=2, the full product is (x_2-x_1)(x_2-x_0)(x_1-x_0). For an arbitrary , there are \frac{n(n-1)}{2} factors in total.

Notes on Linear Algebra for Polynomials

2026-02-25T18:34:00-08:00

We’ll be working with the set P_n(\mathbb{R}), real polynomials of degree \leq n. Such polynomials can be expressed using n+1 scalar coefficients a_i as follows:

\[p(x)=a_0+a_1 x + a_2 x^2 + \cdots + a_n x^n\]

Vector space

The set P_n(\mathbb{R}), along with addition of polynomials and scalar multiplication form a vector space. As a proof, let’s review how the vector space axioms are satisfied. We’ll use p(x), q(x) and r(x) as arbitrary polynomials from the set P_n(\mathbb{R}) for the demonstration. Similarly, a and b are arbitrary scalars in .

Associativity of vector addition:

\[p(x)+[q(x)+r(x)]=p(x)+q(x)+r(x)=[p(x)+q(x)]+r(x)\]

This is trivial because addition of polynomials is associative [1]. Commutativity is similarly trivial, for the same reason:

Commutativity of vector addition:

\[p(x)+q(x)=q(x)+p(x)\]

Identity element of vector addition:

The zero polynomial 0 serves as an identity element. \forall p(x)\in P_n(\mathbb{R}), we have 0 + p(x) = p(x).

Inverse element of vector addition:

For each p(x), we can use q(x)=-p(x) as the additive inverse, because p(x)+q(x)=0.

Identity element of scalar multiplication

The scalar 1 serves as an identity element for scalar multiplication. For each p(x), it’s true that 1\cdot p(x)=p(x).

Associativity of scalar multiplication:

For any two scalars a and b:

\[a[b\cdot p(x)]=ab\cdot p(x)=[ab]\cdot p(x)\]

Distributivity of scalar multiplication over vector addition:

For any p(x), q(x) and scalar a:

\[a\cdot[p(x)+q(x)]=a\cdot p(x)+a\cdot q(x)\]

Distributivity of scalar multiplication over scalar addition:

For any scalars a and b and polynomial p(x):

\[[a+b]\cdot p(x)=a\cdot p(x) + b\cdot p(x)\]

Linear independence, span and basis

Since we’ve shown that polynomials in P_n(\mathbb{R}) form a vector space, we can now build additional linear algebraic definitions on top of that.

A set of k polynomials p_k(x)\in P_n(\mathbb{R}) is said to be linearly independent if

\[\sum_{i=1}^{k}a_i p_i(x)=0\]

implies a_i=0 \quad \forall i. In words, the only linear combination resulting in the zero vector is when all coefficients are 0.

As an example, let’s discuss the fundamental building blocks of polynomials in P_n(\mathbb{R}): the set \{1, x, x^2, \dots x^n\}. These are linearly independent because:

\[a_0 + a_1 x + a_2 x^2 + \cdots a_n x^n=0\]

is true only for zero polynomial, in which all the coefficients a_i=0. This comes from the very definition of polynomials. Moreover, this set spans the entire P_n(\mathbb{R}) because every polynomial can be (by definition) expressed as a linear combination of \{1, x, x^2, \dots x^n\}.

Since we’ve shown these basic polynomials are linearly independent and span the entire vector space, they are a basis for the space. In fact, this set has a special name: the monomial basis (because a monomial is a polynomial with a single term).

Checking if an arbitrary set of polynomials is a basis

Suppose we have some set polynomials, and we want to know if these form a basis for P_n(\mathbb{R}). How do we go about it?

The idea is using linear algebra the same way we do for any other vector space. Let’s use a concrete example to demonstrate:

\[Q=\{1-x, x, 2x+x^2\}\]

Is the set Q a basis for P_n(\mathbb{R})? We’ll start by checking whether the members of Q are linearly independent. Write:

\[a_0(1-x)+a_1 x + a_2(2x+x^2)=0\]

By regrouping, we can turn this into:

\[a_0 + (a_1-a_0+2a_2)x+a_2 x^2=0\]

For this to be true, the coefficient of each monomial has to be zero; mathematically:

\[\begin{aligned} a_0&=0\\ a_1-a_0+2a_2&=0\\ a2&=0\\ \end{aligned}\]

In matrix form:

\[\begin{bmatrix} 1 & 0 & 0\\ -1 & 1 & 2\\ 0 & 0 & 1\\ \end{bmatrix} \begin{bmatrix}a_0\\ a_1\\ a_2\end{bmatrix} =\begin{bmatrix}0\\ 0\\ 0\end{bmatrix}\]

We know how to solve this, by reducing the matrix into row-echelon form. It’s easy to see that the reduced row-echelon form of this specific matrix is I, the identity matrix. Therefore, this set of equations has a single solution: a_i=0 \quad \forall i [2].

We’ve shown that the set Q is linearly independent. Now let’s show that it spans the space P_n(\mathbb{R}). We want to analyze:

\[a_0(1-x)+a_1 x + a_2(2x+x^2)=\alpha +\beta x + \gamma x^2\]

And find the coefficients a_i that satisfy this for any arbitrary , and \gamma. We proceed just as before, by regrouping on the left side:

\[a_0 + (a_1-a_0+2a_2)x+a_2 x^2=\alpha +\beta x + \gamma x^2\]

and equating the coefficient of each power of separately:

\[\begin{aligned} a_0&=\alpha\\ a_1-a_0+2a_2&=\beta\\ a2&=\gamma\\ \end{aligned}\]

If we turn this into matrix form, the matrix of coefficients is exactly the same as before. So we know there’s a single solution, and by rearranging the matrix into I, the solution will appear on the right hand side. It doesn’t matter for the moment what the actual solution is, as long as it exists and is unique. We’ve shown that Q spans the space!

Since the set Q is linearly independent and spans P_n(\mathbb{R}), it is a basis for the space.

Inner product

I’ve discussed inner products for functions in the post about Hilbert space. Well, polynomials are functions, so we can define an inner product using integrals as follows [3]:

\[\langle p, q \rangle = \int_{a}^{b} p(x) q(x) w(x) \, dx\]

Where the bounds a and b are arbitrary, and could be infinite. Whenever we deal with integrals we worry about convergence; in my post on Hilbert spaces, we only talked about L^2 - the square integrable functions. Most polynomials are not square integrable, however. Therefore, we can restrict this using either:

A special weight function w(x) to make sure the inner product integral converges
Set finite bounds on the integral, and then we can just set w(x)=1.

Let’s use the latter, and restrict the bounds into the range [-1,1], setting w(x)=1. We have the following inner product:

\[\langle p, q \rangle = \int_{-1}^{1} p(x) q(x) \, dx\]

Let’s check that this satisfies the inner product space conditions.

Conjugate symmetry:

Since real multiplication is commutative, we can write:

\[\langle p, q \rangle = \int_{-1}^{1} p(x) q(x) \, dx =\int_{-1}^{1} q(x) p(x) \, dx=\langle q, p \rangle\]

We deal in the reals here, so we can safely ignore complex conjugation.

Linearity in the first argument:

Let p_1,p_2,q\in P_n(\mathbb{R}) and a,b\in \mathbb{R}. We want to show that

\[\langle ap_1+bp_2,q \rangle = a\langle p_1,q\rangle +b\langle p_2,q\rangle\]

Expand the left-hand side using our definition of inner product:

\[\begin{aligned} \langle ap_1+bp_2,q \rangle&=\int_{-1}^{1} (a p_1(x)+b p_2(x)) q(x) \, dx\\ &=a\int_{-1}^{1} p_1(x) q(x) \, dx+b\int_{-1}^{1} p_2(x) q(x) \, dx \end{aligned}\]

The result is equivalent to a\langle p_1,q\rangle +b\langle p_2,q\rangle.

Positive-definiteness:

We want to show that for nonzero p\in P_n(\mathbb{R}), we have \langle p, p\rangle > 0. First of all, since p(x)^2\geq0 for all , it’s true that:

\[\langle p, p\rangle=\int_{-1}^{1}p(x)^2\, dx\geq 0\]

What about the result 0 though? Well, let’s say that

\[\int_{-1}^{1}p(x)^2\, dx=0\]

Since p(x)^2 is a non-negative function, this means that the integral of a non-negative function ends up being 0. But p(x) is a polynomial, so it’s continuous, and so is p(x)^2. If the integral of a continuous non-negative function is 0, it means the function itself is 0. Had it been non-zero in any place, the integral would necessarily have to be positive as well.

We’ve proven that \langle p, p\rangle=0 only when p is the zero polynomial. The positive-definiteness condition is satisfied.

In conclusion, P_n(\mathbb{R}) along with the inner product we’ve defined forms an inner product space.

Orthogonality

Now that we have an inner product, we can define orthogonality on polynomials: two polynomials p,q are orthogonal (w.r.t. our inner product) iff

\[\langle p,q\rangle=\int_{-1}^{1}p(x)q(x)\, dx=0\]

Contrary to expectation [4], the monomial basis polynomials are not orthogonal using our definition of inner product.

For example, calculating the inner product for 1 and x^2:

\[\langle 1,x^2\rangle=\int_{-1}^{1}x^2\, dx=\frac{x^3}{3}\biggr|_{-1}^{1}=\frac{2}{3}\]

There are other sets of polynomials that are orthogonal using our inner product. For example, the Legendre polynomials; but this is a topic for another post.

[1]	There’s a level of basic algebra below which we won’t descend in these notes. We could break this statement further down by saying that something like a_i x^i + a_j x^j can be added to b_i x^i + b_j x^j by adding each power of separately for any and j, but let’s just take it for granted.

[2]

Obviously, this specific set of equations is quite trivial to solve without matrices; I just want to demonstrate the more general approach. Once we have a system of linear equations, the whole toolbox of linear algebra is at our disposal. For example, we could also have checked the determinant and seen it’s non-zero, which means that a square matrix is invertible, and in this case has a single solution of zeroes.

[3]	And actually with this (or any valid) inner product, P_n(\mathbb{R}) indeed forms a Hilbert space, because it’s finite-dimensional, and every finite-dimensional inner product space is complete.

[4]	Because of how naturally this set spans P_n(\mathbb{R}). And indeed, we can define alternative inner products using which monomials are orthogonal.

Rewriting pycparser with the help of an LLM

2026-02-04T19:35:00-08:00

pycparser is my most widely used open source project (with ~20M daily downloads from PyPI [1]). It's a pure-Python parser for the C programming language, producing ASTs inspired by Python's own. Until very recently, it's been using PLY: Python Lex-Yacc for the core parsing.

In this post, I'll describe how I collaborated with an LLM coding agent (Codex) to help me rewrite pycparser to use a hand-written recursive-descent parser and remove the dependency on PLY. This has been an interesting experience and the post contains lots of information and is therefore quite long; if you're just interested in the final result, check out the latest code of pycparser - the main branch already has the new implementation.

The issues with the existing parser implementation

While pycparser has been working well overall, there were a number of nagging issues that persisted over years.

Parsing strategy: YACC vs. hand-written recursive descent

I began working on pycparser in 2008, and back then using a YACC-based approach for parsing a whole language like C seemed like a no-brainer to me. Isn't this what everyone does when writing a serious parser? Besides, the K&R2 book famously carries the entire grammar of the C99 language in an appendix - so it seemed like a simple matter of translating that to PLY-yacc syntax.

And indeed, it wasn't too hard, though there definitely were some complications in building the ASTs for declarations (C's gnarliest part).

Shortly after completing pycparser, I got more and more interested in compilation and started learning about the different kinds of parsers more seriously. Over time, I grew convinced that recursive descent is the way to go - producing parsers that are easier to understand and maintain (and are often faster!).

It all ties in to the benefits of dependencies in software projects as a function of effort. Using parser generators is a heavy conceptual dependency: it's really nice when you have to churn out many parsers for small languages. But when you have to maintain a single, very complex parser, as part of a large project - the benefits quickly dissipate and you're left with a substantial dependency that you constantly grapple with.

The other issue with dependencies

And then there are the usual problems with dependencies; dependencies get abandoned, and they may also develop security issues. Sometimes, both of these become true.

Many years ago, pycparser forked and started vendoring its own version of PLY. This was part of transitioning pycparser to a dual Python 2/3 code base when PLY was slower to adapt. I believe this was the right decision, since PLY "just worked" and I didn't have to deal with active (and very tedious in the Python ecosystem, where packaging tools are replaced faster than dirty socks) dependency management.

A couple of weeks ago this issue was opened for pycparser. It turns out the some old PLY code triggers security checks used by some Linux distributions; while this code was fixed in a later commit of PLY, PLY itself was apparently abandoned and archived in late 2025. And guess what? That happened in the middle of a large rewrite of the package, so re-vendoring the pre-archiving commit seemed like a risky proposition.

On the issue it was suggested that "hopefully the dependent packages move on to a non-abandoned parser or implement their own"; I originally laughed this idea off, but then it got me thinking... which is what this post is all about.

Growing complexity of parsing a messy language

The original K&R2 grammar for C99 had - famously - a single shift-reduce conflict having to do with dangling elses belonging to the most recent if statement. And indeed, other than the famous lexer hack used to deal with C's type name / ID ambiguity, pycparser only had this single shift-reduce conflict.

But things got more complicated. Over the years, features were added that weren't strictly in the standard but were supported by all the industrial compilers. The more advanced C11 and C23 standards weren't beholden to the promises of conflict-free YACC parsing (since almost no industrial-strength compilers use YACC at this point), so all caution went out of the window.

The latest (PLY-based) release of pycparser has many reduce-reduce conflicts [2]; these are a severe maintenance hazard because it means the parsing rules essentially have to be tie-broken by order of appearance in the code. This is very brittle; pycparser has only managed to maintain its stability and quality through its comprehensive test suite. Over time, it became harder and harder to extend, because YACC parsing rules have all kinds of spooky-action-at-a-distance effects. The straw that broke the camel's back was this PR which again proposed to increase the number of reduce-reduce conflicts [3].

This - again - prompted me to think "what if I just dump YACC and switch to a hand-written recursive descent parser", and here we are.

The mental roadblock

None of the challenges described above are new; I've been pondering them for many years now, and yet biting the bullet and rewriting the parser didn't feel like something I'd like to get into. By my private estimates it'd take at least a week of deep heads-down work to port the gritty 2000 lines of YACC grammar rules to a recursive descent parser [4]. Moreover, it wouldn't be a particularly fun project either - I didn't feel like I'd learn much new and my interests have shifted away from this project. In short, the Potential well was just too deep.

Why would this even work? Tests

I've definitely noticed the improvement in capabilities of LLM coding agents in the past few months, and many reputable people online rave about using them for increasingly larger projects. That said, would an LLM agent really be able to accomplish such a complex project on its own? This isn't just a toy, it's thousands of lines of dense parsing code.

What gave me hope is the concept of conformance suites mentioned by Simon Willison. Agents seem to do well when there's a very clear and rigid goal function - such as a large, high-coverage conformance test suite.

And pycparser has an very extensive one. Over 2500 lines of test code parsing various C snippets to ASTs with expected results, grown over a decade and a half of real issues and bugs reported by users.

I figured the LLM can either succeed or fail and throw its hands up in despair, but it's quite unlikely to produce a wrong port that would still pass all the tests. So I set it to run.

The initial port

I fired up Codex in pycparser's repository, and wrote this prompt just to make sure it understands me and can run the tests:

This repository implements a Python parser producing an AST. It has a very
extensive test suite; can you first verify you successfully run all the tests?
(with python3 -m unittest discover, from the root dir)

Codex figured it out (I gave it the exact command, after all!); my next prompt was the real thing [5]:

pycparser uses the PLY library for its lexer and parser, and its own AST
package for the ASTs created by the parser. I want to explore replacing the
Parser component (leaving the Lexer alone for now) with a hand written
recursive descent parser that will pass all the same tests. Can you try that?

Here Codex went to work and churned for over an hour. Having never observed an agent work for nearly this long, I kind of assumed it went off the rails and will fail sooner or later. So I was rather surprised and skeptical when it eventually came back with:

Replaced the PLY parse path with a handwritten recursive‑descent parser while
keeping the existing lexer and AST helpers intact; CParser now points to the
new RD implementation, with the old PLY version preserved as PLYCParser in
pycparser/c_parser.py. The RD parser includes a token stream, declarator/type
parsing, expression precedence handling, pragmas, and statement parsing to
match the previous AST output and coordinate behavior.

It took me a while to poke around the code and run it until I was convinced - it had actually done it! It wrote a new recursive descent parser with only ancillary dependencies on PLY, and that parser passed the test suite. After a few more prompts, we've removed the ancillary dependencies and made the structure clearer. I hadn't looked too deeply into code quality at this point, but at least on the functional level - it succeeded. This was very impressive!

A quick note on reviews and branches

A change like the one described above is impossible to code-review as one PR in any meaningful way; so I used a different strategy. Before embarking on this path, I created a new branch and once Codex finished the initial rewrite, I committed this change, knowing that I will review it in detail, piece-by-piece later on.

Even though coding agents have their own notion of history and can "revert" certain changes, I felt much safer relying on Git. In the worst case if all of this goes south, I can nuke the branch and it's as if nothing ever happened. I was determined to only merge this branch onto main once I was fully satisfied with the code. In what follows, I had to git reset several times when I didn't like the direction in which Codex was going. In hindsight, doing this work in a branch was absolutely the right choice.

The long tail of goofs

Once I've sufficiently convinced myself that the new parser is actually working, I used Codex to similarly rewrite the lexer and get rid of the PLY dependency entirely, deleting it from the repository. Then, I started looking more deeply into code quality - reading the code created by Codex and trying to wrap my head around it.

And - oh my - this was quite the journey. Much has been written about the code produced by agents, and much of it seems to be true. Maybe it's a setting I'm missing (I'm not using my own custom AGENTS.md yet, for instance), but Codex seems to be that eager programmer that wants to get from A to B whatever the cost. Readability, minimalism and code clarity are very much secondary goals.

Using raise...except for control flow? Yep. Abusing Python's weak typing (like having None, false and other values all mean different things for a given variable)? For sure. Spreading the logic of a complex function all over the place instead of putting all the key parts in a single switch statement? You bet.

Moreover, the agent is hilariously lazy. More than once I had to convince it to do something it initially said is impossible, and even insisted again in follow-up messages. The anthropomorphization here is mildly concerning, to be honest. I could never imagine I would be writing something like the following to a computer, and yet - here we are: "Remember how we moved X to Y before? You can do it again for Z, definitely. Just try".

My process was to see how I can instruct Codex to fix things, and intervene myself (by rewriting code) as little as possible. I've mostly succeeded in this, and did maybe 20% of the work myself.

My branch grew dozens of commits, falling into roughly these categories:

The code in X is too complex; why can't we do Y instead?
The use of X is needlessly convoluted; change Y to Z, and T to V in all instances.
The code in X is unclear; please add a detailed comment - with examples - to explain what it does.

Interestingly, after doing (3), the agent was often more effective in giving the code a "fresh look" and succeeding in either (1) or (2).

The end result

Eventually, after many hours spent in this process, I was reasonably pleased with the code. It's far from perfect, of course, but taking the essential complexities into account, it's something I could see myself maintaining (with or without the help of an agent). I'm sure I'll find more ways to improve it in the future, but I have a reasonable degree of confidence that this will be doable.

It passes all the tests, so I've been able to release a new version (3.00) without major issues so far. The only issue I've discovered is that some of CFFI's tests are overly precise about the phrasing of errors reported by pycparser; this was an easy fix.

The new parser is also faster, by about 30% based on my benchmarks! This is typical of recursive descent when compared with YACC-generated parsers, in my experience. After reviewing the initial rewrite of the lexer, I've spent a while instructing Codex on how to make it faster, and it worked reasonably well.

Followup - static typing

While working on this, it became quite obvious that static typing would make the process easier. LLM coding agents really benefit from closed loops with strict guardrails (e.g. a test suite to pass), and type-annotations act as such. For example, had pycparser already been type annotated, Codex would probably not have overloaded values to multiple types (like None vs. False vs. others).

In a followup, I asked Codex to type-annotate pycparser (running checks using ty), and this was also a back-and-forth because the process exposed some issues that needed to be refactored. Time will tell, but hopefully it will make further changes in the project simpler for the agent.

Based on this experience, I'd bet that coding agents will be somewhat more effective in strongly typed languages like Go, TypeScript and especially Rust.

Conclusions

Overall, this project has been a really good experience, and I'm impressed with what modern LLM coding agents can do! While there's no reason to expect that progress in this domain will stop, even if it does - these are already very useful tools that can significantly improve programmer productivity.

Could I have done this myself, without an agent's help? Sure. But it would have taken me much longer, assuming that I could even muster the will and concentration to engage in this project. I estimate it would take me at least a week of full-time work (so 30-40 hours) spread over who knows how long to accomplish. With Codex, I put in an order of magnitude less work into this (around 4-5 hours, I'd estimate) and I'm happy with the result.

It was also fun. At least in one sense, my professional life can be described as the pursuit of focus, deep work and flow. It's not easy for me to get into this state, but when I do I'm highly productive and find it very enjoyable. Agents really help me here. When I know I need to write some code and it's hard to get started, asking an agent to write a prototype is a great catalyst for my motivation. Hence the meme at the beginning of the post.

Does code quality even matter?

One can't avoid a nagging question - does the quality of the code produced by agents even matter? Clearly, the agents themselves can understand it (if not today's agent, then at least next year's). Why worry about future maintainability if the agent can maintain it? In other words, does it make sense to just go full vibe-coding?

This is a fair question, and one I don't have an answer to. Right now, for projects I maintain and stand behind, it seems obvious to me that the code should be fully understandable and accepted by me, and the agent is just a tool helping me get to that state more efficiently. It's hard to say what the future holds here; it's going to interesting, for sure.

[1]	pycparser has a fair number of direct dependents, but the majority of downloads comes through CFFI, which itself is a major building block for much of the Python ecosystem.

[2]	The table-building report says 177, but that's certainly an over-dramatization because it's common for a single conflict to manifest in several ways.

[3]	It didn't help the PR's case that it was almost certainly vibe coded.

[4]

There was also the lexer to consider, but this seemed like a much simpler job. My impression is that in the early days of computing, lex gained prominence because of strong regexp support which wasn't very common yet. These days, with excellent regexp libraries existing for pretty much every language, the added value of lex over a custom regexp-based lexer isn't very high.

That said, it wouldn't make much sense to embark on a journey to rewrite just the lexer; the dependency on PLY would still remain, and besides, PLY's lexer and parser are designed to work well together. So it wouldn't help me much without tackling the parser beast.

[5]	I've decided to ask it to the port the parser first, leaving the lexer alone. This was to split the work into reasonable chunks. Besides, I figured that the parser is the hard job anyway - if it succeeds in that, the lexer should be easy. That assumption turned out to be correct.