open-standards/wai/wai-quantum/schemas/estimate.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/estimate.v1.json",
  "title": "wai.quantum.estimate/1",
  "description": "A resource estimate as a host returns it (the command line's estimate --json, both servers' estimate_resources, the job service's POST /v1/estimate): the request, and the result, which its receipt seals in a job's form. The result holds the program's logical counts, the error budget and how it was shared, the decoder calibration the physical model uses, the headline estimate and the frontier trading physical qubits for runtime, each estimate sealed in the resource-estimate receipt family (the frontier's naming the headline's as parent), and the model's notes. A result names the engine that made it and this schema (engine and schema); results made before results carried them have neither. docs/estimate.md explains every number.",
  "type": "object",
  "required": [
    "request",
    "result"
  ],
  "properties": {
    "request": {
      "type": "object",
      "description": "A program (qasm), a logical-counts document (counts) or a routine document (routine), with the estimate's options, as given.",
      "properties": {
        "qasm": {
          "type": "string"
        },
        "counts": {
          "type": "object"
        },
        "routine": {
          "type": "object"
        },
        "inputs": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "budget": {
          "type": "number"
        },
        "qubit": {
          "type": [
            "string",
            "object"
          ]
        },
        "calibration": {
          "type": "string"
        },
        "max_slowdown": {
          "type": "integer"
        },
        "clock": {
          "description": "How long a Toffoli takes: steps (the default: three logical steps of d cycles), or the reaction-limited clock, a Toffoli one tick of the control system's reaction time in µs, its Clifford fixups teleported away, with enough factories to keep up.",
          "anyOf": [
            {
              "const": "steps"
            },
            {
              "type": "object",
              "required": [
                "reaction_us"
              ],
              "properties": {
                "reaction_us": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 1000000000
                }
              },
              "additionalProperties": false
            }
          ]
        },
        "export": {
          "enum": [
            "counts",
            "routine"
          ]
        },
        "name": {
          "type": "string"
        }
      }
    },
    "result": {
      "$ref": "#/$defs/result"
    }
  },
  "$defs": {
    "result": {
      "type": "object",
      "required": [
        "ok",
        "format",
        "program",
        "counts",
        "epsilon",
        "options",
        "estimate",
        "frontier"
      ],
      "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.estimate/1"
        },
        "ok": {
          "const": true
        },
        "format": {
          "const": "wai.quantum.estimate/1"
        },
        "program": {
          "type": "object",
          "description": "What was estimated: a circuit (its digest, BLAKE3 of the program's text), or a document's counts.",
          "properties": {
            "origin": {
              "enum": [
                "circuit",
                "counts",
                "routine"
              ]
            },
            "digest": {
              "type": "string"
            },
            "qubits": {
              "type": "integer"
            },
            "bound": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "counts": {
          "type": "object",
          "description": "The program's logical counts: qubits and ancillas, measurements, Clifford gates, T gates, Toffolis, rotations (each costed at its own synthesised word's T count), T states, depths.",
          "additionalProperties": {
            "type": [
              "integer",
              "number",
              "string",
              "null",
              "array"
            ]
          }
        },
        "epsilon": {
          "type": "object",
          "description": "The error budget, the synthesis share and each rotation's share, the bound the rotations' distances add to, and their T counts.",
          "properties": {
            "budget": {
              "type": [
                "number",
                "null"
              ]
            },
            "synthesis": {
              "type": [
                "number",
                "null"
              ]
            },
            "each": {
              "type": [
                "number",
                "null"
              ]
            },
            "rotations": {
              "type": [
                "integer",
                "null"
              ]
            },
            "angles": {
              "type": [
                "integer",
                "null"
              ]
            },
            "bound": {
              "type": [
                "number",
                "null"
              ]
            },
            "t_per_rotation": {
              "type": [
                "object",
                "null"
              ]
            }
          }
        },
        "calibration": {
          "type": "object",
          "description": "The decoder calibration the physical model uses: the decoder, the experiment, the fit, its measured range, and how to reproduce it."
        },
        "options": {
          "type": "object",
          "description": "The options the estimate ran with, the defaults filled in."
        },
        "estimate": {
          "$ref": "#/$defs/point"
        },
        "frontier": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/point"
          },
          "description": "Estimates no other beats on both physical qubits and runtime; the headline among them."
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The model's assumptions."
        },
        "rotations": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Each distinct rotation angle: how many there are, its T count, gates and distance."
        },
        "export": {
          "type": "object",
          "description": "With export: the program's counts as a logical-counts or a routine document."
        },
        "receipt": {
          "$ref": "receipt.v2.json"
        }
      }
    },
    "point": {
      "type": "object",
      "description": "One estimate on a physical qubit: the code and its distance, the slowdown, physical qubits (the algorithm's and the factories'), factories, runtime, logical steps and their length, tiles, the logical error, T states, and how the budget was shared; sealed by its resource-estimate receipt (receipt), or marked the headline.",
      "properties": {
        "qubit": {
          "type": "string"
        },
        "code": {
          "type": "string"
        },
        "distance": {
          "type": "integer"
        },
        "slowdown": {
          "type": "integer"
        },
        "physical_qubits": {
          "type": "integer"
        },
        "algorithm_qubits": {
          "type": "integer"
        },
        "factory_qubits": {
          "type": "integer"
        },
        "factories": {
          "type": "integer"
        },
        "factory_fraction": {
          "type": "number"
        },
        "runtime_s": {
          "type": "number"
        },
        "steps": {
          "type": "integer"
        },
        "step_us": {
          "type": "number"
        },
        "tiles": {
          "type": "integer"
        },
        "tile_qubits": {
          "type": "integer"
        },
        "logical_error": {
          "type": "number"
        },
        "t_states": {
          "type": "integer"
        },
        "t_target": {
          "type": "number"
        },
        "budget": {
          "type": "object",
          "properties": {
            "logical": {
              "type": "number"
            },
            "distillation": {
              "type": "number"
            },
            "synthesis": {
              "type": "number"
            }
          }
        },
        "factory": {
          "type": [
            "object",
            "null"
          ]
        },
        "headline": {
          "type": "boolean"
        },
        "receipt": {
          "$ref": "#/$defs/resource_receipt"
        },
        "clock": {
          "type": "object",
          "description": "On the reaction-limited clock only: its reaction time, one tick at this estimate's slowdown, and the Toffolis run on ticks. Then steps are the lattice-surgery steps alone, and runtime_s adds the ticks.",
          "required": [
            "reaction_us",
            "tick_us",
            "toffolis"
          ],
          "properties": {
            "reaction_us": {
              "type": "number"
            },
            "tick_us": {
              "type": "number"
            },
            "toffolis": {
              "type": "integer"
            }
          }
        }
      }
    },
    "resource_receipt": {
      "type": "object",
      "description": "A receipt of the resource-estimate family: the estimate, the hashes of its job and its result, its Merkle root, its signer and signature, and the receipt it names as parent.",
      "required": [
        "kind",
        "receipt_hash",
        "sig",
        "signer_pubkey"
      ],
      "properties": {
        "kind": {
          "const": "quantum-resource"
        },
        "clock": {
          "type": "object",
          "description": "On the reaction-limited clock only: the runtime the estimate's steps do not account for, read from its signed figures. How long one tick was is the job's, whose hash binds the reaction time.",
          "required": [
            "kind",
            "tick_time_ns_bits",
            "tick_time_s"
          ],
          "properties": {
            "kind": {
              "const": "reaction"
            },
            "tick_time_ns_bits": {
              "type": "string"
            },
            "tick_time_s": {
              "type": "number"
            }
          },
          "additionalProperties": false
        },
        "estimate": {
          "type": "object"
        },
        "job_hash": {
          "type": "string"
        },
        "joules_micro": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The microjoules the estimate took, where something read them; null in the unmetered form (quantum-ops section 3.5), beside energy_unmetered. An unlabelled 0 is the legacy form of the unmetered statement, sealed before that form: never a figure of zero joules."
        },
        "parent_receipt_hash": {
          "type": [
            "string",
            "null"
          ]
        },
        "receipt_hash": {
          "type": "string"
        },
        "result_hash": {
          "type": "string"
        },
        "root_hash": {
          "type": "string"
        },
        "sig": {
          "type": "string"
        },
        "signer_id": {
          "type": "string"
        },
        "signer_pubkey": {
          "type": "string"
        },
        "energy_provenance": {
          "type": "string"
        },
        "energy_uncertainty": {
          "type": "object"
        },
        "energy_unmetered": {
          "type": "string",
          "description": "The unmetered form (quantum-ops section 3.5): why nothing read the estimate's energy, inside the signature. Every receipt an estimate is sealed with now carries it."
        }
      }
    },
    "verify": {
      "type": "object",
      "description": "An estimate's check: its seal, every estimate's receipt, and the request re-run here giving the same figures.",
      "required": [
        "valid",
        "signed",
        "receipts",
        "reproduced"
      ],
      "properties": {
        "valid": {
          "type": "boolean"
        },
        "reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The provider protocol's section 8.4 reasons: none, since an answer is run again only once its receipt and every rule hold; a receipt that fails is answered with its reasons alone."
        },
        "signed": {
          "type": "boolean"
        },
        "receipts": {
          "type": "boolean"
        },
        "reproduced": {
          "type": "boolean"
        },
        "rerun_error": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why the request could not be run again, when no host runs it (a request an estimate refuses): the answer is then not valid, and nothing is reproduced. Null when it ran."
        },
        "key": {
          "type": [
            "string",
            "null"
          ]
        },
        "signer": {
          "type": [
            "string",
            "null"
          ]
        },
        "estimates": {
          "type": "integer"
        },
        "time": {
          "type": "object",
          "description": "What the receipt seals of when it was issued (the provider protocol's section 8.2): the time, in milliseconds since 1970 by its signer's clock, or that it seals none.",
          "required": [
            "sealed"
          ],
          "properties": {
            "sealed": {
              "type": "boolean"
            },
            "issued_ms": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "not_after_ms": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "The first moment the receipt is no longer offered; null when it states none."
            }
          }
        },
        "trust": {
          "type": "object",
          "description": "With a trust list (section 8.8): whether it lists the receipt's key, and the window and revocation its entry gives.",
          "required": [
            "listed"
          ],
          "properties": {
            "listed": {
              "type": "boolean"
            },
            "not_before_ms": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "not_after_ms": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "revoked_from_ms": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 9007199254740991
            }
          }
        },
        "checked_at_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "With a time to hold the receipt to (section 8.8): that time."
        },
        "skew_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "How far after checked_at_ms a receipt's issue may be."
        },
        "given": {
          "enum": [
            "text",
            "members",
            "parsed"
          ],
          "description": "From a surface that says how the job was given (the provider protocol's section 9): its own text; its members, judged as the message wrote them; or a value already parsed, with no text to judge."
        },
        "not_seen": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "For a job given parsed: what parsing loses, which this verdict could not see."
        }
      }
    }
  }
}