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.

source
operator
destination
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.

operator
destination
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.

identifier
instructions
parameters

The list of parameters that this calibration definition is for.

qubits

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

modifiers

The list of [GateModifier]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

parameters

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

qubits

The qubits on which the gate is applied

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.

arguments

The arguments of the call instruction.

name

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

class Capture:
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
memory_reference
class CircuitDefinition:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

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

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

rhs
destination
lhs
operator
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.

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

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

frame_names
qubits
duration
class DefGateSequence:

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

gates

The list of Gate objects that make up the sequence.

qubits

The list of qubit variable names in the gate signature.

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.

mutable

Whether the parameter is mutable.

name

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

data_type

The data type of the parameter.

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.

return_type

The return type of the extern signature, if any.

parameters

The parameters of the extern signature.

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.

modifiers
qubits
name
parameters
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.

name
specification
signature
parameters
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 is_quil_t(self, /):

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

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.

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.

target
condition
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.

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

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

instructions
target

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

qubit

The qubit that this measure calibration definition is for.

identifier
name

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

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.

target
name
qubit
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.

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

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

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

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

data_type
offset
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.

qubit_parameters
gate_type
name
gate_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:
arguments
expression
class PauliSum:
arguments
terms
class Pragma:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

arguments
data
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.

memory_reference
blocking
duration
frame
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.

frequency
frame
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.

scale
frame
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.

frequency
frame
class ShiftPhase:
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 Store:
def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

destination
offset
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_1
frame_2
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.

operand
operator
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:
parameters
matrix
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