README

README.md

@@ -1,6 +1,96 @@
-# ABP server for VR
+# Graph state server
+[Graph states](https://en.wikipedia.org/wiki/Graph_state) are a way of efficiently representing the state of a system of qubits. This tool simulates the behaviour of the graph state and shows an interactive 3D representation of the state. Interaction with the simulation is done either by clicking on things in the web browser or through an API.
 
-Google Docs for graph states.
+## Using the interface
+The state is initialized as a blank canvas without any qubits.
 
-Served here: [https://abv.peteshadbolt.co.uk/](https://abv.peteshadbolt.co.uk/).
+- Click on the grid to make a new qubit
+- Hold <kbd>Ctrl</kbd> and click on a qubit to act a Hadamard gate
+- Click on a qubit to view its properties
+- Select a qubit, then <kbd>Shift</kbd>-click another node to act a CZ gate
+- Press <kbd>Space</kbd> to rotate the grid
+- Use the up and down arrow keys to move the grid normal to its plane
+- Press <kbd>C</kbd> to toggle curved edges
+
+Arbitrary 3D structures can be constructed by rotating the grid.
+
+The URL contains a unique ID such as `1ed6cc3c-65e4-4f6a-ab14-5e8c01d4593b`. You can share this URL with other people to share your screen and edit collaboratively.
+
+## Python package
+The underlying graph state simulator is based on Anders' and Briegel's method. Full docs for the Python package are [here](https://peteshadbolt.co.uk/static/abp/). You can install it like this:
+
+    :::bash
+    $ pip install abp
+
+
+## API
+
+Here's a complete example of sending a state from Python to the server:
+
+    :::python
+    import abp
+    
+    # Make a new graph and automatically position the nodes
+    g = abp.NXGraphState(range(10))
+    g.layout()
+    
+    # Post to the server
+    g.push()
+
+### Endpoints
+
+- `/<uuid>`: Displays the state using Three.js
+- `/<uuid>/graph`:
+    - `GET` returns JSON representing the state
+    - `POST` accepts JSON in the same format and overwrites the state in memory
+- `/<uuid>/edit`:
+    - `POST` accepts edit commands such as `cz`, `add_node` etc.
+- `doc/`: Shows this page
+
+
+### Data format
+
+An HTTP GET to `/<uuid>/graph` will return some JSON.
+
+    $ curl https://abv.peteshadbolt.co.uk/<uuid>/graph
+    {
+      "adj": {
+        "(0, 0, 1)": {
+          "(0, 1, 1)": {}, 
+          "(1, 0, 1)": {}
+        }, 
+        "(0, 0, 3)": {
+          "(0, 1, 3)": {}, 
+          "(1, 0, 3)": {}
+        }, 
+        "(0, 0, 5)": {
+          "(0, 1, 5)": {}, 
+          "(1, 0, 5)": {}
+        }, 
+        "(0, 1, 0)": {
+          "(0, 1, 1)": {}, 
+          "(1, 1, 0)": {}
+        }, 
+        "(0, 1, 1)": {
+          "(0, 0, 1)": {},
+    ...
+
+The top-level keys are `node` and `adj`. These model the node metadata and adjacency matrix respectively.
+
+Each `node` has 
+
+- a `position` (`{x:<> y:<> z:<>}`) 
+- a `vop` (integer, ignore for now) 
+- and could also have a `color`, `label`, etc.
+
+`adj` uses the same data structure as `networkx` to efficiently represent sparse adjacency matrices. For each key `i` in `adj`, the value of `adj[i]` is itself a map whose keys `j` correspond to the ids of nodes connected to `i`. The value of `adj[i][j]` is a map which is usually empty but which could be used to store metadata about the edge.
+
+Here's an example of a graph `(A-B C)`:
+
+    :::python
+    {'adj': {0: {1: {}}, 1: {0: {}}, 2: {}},
+     'node': {
+      0: {'position': {'x': 0, 'y': 0, 'z': 0}, 'vop': 0},
+      1: {'position': {'x': 1, 'y': 0, 'z': 0}, 'vop': 0},
+      2: {'position': {'x': 2, 'y': 0, 'z': 0}, 'vop': 10}}}