Platform specific Readme

.github/workflows/readme.yml

@@ -0,0 +1,17 @@
+on:
+  pull_request:
+    types: [opened, ready_for_review]
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v5
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'If you are changing the configuration of one or more platforms remember to run `python generate_readme.py path/to/platform ...` to update the `README.md` accordingly.'
+            })

generate_readme.py

@@ -0,0 +1,122 @@
+"""Small script that automatically parses some basic information from the `parameters.json` file and organizes it in a `README.md`"""
+
+import argparse
+import json
+import warnings
+from pathlib import Path
+from typing import Union
+
+
+def get_info(filename: str) -> dict:
+    """Open ``filename`` and extracts: `nqubits`, `qubits`, `topology` and `native_gates`."""
+
+    with open(filename) as f:
+        data = json.load(f)
+
+    if not isinstance(data["topology"], list):
+        raise RuntimeError(
+            f"The topology is expected to be a list of edges (List[List[int, int]] or List[List[str, str]]), but received a {type(data['topology'])}."
+        )
+
+    info = {key: data[key] for key in ("nqubits", "qubits", "topology")}
+    one_q_native_gates = list(
+        next(iter(data["native_gates"]["single_qubit"].values())).keys()
+    )
+    two_q_native_gates = list(
+        next(iter(data["native_gates"]["two_qubit"].values())).keys()
+    )
+    info.update(
+        {
+            "native_gates": {
+                "single_qubit": one_q_native_gates,
+                "two_qubit": two_q_native_gates,
+            }
+        }
+    )
+    return info
+
+
+def create_mermaid_graph(
+    nodes: Union[list[str], list[int]],
+    topology: Union[list[list[str]], list[list[int]]],
+) -> str:
+    """Create a markdown string encoding a mermaid graph given by the input `nodes` and `topology`."""
+    node_to_index = dict(zip(nodes, range(len(nodes))))
+    if isinstance(nodes[0], int) or nodes[0].isdecimal():
+        edges = "\n    ".join(
+            [
+                f"{edge[0]}(({str(edge[0])})) <--> {edge[1]}(({str(edge[1])}));"
+                for edge in topology
+            ]
+        )
+    else:
+        edges = "\n    ".join(
+            [
+                f"{node_to_index[edge[0]]}(({edge[0]})) <--> {node_to_index[edge[1]]}(({edge[1]}));"
+                for edge in topology
+            ]
+        )
+    markdown_str = f"""
+```mermaid
+---
+config:
+layout: elk
+---
+graph TD;
+    {edges}
+```
+"""
+    return markdown_str
+
+
+def create_readme(filename: str) -> str:
+    """Build the `README.md` for the input `filename`."""
+    info = get_info(filename)
+    mermaid_graph = create_mermaid_graph(info["qubits"], info["topology"])
+    qubits = (
+        ", ".join([str(q) for q in info["qubits"]])
+        if isinstance(info["qubits"][0], int) or info["qubits"][0].isdecimal()
+        else ", ".join([f"{q} ({i})" for i, q in enumerate(info["qubits"])])
+    )
+    readme_str = f"""
+## Native Gates
+**Single Qubit**: {", ".join(info["native_gates"]["single_qubit"])}
+
+**Two Qubit**: {", ".join(info["native_gates"]["two_qubit"])}
+
+## Topology
+**Number of qubits**: {info["nqubits"]}
+
+**Qubits**: {qubits}
+{mermaid_graph}
+"""
+    return readme_str
+
+
+if __name__ == "__main__":
+
+    parser = argparse.ArgumentParser(
+        prog="generate_readme",
+        description="Automatically generate the README.md for the given input platform/s.",
+    )
+    parser.add_argument("platform", nargs="+", type=Path)
+    platforms = parser.parse_args().platform
+
+    for platform in platforms:
+
+        filename = platform / "parameters.json"
+        try:
+            readme_str = create_readme(filename)
+        except FileNotFoundError:
+            warnings.warn(
+                f"Couldn't find ``{filename}``, unable to generate the README for platform ``{platform}``."
+            )
+            continue
+        except RuntimeError as err:
+            warnings.warn(
+                err.args[0]
+                + f" Unable to generate the README for platform ``{platform}``."
+            )
+            continue
+
+        (platform / "README.md").write_text(f"# {platform}\n{readme_str}")

qw11q/README.md

@@ -0,0 +1,41 @@
+# qw11q
+
+## Native Gates
+**Single Qubit**: RX, RX12, MZ
+
+**Two Qubit**: CZ, iSWAP
+
+## Topology
+**Number of qubits**: 16
+
+**Qubits**: A1 (0), A2 (1), A3 (2), A4 (3), A5 (4), A6 (5), B1 (6), B2 (7), B3 (8), B4 (9), B5 (10), D1 (11), D2 (12), D3 (13), D4 (14), D5 (15)
+
+```mermaid
+---
+config:
+layout: elk
+---
+graph TD;
+    0((A1)) <--> 1((A2));
+    0((A1)) <--> 2((A3));
+    0((A1)) <--> 15((D5));
+    1((A2)) <--> 3((A4));
+    1((A2)) <--> 5((A6));
+    2((A3)) <--> 3((A4));
+    2((A3)) <--> 14((D4));
+    3((A4)) <--> 4((A5));
+    3((A4)) <--> 8((B3));
+    4((A5)) <--> 6((B1));
+    5((A6)) <--> 8((B3));
+    5((A6)) <--> 13((D3));
+    6((B1)) <--> 7((B2));
+    6((B1)) <--> 8((B3));
+    7((B2)) <--> 9((B4));
+    8((B3)) <--> 9((B4));
+    9((B4)) <--> 10((B5));
+    11((D1)) <--> 12((D2));
+    11((D1)) <--> 13((D3));
+    12((D2)) <--> 14((D4));
+    13((D3)) <--> 14((D4));
+    14((D4)) <--> 15((D5));
+```

qw5q_platinum/README.md

@@ -0,0 +1,23 @@
+# qw5q_platinum
+
+## Native Gates
+**Single Qubit**: RX, RX12, MZ
+
+**Two Qubit**: CZ
+
+## Topology
+**Number of qubits**: 5
+
+**Qubits**: 0, 1, 2, 3, 4
+
+```mermaid
+---
+config:
+layout: elk
+---
+graph TD;
+    0((0)) <--> 2((2));
+    1((1)) <--> 2((2));
+    2((2)) <--> 3((3));
+    2((2)) <--> 4((4));
+```