https://eli.thegreenplace.net/2026/plugins-case-study-pluggy/<p>Recently I came upon <a class="reference external" href="https://pluggy.readthedocs.io/en/latest/">Pluggy</a>, a Python library for developing plugin systems. It was originally developed as part of the <tt class="docutils literal">pytest</tt> project - known for its rich plugin ecosystem - and later extracted into a standalone library. You're supposed to reach out for Pluggy if you want to add a plugin system …</p><div class="section" id="using-pluggy" morss_own_score="2.848" morss_score="21.059533297529537"> <h2>Using Pluggy</h2> <p>Pluggy is built around the concept of <em>hooks</em>: functions that host applications or tools (from here on, just "hosts") expose and plugins implement. A host exposes hooks by using a decorator returned from <tt>pluggy.HookspecMarker</tt> and a plugin implements this hook using a decorator returned from <tt>pluggy.HookimplMarker</tt>.</p> <p>Pluggy's <a href="https://pluggy.readthedocs.io/en/stable/">documentation</a> explains this fairly well; in this post, I'll show how to implement the <tt>htmlize</tt> tool with some plugins, introduced in <a href="https://eli.thegreenplace.net/2012/08/07/fundamental-concepts-of-plugin-infrastructures">the original article in my plugin series</a>.</p> <p>As a reminder, <tt>htmlize</tt> is a toy tool that takes markup notation similar to reStructuredText, and converts it to to HTML. It supports plugins to handle custom "roles" like:</p> <pre>some text :role:`customized text` and more text </pre> <p>As well as plugins that do arbitrary processing on the entire text.</p> <h3>Defining hooks</h3> <p><a href="https://github.com/eliben/code-for-blog/tree/main/2026/plugin-pluggy/htmlize/htmlize">Out host</a> defines two hooks:</p> <pre><span>import</span> <span>pluggy</span> <span>hookspec</span> <span>=</span> <span>pluggy</span><span>.</span><span>HookspecMarker</span><span>(</span><span>"htmlize"</span><span>)</span> <span>@hookspec</span><span>(</span><span>firstresult</span><span>=</span><span>True</span><span>)</span> <span>def</span> <span>htmlize_role_handler</span><span>(</span><span>role_name</span><span>):</span> <span>"""Return a function accepting role contents.</span> <span> The function will be called with a single argument - the role contents, and</span> <span> should return what the role gets replaced with.</span> <span> """</span> <span>pass</span> <span>@hookspec</span> <span>def</span> <span>htmlize_contents</span><span>(</span><span>post</span><span>,</span> <span>db</span><span>):</span> <span>"""Return a function accepting full document contents.</span> <span> The function will be called with a single argument - the document contents</span> <span> (after paragraph splitting and role processing), and should return the</span> <span> transformed contents.</span> <span> """</span> <span>pass</span> </pre> <p>A hook is created by calling <tt>HookspecMarker</tt> with the project's name. This project name has to match between the host and its plugins. Pluggy is permissive about what hooks accept as parameters and what they return; for maximal flexibility and to stay true to the original <tt>htmlize</tt> example, our hooks return functions.</p> <p>To accompany this <tt>HookspecMarker</tt>, the host also defines a <tt>HookimplMarker</tt> with the same name:</p> <pre><span>hookimpl</span> <span>=</span> <span>pluggy</span><span>.</span><span>HookimplMarker</span><span>(</span><span>"htmlize"</span><span>)</span> </pre> <p>This is used by plugins to attach to hooks when they're loaded.</p> <div class="section" id="loading-plugins-in-the-host" morss_own_score="2.8469387755102042" morss_score="16.483089010251987"> <h3>Loading plugins in the host</h3> <p>The host's main function loads plugins at startup as follows:</p> <pre><span>pm</span> <span>=</span> <span>pluggy</span><span>.</span><span>PluginManager</span><span>(</span><span>"htmlize"</span><span>)</span> <span>pm</span><span>.</span><span>add_hookspecs</span><span>(</span><span>hookspecs</span><span>)</span> <span>pm</span><span>.</span><span>load_setuptools_entrypoints</span><span>(</span><span>"htmlize"</span><span>)</span> </pre> <p><tt>hookspecs</tt> is our Python module containing the hooks shown above. <tt>load_setuptools_entrypoints</tt> is Pluggy's helper for loading plugins that were <tt>pip</tt>-installed into the same environment and registered as setuptools <a href="https://setuptools.pypa.io/en/latest/userguide/entry_point.html">entry points</a>. It's a way to signal - in one's <tt>setup.py</tt> or <tt>pyproject.toml</tt> file - some metadata that projects can review at runtime. In our project, the plugins register themselves with this section in the <tt>pyproject.toml</tt> file:</p> <pre>[project.entry-points.htmlize] tt = "tt" </pre> <p>This says "for entry point <tt>htmlize</tt>, define a new entry named <tt>tt</tt>". Pluggy's <tt>load_setuptools_entrypoints</tt> then uses <a href="https://docs.python.org/3/library/importlib.metadata.html">importlib.metadata</a> to access this information.</p> <p>Note that Pluggy doesn't require using this mechanism. Hosts can implement any plugin discovery method they want, and add plugins directly to their <tt>PluginManager</tt> with the <tt>register</tt> method. But this is the mechanism used for <tt>pytest</tt> and many other projects; it makes it very easy to automatically discover and register plugins that are installed with <tt>pip</tt> and equivalent tools.</p> </div> <h3>Invoking plugins</h3> <p>Once <tt>PluginManager</tt> loads the plugins, invoking them is straightforward; here's how <tt>htmlize</tt> invokes the contents hooks </p> <pre><span># Build full contents back again, and ask plugins to act on</span> <span># contents.</span> <span>contents</span> <span>=</span> <span>''</span><span>.</span><span>join</span><span>(</span><span>parts</span><span>)</span> <span>for</span> <span>handler</span> <span>in</span> <span>plugin_manager</span><span>.</span><span>hook</span><span>.</span><span>htmlize_contents</span><span>(</span><span>post</span><span>=</span><span>post</span><span>,</span> <span>db</span><span>=</span><span>db</span><span>):</span> <span>contents</span> <span>=</span> <span>handler</span><span>(</span><span>contents</span><span>)</span> <span>return</span> <span>contents</span> </pre> <p>Generally, hook invocations return a <em>list</em> of all the hooks attached to by different plugins (a single host application can have multiple plugins installed and attaching to the same hook). When the host invokes the hook as shown above, the default order is LIFO, but plugins can affect this with <a href="https://pluggy.readthedocs.io/en/stable/#call-time-order">hook options</a> like <tt>tryfirst</tt> and <tt>trylast</tt>.</p> <h3>Implementing hooks in plugins</h3> <p>Here's our entire <tt>narcissist</tt> plugin that's attaching to the contents hook:</p> <pre><span>import</span> <span>htmlize</span> <span>@htmlize</span><span>.</span><span>hookimpl</span> <span>def</span> <span>htmlize_contents</span><span>(</span><span>post</span><span>,</span> <span>db</span><span>):</span> <span>repl</span> <span>=</span> <span>f</span><span>'&lt;b&gt;I (</span><span>{</span><span>post</span><span>.</span><span>author</span><span>}</span><span>)&lt;/b&gt;'</span> <span>def</span> <span>hook</span><span>(</span><span>contents</span><span>):</span> <span>return</span> <span>re</span><span>.</span><span>sub</span><span>(</span><span>r</span><span>'\bI\b'</span><span>,</span> <span>repl</span><span>,</span> <span>contents</span><span>)</span> <span>return</span> <span>hook</span> </pre> <p>Some notes:</p> <ul> <li>It expects <tt>htmlize</tt> to be installed; as discussed previously, we rely on Pluggy's default install-based approach where both the host and plugins are installed into the same Python environment and can thus find each other. However, Pluggy supports any custom discovery method.</li> <li>It uses the <tt>hookimpl</tt> exported value shown earlier.</li> <li>It returns a function that acts on contents; this is the <tt>htmlize</tt>-specific contract (ABI, if you will) we've discussed before.</li> </ul> </div> Sat, 13 Jun 2026 20:21:00 https://eli.thegreenplace.net/2026/thoughts-on-starting-new-projects-with-llm-agents/<p>A few months ago I wrote about <a class="reference external" href="https://eli.thegreenplace.net/2026/rewriting-pycparser-with-the-help-of-an-llm/">using LLM agents to help restructuring one of my Python projects</a>. It's worth beginning by saying that the rewrite has been successful by all reasonable measures; I've been able to continue maintaining that project since then without an issue.</p> <p>In this post, I …</p><div class="entry-content" morss_own_score="5.688984881209503" morss_score="19.516728071619426"> <p>A few months ago I wrote about <a href="https://eli.thegreenplace.net/2026/rewriting-pycparser-with-the-help-of-an-llm/">using LLM agents to help restructuring one of my Python projects</a>. It's worth beginning by saying that the rewrite has been successful by all reasonable measures; I've been able to continue maintaining that project since then without an issue.</p> <p>In this post, I want to discuss another project I've recently completed with significant help from agents: <a href="https://eli.thegreenplace.net/2026/watgo-a-webassembly-toolkit-for-go/">watgo</a>. In this project many things are different; most notably, it's a from-scratch project rather than a rewrite, and it uses a different programming language (Go). This post describes my experience working on the project, and some lessons learned along the way.</p> <h2>The process</h2> <p>This is a new project, so it required extensive design. I began by iterating on the design with the agent, with a sketch of the API. For this purpose, I recommend using a Markdown file <a href="https://github.com/eliben/watgo/blob/main/doc/notes.md">committed into the repository</a> for future reference.</p> <p>After that, I started asking the agent to write CLs </p> <p>This point is worth reiterating: sometimes a single CL is a huge step forward, but requires lots of review, cleanup and refactoring to be viable. I've had multiple instances where an agent produced several days of work in a single CL, but I then spent hours instructing it to clean up and refactor. Overall, it's still a productivity gain, just not as much as some pundits would like us to believe.</p> <div class="section" id="keeping-the-human-in-the-loop" morss_own_score="2.9285714285714284" morss_score="21.166349206349206"> <h2>Keeping the human in the loop</h2> <p>Given the current state of agent capabilities, I think it's worth splitting projects into two categories:</p> <ol> <li>Low importance / prototype / throw away projects where deep code understanding is unnecessary. These can be "vibe-coded" (submitting agent code without even reviewing it).</li> <li>High importance projects that I actually want to maintain; here, vibe-coding is ill advised and I insist on reviewing and guiding all code the agent writes before it's submitted (or shortly after, as discussed above).</li> </ol> <p>The <tt>watgo</tt> projects is a clear example of (2): I certainly intend to maintain this project in the long term, so I insist on code that I understand. With very few exceptions, no code gets in without full review and often multiple rounds of revisions.</p> <p>Even if the cost for writing code went down, maintaining a project is so much more than that. It's triaging and fixing bugs, it's thinking through what needs to be done rather than how to do it, it's keeping the code healthy over time, and so on. As <a href="https://www.goodreads.com/quotes/273375-everyone-knows-that-debugging-is-twice-as-hard-as-writing">Brian Kernighan said</a>:</p> <blockquote> Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?</blockquote> <p>Maybe at some point agents will become good enough that projects in category (2) can be implemented and maintained completely autonomously. Maybe. But we're certainly not there yet. My hunch is that getting there will require crossing the AGI line </p> <h3>Practical workflow</h3> <p>If you're using an agent to send an actual PR and only review <em>that</em>, it's difficult to be disciplined enough to actually perform a thorough review. I find the following method to be more reliable:</p> <p>I use a CLI agent running locally in my repository, and ask it to update the code there. In parallel, I have a VSCode window open in the same project, where I can:</p> <ol> <li>Review the agent's changes using VSCode's diff view</li> <li>Make my own tweaks and code changes if needed</li> </ol> <p>Once I'm pleased with the change, I manually create a commit.</p> </div> <h2>Keeping the CLs small</h2> <p>As mentioned above, it's imperative to keep making progress in small chunks, with small enough CLs that a human can fully understand in a single review. It's very tempting to sprint ahead submitting thousands of lines of code every day, but this temptation has to be avoided. Coding with an agent is like speed-reading; yes, you're making more progress, but comprehension suffers the faster you go.</p> <p>Particularly for refactoring, agents still take the shortest route to destination. It's important to guide them to think about the "big picture" at all times, find all instances where X is better done as Y, not just a single place noticed during a review. This is why it's sometimes OK to have a CL submitted before you fully agree with everything, and go back to it later for several refactoring rounds. Source control works amazingly well when pair-coding with agents.</p> <h2>Testing strategy</h2> <p>It's a key point discussed in every "how to succeed with AI" article, but still critical enough to reiterate here: a solid testing strategy is absolutely crucial for success. Agents produce - by far - the best results when they have a solid test suite to test their code against.</p> <p>With the <a href="https://github.com/eliben/pycparser">pycparser</a> rewrite, I had a large existing test suite. For <a href="https://github.com/eliben/watgo">watgo</a>, the very first thing I did was think through how to adapt the test suites of the <a href="https://github.com/WebAssembly/spec/">WASM spec</a> and of the <a href="https://github.com/WebAssembly/wabt">wabt project</a> for my needs.</p> <p>If your project doesn't have such tests to rely on, this should be your first order of business - finding one, or building one from scratch. Beware of self-reinforcing loops though; it's dangerous to trust agents for both the tests and the implementations tested against them.</p> <div class="section" id="language-choice-go-for-agent-written-projects" morss_own_score="3.0" morss_score="17.0"> <h2>Language choice - Go for agent-written projects</h2> <p>Go is a fantastic language for agents to write, because it's designed to be very readable by humans. The biggest strengths of Go are exactly what makes the experience of reviewing agent code so positive:</p> <ul> <li>Go changes very infrequently, so you don't have to wonder "are we using the most modern / idiomatic approach" or "what the hell is this construct" as often as with other languages (looking at you, Python and TypeScript).</li> <li>There are relatively few ways to accomplish the same thing in Go, further lowering the mental burden.</li> <li>The standard library is rich and there's much less need to keep abreast of the package-everyone-uses du jour.</li> <li>In general, Go is designed for readability, with a mild-but-still-strong type system, uniform formatting, explicit error propagation and opinionated choices already made for you.</li> </ul> <p>Since most of the time spent by humans when using agents is <em>reading</em> rather than <em>writing</em> code, these effects compound and produce a great experience. Recall the discussion of how some languages are optimized for writability (Perl) while others are optimized for readability (Go)? Well, when working on a project with an agent we live in a world of 99% reading vs. 1% writing, so this really matters.</p> <p>I find this aspect really crucial in light of the earlier points made in this post - namely, keeping the human in the loop by understanding and reviewing all of the agent's design choices and code.</p> </div> <div class="section" id="final-thoughts" morss_own_score="2.895652173913043" morss_score="17.395652173913042"> <h2>Final thoughts</h2> <p>If you're working on a subject that's completely new to you, I would strongly recommend <em>against</em> the approach described in this post. To really learn something, you have to work through it from scratch, yourself, reading, designing, writing the code. Agents don't change this basic fact; even before agents, if you wanted to learn X, copying it from Stack Overflow or some other project clearly wasn't the right way to go. Similarly, while agents can be used as a prop for learning, they cannot learn <em>for you</em>.</p> <p>As a corollary, junior engineers should exercise <em>extreme caution</em> when relying on LLMs. There's no replacement to hard-won experience and the sweat and tears of learning new, challenging topics. Learning is supposed to be hard; if it's too easy, you're probably not learning.</p> <p>For senior engineers, agents are a boon; it's a great tool to increase productivity, avoid the boring stuff, and get unstuck from procrastination; but only when used judiciously.</p> <hr> </div> </div> Sat, 06 Jun 2026 17:38:00 https://eli.thegreenplace.net/2026/notes-on-fourier-series/<link rel="stylesheet" href="https://eli.thegreenplace.net/demos/fourier/fourier-plot.css"><p>The trigonometric Fourier series is a beautiful mathematical theory that shows how to decompose a periodic function into an infinite sum of sinusoids. These are my notes on the subject, with some examples and the connection to linear algebra in Hilbert space.</p> <div class="section" id="coefficients-of-fourier-series"> <h2>Coefficients of Fourier series</h2> <p>Let’s assume that …</p></div><div class="entry-content" morss_own_score="5.847742696960755" morss_score="31.004749926807598"> <p>The trigonometric Fourier series is a beautiful mathematical theory that shows how to decompose a periodic function into an infinite sum of sinusoids. These are my notes on the subject, with some examples and the connection to linear algebra in Hilbert space.</p> <div class="section" id="coefficients-of-fourier-series" morss_own_score="2.975257731958763" morss_score="41.72071227741331"> <h2>Coefficients of Fourier series</h2> <p>Let’s assume that <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> is a <em>well-behaved</em> </p> <p>Then we say that the <em>Fourier series</em> on the right-hand side converges to <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png">. We’ll talk more about the assumptions mentioned above and convergence in the next section.</p> <p>Note that when <img src="https://eli.thegreenplace.net/images/math/4a5997da73aadd118038761e69d01e24586bf958.png">; therefore it’s customary to write the series starting with </p> <p>Our goal is to find the coefficients </p> <p><strong>Step 1:</strong> Integrate both sides of the equation between </p> <p>Per Appendix A, all integrals within the sum are zero, so we’re left with:</p> <p>And thus we find <img src="https://eli.thegreenplace.net/images/math/4a5997da73aadd118038761e69d01e24586bf958.png">:</p> <p><strong>Step 2:</strong> Multiply both sides by </p> <p>Looking at the right-hand side, the first integral is zero per Appendix A, and the last integral is zero per Appendix B. We’re left with:</p> <p>Per Appendix B, the integral on the right is zero for all </p> <p>Recall that <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png">; for consistency, we’ll replace <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png"> and isolate </p> <p><strong>Step 3:</strong> Hopefully it’s clear where this is going now; multiply both sides by </p> <p>We’ve just found a way to calculate all the coefficients of our Fourier series for <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png">:</p> <p>Where:</p> </div> <h2>Conditions on <em>f</em> and convergence of Fourier series</h2> <p>The previous section discusses Fourier series for a function <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> that is <em>well-behaved</em> - but what does that mean? The full answer would lead us deep into analysis, which I’d like to avoid here. So I’ll keep it brief.</p> <p>We typically assume that <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> is <a href="https://en.wikipedia.org/wiki/Square-integrable_function">square integrable</a>, which is denoted as <a href="https://en.wikipedia.org/wiki/Piecewise_function">piecewise smooth</a>: each segment of the function has continuous derivatives. A very simple example of a piecewise smooth function is </p> <p>These conditions hold for pretty much any reasonable function we want to approximate using Fourier series, so they aren’t a serious burden.</p> <p>For a function <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> that satisfies these conditions, it’s guaranteed to have a Fourier series that <em>pointwise converges</em> to it. This means that at every continuous point of <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png">, the Fourier series converges to it exactly; at every jump point, the Fourier series converges to the mid-point of the jump.</p> <h2>Cosine and Sine series</h2> <p>Sometimes, additional properties of the function <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> can help us simplify the Fourier series for it. If <a href="https://eli.thegreenplace.net/2025/notes-on-even-and-odd-functions/">even function</a>, then we know that:</p> <p>Because the function inside the integral is odd, and integrating an odd function over a symmetric interval results in 0.</p> <p>Therefore, the Fourier series for such <em>cosine series</em>:</p> <p>With coefficients <img src="https://eli.thegreenplace.net/images/math/4a5997da73aadd118038761e69d01e24586bf958.png"> and </p> <p>Similarly if <em>odd</em> function, then its <img src="https://eli.thegreenplace.net/images/math/4a5997da73aadd118038761e69d01e24586bf958.png"> and <em>sine series</em>:</p> <div class="section" id="fourier-series-for-a-non-periodic-function-defined-on-an-interval" morss_own_score="2.9810725552050474" morss_score="28.168572555205046"> <h2>Fourier series for a non-periodic function defined on an interval</h2> <p>So far we’ve been talking about </p> <p>E.g. suppose we have </p> <p>Yes! First, we have to make a choice of how to extend the function to the negative interval <em>periodic extension</em>. Note that the Fourier series calculation only cares about the range </p> <p>There are several natural ways to extend a function defined on </p> <ul> <li>Direct periodic repetition: we simply repeat <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> every </li> <li>Even extension: </li> <li>Odd extension: <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> when </li> </ul> <p>Here’s an example of extending our sample function </p> <canvas> Your browser does not support the HTML5 canvas tag. </canvas> <p>Note that the Fourier series for these extended functions will be different. However, they will all converge to <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> in the interval </p> <p>We’ve seen that Fourier series work well for periodic functions and also non-periodic functions defined on a finite domain (because we can extend these periodically). But what about aperiodic functions defined on the entire real line? This is where we’ll have to leave Fourier series behind and move on to their generalization - the <em>Fourier transform</em>; this will be a topic for a separate post.</p> </div> <div class="section" id="example" morss_own_score="2.9731543624161074" morss_score="43.28870991797166"> <h2>Example</h2> <p>Let’s take the following triangular function </p> <canvas> Your browser does not support the HTML5 canvas tag. </canvas> <p>Then making an odd extension into </p> <p>Since this function is odd, we know that we’ll get a <em>sine series</em>, as <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png">. Let’s calculate </p> <p>Since </p> <p>Let’s set </p> <p>And split up the integral for the different segments of </p> <p>The first integral, by the method described in Appendix C:</p> <p>The second integral can also be split into two:</p> <p>The first of these is trivial to calculate; the second can once again use Appendix C. After some tedious but straightforward calculations </p> <p>Adding </p> <p>Now let’s substitute </p> <p>We have </p> <p>Note that for even values of <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png">, </p> <p>Here’s an interactive chart showing how the series <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png"> as for <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png"> is odd.</p> <canvas> Your browser does not support the HTML5 canvas tag. </canvas> <label> n (terms in the Fourier series) </label> </div> <h2>Compact formula using a single phase-shifted sinusoid</h2> <p>We’ve written the Fourier series for <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> as follows so far:</p> <p>We can rewrite this in a somewhat more compact form, using a single sinusoid with a configurable phase at each <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png">:</p> <p>Based on Appendix D, </p> <p>When Fourier series are used in the context of signal processing, this formulation is easier to reason about because it represents the magnitude and phase shift of each harmonic of <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> in the frequency domain </p> <div class="section" id="complex-fourier-series" morss_own_score="2.9637826961770624" morss_score="38.28246401485838"> <h2>Complex Fourier series</h2> <p>It should not come as a surprise that the Fourier series, being a combination of trigonometric functions, can also be represented with complex exponential functions.</p> <p>Specifically, we’ll show that our <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> can be approximated as follows:</p> <p>Let’s calculate </p> <p>By Appendix A, the sum elements are all zero when </p> <p>Therefore, renaming <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png"> (since it’s just an arbitrary integer constant):</p> <p>We’ve found an alternative formulation to Fourier series, using complex exponentials instead of trigonometric functions. While this was a direct derivation, another way to achieve the same result is to use the <a href="https://eli.thegreenplace.net/2024/notes-on-the-euler-formula/">Euler Formula</a> to derive:</p> <p>And substitute these into the original Fourier series formula. I’ll leave this as an exercise for the diligent reader; eventually, the result will be the same. Moreover, it’s possible to show a direct correspondence between </p> <p>Note that <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png">). This helps explain why the complex formulation has negative frequencies in the sum; when the function is actually real, each negative frequency is paired up with a positive frequency and the result is real </p> <p>So, for a real function we only need to account for positive frequencies:</p> <p>We can take it further. </p> <p>And substituting back into the sum:</p> <p>This is precisely the compact formulation from the previous section!</p> </div> <div class="section" id="fourier-orthogonal-basis-in-hilbert-space" morss_own_score="2.890625" morss_score="34.68305136746143"> <h2>Fourier orthogonal basis in Hilbert space</h2> <p>The most beautiful aspect of Fourier theory is that it doesn’t just happen to work by chance, and is deeply connected to linear algebra. Please read <a href="https://eli.thegreenplace.net/2025/hilbert-space-treating-functions-as-vectors/">my post on Hilbert space</a> before proceeding.</p> <p>The space of real-valued square integrable functions </p> <p>We’ve demonstrated that the family of functions:</p> <p>Are all mutually orthogonal, because their pairwise inner products are zero! We’ve also shown that any function in </p> <p>So these functions form a <em>basis</em> for <img src="https://eli.thegreenplace.net/images/math/7a38d8cbd20d9932ba948efaa364bb62651d5ad4.png"> in this basis, we usually find the coefficients by <a href="https://eli.thegreenplace.net/2024/projections-and-projection-matrices/">projecting it</a> onto the basis. E.g. with a basis vector <img src="https://eli.thegreenplace.net/images/math/7a38d8cbd20d9932ba948efaa364bb62651d5ad4.png">:</p> <p>Similarly, when we calculate the coefficient <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png">, we project <img src="https://eli.thegreenplace.net/images/math/3e03f4706048fbc6c5a252a85d066adf107fcc1f.png"> onto the basis vector </p> <p>From Appendix B, we know that the denominator is </p> <p>So we get:</p> <p>Which should look familiar!</p> <p>This is the core linear-algebra idea behind Fourier series: the functions <img src="https://eli.thegreenplace.net/images/math/4a0a19218e082a343a1b17e5333409af9d98f0f5.png"> in this basis. The integral formulas for </p> <p>Fourier series therefore let us decompose a function into independent orthogonal directions, much like decomposing a vector into its <img src="https://eli.thegreenplace.net/images/math/11f6ad8ec52a2984abaafd7c3b516503785c2072.png">, <img src="https://eli.thegreenplace.net/images/math/95cb0bfd2977c761298d9624e4b4d4c72a39974a.png">, and </p> </div> <h2>Appendix A: Integrals of sinusoids</h2> <p>For any integer </p> <p>Similarly:</p> <p>Using these, we can calculate the integral of a complex exponential function for an integer </p> <div class="section" id="appendix-b-integrals-of-products-of-sinusoids" morss_own_score="2.880952380952381" morss_score="27.78720238095238"> <h2>Appendix B: Integrals of products of sinusoids</h2> <p>We’ll start with the product of two sines, for any positive integers <img src="https://eli.thegreenplace.net/images/math/d1854cae891ec7b29161ccaf79a24b00c274bdaa.png">:</p> <p>Using the trigonometric identity for a product of sines, we can write:</p> <p>Now let’s focus on two different scenarios, </p> <p>If <em>ss</em> are 0 (see on Appendix A), so </p> <p>If </p> <p>Therefore:</p> <p>We can use exactly the same approach to show that:</p> <p>One more variant to cover:</p> <p>Since sine is an odd function and cosine is an even function, their product is an odd function. And the integral of an odd function over a symmetric interval is 0 (see <a href="https://eli.thegreenplace.net/2025/notes-on-even-and-odd-functions/">this post for more details</a>).</p> <p>Therefore:</p> </div> <h2>Appendix C: A useful integral</h2> <p>Let’s calculate the indefinite integral:</p> <p>For some constant </p> <p>Here </p> <p>Putting it together:</p> <div class="section" id="appendix-d-sinusoid-with-phase-as-a-sum-of-sin-and-cos" morss_own_score="5.450134770889488" morss_score="33.37870619946092"> <h2>Appendix D: Sinusoid with phase as a sum of sin and cos</h2> <p>Let’s take a general sinusoid with magnitude <img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> and phase <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png">:</p> <p>We’re going to show that <em>sine</em> and a <em>cosine</em> with no phase. This is related to <a href="https://eli.thegreenplace.net/2023/sum-of-same-frequency-sinusoids/">my earlier post on the sum of same-frequency sinusoids</a>.</p> <p>Let’s start by expanding </p> <p>Now we’ll denote: </p> <p>We have <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png">, but what about the other way around?</p> <p>Let’s take the equations:</p> <p>Square both of them and add together:</p> <p>Now we’ll take the equations for </p> <p>Where <a href="https://en.wikipedia.org/wiki/Atan2">the atan2 function</a> is careful to take into account the sign of both numerator and denominator. Also it’s worth mentioning that <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png"> is determined up to additions of </p> <p>To conclude, for any <img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> and <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png">:</p> <p>With the aforementioned conversion formulas for </p> <hr> </div> </div> Wed, 27 May 2026 19:30:00 https://eli.thegreenplace.net/2026/scaling-stretching-and-shifting-sinusoids/<p>This is a brief and simple <a class="footnote-reference" href="#footnote-1" id="footnote-reference-1">[1]</a> explanation of how to adjust the standard sinusoid <object class="valign-m5" data="https://eli.thegreenplace.net/images/math/1f2ea8ffab8deb0e5b854a260a68b42b7eb7b048.svg" style="height: 19px;" type="image/svg+xml">sin(x)</object> to change its amplitude, frequency and phase shift. More precisely, given the general function:</p> <object class="align-center" data="https://eli.thegreenplace.net/images/math/85a45cfe4c1671765c3ab7e3949d8f74f780a0f3.svg" style="height: 19px;" type="image/svg+xml">\[s(x)=A\cdot sin(w\cdot x+\theta)\]</object> <p>We’ll see how adjusting the parameters <img alt="A" class="valign-0" src="https://eli.thegreenplace.net/images/math/6dcd4ce23d88e2ee9568ba546c007c63d9131c1b.png" style="height: 12px;" />, <img alt="w" class="valign-0" src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png" style="height: 8px;" /> and <img alt="\theta" class="valign-0" src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png" style="height: 12px;" /> affect the …</p><div class="entry-content" morss_own_score="5.914893617021276" morss_score="18.62173681196516"> <p>This is a brief and simple </p> <p>We’ll see how adjusting the parameters <img src="https://eli.thegreenplace.net/images/math/6dcd4ce23d88e2ee9568ba546c007c63d9131c1b.png">, <img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> and <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png"> affect the shape of </p> <h2>Scaling</h2> <p>Scaling is conceptually the simplest change; we adjust <img src="https://eli.thegreenplace.net/images/math/6dcd4ce23d88e2ee9568ba546c007c63d9131c1b.png"> to increase or decrease the amplitude (maximal height) of <img src="https://eli.thegreenplace.net/images/math/95cb0bfd2977c761298d9624e4b4d4c72a39974a.png"> value twice as large (in both the positive and negative direction) as the original function.</p> <div class="section" id="stretching" morss_own_score="2.954887218045113" morss_score="17.31203007518797"> <h2>Stretching</h2> <p>Stretching changes the frequency of <img src="https://eli.thegreenplace.net/images/math/11f6ad8ec52a2984abaafd7c3b516503785c2072.png">.</p> <p>If we set <img src="https://eli.thegreenplace.net/images/math/11f6ad8ec52a2984abaafd7c3b516503785c2072.png"> is multiplied by 2 before being fed into the sinusoid. If <img src="https://eli.thegreenplace.net/images/math/11f6ad8ec52a2984abaafd7c3b516503785c2072.png"> changes by </p> <p>More generally, the period of <img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> and observing how the waveform changes.</p> <p>If we know the period <img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> that gives us this period:</p> </div> <h2>Shifting</h2> <p>The final parameter we discuss is <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png">; it’s called the <em>phase</em> of the sinusoid. In the baseline <img src="https://eli.thegreenplace.net/images/math/a1dffbe89f1ec5a919198de979fca459eb7fdf84.png">. The sinusoid is 0 at </p> <p>By adding a non-zero <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png">, we don’t affect the sinusoid’s amplitude or frequency, but we do shift it right or left along the <img src="https://eli.thegreenplace.net/images/math/11f6ad8ec52a2984abaafd7c3b516503785c2072.png"> axis. For example, suppose we use the function <em>left</em> by <img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png"> is negative, everything happens later, and the function is shifted <em>right</em>.</p> <h2>Putting it all together</h2> <p>We’ve now gone over all the parameters for the function:</p> <ul> <li><img src="https://eli.thegreenplace.net/images/math/6dcd4ce23d88e2ee9568ba546c007c63d9131c1b.png"> controls the scaling factor (amplitude).</li> <li><img src="https://eli.thegreenplace.net/images/math/aff024fe4ab0fece4091de044c58c9ae4233383a.png"> is the frequency and controls the repetition period</li> <li><img src="https://eli.thegreenplace.net/images/math/cb005d76f9f2e394a770c2562c2e150a413b3216.png"> controls the phase - how much the sinusoid is shifted left or right</li> </ul> <p>Use the demo below to adjust these parameters and observe their effect on the sinusoid:</p> <canvas> Your browser does not support the HTML5 canvas tag. </canvas> <label> A </label> <label> ω </label> <label> θ </label> <hr> </div> Sat, 02 May 2026 07:17:00 https://eli.thegreenplace.net/2026/thoughts-on-webassembly-as-a-stack-machine/<p>This week the article <a class="reference external" href="https://purplesyringa.moe/blog/wasm-is-not-quite-a-stack-machine/">Wasm is not quite a stack machine</a> has been making the rounds and has caught my eye. The post claims that WASM is not a pure stack machine because it has locals and is missing some stack manipulation operations like <tt class="docutils literal">dup</tt> and <tt class="docutils literal">swap</tt>.</p> <p>While I don't …</p><section id="content" morss_own_score="9.310344827586206" morss_score="12.568965517241379"> <article morss_own_score="6.517241379310344" morss_score="11.38527656992618"> <h1> <a href="https://eli.thegreenplace.net/2026/thoughts-on-webassembly-as-a-stack-machine/" title="Permalink to Thoughts on WebAssembly as a stack machine"> Thoughts on WebAssembly as a stack machine </a> </h1> <div class="entry-content" morss_own_score="5.736070381231672" morss_score="43.966999286265406"> <p>This week the article <a href="https://purplesyringa.moe/blog/wasm-is-not-quite-a-stack-machine/">Wasm is not quite a stack machine</a> has been making the rounds and has caught my eye. The post claims that WASM is not a pure stack machine because it has locals and is missing some stack manipulation operations like <tt>dup</tt> and <tt>swap</tt>.</p> <p>While I don't necessarily disagree, IMHO it's a bit of a semantic discussion because - to the best of my knowledge - there is no <em>formal</em> definition of what is a stack machine. Wikipedia, for example, says:</p> <blockquote> [...], a stack machine is a computer processor or a process virtual machine in which the primary interaction is moving short-lived temporary values to and from a push-down stack.</blockquote> <p>WASM certainly fits this definition; the <em>primary</em> interaction is through the stack, though WASM is augmented with an infinite register file (locals). The more purist stack machines like Forth are only limited to the stack and a memory (pointers into which are managed on the stack); WASM has these too, plus the registers.</p> <p>Speaking of Forth, the mention of <tt>dup</tt> reminded me of my own impressions of programming in that language, documented in my post about <a href="https://eli.thegreenplace.net/2025/implementing-forth-in-go-and-c/">implementing Forth in Go and C</a>. There, I highlighted the following essential library function for Forth; it adds an addend to a value stored in memory.</p> <pre><span>:</span> <span>+!</span> <span>( addend addr -- )</span> <span>tuck</span> <span>( addr addend addr )</span> <span>@</span> <span>( addr addend value-at-addr )</span> <span>+</span> <span>( addr updated-value )</span> <span>swap</span> <span>( updated-value addr )</span> <span>!</span> <span>;</span> </pre> <p>And lamented how difficult it is to understand such code without the detailed stack view in comments alongside it.</p> <p>I find it much simpler to reason about this WASM code:</p> <pre><span>(</span><span>func</span> <span>(</span><span>export</span> <span>"add_to_byte"</span><span>)</span> <span>(</span><span>param</span> <span>$addr</span> <span>i32</span><span>)</span> <span>(</span><span>param</span> <span>$delta</span> <span>i32</span><span>)</span> <span>(</span><span>i32.store8</span> <span>(</span><span>local.get</span> <span>$addr</span><span>)</span> <span>(</span><span>i32.add</span> <span>(</span><span>i32.load8_u</span> <span>(</span><span>local.get</span> <span>$addr</span><span>))</span> <span>(</span><span>local.get</span> <span>$delta</span><span>)))</span> <span>)</span> </pre> <p>You may say this is cheating because folded WASM instructions help readability and they're just syntactic sugar; OK, here's the linear code:</p> <pre><span>local.get</span> <span>$addr</span> <span>local.get</span> <span>$addr</span> <span>i32.load8_u</span> <span>local.get</span> <span>$delta</span> <span>i32.add</span> <span>i32.store8</span> </pre> <p>It's still very readable, because - while the stack is used for all the calculations and actual commands - some of the data lives in named "registers" instead of on the stack. So we don't need all those tuck-swap contortions to get things into the right order.</p> <p>One might worry about the duplicated <tt>local.get $addr</tt>; wouldn't a real <tt>dup</tt> be better? Well, not in terms of readability, as we've already discussed. How about performance? Since the stack VM is just an abstraction and the underlying CPUs executing this code are register machines anyway, the answer is no - it doesn't matter at all.</p> <p>Modern compiler engineers were forged in the fires of C and its descendants; arbitrary control flow, arbitrary register and memory access, anything goes. Compilers are quite sophisticated. Let's see how <tt>wasmtime</tt> compiles our <tt>add_to_byte</tt> to native code (using <tt>wasmtime explore</tt> with its default <tt><span>opt-level=2</span></tt>); comments are added by me:</p> <pre><span>// Prologue</span> <span>push</span> <span>rbp</span> <span>mov</span> <span>rbp</span><span>,</span> <span>rsp</span> <span>// wasmtime's VM context pointer lives in rdi; 0x38 is likely its offset</span> <span>// to the default linear memory. Therefore, r10 will hold the base address</span> <span>// of the linear memory buffer</span> <span>mov</span> <span>r10</span><span>,</span> <span>qword</span> <span>ptr</span> <span>[</span><span>rdi</span> <span>+</span> <span>0x38</span><span>]</span> <span>// The first parameter ($addr) is in edx; since WASM values are i32, it's</span> <span>// zero-extended into the 64-bit r11 by copying into r11d</span> <span>mov</span> <span>r11d</span><span>,</span> <span>edx</span> <span>// r10+r11 is memory[$addr]; this loads the current value into rsi</span> <span>// (zero-extending from 8 bits)</span> <span>movzx</span> <span>rsi</span><span>,</span> <span>byte</span> <span>ptr</span> <span>[</span><span>r10</span> <span>+</span> <span>r11</span><span>]</span> <span>// ecx is the first parameter ($delta); this adds the addend to the</span> <span>// current value</span> <span>add</span> <span>esi</span><span>,</span> <span>ecx</span> <span>// Store cur_value+addend back into memory[$addr]</span> <span>mov</span> <span>byte</span> <span>ptr</span> <span>[</span><span>r10</span> <span>+</span> <span>r11</span><span>],</span> <span>sil</span> <span>// Epilogue</span> <span>mov</span> <span>rsp</span><span>,</span> <span>rbp</span> <span>pop</span> <span>rbp</span> <span>ret</span> </pre> <p>This is pretty much the code we'd expect to be emitted for the C statement <tt>mem[addr] += addend</tt>, or if we were writing x86-64 assembly by hand. The compiler had no difficulty figuring out that two consecutive loads from the same WASM local produce the same value and do not - in fact - have to be duplicated. The WASM model makes it rather easy, because you can't alias locals; as long as there are no intervening writes into the same local, multiple reads are known to produce the same value (redundant load elimination).</p> </div> <hr> <p> For comments, please send me </p> </article> </section> Wed, 29 Apr 2026 19:28:00