open-standards/wai/wai-quantum/schemas/compile-result.v1.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://git.transaction.science/Transaction-Science/open-standards/raw/branch/main/wai/wai-quantum/schemas/compile-result.v1.json",
  "title": "wai.quantum.compile-result/1",
  "description": "A compile as a host returns it (the command line's compile --json, both servers' compile_qasm, the job service's POST /v1/compile): the request as given, and the result, which its receipt seals in the form every job's receipt takes. The result holds the compiled program and its certificate (wai.quantum.compile/1): each pass's counts before and after, the digests of the circuit it was given and the circuit it gave, the layer its check stands on and the distance it adds, its check and verdict, the budget and the bound the passes' distances add to (wai/extensions/quantum-compile.md). A result names the engine that made it and this schema (engine and schema); results made before results carried them have neither.",
  "type": "object",
  "required": [
    "request",
    "result"
  ],
  "properties": {
    "request": {
      "type": "object",
      "description": "The program and the compile's options, as given.",
      "required": [
        "qasm"
      ],
      "properties": {
        "qasm": {
          "type": "string"
        },
        "epsilon": {
          "type": "number"
        },
        "level": {
          "type": "integer"
        },
        "basis": {
          "type": "string"
        },
        "equivalence": {
          "type": "boolean",
          "description": "true: the certificate also holds the equivalence checker's verdict on the whole output against the program."
        },
        "stages": {
          "type": "boolean"
        },
        "twirl": {
          "description": "Twirl each two-qubit Clifford gate with Paulis drawn from a seeded stream: true (seed 1), or {\"seed\": N}. One seed is one instance, checked to be the same circuit.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "required": [
                "seed"
              ],
              "properties": {
                "seed": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          ]
        },
        "dd": {
          "description": "Dynamical decoupling in each window where a qubit idles long enough: xx or xy4 (or {\"sequence\": …}), checked to change nothing without noise.",
          "anyOf": [
            {
              "enum": [
                "xx",
                "xy4"
              ]
            },
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "properties": {
                "sequence": {
                  "enum": [
                    "xx",
                    "xy4"
                  ]
                }
              }
            }
          ]
        }
      }
    },
    "result": {
      "$ref": "#/$defs/result"
    }
  },
  "$defs": {
    "options": {
      "type": "object",
      "description": "What a compile is asked for, each optional: the most the output may differ from the program (epsilon, in the operator norm up to a global phase), the level (0 lowers and approximates; 1 also rewrites and folds phases; 2 also resynthesises), the basis, the gate set it writes the program in (clifford_t: every rotation off the multiples of π/4 a Clifford+T word; standard: nothing approximated; cz, zz or xx: one-qubit gates around a device basis's own two-qubit gate, cz, rzz or rxx at an angle from 0 to π/2, each pair's block around at most three of it), whether to give the circuit after each pass (stages), and the twirl and dd passes, last (twirl, with its seed; dd, with its sequence).",
      "properties": {
        "epsilon": {
          "type": "number",
          "exclusiveMinimum": 0
        },
        "level": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2
        },
        "basis": {
          "enum": [
            "clifford_t",
            "standard",
            "cz",
            "zz",
            "xx"
          ]
        },
        "stages": {
          "type": "boolean"
        },
        "twirl": {
          "description": "Twirl each two-qubit Clifford gate with Paulis drawn from a seeded stream: true (seed 1), or {\"seed\": N}. One seed is one instance, checked to be the same circuit.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "required": [
                "seed"
              ],
              "properties": {
                "seed": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          ]
        },
        "dd": {
          "description": "Dynamical decoupling in each window where a qubit idles long enough: xx or xy4 (or {\"sequence\": …}), checked to change nothing without noise.",
          "anyOf": [
            {
              "enum": [
                "xx",
                "xy4"
              ]
            },
            {
              "type": "boolean"
            },
            {
              "type": "object",
              "properties": {
                "sequence": {
                  "enum": [
                    "xx",
                    "xy4"
                  ]
                }
              }
            }
          ]
        }
      }
    },
    "counts": {
      "type": "object",
      "description": "A circuit's counts, as the compiler counts them.",
      "properties": {
        "gates": {
          "type": "integer",
          "minimum": 0
        },
        "one_qubit": {
          "type": "integer",
          "minimum": 0
        },
        "two_qubit": {
          "type": "integer",
          "minimum": 0
        },
        "three_qubit": {
          "type": "integer",
          "minimum": 0
        },
        "cnots": {
          "type": "integer",
          "minimum": 0
        },
        "t_count": {
          "type": "integer",
          "minimum": 0
        },
        "rotations": {
          "type": "integer",
          "minimum": 0
        },
        "depth": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "result": {
      "type": "object",
      "required": [
        "ok",
        "options",
        "qasm",
        "certificate"
      ],
      "properties": {
        "engine": {
          "type": "object",
          "description": "The engine that made the result: the wai-quantum crate's name and version.",
          "required": [
            "name",
            "version"
          ],
          "properties": {
            "name": {
              "const": "wai-quantum"
            },
            "version": {
              "type": "string"
            }
          }
        },
        "schema": {
          "const": "wai.quantum.compile-result/1"
        },
        "ok": {
          "const": true
        },
        "options": {
          "type": "object",
          "description": "The options the compile ran with, the defaults filled in.",
          "required": [
            "epsilon",
            "level",
            "basis"
          ],
          "properties": {
            "epsilon": {
              "type": "number"
            },
            "level": {
              "type": "integer"
            },
            "basis": {
              "enum": [
                "clifford_t",
                "standard"
              ]
            },
            "twirl": {
              "type": "object",
              "properties": {
                "seed": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "description": "The twirl pass's seed."
            },
            "dd": {
              "enum": [
                "xx",
                "xy4"
              ],
              "description": "The decoupling pass's sequence."
            }
          }
        },
        "qasm": {
          "type": "string",
          "description": "The compiled program, as OpenQASM 3."
        },
        "certificate": {
          "$ref": "#/$defs/certificate"
        },
        "stages": {
          "type": "array",
          "description": "With stages: the circuit after each pass.",
          "items": {
            "type": "object",
            "required": [
              "pass",
              "qasm"
            ],
            "properties": {
              "pass": {
                "type": "string"
              },
              "qasm": {
                "type": "string"
              }
            }
          }
        },
        "receipt": {
          "$ref": "receipt.v2.json"
        },
        "components": {
          "type": "array",
          "description": "The identity of every component that made the compile, when a registered pass took part (engine::registry): the program's format and each pass, each registered one marked so.",
          "items": {
            "$ref": "#/$defs/component"
          }
        }
      }
    },
    "certificate": {
      "type": "object",
      "description": "What the compile did and how each step was checked. Hashes are BLAKE3, in hex, of the program as read (written out as OpenQASM 3) and of the output text.",
      "required": [
        "format",
        "basis",
        "level",
        "source",
        "output",
        "epsilon",
        "passes",
        "verdict"
      ],
      "properties": {
        "format": {
          "const": "wai.quantum.compile/1"
        },
        "basis": {
          "enum": [
            "clifford_t",
            "standard",
            "cz",
            "zz",
            "xx"
          ]
        },
        "level": {
          "type": "integer"
        },
        "source": {
          "type": "object",
          "properties": {
            "hash": {
              "type": "string"
            },
            "qubits": {
              "type": "integer"
            },
            "counts": {
              "$ref": "#/$defs/counts"
            }
          }
        },
        "output": {
          "type": "object",
          "properties": {
            "hash": {
              "type": "string"
            },
            "counts": {
              "$ref": "#/$defs/counts"
            }
          }
        },
        "epsilon": {
          "type": "object",
          "description": "The budget, the bound the passes' distances add to, and how the budget was shared among the rotations.",
          "properties": {
            "budget": {
              "type": "number"
            },
            "bound": {
              "type": "number"
            },
            "rotations": {
              "type": "integer"
            },
            "each": {
              "type": "number"
            }
          }
        },
        "passes": {
          "type": "array",
          "description": "Each pass: its name, the digests of the circuit it was given (input) and the circuit it gave (output), the layer its check stands on, the distance it adds (bound), the counts before and after, and its check (how, the verdict, and its distance where it has one). One pass's output is the next one's input: the first input is source.hash and the last output is output.hash. A certificate sealed before certificates carried them has no input, output, layer or bound.",
          "items": {
            "type": "object",
            "required": [
              "pass",
              "check"
            ],
            "properties": {
              "pass": {
                "type": "string"
              },
              "input": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "The BLAKE3 of the circuit the pass was given, written out as OpenQASM 3."
              },
              "output": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "The BLAKE3 of the circuit the pass gave: its input when the pass was not applied."
              },
              "layer": {
                "enum": [
                  "unchecked",
                  "bounded",
                  "exact_simulation",
                  "exact_arithmetic",
                  "stabilizer"
                ],
                "description": "The layer the pass's check stands on: unchecked (skipped, or its check did not hold and it was left out), bounded (within the distance bound), exact_simulation (compared in double precision), exact_arithmetic (an identity in integers) or stabilizer (equal tableaus)."
              },
              "bound": {
                "type": "number",
                "minimum": 0,
                "description": "The distance the pass adds to epsilon.bound: 0 for a pass checked by exact_arithmetic or stabilizer, or not applied."
              },
              "before": {
                "$ref": "#/$defs/counts"
              },
              "after": {
                "$ref": "#/$defs/counts"
              },
              "check": {
                "type": "object"
              },
              "component": {
                "$ref": "#/$defs/component",
                "description": "Beside a registered pass's record: its identity. Its check is the engine's, on the whole circuit (by: engine)."
              }
            }
          }
        },
        "rotations": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Each rotation written as a Clifford+T word: its angle, its T count, its distance."
        },
        "whole": {
          "type": "object",
          "description": "The check of the whole output against the whole program: how, its verdict, its layer (the certificate's layer), and the distance where it measures one."
        },
        "verdict": {
          "type": "string",
          "description": "proof, exact or approximate."
        },
        "layer": {
          "enum": [
            "pass_equivalence",
            "exact_simulation",
            "exact_arithmetic",
            "stabilizer"
          ],
          "description": "The strongest check the whole output passed against the whole program: stabilizer (equal tableaus), exact_arithmetic (proportional over Z[ω]/√2ᵏ), exact_simulation (their dense unitaries, up to 8 qubits) or pass_equivalence (the passes' own checks, composed)."
        },
        "weakest": {
          "enum": [
            "unchecked",
            "bounded",
            "exact_simulation",
            "exact_arithmetic",
            "stabilizer",
            null
          ],
          "description": "The weakest layer among the passes that were applied; null when none was."
        },
        "reading": {
          "type": "string",
          "description": "What the certificate says of the output, in words."
        },
        "equivalence": {
          "type": "object",
          "description": "When the request asks for it: the equivalence checker's verdict on the whole output against the whole program (verdict proved, refuted with a counterexample, or undecided within its stated budget; the notion, the statement, each route's finding, the wires and the budget). A compile that approximates claims its bound, not equality, and its verdict is undecided, saying so.",
          "required": ["verdict", "notion", "statement", "why"],
          "properties": {
              "version": {
                "type": "integer",
                "description": "The verdict's form: 1."
              },
              "notion": {
                "enum": [
                  "unitary",
                  "measured"
                ],
                "description": "unitary: one unitary up to a global phase; measured: up to phases on the computational basis just before the final measurements."
              },
              "statement": {
                "type": "string",
                "description": "The statement decided, in words."
              },
              "verdict": {
                "enum": [
                  "proved",
                  "refuted",
                  "undecided"
                ]
              },
              "why": {
                "type": "string",
                "description": "How it was decided, or why no route decided it."
              },
              "proved_by": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The routes that proved it: decision_diagram, zx."
              },
              "refuted_by": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The routes that refuted it: stimuli, decision_diagram, zx, shape."
              },
              "arithmetic": {
                "enum": [
                  "exact",
                  "tolerance"
                ],
                "description": "Of a proof: exact (integers in a cyclotomic field, or exact phases), or doubles within tolerance."
              },
              "tolerance": {
                "type": "number",
                "description": "With arithmetic tolerance: within what two doubles were taken equal."
              },
              "global_phase": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "The phase the decision diagram found, as [re, im]."
              },
              "counterexample": {
                "type": "object",
                "description": "Of a refutation: what shows it (found_by: stimuli, decision_diagram, zx or shape), with an input and the outcomes that differ, entries of the miter's matrix, or wires that cross."
              },
              "routes": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "description": "Each route's finding: stimuli, decision_diagram, zx, with its outcome and its counts."
              },
              "wires": {
                "type": "object",
                "description": "The miter's wires: the logical qubits, the physical qubits used, the layout, the ancillas and the closing exchanges."
              },
              "gates": {
                "type": "object",
                "description": "Primitive gates of the source and of the compiled program."
              },
              "budget": {
                "type": "object",
                "description": "The counts each route might spend (no clock): stimuli, state_vector_qubits, diagram_nodes, diagram_steps, zx_rewrites, exact_bits, seed."
              },
              "residual": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "description": "The Z rotations the compiled program leaves unapplied before its measurements, each a physical qubit and m/2^k of a turn, which the statement takes in."
              },
              "residual_is": {
                "type": "string"
              },
              "final_layout_from": {
                "type": "string",
                "description": "Where each logical qubit's end was read from, when it was read from the measurements."
              },
              "final_layout": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            }
        },
        "guard": {
          "type": "object",
          "description": "At a level above 0: the program compiled at this level and at each level below it under the same options, and the output kept, the one with the fewest of the objective's counts compared in order (the highest level's of those that tie), so a level never gives a worse output than a lower one. The passes, the bound and the whole check are the kept compile's. Certificates sealed before the guard have none.",
          "required": [
            "objective",
            "candidates",
            "kept"
          ],
          "properties": {
            "how": {
              "type": "string"
            },
            "objective": {
              "type": "array",
              "items": {
                "enum": [
                  "t_count",
                  "cnots",
                  "two_qubit",
                  "gates"
                ]
              },
              "description": "The counts compared, in order, fewer first: t_count, cnots, gates for clifford_t; cnots, gates for standard; two_qubit, gates for cz, zz and xx."
            },
            "candidates": {
              "type": "array",
              "description": "The certificate's level and each level below it, highest first: the output's digest and its counts on the objective, or why that level refused the program.",
              "items": {
                "type": "object",
                "required": [
                  "level"
                ],
                "properties": {
                  "level": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "output": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$"
                  },
                  "counts": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "integer",
                      "minimum": 0
                    }
                  },
                  "refused": {
                    "type": "string"
                  }
                }
              }
            },
            "kept": {
              "type": "integer",
              "minimum": 0,
              "description": "The level whose output this is."
            }
          }
        }
      }
    },
    "component": {
      "type": "object",
      "description": "One component that made the result (engine::registry): its kind, name and version, the BLAKE3 digest of its descriptor, and whether it is built in. A result carries these only when a registered component took part; one made by built-ins alone names them as it always has (its method, its compile's passes, its noise's channels and the engine's version), the digests of that version listed by the components list.",
      "required": [
        "kind",
        "name",
        "version",
        "digest",
        "origin"
      ],
      "properties": {
        "kind": {
          "enum": [
            "method",
            "pass",
            "channel",
            "front_end"
          ]
        },
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "digest": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "BLAKE3 of the component's descriptor in its canonical JSON (engine::registry::digest_of)."
        },
        "origin": {
          "enum": [
            "built-in",
            "registered"
          ],
          "description": "built-in: the engine's own; registered: a host's own, added in its process, not part of the engine."
        },
        "certified": {
          "const": false,
          "description": "Beside a registered component: the engine does not certify it."
        }
      }
    }
  }
}