mermaid/docs/layouts/ipsepcola/overview.md

Warning

THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

Please edit the corresponding file in /packages/mermaid/src/docs/layouts/ipsepcola/overview.md.

IPSEPCOLA Documentation :

IPSep-CoLa: An Incremental Procedure for Separation Constraint Layout of Graphs

Introduction :

IPSep-CoLa (Incremental Procedure for Separation Constraint Layout) is an advanced graph layout algorithm designed to handle complex diagrams with separation constraints, such as grouped nodes, edge labels, and hierarchical structures. Unlike traditional force-directed algorithms, IPSep-CoLa incrementally refines node positions while enforcing geometric constraints to prevent overlaps, maintain group cohesion, and optimize edge routing.

The algorithm is particularly effective for visualizing nested and clustered graphs, where maintaining clear separation between elements is crucial. It combines techniques from force-directed layout, constraint satisfaction, and incremental refinement to produce readable and aesthetically pleasing diagrams.

How IPSep-CoLa Works :

IPSep-CoLa follows a multi-stage process to compute a well-structured layout:

1. Graph Preprocessing : Cycle Removal: Detects and temporarily removes cyclic dependencies to enable proper layering. Layer Assignment: Assigns nodes to hierarchical layers using topological sorting. Node Ordering: Uses the barycenter heuristic to minimize edge crossings within layers.

2. Force-Directed Simulation with Constraints : Spring Forces: Attracts connected nodes to maintain desired edge lengths. Repulsion Forces: Pushes nodes apart to prevent overlaps. Group Constraints: Ensures child nodes stay near their parent groups. Cooling Factor: Gradually reduces movement to stabilize the layout.

3. Incremental Refinement : Overlap Resolution: Iteratively adjusts node positions to eliminate overlaps. Edge Routing: Computes smooth paths for edges, including curved paths for parallel edges and self-loops. Group Boundary Adjustment: Dynamically resizes group containers to fit nested elements.

Key Features :

1. Group-Aware Layout: Maintains separation between nested structures.
2. Edge Label Placement: Uses edge labels as virtual nodes and automatically positions labels inside their parent groups.
3. Stable Convergence: Uses cooling factors and incremental updates for smooth refinement.
4. Support for Self-Loops & Parallel Edges: Avoids visual clutter with intelligent edge routing.

Use Cases :

1. Hierarchical Diagrams (org charts, flowcharts, decision trees)
2. Network Visualization (dependency graphs, data pipelines)
3. Interactive Graph Editors (real-time layout adjustments)
4. Clustered Data Visualization (UML diagrams, biological networks)

Examples

Example 1

---
config:
   layout: ipsepCola
---

flowchart TD
CEO --> MKT["Marketing Head"]
CEO --> ENG["Engineering Head"]
ENG --> DEV["Developer"]
ENG --> QA["QA Tester"]

Example 2

---
config:
   layout: ipsepCola
---

flowchart TD
  Start["Start"] --> Red{"Is it red?"}
  Red -- Yes --> Round{"Is it round?"}
  Red -- No --> NotApple["❌ Not an Apple"]
  Round -- Yes --> Apple["✅ It's an Apple"]
  Round -- No --> NotApple2["❌ Not an Apple"]

Example 3

---
config:
   layout: ipsepCola
---

flowchart TD
A[Module A] --> B[Module B]
A --> C[Module C]
B --> D[Module D]
C --> D
D --> E[Module E]

Example 4

---
config:
   layout: ipsepCola
---

flowchart TD
Source1["📦 Raw Data (CSV)"]
Source2["🌐 API Data"]

Source1 --> Clean["🧹 Clean & Format"]
Source2 --> Clean

Clean --> Transform["🔄 Transform Data"]
Transform --> Load["📥 Load into Data Warehouse"]
Load --> BI["📊 BI Dashboard"]

Example 5

---
config:
   layout: ipsepCola
---
classDiagram
  class Person {
    -String name
    -int age
    +greet(): void
  }

  class Employee {
    -int employeeId
    +calculateSalary(): float
  }

  class Manager {
    -String department
    +assignTask(): void
  }

  Person <|-- Employee
  Employee <|-- Manager

Example 6

---
config:
   layout: ipsepCola
---
flowchart TD
  Sunlight["☀️ Sunlight"] --> Leaf["🌿 Leaf"]
  Leaf --> Glucose["🍬 Glucose"]
  Leaf --> Oxygen["💨 Oxygen"]

Example 7

---
config:
   layout: ipsepCola
---
flowchart TD
  Internet["🌐 Internet"] --> Router["📡 Router"]
  Router --> Server1["🖥️ Server A"]
  Router --> Server2["🖥️ Server B"]
  Router --> Laptop["💻 Laptop"]

  %% New device joins
  Router --> Mobile["📱 Mobile"]

Limitations :

1. Computational Cost: More iterations may be needed for large graphs (>1000 nodes).
2. Parameter Tuning: Requires adjustments for different graph types.
3. Non-Determinism: Small variations may occur between runs due to force simulation.

Conclusion :

IPSep-CoLa provides a robust solution for constraint-based graph layout, particularly for structured and clustered diagrams. By combining incremental refinement with separation constraints, it achieves readable and well-organized visualizations. Future improvements could include GPU acceleration and adaptive parameter tuning for large-scale graphs.