class pyquil.quil.Program(*instructions)[source]

A list of pyQuil instructions that comprise a quantum program.

>>> from pyquil import Program
>>> from pyquil.gates import H, CNOT
>>> p = Program()
>>> p += H(0)
>>> p += CNOT(0, 1)


instructions Fill in any placeholders and return a list of quil AbstractInstructions.
defined_gates A list of defined gates on the program.
out() Serializes the Quil program to a string suitable for submitting to the QVM or QPU.
get_qubits([indices]) Returns all of the qubit indices used in this program, including gate applications and allocated qubits.
is_protoquil() Protoquil programs may only contain gates, Pragmas, and RESET.

Program Construction

__iadd__(other) Concatenate two programs together using +=, returning a new one.
__add__(other) Concatenate two programs together, returning a new one.
inst(*instructions) Mutates the Program object by appending new instructions.
gate(name, params, qubits) Add a gate to the program.
defgate(name, matrix[, parameters]) Define a new static gate.
define_noisy_gate(name, qubit_indices, kraus_ops) Overload a static ideal gate with a noisy one defined in terms of a Kraus map.
define_noisy_readout(qubit, p00, p11) For this program define a classical bit flip readout error channel parametrized by p00 and p11.
no_noise() Prevent a noisy gate definition from being applied to the immediately following Gate instruction.
measure(qubit, classical_reg) Measures a qubit at qubit_index and puts the result in classical_reg
reset([qubit_index]) Reset all qubits or just a specific qubit at qubit_index.
measure_all(*qubit_reg_pairs) Measures many qubits into their specified classical bits, in the order they were entered.
alloc() Get a new qubit.
declare(name[, memory_type, memory_size, …]) DECLARE a quil variable
wrap_in_numshots_loop(shots) Wraps a Quil program in a loop that re-runs the same program many times.

Control Flow

while_do(classical_reg, q_program) While a classical register at index classical_reg is 1, loop q_program
if_then(classical_reg, if_program[, …]) If the classical register at index classical reg is 1, run if_program, else run else_program.

Utility Methods

copy() Perform a shallow copy of this program.
pop() Pops off the last instruction.
dagger([inv_dict, suffix]) Creates the conjugate transpose of the Quil program.
__getitem__(index) Allows indexing into the program to get an action.

Utility Functions


Takes a program which contains qubit placeholders and provides a mapping to the integers 0 through N-1.

The output of this function is suitable for input to address_qubits().

Parameters:program (Program) – A program containing qubit placeholders
Return type:Dict[Union[Qubit, QubitPlaceholder], Qubit]
Returns:A dictionary mapping qubit placeholder to an addressed qubit from 0 through N-1.
pyquil.quil.address_qubits(program, qubit_mapping=None)[source]

Takes a program which contains placeholders and assigns them all defined values.

Either all qubits must be defined or all undefined. If qubits are undefined, you may provide a qubit mapping to specify how placeholders get mapped to actual qubits. If a mapping is not provided, integers 0 through N are used.

This function will also instantiate any label placeholders.

  • program – The program.
  • qubit_mapping – A dictionary-like object that maps from QubitPlaceholder to Qubit or int (but not both).

A new Program with all qubit and label placeholders assigned to real qubits and labels.


Takes an iterable of instructions which may contain label placeholders and assigns them all defined values.

Return type:List[AbstractInstruction]
Returns:list of instructions with all label placeholders assigned to real labels.

Implicitly declare a register named ro for backwards compatibility with Quil 1.

There used to be one un-named hunk of classical memory. Now there are variables with declarations. Instead of:


You must now measure into a named register, idiomatically:

MEASURE 0 ro[0]

The MEASURE instruction will emit this (with a deprecation warning) if you’re still using bare integers for classical addresses. However, you must also declare memory in the new scheme:

MEASURE 0 ro[0]

This method will determine if you are in “backwards compatibility mode” and will declare a read-out ro register for you. If you program contains any DECLARE commands or if it does not have any MEASURE x ro[x], this will not do anything.

This behavior is included for backwards compatibility and will be removed in future releases of PyQuil. Please DECLARE all memory including ro.

Return type:List[AbstractInstruction]
pyquil.quil.merge_with_pauli_noise(prog_list, probabilities, qubits)[source]

Insert pauli noise channels between each item in the list of programs. This noise channel is implemented as a single noisy identity gate acting on the provided qubits. This method does not rely on merge_programs and so avoids the inclusion of redundant Kraus Pragmas that would occur if merge_programs was called directly on programs with distinct noisy gate definitions.

  • prog_list (Iterable[Program]) – an iterable such as a program or a list of programs. If a program is provided, a single noise gate will be applied after each gate in the program. If a list of programs is provided, the noise gate will be applied after each program.
  • probabilities (Sequence[float]) – The 4^num_qubits list of probabilities specifying the desired pauli channel. There should be either 4 or 16 probabilities specified in the order I, X, Y, Z or II, IX, IY, IZ, XI, XX, XY, etc respectively.
  • qubits (Sequence[int]) – a list of the qubits that the noisy gate should act on.
Return type:



A single program with noisy gates inserted between each element of the program list.


Merges a list of pyQuil programs into a single one by appending them in sequence. If multiple programs in the list contain the same gate and/or noisy gate definition with identical name, this definition will only be applied once. If different definitions with the same name appear multiple times in the program list, each will be applied once in the order of last occurrence.

Parameters:prog_list (Sequence[Program]) – A list of pyquil programs
Return type:Program
Returns:a single pyQuil program

Returns a sorted list of classical addresses found in the MEASURE instructions in the program.

Parameters:program (Program) – The program from which to get the classical addresses.
Return type:Dict[str, List[int]]
Returns:A mapping from memory region names to lists of offsets appearing in the program.

Move all the DECLARE statements to the top of the program. Return a fresh obejct.

Parameters:program (Program) – Perhaps jumbled program.
Return type:Program
Returns:Program with DECLAREs all at the top and otherwise the same sorted contents.

Ensure that a program is valid ProtoQuil, otherwise raise a ValueError. Protoquil is a subset of Quil which excludes control flow and classical instructions.

Parameters:program (Program) – The Quil program to validate.
Return type:None

Parse a raw Quil program and return a corresponding list of PyQuil objects.

Parameters:quil (str) – a single or multiline Quil program
Return type:List[AbstractInstruction]
Returns:list of instructions

Parse a raw Quil program and return a PyQuil program.

Parameters:quil (str) – a single or multiline Quil program
Return type:Program
Returns:PyQuil Program object