open-standards/wai/wai-quantum/schemas/exercise.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/exercise.v1.json",
  "title": "wai.quantum.exercise/1",
  "description": "One lesson's exercise (course/lessons/<id>/exercise.json): what the program must do, checked by the engine (engine::course::check), with its solution and known wrong answers, which the tests hold to pass and to fail. Every text is given in each of the course's locales.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema",
    "id",
    "title",
    "task",
    "starter",
    "hints",
    "reference",
    "wrong"
  ],
  "$defs": {
    "localized": {
      "type": "object",
      "description": "A text in each locale of the course",
      "required": [
        "en",
        "zh-CN"
      ],
      "additionalProperties": false,
      "properties": {
        "en": {
          "type": "string",
          "minLength": 1
        },
        "zh-CN": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "program": {
      "description": "An OpenQASM program: its text, or its lines",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "intent": {
      "description": "One intent or a list, as a job takes it (wai-quantum://docs/verdicts): an exact distribution, a reference program to equal or whose state to prepare, or a sampled test",
      "oneOf": [
        {
          "type": "object"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object"
          }
        }
      ]
    },
    "bound": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "properties": {
        "min": {
          "type": "integer",
          "minimum": 0
        },
        "max": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "at_most": {
      "type": "object",
      "description": "A bound the course says as at most n: its max alone",
      "additionalProperties": false,
      "required": [
        "max"
      ],
      "properties": {
        "max": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "properties": {
    "schema": {
      "const": "wai.quantum.exercise/1"
    },
    "id": {
      "type": "string",
      "description": "The lesson's id, its directory's name"
    },
    "translations": {
      "type": "object",
      "description": "For each locale but English, how its texts were translated (machine-assisted until a fluent reader has reviewed them)",
      "additionalProperties": {
        "type": "string"
      }
    },
    "title": {
      "$ref": "#/$defs/localized"
    },
    "task": {
      "$ref": "#/$defs/localized"
    },
    "starter": {
      "$ref": "#/$defs/program"
    },
    "job": {
      "type": "object",
      "description": "What the check runs the program with, as a job gives it",
      "additionalProperties": false,
      "properties": {
        "shots": {
          "type": "integer",
          "minimum": 1
        },
        "seed": {
          "type": "integer",
          "minimum": 0
        },
        "noise": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      }
    },
    "intent": {
      "$ref": "#/$defs/intent"
    },
    "cases": {
      "type": "array",
      "minItems": 1,
      "maxItems": 16,
      "description": "A generator's inputs to check the program at, each a case with its own verdict, at most 16 (engine::course::MOST_CASES); a case without an intent takes the exercise's. Every input a case gives must be one the program declares, and the constraints hold in every case",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "inputs",
          "name"
        ],
        "properties": {
          "inputs": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "name": {
            "$ref": "#/$defs/localized"
          },
          "intent": {
            "$ref": "#/$defs/intent"
          }
        }
      }
    },
    "constraints": {
      "type": "object",
      "description": "How the program must do it, measured on it by the engine",
      "additionalProperties": false,
      "properties": {
        "allow": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          },
          "description": "The only gates the program may use, by the reader's names"
        },
        "counts": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/bound"
          },
          "description": "Bounds on how many of a gate the program has"
        },
        "t_count": {
          "$ref": "#/$defs/at_most",
          "description": "A bound on the T gates: a t or tdg counts one, a p or rz by an odd multiple of π/4 one (a T up to Clifford gates), a Clifford gate none; a program with any other gate holds to no T count"
        },
        "two_qubit": {
          "$ref": "#/$defs/at_most",
          "description": "A bound on the two-qubit gates; a program with a gate on three qubits holds to none"
        },
        "no_smells": {
          "type": "array",
          "minItems": 1,
          "items": {
            "enum": [
              "cancels",
              "merges",
              "does_nothing",
              "idle",
              "unmeasured"
            ]
          },
          "description": "The critique's smells the program must not have"
        },
        "estimate": {
          "type": "object",
          "description": "Bounds on the resource estimate's logical counts",
          "additionalProperties": false,
          "properties": {
            "toffolis": {
              "$ref": "#/$defs/at_most"
            },
            "t_gates": {
              "$ref": "#/$defs/at_most"
            },
            "rotations": {
              "$ref": "#/$defs/at_most"
            },
            "logical_qubits": {
              "$ref": "#/$defs/at_most"
            },
            "t_states": {
              "$ref": "#/$defs/at_most"
            }
          }
        },
        "qubits": {
          "$ref": "#/$defs/at_most",
          "description": "A bound on the qubits the program declares"
        },
        "inject": {
          "type": "string",
          "minLength": 1,
          "description": "The input whose value, in each case, is the qubit an error flips: the cases' programs may differ only in that one x, so the program finds and corrects the error from the qubits and cannot read it otherwise. Every case gives it, and at least two give different ones"
        }
      }
    },
    "hints": {
      "type": "object",
      "description": "Hints from gentle to specific, the same number in each locale; none gives the solution",
      "required": [
        "en",
        "zh-CN"
      ],
      "additionalProperties": false,
      "properties": {
        "en": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "zh-CN": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        }
      }
    },
    "reference": {
      "$ref": "#/$defs/program",
      "description": "A solution: the tests hold it to pass; no surface shows it"
    },
    "wrong": {
      "type": "array",
      "minItems": 1,
      "description": "Known wrong answers, each held by the tests to fail for the reason it states",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "qasm",
          "fails",
          "note"
        ],
        "properties": {
          "qasm": {
            "$ref": "#/$defs/program"
          },
          "fails": {
            "enum": [
              "intent",
              "constraint",
              "refused"
            ]
          },
          "note": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    }
  }
}