Recently I’ve been reading Thinking in Systems: A Primer which is refreshing. Most of my everyday thinking is likely focused on a small aspects of a complex system, like developer velocity, and I often miss the full picture.

What I felt is that, juggling all the interactions between elements exceed my mental capacity. Stock/Flow diagram seems like a useful tool to map out the elements and help me reason about any complex thing.

At the same time, I’m going back to using Emacs. So a natural question is:

Can I use Emacs for systems modeling?

Emacs is a pretty text editor, so if I can do systems modeling with raw text, then using Emacs is a no-brainer.

After some digging, I found Mermaid. For installation steps, please see here.

I picked a diagram Figure 14. Reinvestment Capital from the book and tried rendering in Mermaid and Org mode.

The original diagram looks like:

The first pass

The first pass looks like below:

#+begin_src mermaid :file investment.png
flowchart LR
  cloud[(source)] --> investment --> capital
  capital --> output
  output -- R --> investment
  fraction --> investment
#+end_src

Because Mermaid doesn’t support pointing an edge to another, so I have to model a faucet as a node. It doesn’t have the cloud shape, so I have to use a database node instead.

Conventions and styling tweaks

Here are mapping between stock/flow graph elements and mermaid shapes I finally arrived at:

• Faucet: Trapezoid node shape
• Stock: Default rectangle node, with the a different color to highlight
• Flow: Default directional edge
• Cloud: A node in a cylindrical shape with the text as “Source”
• Text (or outside label): styled as a text class with no fill
• Reinforcement (Balance feedback loop): A link with text between text & faucet

Below are my styling classes. For simplicity, I didn’t add more tweaks.

classDef text fill:none,stroke:none;
classDef stock fill:#f96;

The source code and rendering looks like:

#+begin_src mermaid :file investment-refined.png
flowchart LR
  source[(source)] --> investment[/investment\] --> capital:::stock
  capital --> output:::text
  output -- R --> investment
  fraction([fraction of output invested]):::text --> investment
  classDef text fill:none,stroke:none;
  classDef stock fill:#f96;
#+end_src

The final rendered graph:

Summary

In this post, I set up Emacs + Org mode + Mermaid as a way to do Stock/Flow systems modeling. Because Mermaid lacks some node shapes, I had to add styling tweaks and my own conventions to get the diagram render reasonably.

Nevertheless, having this setup allow me to do systems modeling in raw text, keep all text editing functionalities in Emacs. The final diagram is a bit raw, but good enough for my use.

Thanks for your read!