It's a bit confusing. Dot apparently is both the language name [1] for the Graphviz syntax, and one of the layout engines [2], possibly with different capitalizations.
I've used GraphViz/Dot (I call `dot` in my terminal, but the package to install is `graphviz`) for probably two decades at this point, and what is what is still not clear to me, kind of like the whole imagemagick/convert thing which is similar, at least to someone on the outside.
Not sure why they can't come up with new names, use those, then when you invoke the program in the terminal, call the binary the same thing, instead of mucking about with calling everything differently, except some things, that share names.
This is exactly what they have done. You can call "dot" and it runs the dot layout engine, but you can also run "neato", "sfdp" or any other -- with the same input.
The "graphviz" package installs all these executables.
I can see how you got that impression and don’t fault you for it in the slightest, but that’s not accurate.
It’s not the language name for all Graphviz syntax; it’s only the syntax for renderings made with the dot engine. Each engine has its own DSL, basically.
Does it? There are slightly different DSLs for directed and non-directed graphs, some features only work with some output formats, but AFAIK, everything in the DSL in independent of the layout engine.
And if I look in my /usr/bin, I see that neato is just symlinked to dot. It's pulling the usual trick of one executable that behaves slightly differently depending on the invocation name.
Looking at the docs again with fresh eyes, I think you and fulafel are on the money.
The specific engine syntaxes are by & large mutually incompatible, but DOT does seem to be the label used for the overall lang as well as the dot-engine-compatible dialect.
I’m not sure how far you can push the generality of the iongraph algorithm. My gut is that it could be made to work somewhat well for any control flow graph with reducible control flow, but I expect there would be many complications.
To get more precise, we benefit from knowing the nesting depth of each block. This plus reducible control flow is enough to reliably find loops. We also know exactly which edges are loop backedges; it’s easiest when these are explicitly annotated but perhaps it would be possible to derive that info from other loop info. (In Ion we have a dedicated “backedge block” per loop, which makes it obvious what we should do, but which other compilers likely wouldn’t have.)
This is a cool example of how specializing a generic algorithm to a specific subspace can yield much better results. This is quite often the case in my experience, but we often don't bother utilizing properties that are specific to our problem space, and just apply the generic algorithm out of convenience (and because it is often good enough)
I wrote my thesis on this! Application-specific system design can get you orders of magnitude performance improvement, as well as better scalability/fault tolerance properties. I focused on graph analytics, but it's reasonable to think it applies more broadly.
Definitely true that application-specific design is often not worth the investment though. Chasing that 1000x improvement can easily cost you a year or two.
Came here to say this, but with caveats. The particular domain has extra properties that allow their "stupider" algorithm to work better in their case. But a general graph drawing system has to deal with the inherent generality of the domain.
Usually there is a good middle ground: heuristic analysis of the input to see if it fits well with special-case "stupid and fast" algorithms, and sophisticated optimizations that are the fallback and work for everything and come with guarantees.
This is a great write up and thank you to the author! Just a note that graphviz dot is not purely Sugiyama’s, there is a paper on the site that details the actual implementation.
Also judging from the final two images (dot vs iongraph for the same large graph) it’s clear that dot is optimized for minimal area where iongraph does not. That’s the trade off. The author claims one is more easy to navigate than the other, I think that’s debatable.
Ultimately I found that visualizing large graphs is rarely helpful in practice; they can certainly look nice for some well defined graphs, but I rarely saw well defined graphs in the wild. Ymmv but maybe some would agree?
Visualizing large graphs is a "tarpit idea," one that initially seems appealing but never succeeds in practice.
Fundamentally, the problem is that visual aids can only really represent a few dozen things before they become as complicated as the thing you were trying to understand in the first place.
And when analyzing messy node diagrams, it’s not just the nodes we’re trying to visualize, but the lines connecting the nodes (the “edges”). We can only visualize a few dozen of those, and that typically means we can visualize only a handful of nodes at a time.
Visualization only works in trivial examples where you don’t need it; it fails in complex environments where you need it the most.
I would go further. The fundamental problem is the idea that there is a fundamentally correct representation of something. This actually goes further than even the visualization of the graph. Symbolic representations have the same trap.
"Ultimately I found that visualizing large graphs is rarely helpful in practice; they can certainly look nice for some well defined graphs, but I rarely saw well defined graphs in the wild."
Since writing that I'm finding my frustration at the inability of diagrams to link out or be linked into is growing. In hindsight it seems a super obvious way of using diagrams in a useful manner and nothing supports it worth a crap, even things that really ought to like Mermaid (which permits out links in text but holds it at arm's length (requiring you to set the diagram to "unsafe"[1]) and as near I can tell in a quick search never mentions this as a thing you can do in its docs, and still has no particular support I can find for linking in to a graph). This has turned into a "can't unsee" for me.
(Obviously I have not used every diagramming solution ever, so maybe there is something out there that supports linking in and/or out, and I'd love to hear about it... however, bear in mind I'm looking for what you might call "first class" support, that is, a feature clearly considered important in the design phase of the project, not the sort of accidental-combination-of-features accidental support that Mermaid half has, if you flip some obscure settings to "lower security" somewhere.)
> There are three basic types of “boxes and lines” (as I derisively refer to them) diagrams:
the point of a boxes-and-lines diagram is to express relationships between components at a single layer/level of abstraction
the best metric for the "quality" of a diagram isn't the number of boxes, rather it's the number of edge-crossings, where >0 is a pretty reliable signal that either (a) the diagram is trying to show too much, or (b) the architecture is sub-optimal
any non-trivial system will always require multiple boxes-and-lines diagrams to be accurately described, one per abstraction-layer
and not really sure that linking between diagram and code is a core requirement, diagrams will generally include identifiers that are unambiguously grep-able, i guess...
I agree that we haven’t gained much yet from looking at large graphs. Usually we can reduce any problem of interest to something small. Still, Graphviz produces very ugly results even for small graphs, whereas this is where iongraph shines.
To be clear, what I think makes the latter graph more readable is particularly that the wires are easier to follow. Yes, it’s subjective, but backed up by my own personal experience. Long term I think we can add more interactive features to help us in such cases, e.g. search and dimming irrelevant wires.
Yep, agreed. CMake does deps graphviz (been there), that is better than nothing. But big diagrams need support for exploding subdiagrams and going back.
The greatest thing about Graphviz is indeed the dot language. A nice thing about using dot is that the graph definition is *portable among all applications that support dot*.
Dot is such a simple and readable format (particularly if using the basic features). Thus, it can make a ton of sense to define graphs in strict dot, even if you will be rendering with another tool than Graphviz.
These days, there are other popular options, too -- Mermaid, etc, as TFA indicates. Nonetheless, Graphviz/dot will remain for the long haul, IMO, because dot is so, so good.
So, you need Graphviz for its syntax definitions primarily, and because it is a standard that could be recognized/run anywhere.
For those who are interested, the Will Evans course on graph drawing [1] covers a lot of cool graph drawing algorithms. Graph drawing is very interesting and many applications get it wrong. I once contributed [2] some small bugfixes to the Dot lexer for the Open Graph Drawing Framework, which has fast implementations of some amazing graph drawing algorithms, and my experience is that the OGDF draws graphs vastly better than the various algorithms in GraphViz (fewer crossings, faster, etc).
I have struggled with code to diagram tools for a while [mermaid and graphviz], and usually return to figjam when I need the readabilty and aesthetics.
graph-viz is MASSIVE and a binary. mermaid requires the browser's svg rendering system to work. I just need something that builds diagrams from description easily ...
The problem with all these tools is that any diagram becomes unreadable past a certain number of nodes. So we need a higher amount of control over the compromise that is inherent in these scenarios. The approach taken by the author is a very good step in this direction and hopefully others will follow.
I used mermaid for https://basisrobotics.tech/2024/11/24/basis-robot-02-softwar... (autogenerated) and it worked out pretty well, but notably I wasn't trying to handle loops. There have to be mermaid to png renderers out there. Beyond that, I view svg/html output as a huge advantage - I can restyle it and it's copyable.
Mermaid is great in its niche, and being web-first has been its greatest asset. But that is also a great frustration because anytime I try to do anything out of the web-world with mermaid, it becomes a massive PITA thanks to needing a full headless browser.
I used graphviz to generate graphs for code structures, and that worked out great.
>graph-viz is MASSIVE and a binary. mermaid requires the browser's svg rendering system to work.
I succeeded to use resvg-js [1] with dagre/graphlib [2] to render graphs. resvg-js uses a 4 MB node library to render SVGs. dagre is used by mermaid for graph layout (for some of the diagram types). if you disable loading system fonts in resvg-js it just takes milliseconds to render the SVG.
I know that mermaid is well-known and very useful, but I don't like the code quality (especially consistency) and the bloat of dependencies. Last time I went through the code I assessed it requires significant refactorings to make it work with resvg-js, i.e. server-side graph layout and rendering.
There is also nomnoml [1], which is so great, it should deserve at least the same amount of attention as mermaid. the nomnoml codebase is a joy to read. the author even converted the dagre/graphlib codebase to typescript [4].
Edit: One of the refactorings to make mermaid work with resvg-js is related to measuring svg text width. It's needed to determine the width of the graph node boxes. mermaid needs to be able to also use `resvg.getBBox()` to make it work with server-side rendering.
Surprised by your comment, I took a gander at graphviz; it's about a quarter of a million lines of code if you discount lib/sparse/color_palette.c and lib/edgepaint/lab_gamut.c, which are hundreds of thousands of lines of data values. This is much more than I expected.
If you want something that builds diagrams from textual descriptions, you might want to check out TikZ, which includes a subset of graphviz but also lets you draw anything you want. See https://en.wikipedia.org/wiki/PGF/TikZ. On the other hand, you won't have the rapid visual feedback you get with WYSIWYG drawing editors like FigJam.
This is a concept I'm working around with Microdiagram (microdiagram.com) prototype.
i.e. having a general purpose diagram/graph layout is hellishly difficult, but most of the diagrams/charts follow much simpler rules, thus it's much easier to have N languages, each for 1 type of diagram, than 1 language for N types of diagrams.
While I fully support your efforts to make better tooling, UML is the poster child for this.
I highly encourage people working in this space to revisit those lessons.
Obviously if you find a new way to work around the limitations please run with it.
But limited scope, and targeted simplifications is the only way I have found, over application by trying to describe everything almost always ends up being more harmful in my experience.
The Piano chart on prototype is an example, that's for discussing piano keys and chords on basic level.
I already implemented (in other prototype) diagram for event calculus (i.e. consideration of event stream through addition of new events like rollback, modify etc.)
On paper I have designs for point-in-time designs, scenario divergence and also some fun ones like a bingo card template. Diagrams are one thing, but there's also a design for collaboration and play-replay capabilities.
That being said, that's only a design right now with a simple prototype on the website :)
I would love to see this evolve into a more general purpose control flow graph viewer - pretty much any language implementation would find it a great debugging tool. it's probably most of the way there already.
this tool works by replacing the "general purpose" algorithm by specializing it, which made it less general purpose but simpler and more efficient ... and now there's the request to make it more general purpose.
(it's a joke! and the joke is that those are two different general purpose. but still.)
Language developers really do struggle with debugging our data-structures since they are often both circular and complex compared to many other applications, I wrote yet-another-UI tool for inspecting code back when I was doing my thesis work.
Maybe I should brush it off (and make it general... ), it would give you a source-code view and navigating the source-text you would be shown compiler nodes related to the lines/statements.
It was almost the only way to make sense of it since I was often generating multiple paths per statement (It was a lossy type-inference system so previous type branchings could lead to multiple subsequent code-paths through each statement and expression).
this article is confusing, it appears to conflate graphviz (an umbrella term/tool that collects a set of layout engines and output formats) with both dot (a specific layout engine) and sstangl/iongraph (a specific tool that transforms a particular SSA/AST input format to a specific dot output format)
it also seems to conflate how a DAG is expressed, with how that expression is rendered
Nice work! The examples look better than the Graphviz output, indeed. This is a good example of how you can always beat a long-developed, generic tool by specializing for a much narrower use case.
Wonder how it compares with elkjs? I had written a few things that wrapped dot, which felt clunky, but have since had good success writing react components that use elkjs. Elkjs has a stupid amount of configuration options, some of which aren't very clearly documented, but I've been able to get decent output for use cases like argument mapping and choose-your-own-adventure maps.
This is great! There are surprisingly few tools that actually output anything nice when it feels like such a doable problem.
One small improvement they could probably make is the ability to rearrange outputs at the bottom to reduce crossings. Just from the very first example it seems flipping the 0 and 1 outputs on the bottom graph would be nicer.
For anyone else interested in this general area, Steve Ruiz and Lu Wilson from tldraw often tweet a lot of fun nitty gritty edge cases in graph drawing.
Resist this temptation. It is better for the true and false branches to always appear in the same order than to permute things to avoid edge crossings.
Layout is one of those things humans do so easily and intuitively, yet you couldn't write an easy algorithm for it. I wonder if there's potential to use gen ai to achieve human like results. Anyone has any thoughts on feasibility and complexity of such an approach?
I think the hard part is more defining the different types of visually pleasing layouts that you want to support. What to align to what, what metrics to minimize, etc.
There is no single layout definition that looks good for all applications. What looks good for one type of graph data (flow charts, org charts, ASTs, family trees, etc, etc) may not look good for another.
Once you've reduced a desired type of layout to a set of layout rules, then I don't think implementing it is the bottleneck, and it seems this part could even be automated if wanted (e.g. evolve layout to best meet constraints).
I dabbled in this area, there are poster layout generation attempts that use gen ai to come up with an initial layout plan, and even feed the visualization back into the llm for iterative fine-tuning.
I was intrigued, but couldn't make it work reliably. Perhaps I forgot to add "make it look nice" to my prompts.
We looked at using Graphviz, but the copyleft nature of Graphviz license (Eclipse Public License) means that this will never be allowed in our company's software.
Interesting. The wiki says: "The Eclipse Public License is designed to be a business-friendly free software license, and features weaker copyleft provisions than licenses such as the GNU General Public License (GPL)."
Well, it's just they think it's business-friendly.
From EPL:
> If a Contributor Distributes the Program in any form, then: a) the Program must also be made available as Source Code, in accordance with section 3.2 ...
Except in startups that really embrace the idea of open source, no "serious" company will offer any portion of their source code under EPL license, even if that's just the modified/derived part of it. Not a chance.
For most companies, in reality, there are only two types of licenses -- copyleft and permissive, no middle ground. You either don't touch it with a 10 foot pole or do whatever you want as long as you copy and paste the attributions.
So this basically depends on how you intend to use. All big corporations use tons of copyleft software, starting with Linux. But if your aim is to take a piece of software, modify it, and don't share your modifications, and this scenario makes you not to choose this particular project, then yes, the license is working as expected. Whether the net benefit of this is positive or not is another question.
There are a pretty large number of "serious" companies that distribute code under the GNU GPL, which has similar but more stringent copyleft terms. IBM, for example, which also originated the Eclipse Public License, and TI, and ARM, and Apple. Almost every microcontroller vendor uses GCC.
If you can get the AST output into a text file, then it should be easy to convert it to the DOT input that GraphViz takes, which at heart is just a list of node connections (A -> B).
D2 "should" handle most cases OP was annoyed about. Its written in Go, so its really fast too. I never had to wait for it to finish, but that said i never produced huge diagrams that i could imagine a compiler would.
This is great. I've been trying to generate diagrams for HDL hierarchies and neither Graphviz nor ELK can do a remotely good job. In fact I've never got good results from Graphviz for any graphs over a handful of nodes. I think it just isn't actually very good. But it has such huge mindshare even if there was a better option I wouldn't be able to find it.
The part that is timing out is actually the JS interpreter, not the graph viewer. It’s a total hack to get SpiderMonkey running on the page at all.
The full Frankenstein stack is: SpiderMonkey compiled in arm emulation mode, to a WASI 0.1 module, adapted to a WASI 0.2 component, transpiled to the web with jco, running in some random WASI shim.
We do this because the JS runtime needs inline caches to be filled out before optimization, which requires an JIT and actual execution of machine code. Otherwise you just get a graph full of Unreachable. Frankly I’m amazed it works at all.
It used to be a that the barrier of entry of creating a new tool was high - so we had to use popular pieces of software, often stretching them, or writing plugins (that had their own constraints).
Now it is often easier to write from scratch a new piece of software, for which with have full control.
We can stand on the shoulders of giants - not just "a giant".
To me, this article demonstrated the value of knowing your domain and its particular constraints, as well as a good understanding of prior art. Together with the only 1000 line demo it took to produce (which I suppose could have been aided by an LLM), I did not finish reading with any specific appreciation for AI.
But based on my experience with multiple project, both current frameworks and AI changed the game. I used to much more reply on existing software and cursing that they don't do what I want - as the time to create a personalized tool was simply much to afford. Now often it is quicker to create a personalized tool than fight with existing one.
To be more accurate, the comparison is not with Graphviz, but with dot(1).
Graphviz is a visualization framework and it includes many layout engines, implementing different algorithms: dot, neato, fdp, sfdp, circo, twopi, ...
It would be great if this new custom algorithm were to be contributed to Graphviz.
It's a bit confusing. Dot apparently is both the language name [1] for the Graphviz syntax, and one of the layout engines [2], possibly with different capitalizations.
[1] https://graphviz.org/doc/info/lang.html [2] https://graphviz.org/docs/layouts/dot/
I've used GraphViz/Dot (I call `dot` in my terminal, but the package to install is `graphviz`) for probably two decades at this point, and what is what is still not clear to me, kind of like the whole imagemagick/convert thing which is similar, at least to someone on the outside.
Not sure why they can't come up with new names, use those, then when you invoke the program in the terminal, call the binary the same thing, instead of mucking about with calling everything differently, except some things, that share names.
> Not sure why they can't ...
This is exactly what they have done. You can call "dot" and it runs the dot layout engine, but you can also run "neato", "sfdp" or any other -- with the same input.
The "graphviz" package installs all these executables.
At least Imagemagick came to their senses and renamed their command to magick (with convert still aliased for BC).
I can see how you got that impression and don’t fault you for it in the slightest, but that’s not accurate.
It’s not the language name for all Graphviz syntax; it’s only the syntax for renderings made with the dot engine. Each engine has its own DSL, basically.
> Each engine has its own DSL, basically.
Does it? There are slightly different DSLs for directed and non-directed graphs, some features only work with some output formats, but AFAIK, everything in the DSL in independent of the layout engine.
You can also set:
in a dot file, call dot, and it will use the neato layout engine.(See https://graphviz.org/docs/attrs/layout/)
And if I look in my /usr/bin, I see that neato is just symlinked to dot. It's pulling the usual trick of one executable that behaves slightly differently depending on the invocation name.
Looking at the docs again with fresh eyes, I think you and fulafel are on the money.
The specific engine syntaxes are by & large mutually incompatible, but DOT does seem to be the label used for the overall lang as well as the dot-engine-compatible dialect.
I’m not sure how far you can push the generality of the iongraph algorithm. My gut is that it could be made to work somewhat well for any control flow graph with reducible control flow, but I expect there would be many complications.
To get more precise, we benefit from knowing the nesting depth of each block. This plus reducible control flow is enough to reliably find loops. We also know exactly which edges are loop backedges; it’s easiest when these are explicitly annotated but perhaps it would be possible to derive that info from other loop info. (In Ion we have a dedicated “backedge block” per loop, which makes it obvious what we should do, but which other compilers likely wouldn’t have.)
Yes, that would be great. Iongraph is MPL, graphviz is EPL. But Iongraph is Javascript anyway, so you would need to use Claude to translate it to C
Why would you need Claude for that?
Everyone knows it is impossible to translate 1000 lines of JS to C in a reasonable amount of time. I mean, 1000 lines is kind of a lot, you know?
Kimi is also good. New habits, you know
This is a cool example of how specializing a generic algorithm to a specific subspace can yield much better results. This is quite often the case in my experience, but we often don't bother utilizing properties that are specific to our problem space, and just apply the generic algorithm out of convenience (and because it is often good enough)
I wrote my thesis on this! Application-specific system design can get you orders of magnitude performance improvement, as well as better scalability/fault tolerance properties. I focused on graph analytics, but it's reasonable to think it applies more broadly.
Definitely true that application-specific design is often not worth the investment though. Chasing that 1000x improvement can easily cost you a year or two.
Came here to say this, but with caveats. The particular domain has extra properties that allow their "stupider" algorithm to work better in their case. But a general graph drawing system has to deal with the inherent generality of the domain.
Usually there is a good middle ground: heuristic analysis of the input to see if it fits well with special-case "stupid and fast" algorithms, and sophisticated optimizations that are the fallback and work for everything and come with guarantees.
That's how all application-specific specializations work though, take advantage of domain properties that make you need a less generic algorithm.
This is a great write up and thank you to the author! Just a note that graphviz dot is not purely Sugiyama’s, there is a paper on the site that details the actual implementation.
Also judging from the final two images (dot vs iongraph for the same large graph) it’s clear that dot is optimized for minimal area where iongraph does not. That’s the trade off. The author claims one is more easy to navigate than the other, I think that’s debatable.
Ultimately I found that visualizing large graphs is rarely helpful in practice; they can certainly look nice for some well defined graphs, but I rarely saw well defined graphs in the wild. Ymmv but maybe some would agree?
Visualizing large graphs is a "tarpit idea," one that initially seems appealing but never succeeds in practice.
Fundamentally, the problem is that visual aids can only really represent a few dozen things before they become as complicated as the thing you were trying to understand in the first place.
And when analyzing messy node diagrams, it’s not just the nodes we’re trying to visualize, but the lines connecting the nodes (the “edges”). We can only visualize a few dozen of those, and that typically means we can visualize only a handful of nodes at a time.
Visualization only works in trivial examples where you don’t need it; it fails in complex environments where you need it the most.
I would go further. The fundamental problem is the idea that there is a fundamentally correct representation of something. This actually goes further than even the visualization of the graph. Symbolic representations have the same trap.
"Ultimately I found that visualizing large graphs is rarely helpful in practice; they can certainly look nice for some well defined graphs, but I rarely saw well defined graphs in the wild."
Yes, I'm with you: https://jerf.org/iri/post/2025/on_layers_and_boxes_and_lines...
Since writing that I'm finding my frustration at the inability of diagrams to link out or be linked into is growing. In hindsight it seems a super obvious way of using diagrams in a useful manner and nothing supports it worth a crap, even things that really ought to like Mermaid (which permits out links in text but holds it at arm's length (requiring you to set the diagram to "unsafe"[1]) and as near I can tell in a quick search never mentions this as a thing you can do in its docs, and still has no particular support I can find for linking in to a graph). This has turned into a "can't unsee" for me.
(Obviously I have not used every diagramming solution ever, so maybe there is something out there that supports linking in and/or out, and I'd love to hear about it... however, bear in mind I'm looking for what you might call "first class" support, that is, a feature clearly considered important in the design phase of the project, not the sort of accidental-combination-of-features accidental support that Mermaid half has, if you flip some obscure settings to "lower security" somewhere.)
[1]: https://stackoverflow.com/questions/41960529/how-to-add-a-li...
> There are three basic types of “boxes and lines” (as I derisively refer to them) diagrams:
the point of a boxes-and-lines diagram is to express relationships between components at a single layer/level of abstraction
the best metric for the "quality" of a diagram isn't the number of boxes, rather it's the number of edge-crossings, where >0 is a pretty reliable signal that either (a) the diagram is trying to show too much, or (b) the architecture is sub-optimal
any non-trivial system will always require multiple boxes-and-lines diagrams to be accurately described, one per abstraction-layer
and not really sure that linking between diagram and code is a core requirement, diagrams will generally include identifiers that are unambiguously grep-able, i guess...
Enterprise architect ($$) had that buried in the gui, and wondered for long if obsidian canvas could do the same, reports wanted.
I agree that we haven’t gained much yet from looking at large graphs. Usually we can reduce any problem of interest to something small. Still, Graphviz produces very ugly results even for small graphs, whereas this is where iongraph shines.
To be clear, what I think makes the latter graph more readable is particularly that the wires are easier to follow. Yes, it’s subjective, but backed up by my own personal experience. Long term I think we can add more interactive features to help us in such cases, e.g. search and dimming irrelevant wires.
I confess I found the graphs GraphViz made for me in https://taeric.github.io/many_sums.html oddly pretty. :D
Yep, agreed. CMake does deps graphviz (been there), that is better than nothing. But big diagrams need support for exploding subdiagrams and going back.
The greatest thing about Graphviz is indeed the dot language. A nice thing about using dot is that the graph definition is *portable among all applications that support dot*.
Dot is such a simple and readable format (particularly if using the basic features). Thus, it can make a ton of sense to define graphs in strict dot, even if you will be rendering with another tool than Graphviz.
These days, there are other popular options, too -- Mermaid, etc, as TFA indicates. Nonetheless, Graphviz/dot will remain for the long haul, IMO, because dot is so, so good.
So, you need Graphviz for its syntax definitions primarily, and because it is a standard that could be recognized/run anywhere.
"I love the status quo! My favorite thing about it is that it is the status quo."
For those who are interested, the Will Evans course on graph drawing [1] covers a lot of cool graph drawing algorithms. Graph drawing is very interesting and many applications get it wrong. I once contributed [2] some small bugfixes to the Dot lexer for the Open Graph Drawing Framework, which has fast implementations of some amazing graph drawing algorithms, and my experience is that the OGDF draws graphs vastly better than the various algorithms in GraphViz (fewer crossings, faster, etc).
[1] https://www.cs.ubc.ca/~will/536E/
[2] https://github.com/ogdf/ogdf/pulls?q=is%3Apr%20author%3Adllu...
This is a great write up.
I wonder if any of these techniques turn up in whatever the magic sauce is in D2’s TALA layout engine, which is in a league of its own IMO.
https://d2lang.com/examples/tala/
anyone working on this space easily gets a +1!
I have struggled with code to diagram tools for a while [mermaid and graphviz], and usually return to figjam when I need the readabilty and aesthetics.
graph-viz is MASSIVE and a binary. mermaid requires the browser's svg rendering system to work. I just need something that builds diagrams from description easily ...
The problem with all these tools is that any diagram becomes unreadable past a certain number of nodes. So we need a higher amount of control over the compromise that is inherent in these scenarios. The approach taken by the author is a very good step in this direction and hopefully others will follow.
I used mermaid for https://basisrobotics.tech/2024/11/24/basis-robot-02-softwar... (autogenerated) and it worked out pretty well, but notably I wasn't trying to handle loops. There have to be mermaid to png renderers out there. Beyond that, I view svg/html output as a huge advantage - I can restyle it and it's copyable.
Mermaid is great in its niche, and being web-first has been its greatest asset. But that is also a great frustration because anytime I try to do anything out of the web-world with mermaid, it becomes a massive PITA thanks to needing a full headless browser.
I used graphviz to generate graphs for code structures, and that worked out great.
https://niravko.com/blog/visualize-cpp-data-structures#resul...
You might also check out D2, which had a recent run on the HN front page.
https://news.ycombinator.com/item?id=45707539
>graph-viz is MASSIVE and a binary. mermaid requires the browser's svg rendering system to work.
I succeeded to use resvg-js [1] with dagre/graphlib [2] to render graphs. resvg-js uses a 4 MB node library to render SVGs. dagre is used by mermaid for graph layout (for some of the diagram types). if you disable loading system fonts in resvg-js it just takes milliseconds to render the SVG.
I know that mermaid is well-known and very useful, but I don't like the code quality (especially consistency) and the bloat of dependencies. Last time I went through the code I assessed it requires significant refactorings to make it work with resvg-js, i.e. server-side graph layout and rendering.
There is also nomnoml [1], which is so great, it should deserve at least the same amount of attention as mermaid. the nomnoml codebase is a joy to read. the author even converted the dagre/graphlib codebase to typescript [4].
[1] https://github.com/thx/resvg-js [2] https://github.com/dagrejs/dagre [3] https://github.com/skanaar/nomnoml [4] https://github.com/skanaar/graphre
---
Edit: One of the refactorings to make mermaid work with resvg-js is related to measuring svg text width. It's needed to determine the width of the graph node boxes. mermaid needs to be able to also use `resvg.getBBox()` to make it work with server-side rendering.
Surprised by your comment, I took a gander at graphviz; it's about a quarter of a million lines of code if you discount lib/sparse/color_palette.c and lib/edgepaint/lab_gamut.c, which are hundreds of thousands of lines of data values. This is much more than I expected.
If you want something that builds diagrams from textual descriptions, you might want to check out TikZ, which includes a subset of graphviz but also lets you draw anything you want. See https://en.wikipedia.org/wiki/PGF/TikZ. On the other hand, you won't have the rapid visual feedback you get with WYSIWYG drawing editors like FigJam.
I've had good results using ELK for a terraform diagram generator. You can see some samples here.
https://marketplace.visualstudio.com/items?itemName=infragra...
This is a concept I'm working around with Microdiagram (microdiagram.com) prototype.
i.e. having a general purpose diagram/graph layout is hellishly difficult, but most of the diagrams/charts follow much simpler rules, thus it's much easier to have N languages, each for 1 type of diagram, than 1 language for N types of diagrams.
While I fully support your efforts to make better tooling, UML is the poster child for this.
I highly encourage people working in this space to revisit those lessons.
Obviously if you find a new way to work around the limitations please run with it.
But limited scope, and targeted simplifications is the only way I have found, over application by trying to describe everything almost always ends up being more harmful in my experience.
Sounds intriguing. What is an example of a chart and its language that you have designed so far?
The Piano chart on prototype is an example, that's for discussing piano keys and chords on basic level.
I already implemented (in other prototype) diagram for event calculus (i.e. consideration of event stream through addition of new events like rollback, modify etc.)
On paper I have designs for point-in-time designs, scenario divergence and also some fun ones like a bingo card template. Diagrams are one thing, but there's also a design for collaboration and play-replay capabilities.
That being said, that's only a design right now with a simple prototype on the website :)
I would love to see this evolve into a more general purpose control flow graph viewer - pretty much any language implementation would find it a great debugging tool. it's probably most of the way there already.
this tool works by replacing the "general purpose" algorithm by specializing it, which made it less general purpose but simpler and more efficient ... and now there's the request to make it more general purpose.
(it's a joke! and the joke is that those are two different general purpose. but still.)
I do get the joke but it's a tad misplaced here.
Language developers really do struggle with debugging our data-structures since they are often both circular and complex compared to many other applications, I wrote yet-another-UI tool for inspecting code back when I was doing my thesis work.
Maybe I should brush it off (and make it general... ), it would give you a source-code view and navigating the source-text you would be shown compiler nodes related to the lines/statements.
It was almost the only way to make sense of it since I was often generating multiple paths per statement (It was a lossy type-inference system so previous type branchings could lead to multiple subsequent code-paths through each statement and expression).
this article is confusing, it appears to conflate graphviz (an umbrella term/tool that collects a set of layout engines and output formats) with both dot (a specific layout engine) and sstangl/iongraph (a specific tool that transforms a particular SSA/AST input format to a specific dot output format)
it also seems to conflate how a DAG is expressed, with how that expression is rendered
strange
Nice work! The examples look better than the Graphviz output, indeed. This is a good example of how you can always beat a long-developed, generic tool by specializing for a much narrower use case.
Wonder how it compares with elkjs? I had written a few things that wrapped dot, which felt clunky, but have since had good success writing react components that use elkjs. Elkjs has a stupid amount of configuration options, some of which aren't very clearly documented, but I've been able to get decent output for use cases like argument mapping and choose-your-own-adventure maps.
This is great! There are surprisingly few tools that actually output anything nice when it feels like such a doable problem.
One small improvement they could probably make is the ability to rearrange outputs at the bottom to reduce crossings. Just from the very first example it seems flipping the 0 and 1 outputs on the bottom graph would be nicer.
For anyone else interested in this general area, Steve Ruiz and Lu Wilson from tldraw often tweet a lot of fun nitty gritty edge cases in graph drawing.
Resist this temptation. It is better for the true and false branches to always appear in the same order than to permute things to avoid edge crossings.
Layout is one of those things humans do so easily and intuitively, yet you couldn't write an easy algorithm for it. I wonder if there's potential to use gen ai to achieve human like results. Anyone has any thoughts on feasibility and complexity of such an approach?
I think the hard part is more defining the different types of visually pleasing layouts that you want to support. What to align to what, what metrics to minimize, etc.
There is no single layout definition that looks good for all applications. What looks good for one type of graph data (flow charts, org charts, ASTs, family trees, etc, etc) may not look good for another.
Once you've reduced a desired type of layout to a set of layout rules, then I don't think implementing it is the bottleneck, and it seems this part could even be automated if wanted (e.g. evolve layout to best meet constraints).
I dabbled in this area, there are poster layout generation attempts that use gen ai to come up with an initial layout plan, and even feed the visualization back into the llm for iterative fine-tuning.
I was intrigued, but couldn't make it work reliably. Perhaps I forgot to add "make it look nice" to my prompts.
https://arxiv.org/abs/2412.04237v3
https://haoyuchen.com/POSTA
https://github.com/microsoft/LayoutGeneration/blob/main/Layo...
Thanks for sharing. Although diagrams have a unique requirement that the boxes are inter-connected, and those connections must also look "nice".
looking at the spagetti: neither is readable, but I'd say wonky graphviz wins because you have a chance following some of the lines.
I love how bitwig solved it: gravity, color coding, stiffness, directionality (ins on the left, outs on the right).
https://polarity.me/img/bitwig-course-02-whatisthegrid-3.jpg
Wow, thank you very much. I like the graphviz dot language. I may translate this to Rust.
We looked at using Graphviz, but the copyleft nature of Graphviz license (Eclipse Public License) means that this will never be allowed in our company's software.
Interesting. The wiki says: "The Eclipse Public License is designed to be a business-friendly free software license, and features weaker copyleft provisions than licenses such as the GNU General Public License (GPL)."
Well, it's just they think it's business-friendly.
From EPL:
> If a Contributor Distributes the Program in any form, then: a) the Program must also be made available as Source Code, in accordance with section 3.2 ...
Except in startups that really embrace the idea of open source, no "serious" company will offer any portion of their source code under EPL license, even if that's just the modified/derived part of it. Not a chance.
For most companies, in reality, there are only two types of licenses -- copyleft and permissive, no middle ground. You either don't touch it with a 10 foot pole or do whatever you want as long as you copy and paste the attributions.
So this basically depends on how you intend to use. All big corporations use tons of copyleft software, starting with Linux. But if your aim is to take a piece of software, modify it, and don't share your modifications, and this scenario makes you not to choose this particular project, then yes, the license is working as expected. Whether the net benefit of this is positive or not is another question.
There are a pretty large number of "serious" companies that distribute code under the GNU GPL, which has similar but more stringent copyleft terms. IBM, for example, which also originated the Eclipse Public License, and TI, and ARM, and Apple. Almost every microcontroller vendor uses GCC.
Can't you buy an exception to the license?
Not my call.
> if a Contributor Distributes
Doesn't this only apply to contributors and dev users?
I think it applies to anyone who distributes it; https://www.eclipse.org/legal/epl-2.0/ says:
Looks nice. Two things on my wish list:
1. Make graphs from Clang's AST.
2. Invent some style flourish to help follow an edge that becomes part of a bundle of many edges.
If you can get the AST output into a text file, then it should be easy to convert it to the DOT input that GraphViz takes, which at heart is just a list of node connections (A -> B).
"clang -Xclang -ast-dump=json" will take you partway there.
D2 "should" handle most cases OP was annoyed about. Its written in Go, so its really fast too. I never had to wait for it to finish, but that said i never produced huge diagrams that i could imagine a compiler would.
When should one use D2 vs graphviz?
I stumbled upon this link that should help: https://text-to-diagram.com/
This is a very nicely presented graph layout algorithm, and it produces very readable CFG output.
eclipse also does better than dot, but it's useful to notice that graphviz never dies
https://github.com/eclipse-elk/elk
please make this as agent for AI
This is great. I've been trying to generate diagrams for HDL hierarchies and neither Graphviz nor ELK can do a remotely good job. In fact I've never got good results from Graphviz for any graphs over a handful of nodes. I think it just isn't actually very good. But it has such huge mindshare even if there was a better option I wouldn't be able to find it.
I added one statement and it only says `timed out`. I'll stick with Graphviz, which certainly doesn't time out.
The part that is timing out is actually the JS interpreter, not the graph viewer. It’s a total hack to get SpiderMonkey running on the page at all.
The full Frankenstein stack is: SpiderMonkey compiled in arm emulation mode, to a WASI 0.1 module, adapted to a WASI 0.2 component, transpiled to the web with jco, running in some random WASI shim.
We do this because the JS runtime needs inline caches to be filled out before optimization, which requires an JIT and actual execution of machine code. Otherwise you just get a graph full of Unreachable. Frankly I’m amazed it works at all.
It's a shame that Wasm is so hostile to runtime code generation. I've been trying to figure out how to design something that's better on that axis.
Hackernews hug of death maybe
It is one of the game changers of AI.
It used to be a that the barrier of entry of creating a new tool was high - so we had to use popular pieces of software, often stretching them, or writing plugins (that had their own constraints).
Now it is often easier to write from scratch a new piece of software, for which with have full control.
We can stand on the shoulders of giants - not just "a giant".
To me, this article demonstrated the value of knowing your domain and its particular constraints, as well as a good understanding of prior art. Together with the only 1000 line demo it took to produce (which I suppose could have been aided by an LLM), I did not finish reading with any specific appreciation for AI.
No LLMs were used, at least not in any substantial way.
I'm sorry, I don't get your comment. What makes you think the approach or the code described in the article were developed by an LLM?
I don't know how the code was created.
But based on my experience with multiple project, both current frameworks and AI changed the game. I used to much more reply on existing software and cursing that they don't do what I want - as the time to create a personalized tool was simply much to afford. Now often it is quicker to create a personalized tool than fight with existing one.
Probably, but I see no connection with the article we're discussing.