quil.instructions

class InstructionError(quil.QuilError):

Base error type for errors related to Instruction processing.

class CallError(quil.QuilError):

Errors that may occur when initializing a Call.

class ExternError(quil.QuilError):

Errors that may occur when initializing or validating a PRAGMA EXTERN instruction.

class GateError(quil.QuilError):

Errors that may occur when performing operations on a Gate.

class DefGateSequenceError(InstructionError):

Errors that can occur when initializing a sequence gate definition.

class ParseInstructionError(InstructionError):

Errors that may occur while parsing an Instruction.

class ParseMemoryReferenceError(quil.QuilError):

Errors that may occur while parsing a MemoryReference.

class Arithmetic:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

operator
destination
source
class ArithmeticOperand:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class ArithmeticOperand.LiteralInteger(ArithmeticOperand):
class ArithmeticOperand.LiteralReal(ArithmeticOperand):
class ArithmeticOperand.MemoryReference(ArithmeticOperand):
class ArithmeticOperator:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

ADD = Add
SUBTRACT = Subtract
DIVIDE = Divide
MULTIPLY = Multiply
class AttributeValue:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class AttributeValue.String(AttributeValue):
class AttributeValue.Expression(AttributeValue):
class BinaryLogic:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

destination
operator
source
class BinaryOperand:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class BinaryOperand.LiteralInteger(BinaryOperand):
class BinaryOperand.MemoryReference(BinaryOperand):
class BinaryOperator:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

AND = And
IOR = Ior
XOR = Xor
class CalibrationDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

name

The gate name that this calibration definition is for.

instructions
identifier
parameters

The list of parameters that this calibration definition is for.

modifiers

The list of [GateModifier]s that this calibration definition is for.

qubits

The list of [Qubit]s that this calibration definition is for.

class CalibrationIdentifier:

Unique identifier for a calibration definition within a program

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

modifiers

The modifiers applied to the gate

name

The name of the gate

qubits

The qubits on which the gate is applied

parameters

The parameters of the gate - these are the variables in the calibration definition

class Call:

A call instruction with a name and arguments.

An instruction that calls an external function declared with a PRAGMA EXTERN instruction. These calls are generally specific to a particular hardware or virtual machine backend.

For further detail, see:

Also see [ExternSignature].

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

name

The name of the call instruction. This must be a valid user identifier.

arguments

The arguments of the call instruction.

class Capture:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

blocking
memory_reference
frame
waveform
class CircuitDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

instructions
name
parameters
qubit_variables
class Comparison:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

operator
lhs
destination
rhs
class ComparisonOperand:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class ComparisonOperand.LiteralInteger(ComparisonOperand):
class ComparisonOperand.LiteralReal(ComparisonOperand):
class ComparisonOperand.MemoryReference(ComparisonOperand):
class ComparisonOperator:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

EQUAL = Equal
GREATER_THAN_OR_EQUAL = GreaterThanOrEqual
GREATER_THAN = GreaterThan
LESS_THAN_OR_EQUAL = LessThanOrEqual
LESS_THAN = LessThan
class Convert:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

source
destination
class Declaration:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

size
sharing
name
class Delay:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

duration
frame_names
qubits
class DefGateSequence:

A sequence of gates that make up a defined gate (i.e. with DEFGATE ... AS SEQUENCE).

qubits

The list of qubit variable names in the gate signature.

gates

The list of Gate objects that make up the sequence.

class Exchange:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

left
right
class ExternParameter:

An extern parameter with a name, mutability, and data type.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

data_type

The data type of the parameter.

name

The name of the parameter. This must be a valid user identifier.

mutable

Whether the parameter is mutable.

class ExternParameterType:

A parameter type within an extern signature.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class ExternParameterType.Scalar(ExternParameterType):
class ExternParameterType.FixedLengthVector(ExternParameterType):
class ExternParameterType.VariableLengthVector(ExternParameterType):
class ExternSignature:

An extern signature with a return type and parameters.

The signature of a PRAGMA EXTERN instruction. This signature is defined by a list of ExternParameters and an optional return type. See the Quil Specification for details on how these signatures are formed.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

parameters

The parameters of the extern signature.

return_type

The return type of the extern signature, if any.

class Fence:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

qubits
class FrameDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

attributes
identifier
class FrameIdentifier:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

name
qubits
class Gate:

A struct encapsulating all the properties of a Quil Quantum Gate.

def dagger(self, /):

Return a copy of the Gate with the DAGGER modifier added to it.

def controlled(self, /, control_qubit):

Return a copy of the Gate with the CONTROLLED modifier added to it.

def forked(self, /, fork_qubit, alt_params):

Return a copy of the Gate with the FORKED modifier added to it.

Raises a GateError if the number of provided alternate parameters don't equal the number of existing parameters.

def to_unitary(self, /, n_qubits):

Get the matrix resulting from lifting this Gate to the full n_qubits-qubit Hilbert space.

Raises a GateError if any of the parameters of this Gate are non-constant, if any of the Qubits are variable, if the name of this Gate is unknown, or if there are an unexpected number of parameters.

Notes

A previous version of this library called this to_unitary_mut, and modified the Gate when called. This is no longer possible, as it would modify the Gate's hash, leading to confusing bugs. Gates, as well as all other hashable classes, are immutable from Python.

Bugs

Supplying n_qubits as 0 will raise an unspecified exception; other invalid input parameters may silently return an invalid result.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

parameters
qubits
modifiers
name
class GateDefinition:

A struct encapsulating a quil Gate Definition

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

parameters
signature
specification
name
class GateModifier:

An enum of all the possible modifiers on a quil [Gate]

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

CONTROLLED = Controlled
DAGGER = Dagger
FORKED = Forked
class GateSpecification:

An enum representing a the specification of a [GateDefinition] for a given [GateType]

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class GateSpecification.Matrix(GateSpecification):
class GateSpecification.Permutation(GateSpecification):
class GateSpecification.PauliSum(GateSpecification):
class GateSpecification.Sequence(GateSpecification):
class GateType:

The type of a [GateDefinition] used within the [GateSignature].

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

MATRIX = Matrix
PERMUTATION = Permutation
PAULI_SUM = PauliSum
SEQUENCE = Sequence
class Include:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

filename
class Instruction:

A Quil instruction.

Each variant (for Python users, each nested subclass) corresponds to a possible type of Quil instruction, which is accessible as a member within the variant.

Python Users

The subclasses of this class are class attributes defined on it, and can be used to "wrap" instructions when they should be stored together. In particular, they are NOT the instruction classes you'd typically create, and instances of instruction classes are NOT subclasses of this class:

>>> from quil.instructions import Instruction, Gate, Qubit
>>> issubclass(Instruction.Gate, Instruction)
True
>>> issubclass(Gate, Instruction)
False
>>> g = Gate("X", (), (Qubit.Fixed(0),), ())
>>> isinstance(g, Gate)
True
>>> isinstance(g, Instruction.Gate)
False
>>> g_instr = Instruction.Gate(g)
>>> isinstance(g_instr, Gate)
False
>>> isinstance(g_instr, Instruction.Gate)
True
>>> isinstance(g_instr._0, Gate)
True
>>> g_instr._0 == g
True

The point of this class is to wrap different kinds of instructions when stored together in a collection, all of which are of type Instruction. You can check for different instruction variants and destructure them using match:

match g_instr:
    case Instruction.Gate(gate):
        assert isinstance(gate, Gate)
    case Instruction.Wait() | Instruction.Nop():
        # note the `()` -- these aren't like Python's enumerations!
def parse(string):

The type of the None singleton.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

def is_quil_t(self, /):

Returns true if the instruction is a Quil-T instruction.

class Instruction.Arithmetic(Instruction):
class Instruction.BinaryLogic(Instruction):
class Instruction.CalibrationDefinition(Instruction):
class Instruction.Call(Instruction):
class Instruction.Capture(Instruction):
class Instruction.CircuitDefinition(Instruction):
class Instruction.Convert(Instruction):
class Instruction.Comparison(Instruction):
class Instruction.Declaration(Instruction):
class Instruction.Delay(Instruction):
class Instruction.Exchange(Instruction):
class Instruction.Fence(Instruction):
class Instruction.FrameDefinition(Instruction):
class Instruction.Gate(Instruction):
class Instruction.GateDefinition(Instruction):
class Instruction.Halt(Instruction):
class Instruction.Include(Instruction):
class Instruction.Jump(Instruction):
class Instruction.JumpUnless(Instruction):
class Instruction.JumpWhen(Instruction):
class Instruction.Label(Instruction):
class Instruction.Load(Instruction):
class Instruction.MeasureCalibrationDefinition(Instruction):
class Instruction.Measurement(Instruction):
class Instruction.Move(Instruction):
class Instruction.Nop(Instruction):
class Instruction.Pragma(Instruction):
class Instruction.Pulse(Instruction):
class Instruction.RawCapture(Instruction):
class Instruction.Reset(Instruction):
class Instruction.SetFrequency(Instruction):
class Instruction.SetPhase(Instruction):
class Instruction.SetScale(Instruction):
class Instruction.ShiftFrequency(Instruction):
class Instruction.ShiftPhase(Instruction):
class Instruction.Store(Instruction):
class Instruction.SwapPhases(Instruction):
class Instruction.UnaryLogic(Instruction):
class Instruction.WaveformDefinition(Instruction):
class Instruction.Wait(Instruction):
class Jump:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

target
class JumpUnless:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

condition
target
class JumpWhen:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

condition
target
class Label:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

target
class Load:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

destination
source
offset
class MeasureCalibrationDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

target

The name the measurement calibration uses for the variable it will write the measurement result to, if this is a measurement for record.

name

The Quil-T name of the measurement that this measure calibration definition is for, if any.

instructions
identifier
qubit

The qubit that this measure calibration definition is for.

class MeasureCalibrationIdentifier:

A unique identifier for a measurement calibration definition within a program

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

qubit

The qubit which is being measured.

target

The name the definition uses for the variable it will write the measurement result to, if this is a measurement for record.

If this is missing, this is a calibration for a measurement for effect.

name

The Quil-T name of the measurement, if any.

class Measurement:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

name
qubit
target
class MemoryReference:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

def parse(string):

The type of the None singleton.

name
index
class Move:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

source
destination
class Offset:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

offset
data_type
class GateSignature:

A signature for a gate definition; this does not include the gate definition content. To get a signature from a definition, use GateDefinition.signature.

gate_type
gate_parameters
name
qubit_parameters
class PauliGate:
def parse(input):

Parse a PauliGate from a string.

Raises a ParseExpressionError error if the string isn't a valid Quil expression.

I = I
X = X
Y = Y
Z = Z
class PauliTerm:
expression
arguments
class PauliSum:
terms
arguments
class Pragma:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

data
arguments
name
class PragmaArgument:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class PragmaArgument.Identifier(PragmaArgument):
class PragmaArgument.Integer(PragmaArgument):
class Pulse:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

waveform
blocking
frame
class Qubit:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class Qubit.Fixed(Qubit):
class Qubit.Placeholder(Qubit):
class Qubit.Variable(Qubit):
class QubitPlaceholder:

An opaque placeholder for a qubit whose index may be assigned at a later time.

class RawCapture:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

blocking
memory_reference
frame
duration
class Reset:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

qubit
class ScalarType:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

BIT = Bit
INTEGER = Integer
OCTET = Octet
REAL = Real
class SetFrequency:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame
frequency
class SetPhase:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame
phase
class SetScale:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame
scale
class Sharing:
name
offsets
class ShiftFrequency:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame
frequency
class ShiftPhase:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

phase
frame
class Store:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

offset
destination
source
class SwapPhases:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame_2
frame_1
class Target:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class Target.Fixed(Target):
class Target.Placeholder(Target):
class TargetPlaceholder:

An opaque placeholder for a label whose index may be assigned at a later time.

base_label
class UnaryLogic:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

operator
operand
class UnaryOperator:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

NEG = Neg
NOT = Not
class CallArgument:

A parsed, but unresolved call argument. This may be resolved into a [ResolvedCallArgument] with the appropriate [ExternSignature]. Resolution is required for building the [crate::Program] memory graph.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

class CallArgument.Identifier(CallArgument):
class CallArgument.MemoryReference(CallArgument):
class CallArgument.Immediate(CallArgument):
class Vector:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

data_type
length
class Waveform:
matrix
parameters
class WaveformDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

definition
name
class WaveformInvocation:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

name
parameters