API schema reference

quantum-viz.js takes in as input a JSON object called a Circuit that has the following schema:

Circuit

A Circuit object represents the circuit to be visualized.

Circuit Properties

	Type	Description	Required
qubits	Qubit[]	List of qubit registers.	✓ Yes
operations	Operation[]	Ordered sequence of operations.	✓ Yes

Qubit

Represents a unique qubit resource.

Qubit Properties

	Type	Description	Required
id	integer	Qubit ID.	✓ Yes
numChildren	integer	Number of classical registers attached to quantum register.	No, default: 0

Qubit.id

Unique ID associated with the quantum register. This qubit ID is used by the circuit to specify which qubit an Operation is acting on.

• Type: integer
• Required: ✓ Yes

Qubit.numChildren

The number of classical registers associated with this quantum registers. This corresponds to the number of measurements being performed on the register. Operations using the classical output of measurements will reference these classical registers by the zero-indexed ID.

• Type: integer
• Required: No, default: 0

Operation

Represents a quantum operation.

Operation Properties

	Type	Description	Required
gate	string	Label of gate.	✓ Yes
displayArgs	string	Gate arguments to be displayed.	No
children	Operation[]	Nested operations.	No, default: []
isMeasurement	boolean	Whether gate is a measurement operation.	No, default: false
isConditional	boolean	Whether gate is a conditional operation.	No, default: false
isControlled	boolean	Whether gate is a controlled operation.	No, default: false
isAdjoint	boolean	Whether gate is an adjoint operation.	No, default: false
controls	Register[]	List of control registers.	No, default: []
targets	Register[]	List of target registers.	✓ Yes
conditionalRender	ConditionalRender	Specify when to render operation.	No, default: ConditionalRender.Always
dataAttributes	DataAttributes	Custom HTML data attributes for gate.	No

Operation.gate

Name of gate to be displayed when rendered. For example, the gate label for the X rotation gate is "RX".

• Type: string
• Required: ✓ Yes

Operation.displayArgs

An optional string of arguments to be displayed together with the gate label. For example, the X rotation gate comes with a rotation angle such as "0.5". This would be displayed as RX(0.5). If displayArgs is not provided, then no arguments are displayed. For example, the Hadamard gate has no arguments, so it would be displayed as H.

• Type: string
• Required: No

Operation.children

List of nested Operations within this operation. Each Operation can be made out of many nested operations. For example, we can define an Entangle operation that is made out of a H and CNOT gate.

• Type: Operation[]
• Required: No, default: []

Operation.isMeasurement

Specifies a measurement gate. If specified, all other Operation attributes are ignored, except:

1. controls: controls[0] is used as the quantum register to be measured
2. targets: targets[0] is used as the classical register containing the measurement outcome

• Type: boolean
• Required: No, default: false

Operation.isConditional

Specifies a classically-controlled operation that depends on a measurement result (i.e. classical register) and applies a different series of gates depending on the measurement outcome. If specified, all other Operation attributes are ignored, except:

1. controls: controls[0] is used as the classical register containing the measurement outcome
2. children: ordered sequence of operations to be conditionally rendered depending on the measurement outcome.

• Type: boolean
• Required: No, default: false

e.g.

{
    gate: 'Conditional',
    isConditional: true,
    controls: [{ type: 1, qId: 0, cId: 0 }],
    targets: [],
    children: [
        {
            gate: 'H',
            targets: [{ qId: 1 }],
            conditionalRender: 1,
        },
        {
            gate: 'X',
            isControlled: true,
            controls: [{ qId: 0 }],
            targets: [{ qId: 1 }],
            conditionalRender: 2,
        },
    ],
}

In this example, we have a classically-controlled operation called Conditional that depends on the measurement outcome of the classical register with cId 0 attached to qubit 0. If the outcome is 0, an H gate is applied on qubit 1. If the outcome is 1, a CNOT gate is applied on qubits 0 and 1.

Operation.isAdjoint

Specifies an adjoint operation.

• Type: boolean
• Required: No, default: false

Operation.controls

List of control registers that the operation acts on.

• Type: Register[]
• Required: No, default: []

Operation.targets

List of target registers that the operation acts on.

• Type: Register[]
• Required: ✓ Yes

Operation.conditionalRender

Specifies the conditions on when to render the operation. Refer to ConditionalRender for more info.

• Type: ConditionalRender
• Required: No, default: ConditionalRender.Always

Operation.dataAttributes

Specifies custom data attributes to be attached to the HTML element created from this operation. This is mainly used for implementing interactive elements. Refer to DataAttributes for more info.

• Type: DataAttributes
• Required: No

Register

Represents a quantum or classical resource.

Register Properties

	Type	Description	Required
type	RegisterType	Type of register.	No, default: RegisterType.Qubit
qId	integer	ID of quantum register.	✓ Yes
cId	integer	ID of classical register.	No (needed if classical)

Register.type

The type of register.

• Type: RegisterType
• Required: No, default: RegisterType.Qubit

Register.qId

ID of quantum register.

• Type: integer
• Required: ✓ Yes

Register.cId

ID of classical register. This is only needed if type is RegisterType.Classical.

• Type: integer
• Required: No (needed if classical)

RegisterType

Represents the type of the register. Has 2 possible values:

1. RegisterType.Qubit or 0: quantum register
2. RegisterType.Classical or 1: classical register

ConditionalRender

Represents the conditions under which to render a given operation. Mainly used for interactive elements, such as classically-controlled operations. Has 4 possible values:

1. ConditionalRender.Always or 0: always rendered (default)
2. ConditionalRender.OnZero or 1: only rendered if the outcome of a measurement is 0
3. ConditionalRender.OnOne or 2: only rendered if the outcome of a measurement is 1
4. ConditionalRender.AsGroup or 3: contains a group of nested operations and renders its immediate children operation a group with a dashed box around it:

DataAttributes

A map of data attributes from the attribute name to its value (e.g. data-{attr}="{val}"):

export interface DataAttributes {
    [attr: string]: string;
}