Improve documentation for plotting and graph generation

pc2 · Mar 10, 2023 · 91bd56f · 91bd56f
1 parent 8e8f680
commit 91bd56f
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 4 deletions.
diff --git a/docs/src/refs/api.md b/docs/src/refs/api.md
@@ -10,5 +10,5 @@ Order   = [:function, :type]
 ## References
 ```@autodocs
 Modules = [MPITape]
-Pages   = ["api.jl", "printing.jl", "fileio.jl"]
+Pages   = ["api.jl", "printing.jl", "fileio.jl", "plotting.jl", "communication_graph.jl"]
 ```
diff --git a/src/communication_graph.jl b/src/communication_graph.jl
@@ -50,7 +50,14 @@ end
 """
 $(SIGNATURES)
 Generates the edges of a directed communication graph, where the edges represent 
-communication between two MPIEvents.
+communication between two `MPIEvent`s.
+
+The method returns an Array of `Tuple{MPIEvent, MPIEvent}`. Every tuple directed edge between MPI calls that exchanged data.
+In consequence, a MPI_Send call and its matching MPI_Recv call will result in a single edge in the graph whereas a MPI_Bcast
+over `n` ranks will lead to `n - 1` edges since the root will exchange data with all other ranks.
+
+The methods checks for completeness of the created graph and throws an error, if not all MPI calls can be matched.
+Setting `check = false` will skip these tests.
 """
 function get_edges(tape::Array{MPIEvent}; check = true)
     # Data structure containing communication edges

diff --git a/src/plotting.jl b/src/plotting.jl
@@ -18,7 +18,9 @@ end
 """
 $(SIGNATURES)
 Plots a gantt chart of the recorded MPI API calls and store it to a file.
-Additionally draws arrows between communicating MPIEvents.
+Additionally draws arrows between communicating `MPIEvent`s.
+
+
 """
 function plot_merged(tape::Array{MPIEvent}; palette = palette(:Accent_8),
                      fname = "gantt.png")
@@ -50,7 +52,39 @@ end
 
 """
 $(SIGNATURES)
-Plot a sequence diagram of the communication between ranks.
+Plot a sequence diagram of the communication between ranks using the communication graph created by `get_edges`.
+
+Creates a plot of the following form using Kroki.jl:
+
+┌──────┐          ┌──────┐          ┌──────┐          ┌──────┐          ┌──────┐
+│Rank_0│          │Rank_1│          │Rank_2│          │Rank_3│          │Rank_4│
+└──┬───┘          └──┬───┘          └──┬───┘          └──┬───┘          └──┬───┘
+   │     MPI_Send    │                 │                 │                 │    
+   │ ────────────────>                 │                 │                 │    
+   │                 │                 │                 │                 │      
+   │              MPI_Send             │                 │                 │    
+   │ ──────────────────────────────────>                 │                 │    
+   │                 │                 │                 │                 │    
+   │                 │     MPI_Send    │                 │                 │    
+   │ ────────────────────────────────────────────────────>                 │                
+   │                 │                 │                 │                 │    
+   │                 │              MPI_Send             │                 │    
+   │ ──────────────────────────────────────────────────────────────────────>       
+   │                 │                 │                 │                 │    
+   │     MPI_Send    │                 │                 │                 │    
+   │ <────────────────                 │                 │                 │    
+   │                 │                 │                 │                 │    
+   │              MPI_Send             │                 │                 │    
+   │ <──────────────────────────────────                 │                 │    
+   │                 │                 │                 │                 │    
+   │                 │     MPI_Send    │                 │                 │    
+   │ <────────────────────────────────────────────────────                 │    
+   │                 │                 │                 │                 │    
+   │                 │              MPI_Send             │                 │    
+   │ <──────────────────────────────────────────────────────────────────────    
+┌──┴───┐          ┌──┴───┐          ┌──┴───┐          ┌──┴───┐          ┌──┴───┐
+│Rank_0│          │Rank_1│          │Rank_2│          │Rank_3│          │Rank_4│
+└──────┘          └──────┘          └──────┘          └──────┘          └──────┘
 """
 function plot_sequence_merged(tape)
     edges = get_edges(tape)