Back from the Code Mines
Introducing Emmy and its visualization toolkit.
It’s coming on 2.5 years since my last update! This has definitely been the longest period in my life of uninterrupted studying and hacking. Unfortunately for you all, I haven’t interrupted the phase with any writing or explanation of where I’ve been spending my time.
My dream for this newsletter was that I could write each post as an interactive, executable experience, with embedded simulations that would function as little experiments. If you changed any of the code in the post, the simulation would respond and show you the implications of your change. In my last update I promised that I was going to write the first posts as storyboards, and then backfill them with interactivity:
A lot of what’s coming is going to weave language and code, since I don’t have the animating notebook yet. Please treat this as an intermediate step! I am going to do by best to draw and describe along the way the pictures that the code is supposed to be animating.
The puppet-show approach felt so lame that I switched my focus to building out what I saw as the minimal set of tools that I needed to write essays in this new style.
I haven’t shared any of this because I saw this newsletter as being about the physics that I had promised to write about, not about these prerequisite tools. This was a mistake! In this post I’ll attempt to remedy this error by showing off what I’ve made and shipped so far, what’s left, what’s still confusing to me and where we’re headed next.
Here’s a list of what I’ve built so far:
MathBox.cljs, a declarative 3D graphing library
Mafs.cljs and JSXGraph.cljs, two takes on interactive 2D graphing libraries
Leva.cljs, a library for building UI control panels
MathLive.cljs, an equation editor that can speak with Emmy
I’ll describe Emmy in this post and follow up on the others in my next update.
Emmy (formerly SICMUtils)
"Building Tools for Sharing Physics" describes the beginning of my love affair with Sussman and Wisdom’s textbook, “Structure and Interpretation of Classical Mechanics”, “SICM” for short. Sussman and Wisdom had done the hard work of building a good chunk of the tools to explore modern physics (Lagrangian and Hamiltonian mechanics, differential geometry, general relativity) up as an MIT Scheme library. MIT Scheme is a member of the Lisp family of programming languages, and I happen to have a lot of experience in Clojure, another Lisp with the ability to run code inside of a web browser.
“Aha!” I thought. “All I have to do is port the code that runs the book into Clojure, and I’ll get years of newsletter material for free. This is so easy it feels like cheating!” The library behind the book is Gerald Sussman’s scmutils, short for “Scheme Utilities”. It’s a ~65,000-line-of-code treasure trove of ideas and experiments in physics, electrical engineering and software design accumulated over the course of Sussman’s career. He started the project during a sabbatical to Caltech in the late 80s to work with Feynman and learn astronomy, and has spent the subsequent decades enriching it with the artifacts produced by his intense curiosity.
Colin Smith had made good progress on a port of scmutils to Clojure, and gave a lovely talk on the port in this talk, called “Physics in Clojure”. I picked up on this project by porting all of Colin’s work into ClojureScript, the dialect of Clojure that can run in the browser, and eventually adding maybe 20,000 more lines of code, lots of documentation and essay-style exposition, and thousands of tests.
The port was initially named “SICMUtils”, a riff on “SICM” and “scmutils”. We’ve since renamed it to Emmy, after mathematician Emmy Noether. We still don’t have everything from scmutils, but we have most of it, and the codebase is very fast and well documented. I pushed every bug I found and improvement I made back to Sussman for inclusion in the original library. This turned out to be a great way to get to know Sussman, or GJS. Here was his response to my first bug report:
Remember: bugs are not evil. They are just an opportunity to learn something new. So this is fun! I will not sleep tonight thinking about it. :-)
What is Emmy?
Emmy is a collection of mathematical objects represented as data structures, operations on those data structures, and a small set of utilities for displaying the objects in various ways.
The most basic way to interact with Emmy is via a Clojure “REPL”, or Read-Eval-Print loop. A REPL is a prompt that looks like this:
user=>You type in a Clojure form and hit <return>, and Clojure-the-language:
(R)eads your input,
(E)valuates the form
(P)rints the result of evaluating the form
(L)oops back to the waiting state before (R)eading your next form.
If you want to follow along, install Java and Clojure using the Practicalli Clojure guides, then come back here when you can successfully run the
cljcommand at your terminal. Write to me if you have trouble and I’ll get you sorted.
To play with Emmy, enter the following command at your terminal:
clj -Sdeps '{:deps {io.github.mentat-collective/emmy {:git/sha "fe0e8bb755baf677cd615ba8e69be4f7f6f3ce40"}}}' -M -e "(use 'emmy.env)" -rThis will start a REPL with every function in the emmy.env namespace available. Evaluate something simple:
user=> (* 2 2)
4Try out some symbolic math, first rendered as a Clojure value and then rendered as an “infix” string, i.e., a text representation of the mathematical expression you’ve entered:
user=> (* 1/2 'm (square 'v))
(* 1/2 m (expt v 2))
user=> (->infix (* 1/2 'm (square 'v)))
"1/2 m v²"You can also try Emmy in the browser at this NextJournal page, and play with these interactive versions of many of the SICM exercises. The advantage of these other environments is that we gain control over the (p)rint stage of the REPL, and can render outputs as mathematical objects:
Or even as full-blown interactive animations! More on that in the next post.
Here’s a mostly-complete list of Emmy’s mathematical objects:
Integers, rational numbers, real numbers and complex numbers
Symbolic versions of all of the above! For example,
(+ 1 2)evaluates to 3, but(+ x x y)evaluates to(+ (* 2 x) y).Quaternions
Vectors, matrices and “structures”, used to represent tensors
Functions and higher order “operators”
Power series, polynomials, rational functions
Many objects from differential geometry, like manifolds, points, patches, coordinate systems etc
On top of these objects, Emmy has implementations of numerical calculus, function minimization routines, ODE solvers for running simulations of systems based on their differential equations, automatic differentiation, symbolic differentiation, mathematical expression simplification… really everything you need to explore modern physics at the graduate level, as proven out by Sussman and Wisdom.
The library is built in the “additive” style advocated by Sussman and Hanson in their book “Software Design for Flexibility”. This means that many of the operations available on these mathematical objects are open and extensible; the same + function you use to add numbers together can also add matrices, or vectors, or polynomials… and if you bring some new data type, like a number-wrapped-in-units (“1 foot”), then you can teach + how to add these as well.
I decided while porting the library that I would try to understand and heavily document the entire codebase. For example, here’s the implementation of polynomial interpolation, a process for taking a bunch of points and drawing a polynomial that hits all of them. This process used all over the place, and writing it up this was led me to illuminating connections with old functional programming work I’d done on functional folds. This heavy documentation is my allergic reaction to the confusing, obfuscated style that so many numerical algorithms are written in. See my 2020 talk “Functional Physics and the Preservation of Society” for more color here.
As I worked on Emmy, documented, researched the algorithms, and stitched things together, I realized that the scmutils codebase itself was a brilliant narrative accomplishment. The question that the codebase addresses, and answers in the affirmative, is — given a very small set of primitives, symbols, lists, and some rules for manipulating these, is it possible to build up all of the machinery necessary to simulate physical systems?
The library itself and its design provides the perfect narrative backbone for an essay series describing how to get to graduate level physics, starting with the basics. I feel strongly that the story of the library is enough to fill at least one more book, a sort of prequel to SICM. Maybe we’ll end up writing that book here.
What’s missing?
As you can see here, Emmy can run in your browser and render both mathematical output and Clojure output, in an environment where a reader can take over and play with the code.
What was missing for me was the ability to visualize these mathematical objects in different ways. The 3blue1brown series on Linear Algebra completely changed my attitude toward that subject by giving me a rock-solid visual intuition for what it means to say that “a matrix represents a linear transformation”.
But the videos in that series are tightly scripted and composed, not interactive at all. Playing with the Clojure REPL feels more like a dialogue. When I type a function into the REPL, I want to see a graph of that function, damnit! And, better yet, if there are variables, I want to be able to manipulate those variables in my UI.
Lucky for us, here in 2023, the JavaScript story around high-performance animation and physics simulation is extremely impressive. Here are some references that had me tingling:
Page full of vector fields, running on MathBox
How to Fold a Julia Fractal, by Steven Wittens
The driven pendulum, Van der Pol equations and other lovely demos at Colin Smith’s homepage showing off the power of the ODE solver that we use in Emmy.
The next phase of work centered on figuring out
how to make visualizations like these at all,
how to drive these visualizations from Emmy, and
how to embed these visualizations into a narrative and let the reader take over and veer off into their own explorations.
I’ll save details on the next libraries I built for the next post. If you want a preview, see the bullet points at the top of this post.
References
Some other links related to the above, that you might enjoy for dessert:
Here are some notes on what I’ve been up to personally.
Daniel Compton interviewed me about this work for the REPL Podcast, episode 47, “Executable Textbooks with Sam Ritchie”.
I co-interviewed Gerald Sussman on episode 18 of the JUXT podcast
Scratch-like physics tutorial built on top of Emmy. Building the pieces of this project as libraries means other people can mix and match for their own work.
The automatic differentiation code manually exported into kind-of-pretty blog post form, back before I knew how to do this automatically from the code.
Sussman’s talk “We really don’t know how to compute!” with strong appearances from scmutils code
I’ll be speaking at the Clojure Conj on Friday, April 28th about this work. Register, and if you’ll be there, please come say hi!
I’d completely forgotten I’d subscribed to this newsletter 😅
Emmy looks interesting. I look forward to trying it out.
He lives!