quil.program

The quil.program module contains classes for constructing and representing a Quil program.

Examples

Source Mapping for Calibration Expansion

import inspect
from quil.program import Program

program_text = inspect.cleandoc(
    """
    DEFCAL X 0:
        Y 0

    DEFCAL Y 0:
        Z 0

    X 0 # This instruction is index 0
    Y 0 # This instruction is index 1
    """
)

# First, we parse the program and expand its calibrations
program = Program.parse(program_text)
expansion = program.expand_calibrations_with_source_map()
source_map = expansion.source_map()

# This is what we expect the expanded program to be. X and Y have each been replaced by Z.
expected_program_text = inspect.cleandoc(
    """
    DEFCAL X 0:
        Y 0

    DEFCAL Y 0:
        Z 0

    Z 0 # This instruction is index 0
    Z 0 # This instruction is index 1
    """
)
assert expansion.program().to_quil() == Program.parse(expected_program_text).to_quil()

# In order to discover _which_ calibration led to the first Z in the resulting program, we
# can interrogate the expansion source mapping.
#
# For instance, the X at index 0 should have been replaced with a Z at index 0.
# Here's how we can confirm that:

# First, we list the calibration expansion targets for that first instruction...
targets = source_map.list_targets_for_source_index(0)

# ...then we extract the expanded instruction.
# If the instruction had _not_ been expanded (i.e. there was no matching calibration), then `as_expanded()` would return `None`.
expanded = targets[0].as_expanded()

# This line shows how that `X 0` was expanded into instruction index 0 (only) within the expanded program.
# The end of the range is exclusive.
assert expanded.range() == range(0, 1)

# We can also map instructions in reverse: given an instruction index in the expanded program, we can find the source index.
# This is useful for understanding the provenance of instructions in the expanded program.
sources = source_map.list_sources_for_target_index(1)

# In this case, the instruction was expanded from the source program at index 1.
assert sources == [1]
class ProgramError(quil.QuilError):

Errors encountered related to a Program.

class ComputedScheduleError(ProgramError):

Error raised if the computed schedule is invalid.

class BasicBlockScheduleError(ProgramError):
class QubitGraphError(ProgramError):
class BasicBlock:
def as_schedule_seconds(self, /, program):

The type of the None singleton.

def gate_depth(self, /, gate_minimum_qubit_count):

Return the length of the longest path from an initial instruction (one with no prerequisite instructions) to a final instruction (one with no dependent instructions), where the length of a path is the number of gate instructions in the path.

Parameters
  • gate_minimum_qubit_count: The minimum number of qubits in a gate for it to be counted in the depth.
instructions

A list of the instructions in the block, in order of definition.

This does not include the label or terminator instructions.

label

The label of the block, if any. This is used to target this block in control flow.

terminator

The control flow terminator instruction of the block, if any.

If this is None, the implicit behavior is to "continue" to the subsequent block.

class CalibrationExpansion:

Details about the expansion of a calibration.

expansions

The source map describing the nested expansions made.

calibration_used

The calibration used to expand the instruction.

range

The range of instructions in the expanded list which were generated by this expansion.

class CalibrationExpansionSourceMap:
def entries(self, /):

The type of the None singleton.

def list_sources_for_target_index(self, /, target_index):

Return all source ranges in the source map which were used to generate the target index.

This is O(n) where n is the number of entries in the map.

def list_sources_for_calibration_used(self, /, calibration_used):

Given a particular calibration (DEFCAL or DEFCAL MEASURE), = return the locations in the source which were expanded using that calibration.

This is O(n) where n is the number of first-level calibration expansions performed.

def list_targets_for_source_index(self, /, source_index):

Return all target ranges which were used to generate the source range.

This is O(n) where n is the number of entries in the map.

class CalibrationExpansionSourceMapEntry:

A description of the expansion of one instruction into other instructions.

If present, the instruction located at source_location was expanded using calibrations into the instructions located at target_location.

Note that both source_location and target_location are relative to the scope of expansion.

In the case of a nested expansion, both describe the location relative only to that level of expansion and not the original program.

Consider the following example:

DEFCAL A:
    NOP
    B
    HALT


DEFCAL B:
    NOP
    WAIT

NOP
NOP
NOP
A

In this program, A will expand into NOP, B, and HALT. Then, B will expand into NOP and WAIT. Each level of this expansion will have its own CalibrationExpansionSourceMap describing the expansion. In the map of B to NOP and WAIT, the source_location will be 1 because B is the second instruction in DEFCAL A, even though A is the 4th instruction (index = 3) in the original program.

def source_location(self, /):

The instruction index within the source program's body instructions.

def target_location(self, /):

The location of the expanded instruction within the target program's body instructions.

class CalibrationSet:

A collection of Quil calibrations (DEFCAL instructions) with utility methods.

This exposes the semantics similar to [CalibrationSet] to Python users, so see the documentation there for more information.

def is_empty(self, /):

Return true if this contains no data.

def insert_calibration(self, /, calibration):

Insert a [CalibrationDefinition] into the set.

If a calibration with the same [signature][crate::instruction::CalibrationSignature] already exists in the set, it will be replaced and the old calibration will be returned.

def insert_measurement_calibration(self, /, calibration):

Insert a [MeasureCalibrationDefinition] into the set.

If a calibration with the same [signature][crate::instruction::CalibrationSignature] already exists in the set, it will be replaced and the old calibration will be returned.

def extend(self, /, other):

Append another [CalibrationSet] onto this one.

Calibrations with conflicting [CalibrationSignature]s are overwritten by the ones in the given set.

def to_instructions(self, /):

Return the Quil instructions which describe the contained calibrations.

def expand(self, /, instruction, previous_calibrations):

Given an instruction, return the instructions to which it is expanded if there is a match. Recursively calibrate instructions, returning an error if a calibration directly or indirectly expands into itself.

Return only the expanded instructions; for more information about the expansion process, see [Self::expand_with_detail].

def get_match_for_measurement(self, /, measurement):

Returns the last-specified MeasureCalibrationDefinition that matches the target qubit (if any), or otherwise the last-specified one that specified no qubit.

If multiple calibrations match the measurement, the precedence is as follows:

  1. Match fixed qubit.
  2. Match variable qubit.
  3. Match no qubit.

In the case of multiple calibrations with equal precedence, the last one wins.

def get_match_for_gate(self, /, gate):

Return the final calibration which matches the gate per the QuilT specification:

A calibration matches a gate if:

  1. It has the same name
  2. It has the same modifiers
  3. It has the same qubit count (any mix of fixed & variable)
  4. It has the same parameter count (both specified and unspecified)
  5. All fixed qubits in the calibration definition match those in the gate
  6. All specified parameters in the calibration definition match those in the gate
measure_calibrations

Return a list of all [MeasureCalibrationDefinition]s in the set.

calibrations

Return a list of all [CalibrationDefinition]s in the set.

class CalibrationSource:

The source of a calibration, either a [CalibrationIdentifier] or a [MeasureCalibrationIdentifier].

class CalibrationSource.Calibration(CalibrationSource):
Inherited Members
CalibrationSource
Calibration
MeasureCalibration
class CalibrationSource.MeasureCalibration(CalibrationSource):
Inherited Members
CalibrationSource
Calibration
MeasureCalibration
class ControlFlowGraph:
def has_dynamic_control_flow(self, /):

Return True if the program has dynamic control flow, i.e. contains a conditional branch instruction.

False does not imply that there is only one basic block in the program. Multiple basic blocks may have non-conditional control flow among them, in which the execution order is deterministic and does not depend on program state. This may be a sequence of basic blocks with fixed JUMPs or without explicit terminators.

def basic_blocks(self, /):

Return a list of all the basic blocks in the control flow graph, in order of definition.

class FrameSet:

A collection of Quil frames (DEFFRAME instructions) with utility methods.

def insert(self, /, identifier, attributes):

Insert a new frame by ID, overwriting any existing one.

def merge(self, /, other):

Merge another [FrameSet] with this one, overwriting any existing keys

def is_empty(self, /):

Return true if this describes no frames.

def to_instructions(self, /):

Return the Quil instructions which describe the contained frames.

def get(self, /, identifier):

Retrieve the FrameAttributes of a Frame by its FrameIdentifier.

def get_keys(self, /):

Return a list of all FrameIdentifiers described by this FrameSet.

def get_all_frames(self, /):

The type of the None singleton.

def intersection(self, /, identifiers):

Return a new FrameSet which describes only the given FrameIdentifiers.

class MaybeCalibrationExpansion:

The result of an attempt to expand an instruction within a [Program]

class MaybeCalibrationExpansion.Expanded(MaybeCalibrationExpansion):
Inherited Members
MaybeCalibrationExpansion
Expanded
Unexpanded
class MaybeCalibrationExpansion.Unexpanded(MaybeCalibrationExpansion):
Inherited Members
MaybeCalibrationExpansion
Expanded
Unexpanded
class MemoryRegion:
size
sharing
class Program:

A Quil Program instance describes a quantum program with metadata used in execution.

This contains not only instructions which are executed in turn on the quantum processor, but also the "headers" used to describe and manipulate those instructions, such as calibrations and frame definitions.

def clone_without_body_instructions(self, /):

Return a deep copy of the Program, but without the body instructions.

def add_instruction(self, /, instruction):

Add an instruction to the end of the program.

Note, parsing extern signatures is deferred here to maintain infallibility of [Program::add_instruction]. This means that invalid PRAGMA EXTERN instructions are still added to the [Program::extern_pragma_map]; duplicate PRAGMA EXTERN names are overwritten.

def dagger(self, /):

Creates a new conjugate transpose of the [Program] by reversing the order of gate instructions and applying the DAGGER modifier to each.

Errors

Errors if any of the instructions in the program are not [Instruction::Gate]

def expand_calibrations(self, /):

Expand any instructions in the program which have a matching calibration, leaving the others unchanged. Return the expanded copy of the program.

Returns an error if any instruction expands into itself.

See [Program::expand_calibrations_with_source_map] for a version that returns a source mapping.

def into_simplified(self, /):

Simplify this program into a new [Program] which contains only instructions and definitions which are executed; effectively, perform dead code removal.

Removes:

  • All calibrations, following calibration expansion
  • Frame definitions which are not used by any instruction such as PULSE or CAPTURE
  • Waveform definitions which are not used by any instruction
  • PRAGMA EXTERN instructions which are not used by any CALL instruction (see [Program::extern_pragma_map]).

When a valid program is simplified, it remains valid.

Note

If you need custom instruction handling during simplification, use [InstructionHandler::simplify_program] instead.

def wrap_in_loop(self, /, loop_count_reference, start_target, end_target, iterations):

Return a copy of the [Program] wrapped in a loop that repeats iterations times.

The loop is constructed by wrapping the body of the program in classical Quil instructions. The given loop_count_reference must refer to an INTEGER memory region. The value at the reference given will be set to iterations and decremented in the loop. The loop will terminate when the reference reaches 0. For this reason your program should not itself modify the value at the reference unless you intend to modify the remaining number of iterations (i.e. to break the loop).

The given start_target and end_target will be used as the entry and exit points for the loop, respectively. You should provide unique [Target]s that won't be used elsewhere in the program.

If iterations is 0, then a copy of the program is returned without any changes.

def resolve_placeholders(self, /):

Resolve [LabelPlaceholder]s and [QubitPlaceholder]s within the program using default resolvers.

See resolve_placeholders_with_custom_resolvers, default_target_resolver, and default_qubit_resolver for more information.

def to_instructions(self, /):

Return a copy of all of the instructions which constitute this [Program].

def parse(input):

Parse a Program from a string.

Errors

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

def copy(self, /):

Return a deep copy of the Program.

def control_flow_graph(self, /):

Return the control flow graph of the program.

def expand_calibrations_with_source_map(self, /):

Expand any instructions in the program which have a matching calibration, leaving the others unchanged. Return the expanded copy of the program and a source mapping describing the expansions made.

def add_instructions(self, /, instructions):

Add a list of instructions to the end of the program.

def filter_instructions(self, /, predicate):

Return a new Program containing only the instructions for which predicate returns true.

def resolve_placeholders_with_custom_resolvers(self, /, *, target_resolver=None, qubit_resolver=None):

Resolve TargetPlaceholders and QubitPlaceholders within the program.

The resolved values will remain unique to that placeholder within the scope of the program. If you provide target_resolver and/or qubit_resolver, those will be used to resolve those values respectively. If your resolver returns None for a particular placeholder, it will not be replaced but will be left as a placeholder. If you do not provide a resolver for a placeholder, a default resolver will be used which will generate a unique value for that placeholder within the scope of the program using an auto-incrementing value (for qubit) or suffix (for target) while ensuring that unique value is not already in use within the program.

def to_unitary(self, /, n_qubits):

Return the unitary of a program.

Errors

Returns an error if the program contains instructions other than Gates.

def to_quil(self, /):

The type of the None singleton.

def to_quil_or_debug(self, /):

The type of the None singleton.

body_instructions
declarations
gate_definitions
calibrations
used_qubits
memory_regions
pragma_extern_map
frames
waveforms
instructions
class ProgramCalibrationExpansion:
source_map

The source mapping describing the expansions made.

program

The program containing the instructions.

class ProgramCalibrationExpansionSourceMap:
def entries(self, /):

The type of the None singleton.

def list_sources_for_target_index(self, /, target_index):

Return all source ranges in the source map which were used to generate the target index.

This is O(n) where n is the number of entries in the map.

def list_sources_for_calibration_used(self, /, calibration_used):

Given a particular calibration (DEFCAL or DEFCAL MEASURE), = return the locations in the source which were expanded using that calibration.

This is O(n) where n is the number of first-level calibration expansions performed.

def list_targets_for_source_index(self, /, source_index):

Return all target ranges which were used to generate the source range.

This is O(n) where n is the number of entries in the map.

class ProgramCalibrationExpansionSourceMapEntry:
def source_location(self, /):

The instruction index within the source program's body instructions.

def target_location(self, /):

The location of the expanded instruction within the target program's body instructions.

class ScheduleSeconds:

A Schedule is a DependencyGraph flattened into a linear sequence of instructions, each of which is assigned a start time and duration.

items

Scheduled items, in an unspecified order.

duration

The schedule duration, in seconds.

This is the maximum end time among all scheduled items.

class ScheduleSecondsItem:

A single item within a schedule, representing a single instruction within a basic block.

instruction_index

The time span during which the instruction is scheduled.

time_span

The index of the instruction within the basic block.

class TimeSpanSeconds:

A time span, in seconds.

duration

The duration of the time span, in seconds.

end

The end time of the time span, in seconds.

This is the sum of the start time and duration.

start

The inclusive start time of the time span, in seconds relative to the start of the scheduling context (such as the basic block).