abv/templates/doc.md

# ABP server

This server does a few things:

- Keeps a graph state in memory using a data structure that is compatible with `abp`
- Serves a JSON representation of that object 
- Accepts updates to that object via POST requests 
- Displays a 3D representation of the state 
- Randomly updates the state every five seconds

## Using the interface
Sessions are identified by a UUID such as `oranges-arkansas-mexico-fish`. You can share this URL with other people to share your screen and edit collaboratively.

- Click on the grid to make a new node
- Ctrl-click a node to act a Hadamard gate
- Select a node, then shift-click another node to act a CZ gate
- Press space to rotate the grid

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


## API

We expose an API so that you can programmatically read and write states to/from the server and simulate mouse clicks.

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

If you do an HTTPS GET against `/<uuid>/graph`, you will receive some JSON.

    :::bash
    $ curl https://abv.peteshadbolt.co.uk/<uuid>/graph

outputs

    :::python
    {"node": 
        {"30": 
            {"position": 
                {"y": 3.245091885135617, "x": -1.0335390368621762, "z": 0.12485495696298532}, "vop": 0}, "28": 
            {"position": 
                {"y": 0.1811335599620998, "x": 3.7102305790943295, "z": 0.3375519427305571}, "vop": 0}, "29": 
            {"position": 
                {"y": -1.834182888403804, "x": 1.5968911365745622, "z": 2.8585980299131886 
    ...

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}}}