Support for Circular Flow Diagram

[secnigma]

Is your feature request related to a problem? Please describe. I often want to create circular diagrams and when I try to draw circular diagram using mermaid flowchart, the diagram gets totally ugly and not at all circular looking.

Describe the solution you'd like Include support for creating circular flow charts.

Describe alternatives you've considered An alternative I'm considering is diagrams.net, but that's not flexible as mermaid, since we have to create diagrams by hand. It's fine for creating small quantity of diagrams. But when the number increases, it's a pain to do it in diagrams.net.

Additional context An example for circular flow diagram can be seen here.

[secnigma]

Accidentally opened request for mermaid-js in mermaid-live-editor.

[SteffenLm]

are there any news on this?

[shadowlift]

I found a way to make this work; use "---" instead of "-->" as your node connections. Then arrange your nodes like "A---B, A---C, B---D, C---D" for four node graph, or "A---B, A---C; B---D, C---F; D---E, F---E" for six, etc.

This doesn't create a perfect circle but is at least neater than the asymmetry you get when doing something like "A-->B-->C-->D-->A"

[secnigma]

I found a way to make this work; use "---" instead of "-->" as your node connections. Then arrange your nodes like "A---B, A---C, B---D, C---D" for four node graph, or "A---B, A---C; B---D, C---F; D---E, F---E" for six, etc.

This doesn't create a perfect circle but is at least neater than the asymmetry you get when doing something like "A-->B-->C-->D-->A"

Though we still can't use directions without breaking the diagram, and the result is not fully a circular one, what @shadowlift said can be used as an interim solution. Still, full ciruclar diagram with directions support would be nice though.

[endolith]

Can there be a style/option that ignores ranks and renders flowcharts like a more conventional graph diagram, minimizing length of edges? Like this editor that automatically arranges the nodes in a "lowest energy configuration": https://csacademy.com/app/graph_editor/

Actually I guess it could be added to the "Flowchart Orientation" options.

I guess the "lowest energy configuration" is called "force-directed graphs", and doesn't actually always produce a circle when the graph loops:

So maybe there should just be a flowchart C for circular graphs or something explicit like that?

But I think it would be good to support some kind of force-directed graphs in Mermaid, too, with a similar interface to the flowcharts, maybe as an orientation of flowcharts.

Related:

• https://github.com/peoplesfeelings/pfmindmap
• https://github.com/d3/d3-force
• https://observablehq.com/@d3/disjoint-force-directed-graph?collection=@d3/d3-force
• https://observablehq.com/@d3/build-your-own-graph?collection=@d3/d3-force

Maybe a better example of what I'm imagining is Layered graph drawing:

[runspired]

I struggled with this for a basic triangular flow when trying to communicate that the response from A to B was intercepted by C. The trick of building this without directional arrows works though the arrows would be preferrable.

A --> B B --> C C --> A

flowchart LR
    A[fa:fa-terminal App] --- B(Model)
    A === C{fa:fa-code-fork Store}
    B --- C

[endolith]

FYI: I asked ChatGPT and found it's pretty simple syntax to make equivalent graphs in graphviz:

http://dreampuf.github.io/GraphvizOnline/#digraph%20%7B%0A%20%20%20%20A%20-%3E%20B%0A%20%20%20%20B%20-%3E%20C%0A%20%20%20%20C%20-%3E%20D%0A%20%20%20%20D%20-%3E%20E%0A%20%20%20%20E%20-%3E%20F%0A%20%20%20%20F%20-%3E%20A%0A%7D%0A

Select the neato engine to make it a force-minimizing graph.

[nirname]

I think this is not really a new type of diagram, but rather a layout algorithm

[secnigma]

I think this is not really a new type of diagram, but rather a layout algorithm

@nirname

Layout algorithms does seems to have Circular Layout graphs support and looks like it's much more advanced than regular Circular Flow Diagrams.

What I've proposed was support for Circular Flow Diagrams(which is a separate diagram type, as far as I understand), used in Economics to demonstrate Circular flow of income; which is a much simpler version of Circular Layout Graphs. Reference

But yeah, implementing support for Circular Layout graphs would solve this issue.

[nirname]

May be it is something like cycle / recycle diagram. It can be unidirectional or bidirectional

It also can be a visual extension for donuts (which are extension of pie charts). I think they better not to be mixed in one diagram, but definitely they have something in common.

As some of the examples shows, it can contain nested rings. And these rings somehow synchronized with each other.

Links: https://datavizproject.com/data-type/cycle-diagram/ https://developers.google.com/chart/interactive/docs/gallery/piechart#donut https://datavizproject.com/wp-content/uploads/examples/Sk%C3%A6rmbillede-2016-11-07-kl.-10.19.37.png https://datavizcatalogue.com/methods/donut_chart.html

In comments there were requests about diagrams being ugly and different suggestions to use neato (there is even better circo) or flowchart orientation, so it is not still clear to me what this proposition is about. Let me know if the examples I provided is what you want.

[secnigma]

Apologies for the late reply @nirname

May be it is something like cycle / recycle diagram. It can be unidirectional or bidirectional

Yes, that's exactly what I meant.

It could be a visual extension of donut style diagram; I'm not sure if it's the case.

In short it should have the following features: 1. Must contain at least 2 Nodes 2. Arrows can be uni/bi-directional 3. Arrow body must be circular in shape 4. Nodes must be arranged in a circular fashion

With my limited editing skills, I've tried to create a sample diagram by hand for better clarification.

Let me know, if you require any further clarification.

Circular diagram showing data flow from Left to Right.

[nirname]

@secnigma Glad to hear that, thanks, that is good proposal.

My reasoning on that topic.

1. Must contain at least 2 Nodes

I think it is perfectly fine with only one, it does not have to contain 2 or more nodes only, it can easily be a graphical representation of something completely recycled like "plastic becomes plastic" or "energy becomes energy" doing full circle

3. Arrow body must be circular in shape
4. Nodes must be arranged in a circular fashion

No doubts on that

2. Arrows can be uni/bi-directional

That is for sure, but for some cases we could have like 2 arrows instead of a bidirectional one, how to handle it?

---

On top of that:

• Can a node can have a value to represent a part of a circle alike a pie or donut chart?
• How to position the beginning of the chart? Say, I want a specific node to be tilted 23.5, like the Earth axis, saying it is "North"
• In that case how bidirectional arrows should look like?
• Title of the diagram could be in the middle or in more standard way at the top or bottom
• How to print the labels (curved or straight)
• Should it always be 100% full circle or is there some exceptions? May be it is like gauge bar from 0 to 180 degrees with several zones?
• Do we need a legend?

And the last but not the least:

• Any syntax propositions?

[secnigma]

I've tried my best to come up with some answers to your queries. Please let me know if you require further clarifications or if I misread any of your questions @nirname

Question: 1

I think it is perfectly fine with only one, it does not have to contain 2 or more nodes only, it can easily be a graphical representation of something completely recycled like "plastic becomes plastic" or "energy becomes energy" doing full circle

Yes, that seems to be logical.

Question: 2

Can a node can have a value to represent a part of a circle alike a pie or donut chart?

If I understood your question correctly, then this is not required. Circular Graphs are there just to represent flow between nodes and associating a part of circle with a value is not needed.

Question: 3

Question: 3.1

How to position the beginning of the chart?

The first node should be at the top with center aligned. If there are only 2 nodes, then first node should be at the top and the second should be at the bottom.

The other nodes should be placed to left/right of a node in a circular fashion, according to the direction of the arrow by prioritizing the order in which a node is added.

A sample syntax, as well as explanation for the idea of this direction and order of node placement is mentioned at the bottom of this comment. (Question: 9)

Question: 3.2

Say, I want a specific node to be tilted 23.5, like the Earth axis, saying it is "North"

I believe tilting is not required in circular flow diagrams, but if a node have to be tilted, then it should look like this.

A sample syntax for this graph is given at the bottom.

Question: 4

In that case how bidirectional arrows should look like?

Probably something like this:

Question: 5

Title of the diagram could be in the middle or in more standard way at the top or bottom

From what I've seen in most circle diagrams, this is correct. Title could be placed in any one of the mentioned positions.

Question: 6

How to print the labels (curved or straight)

This is a bit tricky as I've seen both styles of labels.

In my understanding, If the node count is <=4, and the label isn't too long, then Circular style labels could work. Something like this: Source

But most of the times, a straight label would be sufficient. Example: Source

However, there are also cases where the label can be placed outside of the edge (arrow body) Example: Source

Question: 7

Should it always be 100% full circle or is there some exceptions? May be it is like gauge bar from 0 to 180 degrees with several zones?

This sounds something like a semi-circle diagram. But semi-circle diagrams are usually used to represent some form of arcs, rather than cycles like Circular flow diagram. This idea wasn't intended in the proposed circle diagram and it seems like a subset of Circular flow diagram.

But, I believe a semi-circle diagram could theoretically share most of the logic/syntax of a circular flow diagram.

So, I'm not entirely sure if it should come under Circular flow diagram or it should be added as a separate diagram. It's a judgement call.

Question: 8

Do we need a legend?

It would a nice to have feature. But this feature wasn't intended in the original proposal.

Question: 9

Any syntax propositions?

Here's my try on mermaid sytnax for Circular flow diagram:

We have the following things in a circular flow diagram.

• Nodes
• Edges (Arrow body) that connects Nodes
• Direction
• Order of Node

The order of nodes placed is dependent on the graph's direction (Left-Right or Right-Left) and the order in which a node is declared.

For example, in the below diagram, the graph have Left-Right direction.

To generate such graph, a syntax similar to this can be used.

graph circular;
    direction LR;
    A;
    D;
    C;
    B;

Why direction as a separate thing?

Because circular diagrams are almost always directional.

By separating the direction, we don't have to explicitly specify relation between nodes like this

A--->B

Instead, we can focus on the direction and the order of nodes and mermaid should automatically add a circular diagram.

Example:

graph circular;
direction LR;
A;
B;

---

Note: If a circular graph doesn't specify a direction, then it should be directionless. Means, it should look like this

Example:

graph circular;
A;
B;
C;
D;

Example images with proposed syntax

Circular flow diagram with Left-Right direction

From the above example image I've provided, the syntax could look like the following

graph circular;
   direction LR;
   A;
   D;
   C;
   B;

Notice that I have only declared nodes and specified an arrow direction. Since this is a circular flow diagram, we only needs to specify the nodes and mermaid should automatically arrange the nodes in a circular fashion.

And since I've specified the direction, mermaid should point the arrows in the specified direction. Here, I've used Left to Right direction.

Note: Explict directions are still useful, since it can be used to specify bi-directional relationship between nodes. Example for this syntax is given in the below image .

Circular flow diagram with Right-Left direction, along with a custom arrow

graph circular;
   direction RL;
   A;
   B;
   C;
   D;
   A-->D;

Edit: Corrected syntax for clarification.

Here, we have an extra arrow from A-->D , denoting that in addition to the Right-Left direction of the graph, there's an extra relation between A and D.

[nirname]

@secnigma Great job! Thank you!

Initial position or graph rotation

My fault, when I was taking about "tilting" node I was wrong, I meant what if I need the whole graph to be rotated? The question what is the position of the first node? You suggested this to be at the top. Should we be able to configure it?

In some cases values could be needed too

This is just an image, but the main idea is "ordered proportion"

Sleep 8 hours -> Morning Routine 1 hour -> Work 8 hours -> Having fun 7 hours

May be this is not a value of the node, but a value of the flow. Thus nodes could have their own position on the dial, so we could start our "daily routine example" at 8 AM on the circular graph. And the value of that flow could be represented by the length or arc (part of the circle).

(My apologies if my idea is out of the boundaries, I am trying restrain myself from switching to some other more complex examples, like XY in polar coordinates.)

Direction absence is a direction too

In case direction would be a configuration option also (not only in the syntax), if one wants a particular diagram to be directionless he should be able to override it

Global config:

mermaid.initialize({
  theme: 'default',
  circular: {
    radius: 300,
    direction: 'CW',
  },
});

Diagram

circular NONE
A -> B -> C

Direction names

I would prefer clockwise CW and counterclockwise CCW, instead of LR or RL because it can be controversial. It could also be POSTITVE or +, which would equal to CCW because math says so or NEGATIVE or - which would equal to CW, thus:

• CW, default, alias NEGATIVE or -
• CCW, alias POSITIVE, +
• NONE, means directionless

Using CW seems like the most natural option

Labels and styling

Obviously we need

• labels for nodes
• labels for edges
• display style for edges (thin or thick)
• display style for nodes (or even hide them in some cases)

Judging by your examples we also need

• separate labels for forward and backward flows, sometimes it is like 2 rings of them

Chords

There is a different type of diagrams called chords, but this is not about them. Syntax does not limit user from doing this:

circular
A
B
C
D

A --> C 
D --> D

Should we allow to draw chords?

[nirname]

@secnigma Have you ever considered making a contribution?

[damascene]

Having circular flow diagram is important. hopefully someone will pick this up. I think basic fix could be done by having some css.

currently this:

flowchart LR
   a --> b 
   b --> d
   d --> c
   c --> a

Produces:

Which isn't very bad but could be fixed in CSS to avoid the long empty line at the bottom?

[nirname]

@damascene I think this is only a temporary workaround