Extended README.md and added example.png to introduce the graphviz tool

README.md

@@ -7,12 +7,13 @@ SPDX-License-Identifier: GPL-3.0-or-later
 # SOC Observation Code
 
 ## Description
-SOC stands for **S**OC **O**bservation **C**ode, and is composed of two C programs:
+SOC stands for **S**OC **O**bservation **C**ode, and is composed of three C programs:
 
 - One, `SOCgen`, to generate SOC graphs (here, SOC stands for Siblings-on-Cycles),
-- and another, `SOCadmissible`, to verify the admissibility of these graphs as quantum causal structures.
+- and another, `SOCadmissible`, to verify the admissibility of these graphs as quantum causal structures,
+- and the last, `SOCgraphviz`, to translate adjancency matrices into the [Graphviz language](https://graphviz.org/).
 
-These programs are used in support of Conjecture 1 in the article [Admissible Causal Structures and Correlations, arXiv:2210.12796 \[quant-ph\]](https://arxiv.org/abs/2210.12796).
+The first two programs are used in support of Conjecture 1 in the article [Admissible Causal Structures and Correlations, arXiv:2210.12796 \[quant-ph\]](https://arxiv.org/abs/2210.12796).
 
 ## Installation
 First, clone this repository, and then simply run
@@ -22,7 +23,7 @@ $ cd soc-observation-code/
 $ make
 ```
 
-This compiles the two programs as `SOCgen` and `SOCadmissible`.
+This compiles the programs `SOCgen`, `SOCadmissible`, and `SOCgraphviz`.
 
 ## Usage
 To display help and exit, run the respective program without command-line arguments.
@@ -60,7 +61,21 @@ Usage: ./SOCadmissible <filename> [<startline> [<endline> | +<count>]]
 This program verifies the admissibility of simple directed graphs.
 ```
 
-### Example
+### SOCgraphviz
+```
+$ ./SOCgraphviz
+Usage: ./SOCgraphviz <filename>
+       <filename>     File name with adjacency matrices of simple directed graphs
+
+[FILE FORMAT]
+       Each line in `filename' must contain the adjacency matrix of a simple directed graph in the format
+         {{a00,a01,...},{a10,a11,...},...}  where aij=1 if and only if the graph has the edge i -> j
+       The file `filename' may contain graphs with different order (number of vertices)
+
+This program translates to adjacency matrices into the Graphviz format, and prints them to stdout.
+```
+
+### Examples
 To generate all SOCs with three nodes, and save them in the file `3.soc`, run:
 ```
 $ ./SOCgen -n 3 > 3.soc
@@ -76,13 +91,23 @@ Verifying the admissibility of 6 graphs in the file `3.soc' (line 1 to line 6)
 These graphs are admissible
 ```
 
-The SOCs generated can easily be displayed with Mathematica using the following:
+The SOCs generated can easily be displayed with the [Graphviz](https://graphviz.org/) tools:
 ```
-SOCs = DirectedGraph[AdjacencyGraph[#]] & /@ ToExpression[Import["./3.soc", "List"]];
+./SOCgraphviz 3.soc | dot | gvpack | circo -Nshape=point -Tx11
+```
+or in [Wolfram Mathematica](https://www.wolfram.com/mathematica/) using:
+```
+SOCs = AdjacencyGraph[#] & /@ ToExpression[Import["./3.soc", "List"]];
 SOCs = DeleteDuplicatesBy[SOCs, CanonicalGraph];
 SOCs
 ```
 
+To generate all SOCs with four nodes, and to display them using Graphviz, you may run:
+```
+./SOCgen -n 4 | ./SOCgraphviz /dev/stdin | dot | gvpack | circo -Nshape=point -Tx11
+```
+![All SOCs with four nodes](./example.png "SOCs with four nodes")
+
 ## Limitations
 In `SOCgen`, each simple directed graph is represented by a 64bit unsigned integer:
 This integer is interpreted as a vector of bits, where each bit specifies the absence or presence of a directed edge from one node to another.