pyquil.pyqvm module

A pure Python implementation of the Quantum Virtual Machine (QVM).

class pyquil.pyqvm.AbstractQuantumSimulator(n_qubits: int, rs: RandomState | None)[source]

Bases: ABC

An abstract interface for a quantum simulator.


  • n_qubits – Number of qubits to simulate.

  • rs – a RandomState (shared with the owning PyQVM) for doing anything stochastic.

abstract do_gate(gate: Gate) AbstractQuantumSimulator[source]

Perform a gate.


self to support method chaining.

abstract do_gate_matrix(matrix: ndarray, qubits: Sequence[int]) AbstractQuantumSimulator[source]

Apply an arbitrary unitary; not necessarily a named gate.

  • matrix – The unitary matrix to apply. No checks are done

  • qubits – A list of qubits to apply the unitary to.


self to support method chaining.

abstract do_measurement(qubit: int) int[source]

Measure a qubit and collapse the wavefunction.


The measurement result. A 1 or a 0.

abstract do_post_gate_noise(noise_type: str, noise_prob: float, qubits: list[int]) AbstractQuantumSimulator[source]

Apply noise that happens after each gate application.

WARNING! This is experimental and the signature of this interface will likely change.

  • noise_type – The name of the noise type

  • noise_prob – The probability of that noise happening

  • qubits – Apply noise to these qubits.


self to support method chaining

do_program(program: Program) AbstractQuantumSimulator[source]

Perform a sequence of gates contained within a program.


program – The program



abstract expectation(operator: PauliTerm | PauliSum) complex[source]

Compute the expectation of an operator.


operator – The operator


The operator’s expectation value

abstract reset() AbstractQuantumSimulator[source]

Reset the wavefunction to the |000...00> state.


self to support method chaining.

abstract sample_bitstrings(n_samples: int) ndarray[source]

Sample bitstrings from the current state.


n_samples – The number of bitstrings to sample


A numpy array of shape (n_samples, n_qubits)

class pyquil.pyqvm.PyQVM(n_qubits: int, quantum_simulator_type: type[AbstractQuantumSimulator] | None = None, seed: int | None = None, post_gate_noise_probabilities: dict[str, float] | None = None)[source]

Bases: QAM[PyQVM]

A pure python implementation of the Quantum Virtual Machine.

PyQuil’s built-in Quil virtual machine.

This class implements common control flow and plumbing and dispatches the “actual” work to quantum simulators like ReferenceWavefunctionSimulator, ReferenceDensitySimulator, and NumpyWavefunctionSimulator

  • n_qubits – The number of qubits. Typically this results in the allocation of a large ndarray, so be judicious.

  • quantum_simulator_type – A class that can be instantiated to handle the quantum aspects of this QVM. If not specified, the default will be either NumpyWavefunctionSimulator (no noise) or ReferenceDensitySimulator (noise)

  • post_gate_noise_probabilities – A specification of noise model given by probabilities of certain types of noise. The dictionary keys are from “relaxation”, “dephasing”, “depolarizing”, “phase_flip”, “bit_flip”, and “bitphase_flip”. WARNING: experimental. This interface will likely change.

  • seed – An optional random seed for performing stochastic aspects of the QVM.

execute(executable: EncryptedProgram | Program, memory_map: Mapping[str, Sequence[int] | Sequence[float]] | None = None, **__: Any) PyQVM[source]

Execute a program on the PyQVM.

Note that the state of the instance is reset on each call to execute.


self to support method chaining.

execute_once(program: Program) PyQVM[source]

Execute one outer loop of a program on the PyQVM without re-initializing its state.

Note that the PyQVM is stateful. Subsequent calls to execute_once() will not automatically reset the wavefunction or the classical RAM. If this is desired, consider starting your program with RESET.


self to support method chaining.

execute_with_memory_map_batch(executable: EncryptedProgram | Program, memory_maps: Iterable[Mapping[str, Sequence[int] | Sequence[float]]], **__: Any) list[PyQVM][source]

Operation is not supported by PyQVM as the state of the instance is reset at the start of each execution.

find_label(label: Label | LabelPlaceholder) int[source]

Iterate over the program and find a JumpTarget that has a Label matching the input label.


label – Label object to search for in program


Program index where label is found

get_result(execute_response: PyQVM) QAMExecutionResult[source]

Return results from the PyQVM according to the common QAM API.

Note that while the execute_response is not used, it’s accepted in order to conform to that API; it’s unused because the PyQVM, unlike other QAM’s, is itself stateful.

read_memory(*, region_name: str) ndarray[source]

Read memory from the PyQVM.

transition() bool[source]

Perform a QAM-like transition.

This function assumes program and program_counter instance variables are set appropriately, and that the wavefunction simulator and classical memory ram instance variables are in the desired QAM input state.


whether the QAM should halt after this transition.