The Dynamic Notebook

What I'm making, what inspired it, and where we're headed.

The last few letters have been grandiose. Reclaim our humanity from the machines! Overhaul education! But how do we get there? This has become a very personal problem.

I started this newsletter with the goal of reading Penrose’s Road to Reality and bringing others along for the journey, in particular others with brains that had recoiled from the usual gauntlet of equations and symbols that hits you right out of the gate. I learned a lot on my own, but every essay I put together to share reads like a mini-textbook.

This doesn’t help anyone, or make any incremental difference to the problem. So how do we fix it?

I’m working on a prototype of what I’m calling a “Dynamic Notebook” that I think could provide an answer. The prototype I’m building is, concretely:

• A Clojurescript (and therefore browser-based) port of the computer algebra system that powers the SICM book, effectively Mathematica in the browser, with a REPL scratchpad on the side to experiment with as you follow along

• A port of physics lessons inspired by the SICM book into a custom fork of the Maria.cloud executable notebook environment, with

• Roam Research’s bidirectional linking functionality upgraded to work, not just with text or phrases, but between actual function definitions.

These ingredients open the portal to a future where notes, exploration, research and learning fuse. It’s so simple! Read on while I drape flesh over these bullet-point bones, and describe what is is about these ingredients that makes them so powerful.

The Dynamic Notebook

Imagine if this newsletter felt more like the following:

Each “post”, or “lesson”, is a page in a browser-based notebook interface with the ability to execute code inline.

Each “lesson” is an interactive essay, exploring and building up to some concept like the “Principle of Least Action”, just like in “Structure and Interpretation of Classical Mechanics” (SICM)… but unlike that book, or any book I’ve ever seen, the essay builds up to some actual piece of code, some function that we can depend on and use in:

• future lessons

• a robotics project, both simulated and powering some actual robotic system

• An artistic experiment where we make a pen follow physically “realizable” paths around a piece of paper

All of which themselves live in the interactive system.

Maria is an online executable notebook that’s close to what we need. Here’s what Maria’s interface looks like now:

It’s warm and inviting, and everything on the page is editable. The format invites you to play and break things. It’s so important that anyone exploring an interactive essay be able to grab the controller and veer the whole thing far off the original course that the author had in mind.

Maria encourages you to build pages that feel more like control panels than essays. Jack Rusher demonstrates some “advanced” usage of Maria, where he explores a complicated-looking mathematical function by summoning a user interface and wiring his function bodies to a UI:

Working through SICM feels much more traditional and dead than Jack’s demo, or any of Maria’s other examples. But the hidden beauty of SICM is that every new concept ends up distilled into a Scheme function, waiting to be brought to life by appropriate sorcery.

Here’s a function that defines the formula for the “action” of some path q governed by a Lagrangian L:

(defn Lagrangian-action
  [L q t1 t2]
  (i/definite-integral (compose L (Gamma q)) t1 t2))

There is so much here! The definition itself is executable. A lesson building up to Lagrangian-action might grow out of a dynamic, interactive microworld that uses the function. (For this lesson you might draw a path, and then have the system wiggle and shimmy your path until it settles onto the path of “least action”. You’ll have to wait for that essay to know more about what that means.)

Now look deeper. The function definition itself is full of portals into other interesting ideas. In the real textbook, these portals are relegated to footnotes, little dessicated things in literally tiny font, declaring their insignificance.

In the Dynamic Notebook version of SICM, the interior functions themselves are hyperlinks to other function bodies, demarcated by [[Double Brackets]]:

(defn Lagrangian-action
  "Generates a scalar [[Action]] for the supplied path `q`
   in a system governed by the [[Lagrangian]] `L`."
  [L q t1 t2]
  ([[Calculus/definite-integral]]
     (compose L (Gamma q)) t1 t2))

So we see that the Dynamic Notebook is not a single page; it’s a web of linked notebooks, some of which house large, intricate microworlds (perhaps an orbital mechanics notebook that lets you play with the chaotic systems living there, like the game it really is), and some that are a single function long, with a few lines of text or a hyperlink, maybe a saved REPL session.

Roam Research users are nodding along right now.

Unlike anything in Maria or Roam today, function definitions will also automatically generate bidirectional links of their own. Every function will be able to tell you where it’s used — for functions like Lagrangian-action, this provides automatic answers to the age-old question of “where is this useful?”

Every function will also be namespaced by its page, and accessible from other pages, not tied to an arbitrary directory structure.

I’m imagining a new style of “literate programming” that feels much more like working in a messy personal notebook, inside the graph of your own mind.

Roam Research

I have to say more about Roam Research, as it’s a brilliant tool for thinking. The way Roam has helped me structure my learning and thinking is a major inspiration for this new system. Roam has been transformative for my ability to process fleeting thoughts, books, anything based in words and language. It’s not good (yet) for absorbing technical material.

Roam is billed as a “note taking” system. I discovered it as a tool that let me implement the Zettelkasten system described in How to Take Smart Notes.

I use Roam to take notes on things I’m reading, store links I’ve found around the web, manage task lists, and work through difficult technical papers. When I open the site for the day I see this:

Each of those blue links is a hyperlink to a new page. You can make new pages by surrounding any text in [[double braces]].

Here’s the kicker: the new page has a list of hyperlinked references to every place its title is mentioned, whether you thought to link it or not. This is such a gorgeous idea. You start writing notes to yourself, peppered with hyperlinks. At first you only think to link Wikipedia-style page names, like [[Brent’s Method]] or [[Complex Number]]. But soon you realize that there are full phrases or ideas, maybe only meaningfully to you, that keep recurring in your thoughts. You decide to link those too.

Some of my favorites are:

• [[Embodied Experience]]

• [[Go to Mars]]

• [[Memorizing the Phonebook]]

• [[Mathematical Microaggression]]

• [[What Is a Thing]]

• [[Mathematical Beauty]]

• [[Tricking Yourself]]

• [[Word Blimp]]

• [[Creative Bottleneck]]

  • [[Creative Jigs]]

• [[Map vs Territory]]

• [[External Brain]], [[External Structure]]

• [[Tool for Thinking]]

• [[Idea Congress]]

• [[Idea Lattice]]

• [[Embodied Experience]]

• [[Review Your Own Pull Requests]]

I add mass to each of these… mental clusters? planetary bodies in the Mindscape? by hyperlinking the phrase as I type. And links autocomplete, providing you additional incentive to sew together the graph.

When I find myself linking one of these phrases, I use a keyboard shortcut to open up its page in the sidebar, and I have a look at other places where I mentioned it. Often I had the same thought weeks ago, and I use the chance to expand on that thought. I’m writing many essays at once, with no pressure, over weeks and months.

Here’s a subset of notes I took on March 23rd (my brother’s birthday, incidentally):

(The actual Roam Research page from my Roam database is here if you want to see more of that day’s notes.)

Do you see what’s happening? I’m building out first drafts of articles and essays I didn’t even know I wanted to write, just by following my own interest and curiosity around. No more fear of the blank page.

Nat Eliason has a brilliant video showing how to turn all of these raw paragraphs into essays with Roam. If you’re intrigued, this is well worth a watch:

The original source for this style of working is Sönke Ahrens’s How to Take Smart Notes. I have 10,000 words of heavily hyperlinked notes on that book at this page in Roam. Give it a skim, and watch my note-taking style morph as I absorb the book.

Roam’s Brilliance, and Mental Graphs

Roam’s brilliance is that it makes it trivial to build a large, personal mental graph out of your own thoughts and interests. Other systems like Evernote give you big swathes of page and invite you to write, and force you to cobble together links between pages with “tags” or folders. This is all blank page with none of the critical scaffolding that holds it all together.

We think and explore creatively by building up mental graphs. Writing and teaching are about exposing a particular path through that mental graph. Dropping someone else into my mental graph would drive them insane, so I have to hew out paths for them by writing and publishing essays.

Roam is special because it doesn’t force me to excise the path from the graph. I can read a “lesson” or essay I’ve put together in Roam, and get a deep sense of context from all of the terms and phrases I’ve linked.

This is a deeply unusual property for an essay or research artifact. Modern research papers are all paths through the graph of someone’s mind, or a lab’s built-up history. But academic reputations are built on PDFs and a system of journal publication that’s backwards-compatible with 17th century printing technology. “Citations” are the best we get, unclickable references to, not a phrase, not an idea, but to an often-inaccessible book or paper.

The ability to publish a Roam page and keep its backlinks intact would be revolutionary. You’d be able to remind yourself how some idea in your paper was triggered by something random you read that day, or a walk with your daughter, and rebuild the mental context that led to the thought in the first place.

Text is the most difficult medium to structure; some ML system that tried to do this for me would have to think my thoughts. By mixing text and a graph structure, Roam has taught me how to explore and map out my own mind by following my own curiosity. Roam truly is a tool for thinking.

So what’s missing?

The Problem with Executable Notebooks

Roam can’t host code or generate anything dynamic. You can’t build interfaces (yet) inside of Roam, or calculate anything. You can write LaTeX, but it’s clunky, and you can’t use code to generate LaTeX instead of writing it by hand.

When I explore technical topics, I want to write code. I want to draw. I want to explore the topic by generating little microworlds. At the very least I need to be able to visualize and graph data, and store, or access, that data from inside my notebook.

Here are some current executable notebooks that try to answer this need:

• Mathematica

• Jupyterlab

• Observable HQ’s Notebooks

• Nextjournal

• Maria.cloud, which we discussed above

These systems are powerful at building paths through a mental graph. They present a single linear page that can grow without bound. You’re not encouraged, or even able, to leave the page and depend on functions or blocks of code you’ve written in other notebooks. These systems are not good at building up the graph.

I’ve been asking colleagues how they use Mathematica. Most folks seem to use these notebooks as a REPL; they have a single document that grows without bound, until they finally become exasperated, declare Notebook Bankruptcy, delete the notebook and start again.

Jupyter is popular with the Python community. I have colleagues that do initial machine learning experiments in a notebook, but stumble and quit due to the mundane decisions that Jupyter forces:

• What do you name the notebook?

• Where does it live?

• If you write some code in the notebook, how do you share it with a different notebook?

• Well… you have to move the code out into a common place. Where?

You can’t even commit notebooks to a version control system without introducing huge amounts of noise into the version control system’s commit messages, so many never do.

The world is waking up to interactive articles. This Distill.pub survey article from a few days ago catalogues many of these. But because of these problems with executable notebooks, I haven’t yet encountered anyone that actually works inside the system. Everyone seems to write their interactive essays after the fact. No one is working inside of an interactive essay and using its structure to drive research forward.

What we need is a dynamic research notebook; a tool that combines Roam’s strengths with the dynamic power of an executable research environment.

Primers, Projects, Notes

My goal is to generate interactive, executable essays that can help others see what I figured out how to see during the learning process.

But what about projects? What do we do with all of this learning? If people have to leave the Dynamic Notebook to explore the ideas they’ve learned, it’s a failure. The notebook has to make it possible to stay inside the graph, and feel more productive because of this.

Andy Matuschak has been stressing to me that many of the tools we build up in existing interactive essays are toys. Functional Differential Geometry builds up the mathematical tools for general relativity in code. But do any astrophysicists actually use this stuff? There’s certainly no page full of examples, or projects using the code that you can fork and play with.

Science experiments in science museums often have this character. There’s some system set up in a plastic box, with a knob that you turn. Turn the knob and a glowing charge gathers on some plate in the box. Is this science? You can’t break it, or fiddle with it. It’s a magic trick. It’s a toy.

The beauty of the executable essays I’m imagining authoring in the Dynamic Notebook is that each is focused around:

• the creation and understanding of some software tool or function

• The use of an artistic visualization tool, like the turtle’s pen in LOGO

• code that drive a physical system like the Axidraw

These essays will live in the dynamic notebook’s graph structure. Any function inside the essays will be linkable and usable by any other page. As you’re reading, if you get inspired, simply make a new page and start playing; or copy the page, and rebuild the functions along with the essay, using the executable essay’s embedded tests to check your understanding.

At any point you’ll feel encouraged and empowered to leave the text and simply use the thing that the essay was describing. And the essay will gain a backlink to your project, accreting mass, and automatically answering the question of “how is this useful?”

“Primers” in this system simultaneously explain and build tools that you can use for projects. Project are their own primers, detailing how you investigated some area you were curious about, or generated some artistic thing, some game, some window into an idea. And if you developed anything along the way that helped, that tool becomes available for others to use.

The Dynamic Notebook, Redux

Back to what I’m making, concretely.

I’ve been working with Colin Smith to port his Clojure version of the engine behind SICM, called “SICMUtils”, to Clojurescript. This now works. Almost all of the code that powers Structure and Interpretation of Classical Mechanics and Functional Differential Geometry runs in the browser.

I’ve got SICMUtils working in a local build of Maria. I’m two Clojurescript functions away from being able to interactively animate physical systems inside Maria. This will let me write my first essays. These will be:

• A port of the first chapter of SICM, peppered with Roam-style links, building up the ideas of Lagrangian mechanics and how a one-line mathematical equation can breathe life into a physical system (like a satellite moving between orbiting planets)

• Side-essays on function minimization, calculus and Clojure, designed to be used by the SICM essays

• Suggested “exercises” that you can complete inside the system.

I’ve asked Conor White-Sullivan, Roam’s founder, to let me prototype this system inside of actual Roam. If he doesn’t bite, I’ll build a toy version, with the ability to execute code and link code across Roam-style pages.

So much of human knowledge only exists due to a sort of oral tradition. Yes, so much of our knowledge is written down. But the graph structure itself that defines the links between subjects, ideas, concepts lives in the minds of researchers and learners. We have to continually teach these disciplines to keep the structure alive through our stories and lessons.

A Dynamic Notebook would allow the process of learning and research to contribute to a living graph. Imagine that every problem set completed by every student contributed a living document to something like the dynamic notebook. Rather than re-implementing basics, students could choose to upgrade and polish our old implementations; contribute visualizations; or build dense graphs of projects and examples that link back to the original concepts that inspired them.

Without the Dynamic Notebook, we can only produce dead artifacts, puppets in a millenia-long puppet show.

Conclusion, and Call for Help

I would love if you’d send feedback and stories. Have you wished for a system like this before? Does it exist? Where am I going wrong, and what should I emphasize?

I can’t wait to share this with you!

Keep dreaming,

Sam