SOC-Observation-Code/README.md

<!--
SPDX-FileCopyrightText: 2023 Ämin Baumeler <amin@indyfac.ch> and Eleftherios-Ermis Tselentis <eleftheriosermis.tselentis@oeaw.ac.at>

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 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 the last, `SOCgraphviz`, to translate adjancency matrices into the [Graphviz language](https://graphviz.org/).

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

```
$ cd soc-observation-code/
$ make
```

This compiles the programs `SOCgen`, `SOCadmissible`, and `SOCgraphviz`.

## Usage
To display help and exit, run the respective program without command-line arguments.

### SOCgen
```
$ ./SOCgen 
Usage: ./SOCgen -n <order> [-r <num> ] [FILTER ...]
       -n <order>     Generate SOCs with `order' connected nodes
       -r <num>       Pick directed graphs at random, and exit after having found `num' SOCs

[FILTER]              Consider only simple directed graphs ...
       -c             ... that are cyclic (i.e., not DAGs)
       --no-sink      ... without sink nodes (this logically implies -c)
       --no-source    ... without source nodes (also this logically implies -c)

This program prints the found SOCs as adjacency matrices to stdout.
To exclude (some) of the isomorphic SOCs, it uses a degree-order filter.
```

### SOCadmissible
```
$ ./SOCadmissible 
Usage: ./SOCadmissible <filename> [<startline> [<endline> | +<count>]]
       <filename>     File name with adjacency matrices of simple directed graphs
       <startline>    Verify graphs starting from line `startline'
       <endline>      Verify graphs up to and including line `endline'
       +<count>       Verify `count' number of 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 verifies the admissibility of simple directed graphs.
```

### 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
Generating SOCs with 3 nodes
100.00%    64/64 (6 SOCs found, 0 seconds, 64.00 graphs/s,  6.00 SOCs/s, 0.00h estimated time left)
Found 6 SOCs in 0 seconds
```
The admissibility of these graphs can then be checked by running:
```
$ ./SOCadmissible 3.soc 
Verifying the admissibility of 6 graphs in the file `3.soc' (line 1 to line 6)
100.00%    6/6 (6.00 graphs/s in 0 seconds; current line 6)
These graphs are admissible
```

The SOCs generated can easily be displayed with the [Graphviz](https://graphviz.org/) tools:
```
./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.
Since we consider simple directed graphs only (no self-loops), there are `n(n-1)` possible directed edges, where `n` is the number of nodes.
This means that the largest number of nodes possible is limited by `n=8`.

While the SOCs generated by `SOCgen` satisfy some degree-order (see function `isdegreeordered(...)` in [SOCgen.c](./src/SOCgen.c)), `SOCgen` does not perform graph-isomorphism tests, and may output multiple isomorphic graphs.

## License
[GPL-3.0-or-later](./LICENSES/GPL-3.0-or-later.txt)