open-standards/wai/wai-quantum-qpu/schemas/provider.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-qpu/schemas/provider.v1.json",
  "title": "wai.quantum.provider/1",
  "description": "The open provider protocol's messages as JSON Schema (wai/extensions/quantum-providers.md): a client's message to a provider (#/$defs/message), the program it carries (#/$defs/program), and the provider's answer to each operation (#/$defs/answer). Fields marked optional may be added to answers without a new protocol version, and a client ignores fields it does not know.",
  "$defs": {
    "message": {
      "description": "A message: the protocol, the operation, the person's settings, and the operation's fields.",
      "oneOf": [
        { "$ref": "#/$defs/describe" },
        { "$ref": "#/$defs/estimate" },
        { "$ref": "#/$defs/submit" },
        { "$ref": "#/$defs/status" },
        { "$ref": "#/$defs/result" },
        { "$ref": "#/$defs/cancel" }
      ]
    },
    "settings": { "type": "object", "description": "The person's non-secret settings for this provider, passed as they are." },
    "describe": {
      "type": "object",
      "required": ["protocol", "op"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "describe" }, "settings": { "$ref": "#/$defs/settings" } }
    },
    "estimate": {
      "type": "object",
      "required": ["protocol", "op"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "estimate" }, "settings": { "$ref": "#/$defs/settings" }, "program": { "$ref": "#/$defs/program" }, "shots": { "type": "integer", "minimum": 1 }, "landscape": { "$ref": "#/$defs/landscape_job" } },
      "oneOf": [
        { "description": "A circuit: its program in the device's gates, and its shots.", "required": ["program", "shots"] },
        { "description": "An energy-landscape job (section 11), in place of a program and its shots.", "required": ["landscape"] }
      ]
    },
    "submit": {
      "type": "object",
      "required": ["protocol", "op"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "submit" }, "settings": { "$ref": "#/$defs/settings" }, "program": { "$ref": "#/$defs/program" }, "shots": { "type": "integer", "minimum": 1 }, "seed": { "type": "integer", "minimum": 0, "description": "A seeded simulator uses it; a device ignores it." }, "landscape": { "$ref": "#/$defs/landscape_job" } },
      "oneOf": [
        { "description": "A circuit: its program in the device's gates, and its shots.", "required": ["program", "shots"] },
        { "description": "An energy-landscape job (section 11), in place of a program, its shots and its seed.", "required": ["landscape"] }
      ]
    },
    "landscape_job": {
      "type": "object",
      "description": "An energy-landscape job (section 11.2): an operation of wai.quantum.landscape/1 or wai.quantum.landscape/2 and its request, in that extension's own form. The request's `protocol` names the version, the first where it names none.",
      "required": ["op", "request"],
      "properties": {
        "op": { "enum": ["run", "sweep", "compare", "replay"] },
        "request": { "type": "object", "description": "The request of wai/extensions/quantum-landscape.md section 2 (or of quantum-landscape-2.md section 2, with `protocol`): its program, and its seed, temperatures and parity where it gives them." }
      }
    },
    "status": {
      "type": "object",
      "required": ["protocol", "op", "job"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "status" }, "settings": { "$ref": "#/$defs/settings" }, "job": { "type": "string" } }
    },
    "result": {
      "type": "object",
      "required": ["protocol", "op", "job"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "result" }, "settings": { "$ref": "#/$defs/settings" }, "job": { "type": "string" } }
    },
    "cancel": {
      "type": "object",
      "required": ["protocol", "op", "job"],
      "properties": { "protocol": { "const": "wai.quantum.provider/1" }, "op": { "const": "cancel" }, "settings": { "$ref": "#/$defs/settings" }, "job": { "type": "string" } }
    },
    "turns": {
      "type": "array",
      "description": "An angle as a fraction of a full turn, [m, k] meaning m/2^k of 2π, 0 ≤ m < 2^k, k ≤ 32.",
      "items": { "type": "integer", "minimum": 0 },
      "minItems": 2,
      "maxItems": 2
    },
    "program": {
      "type": "object",
      "description": "A program in the device's own gates on its physical qubits, every angle an exact fraction of a turn, with the same program as OpenQASM 3 beside it (informative: where they differ, the gates are the program).",
      "required": ["format", "basis", "bits", "gates", "measure"],
      "properties": {
        "format": { "const": "wai.native/1" },
        "basis": { "enum": ["rzsxxcz", "prxcz", "gpizz", "prxrzxx", "gpims"] },
        "bits": { "type": "integer", "minimum": 0 },
        "gates": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["gate", "qubits"],
            "properties": {
              "gate": { "enum": ["rz", "sx", "x", "cz", "prx", "gpi", "gpi2", "zz", "xx", "ms", "move"] },
              "qubits": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1, "maxItems": 2 },
              "turns": { "type": "array", "items": { "$ref": "#/$defs/turns" }, "description": "rz(t), zz(t), xx(t), gpi(p), gpi2(p): one; prx(t, p): two; ms(p0, p1, t), the first qubit's phase, the second's, and the angle: three; move (a qubit, then a resonator): none." }
            }
          }
        },
        "measure": {
          "type": "array",
          "description": "For each classical bit, the physical qubit it reads at the end.",
          "items": { "type": "object", "required": ["qubit", "bit"], "properties": { "qubit": { "type": "integer", "minimum": 0 }, "bit": { "type": "integer", "minimum": 0 } } }
        },
        "qasm3": { "type": "string" }
      }
    },
    "error": {
      "type": "object",
      "description": "An answer that is not ok: a code, and a message for a person that never quotes a credential.",
      "required": ["ok", "error"],
      "properties": {
        "ok": { "const": false },
        "error": {
          "type": "object",
          "required": ["code", "message"],
          "properties": {
            "code": { "enum": ["invalid", "unsupported", "unsupported_version", "unauthorized", "not_found", "refused", "quota", "unavailable", "internal"] },
            "message": { "type": "string" },
            "line": { "type": "integer", "minimum": 1, "description": "For an energy-landscape request a reader refuses (section 11.2): the line of the program its sentence names, where it names one." }
          }
        }
      }
    },
    "answer": {
      "description": "An answer: ok with the operation's fields, or an error.",
      "anyOf": [
        { "$ref": "#/$defs/describe_answer" },
        { "$ref": "#/$defs/estimate_answer" },
        { "$ref": "#/$defs/submit_answer" },
        { "$ref": "#/$defs/status_answer" },
        { "$ref": "#/$defs/result_answer" },
        { "$ref": "#/$defs/error" }
      ]
    },
    "describe_answer": {
      "type": "object",
      "required": ["ok", "protocol", "provider", "device", "provenance", "qubits", "native_gates", "connectivity", "calibration", "billing"],
      "properties": {
        "ok": { "const": true },
        "protocol": { "const": "wai.quantum.provider/1" },
        "provider": { "type": "string" },
        "device": { "type": "string" },
        "provenance": { "enum": ["silicon", "emulator", "simulator"] },
        "simulator": { "type": "string", "description": "What the simulator is, in a sentence." },
        "emulator": { "type": "string", "description": "What the emulator is, in a sentence." },
        "qubits": { "type": "integer", "minimum": 0, "description": "The device's qubit count: 0 for a device that takes energy-landscape jobs and no circuits (section 11.1)." },
        "native_gates": { "type": "array", "items": { "type": "string" } },
        "connectivity": {
          "anyOf": [
            { "const": "all" },
            { "type": "array", "items": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 } }
          ]
        },
        "resonators": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Optional (section 5.1): the places among 0 to qubits − 1 that are computational resonators, each reached by cz from the qubits connectivity pairs with it." },
        "moves": { "type": "array", "items": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 }, "description": "Optional, with resonators: each [qubit, resonator] on which move runs." },
        "durations": { "type": "object", "description": "Gate and measurement durations, with their unit." },
        "calibration": {
          "type": "object",
          "required": ["id"],
          "properties": {
            "id": { "type": "string" },
            "qubits": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["qubit"],
                "properties": {
                  "qubit": { "type": "integer", "minimum": 0 },
                  "readout_error": { "type": "number", "minimum": 0, "maximum": 1 },
                  "error_1q": { "type": "number", "minimum": 0, "maximum": 1 },
                  "t1_us": { "type": "number", "minimum": 0 },
                  "t2_us": { "type": "number", "minimum": 0 }
                }
              }
            },
            "edges": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["qubits"],
                "properties": {
                  "qubits": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 2, "maxItems": 2 },
                  "error": { "type": "number", "minimum": 0, "maximum": 1 }
                }
              }
            }
          }
        },
        "billing": {
          "anyOf": [
            {
              "type": "object",
              "required": ["free"],
              "properties": { "free": { "const": true }, "free_tier": { "description": "The free use offered, and its limits, as the provider states them." } }
            },
            {
              "type": "object",
              "required": ["unit", "price", "currency"],
              "properties": {
                "free": { "const": false },
                "unit": { "type": "string", "description": "shot, job, second, …" },
                "price": { "type": "string", "description": "The price of one unit, as a decimal string." },
                "currency": { "type": "string" },
                "free_tier": { "description": "The free use offered, and its limits, as the provider states them." }
              }
            },
            {
              "type": "object",
              "required": ["free", "priced"],
              "description": "The device is not free, and the provider sets no price (section 5.1): a job no estimate prices has an unknown cost, which a client shows as unknown and submits only on the person's confirmation (section 7). It holds no unit, price or currency, and priced is in this form only.",
              "properties": {
                "free": { "const": false },
                "priced": { "const": false },
                "free_tier": { "description": "The free use offered, and its limits, as the provider states them." }
              }
            }
          ]
        },
        "max_shots": { "type": "integer", "minimum": 1 },
        "seeded": { "type": "boolean" },
        "approximate": { "type": "boolean", "description": "Optional, with provenance simulator or emulator: true when the simulator's results are approximate (a truncated tensor network, a sampled Pauli path); a result is then labelled approximate (section 5.1)." },
        "landscape": {
          "type": "object",
          "description": "Optional (section 11.1): the energy-landscape jobs the device takes.",
          "required": ["protocol", "ops"],
          "properties": {
            "protocol": { "enum": ["wai.quantum.landscape/1", "wai.quantum.landscape/2"], "description": "The earliest version of the landscape protocol it takes: wai.quantum.landscape/1 for a device that takes the first, as every device of the earlier text states." },
            "protocols": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "enum": ["wai.quantum.landscape/1", "wai.quantum.landscape/2"] }, "description": "Optional: every version it takes, none twice, `protocol` the earliest of them. Where it is absent the device takes `protocol` alone." },
            "ops": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "enum": ["run", "sweep", "compare", "replay"] }, "description": "The operations it takes, none twice." },
            "members": { "type": "array", "description": "What it places jobs on, in the order it offers them.", "items": { "type": "object", "required": ["id", "class"], "properties": { "id": { "type": "string" }, "class": { "enum": ["cpu", "gpu", "fpga"] } } } },
            "max_bytes": { "type": "integer", "minimum": 1, "description": "The most memory a job may hold on it, as wai.quantum.landscape/1 section 2.0 counts it (the second version counts the same), where that is less than 268,435,456." }
          }
        }
      }
    },
    "estimate_answer": {
      "type": "object",
      "description": "Section 5.2: free; priced, an amount and its currency; or unpriced, not free and no price set for the job, its cost unknown (a client shows it as unknown and submits the job only on the person's confirmation for that run). priced is in the unpriced form only.",
      "required": ["ok", "free"],
      "properties": {
        "ok": { "const": true },
        "free": { "type": "boolean" },
        "amount": { "type": "string", "description": "When it is priced: the cost, as a decimal string." },
        "currency": { "type": "string" },
        "unit": { "type": "string", "description": "Optional, when it is priced: the billing unit the cost counts." },
        "at_least": { "type": "boolean", "description": "Optional, when it is priced: true when the amount is only the least the job can come to." },
        "priced": { "const": false, "description": "The unpriced form only: the job is not free, and the provider sets no price for it." },
        "seconds": { "type": "number", "minimum": 0 },
        "note": { "type": "string" },
        "operations": { "type": "integer", "minimum": 0, "description": "For an energy-landscape job (section 11.2): its operations, as wai.quantum.landscape/1 section 2.0 counts them before anything runs." },
        "bytes": { "type": "integer", "minimum": 0, "description": "For an energy-landscape job: the memory it can hold, counted the same way." }
      },
      "oneOf": [
        {
          "description": "Free.",
          "properties": {
            "ok": { "const": true }, "free": { "const": true },
            "seconds": { "type": "number", "minimum": 0 }, "note": { "type": "string" },
            "operations": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }
          }
        },
        {
          "description": "Priced: an amount and its currency.",
          "required": ["amount", "currency"],
          "properties": {
            "ok": { "const": true }, "free": { "const": false },
            "amount": { "type": "string" }, "currency": { "type": "string" }, "unit": { "type": "string" }, "at_least": { "type": "boolean" },
            "seconds": { "type": "number", "minimum": 0 }, "note": { "type": "string" },
            "operations": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }
          }
        },
        {
          "description": "Unpriced: not free, no price set for the job, and no amount, currency, unit or at_least.",
          "required": ["priced"],
          "properties": {
            "ok": { "const": true }, "free": { "const": false }, "priced": { "const": false },
            "seconds": { "type": "number", "minimum": 0 }, "note": { "type": "string" },
            "operations": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }
          }
        }
      ]
    },
    "submit_answer": {
      "type": "object",
      "required": ["ok", "job"],
      "properties": { "ok": { "const": true }, "job": { "type": "string" } }
    },
    "status_answer": {
      "type": "object",
      "description": "status, and cancel's answer: to a cancel, cancelled; or, for a job that had already ended, how it ended: done, or failed with its reason (section 5.6).",
      "required": ["ok", "status"],
      "properties": {
        "ok": { "const": true },
        "status": { "enum": ["queued", "running", "done", "failed", "cancelled"] },
        "reason": { "type": "string" }
      }
    },
    "result_answer": {
      "type": "object",
      "required": ["ok"],
      "oneOf": [
        { "description": "A circuit's counts.", "required": ["counts", "shots"] },
        { "description": "An energy-landscape job's answer (section 11.2).", "required": ["landscape"] }
      ],
      "properties": {
        "ok": { "const": true },
        "landscape": { "type": "object", "description": "For an energy-landscape job (section 11.2): the answer of wai.quantum.landscape/1 section 3 to its operation, or of wai.quantum.landscape/2 section 3 for a job of that version." },
        "counts": { "type": "object", "description": "Outcomes to counts, the highest bit first, summing to the shots, or to accepted_shots where it is given.", "additionalProperties": { "type": "integer", "minimum": 0 } },
        "shots": { "type": "integer", "minimum": 1 },
        "accepted_shots": { "type": "integer", "minimum": 1, "description": "Optional (section 5.5): the shots the device kept, where it kept another number than asked (a post-selected or heralded readout, or a device that runs more than asked). The counts are of these shots, and sum to it." },
        "calibration": { "type": "string" },
        "charged": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } } },
        "energy": { "type": "object", "properties": { "kwh": { "type": "number", "minimum": 0 } } },
        "counts_source": { "enum": ["shots", "vendor_counts", "probabilities"], "description": "Optional (section 5.5): one record a shot, tallied (shots); the provider's own counts (vendor_counts, how an answer that does not say is read); or counts rebuilt from probabilities, derived and not shot records (probabilities)." },
        "execution": {
          "type": "object",
          "description": "Optional (section 5.5): how the device ran the program. Each of the five steps is off, on, none (the device has no such step), or unknown (a step the provider cannot vouch for); verbatim says whether the gates ran as written. A provider that relays a job to another service states it.",
          "required": ["mitigation", "twirling", "decoupling", "remapping", "optimisation", "verbatim"],
          "properties": {
            "mitigation": { "enum": ["off", "on", "none", "unknown"] },
            "twirling": { "enum": ["off", "on", "none", "unknown"] },
            "decoupling": { "enum": ["off", "on", "none", "unknown"] },
            "remapping": { "enum": ["off", "on", "none", "unknown"] },
            "optimisation": { "enum": ["off", "on", "none", "unknown"] },
            "verbatim": { "type": "boolean" },
            "note": { "type": "string" }
          },
          "additionalProperties": false
        }
      }
    }
  }
}