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 two 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.

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).

## Installation
First, clone this repository, and then simply run

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

This compiles the two programs as `SOCgen` and `SOCadmissible`.

## 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.
```

### Example
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 (found=6 at rate 64.00 graphs/s in 0 seconds)
Found 6 SOCs at rate 64.00 graphs/s 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 (verification rate 6.00 graphs/s in 0 seconds; current line 6)
These graphs are admissible
```

The SOCs generated can easily be displayed with Mathematica using the following:
```
SOCs = DirectedGraph[AdjacencyGraph[#]] & /@ ToExpression[Import["./3.soc", "List"]];
SOCs = DeleteDuplicatesBy[SOCs, CanonicalGraph];
SOCs
```

## 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](./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)