pyquil.api

Module for facilitating connections to the QVM / QPU.

class pyquil.api.QVMConnection(device=None, sync_endpoint='https://api.rigetti.com', async_endpoint='https://job.rigetti.com/beta', api_key=None, user_id=None, use_queue=False, ping_time=0.1, status_time=2, gate_noise=None, measurement_noise=None, random_seed=None)

Bases: object

Represents a connection to the QVM.

expectation(prep_prog, operator_programs=None, needs_compilation=False, isa=None)

Calculate the expectation value of operators given a state prepared by prep_program.

Note:

If the execution of quil_program is non-deterministic, i.e., if it includes measurements and/or noisy quantum gates, then the final wavefunction from which the expectation values are computed itself only represents a stochastically generated sample. The expectations returned from different expectation calls will then generally be different.
Parameters:
  • prep_prog (Program) – Quil program for state preparation.
  • operator_programs (list) – A list of PauliTerms. Default is Identity operator.
  • needs_compilation (bool) – If True, preprocesses the job with the compiler.
  • isa (ISA) – If set, compiles to this target ISA.
Returns:

Expectation value of the operators.
Return type:

float
expectation_async(prep_prog, operator_programs=None, needs_compilation=False, isa=None)

Similar to expectation except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

get_job(job_id)

Given a job id, return information about the status of the job

Parameters:job_id (str) – job id
Returns:Job object with the status and potentially results of the job
Return type:Job
ping()
run(quil_program, classical_addresses, trials=1, needs_compilation=False, isa=None)

Run a Quil program multiple times, accumulating the values deposited in a list of classical addresses.

Parameters:
  • quil_program (Program) – A Quil program.
  • classical_addresses (list|range) – A list of addresses.
  • trials (int) – Number of shots to collect.
  • needs_compilation (bool) – If True, preprocesses the job with the compiler.
  • isa (ISA) – If set, compiles to this target ISA.
Returns:

A list of lists of bits. Each sublist corresponds to the values in classical_addresses.
Return type:

list
run_and_measure(quil_program, qubits, trials=1, needs_compilation=False, isa=None)

Run a Quil program once to determine the final wavefunction, and measure multiple times.

Note:

If the execution of quil_program is non-deterministic, i.e., if it includes measurements and/or noisy quantum gates, then the final wavefunction from which the returned bitstrings are sampled itself only represents a stochastically generated sample and the outcomes sampled from different run_and_measure calls generally sample different bitstring distributions.
Parameters:
  • quil_program (Program) – A Quil program.
  • qubits (list|range) – A list of qubits.
  • trials (int) – Number of shots to collect.
  • needs_compilation (bool) – If True, preprocesses the job with the compiler.
  • isa (ISA) – If set, compiles to this target ISA.
Returns:

A list of a list of bits.
Return type:

list
run_and_measure_async(quil_program, qubits, trials=1, needs_compilation=False, isa=None)

Similar to run_and_measure except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

run_async(quil_program, classical_addresses, trials=1, needs_compilation=False, isa=None)

Similar to run except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

wait_for_job(job_id, ping_time=None, status_time=None)

Wait for the results of a job and periodically print status

Parameters:
  • job_id – Job id
  • ping_time – How often to poll the server. Defaults to the value specified in the constructor. (0.1 seconds)
  • status_time – How often to print status, set to False to never print status. Defaults to the value specified in the constructor (2 seconds)
Returns:

Completed Job
wavefunction(quil_program, classical_addresses=None, needs_compilation=False, isa=None)

Simulate a Quil program and get the wavefunction back.

Note:

If the execution of quil_program is non-deterministic, i.e., if it includes measurements and/or noisy quantum gates, then the final wavefunction from which the returned bitstrings are sampled itself only represents a stochastically generated sample and the wavefunctions returned by different wavefunction calls will generally be different.
Parameters:
  • quil_program (Program) – A Quil program.
  • classical_addresses (list|range) – An optional list of classical addresses.
  • needs_compilation – If True, preprocesses the job with the compiler.
  • isa – If set, compiles to this target ISA.
Returns:

A tuple whose first element is a Wavefunction object, and whose second element is the list of classical bits corresponding to the classical addresses.
Return type:

Wavefunction
wavefunction_async(quil_program, classical_addresses=None, needs_compilation=False, isa=None)

Similar to wavefunction except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

class pyquil.api.QPUConnection(device=None, async_endpoint='https://job.rigetti.com/beta', api_key=None, user_id=None, ping_time=0.1, status_time=2, device_name=None)

Bases: object

Represents a connection to the QPU (Quantum Processing Unit)

get_job(job_id)

Given a job id, return information about the status of the job

Parameters:job_id (str) – job id
Returns:Job object with the status and potentially results of the job
Return type:Job
run(quil_program, classical_addresses, trials=1, needs_compilation=True, isa=None)

Run a pyQuil program on the QPU and return the values stored in the classical registers designated by the classical_addresses parameter. The program is repeated according to the number of trials provided to the run method. This functionality is in beta.

It is important to note that our QPUs currently only allow a single set of simultaneous readout pulses on all qubits in the QPU at the end of the program. This means that missing or duplicate MEASURE instructions do not change the pulse program, but instead only contribute to making a less rich or richer mapping, respectively, between classical and qubit addresses.

Parameters:
  • quil_program (Program) – Pyquil program to run on the QPU
  • classical_addresses (list|range) – Classical register addresses to return
  • trials (int) – Number of times to run the program (a.k.a. number of shots)
  • needs_compilation (bool) – If True, preprocesses the job with the compiler.
  • isa (ISA) – If set, specifies a custom ISA to compile to. If left unset, Forest uses the default ISA associated to this QPU device.
Returns:

A list of a list of classical registers (each register contains a bit)
Return type:

list
run_and_measure(quil_program, qubits, trials=1, needs_compilation=True, isa=None)

Similar to run, except for how MEASURE operations are dealt with. With run, users are expected to include MEASURE operations in the program if they want results back. With run_and_measure, users provide a pyquil program that does not have MEASURE instructions, and also provide a list of qubits to measure. All qubits in this list will be measured at the end of the program, and their results stored in corresponding classical registers.

Parameters:
  • quil_program (Program) – Pyquil program to run on the QPU
  • qubits (list|range) – The list of qubits to measure
  • trials (int) – Number of times to run the program (a.k.a. number of shots)
  • needs_compilation (bool) – If True, preprocesses the job with the compiler.
  • isa (ISA) – If set, specifies a custom ISA to compile to. If left unset, Forest uses the default ISA associated to this QPU device.
Returns:

A list of a list of classical registers (each register contains a bit)
Return type:

list
run_and_measure_async(quil_program, qubits, trials, needs_compilation=True, isa=None)

Similar to run_and_measure except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

run_async(quil_program, classical_addresses, trials=1, needs_compilation=True, isa=None)

Similar to run except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

wait_for_job(job_id, ping_time=None, status_time=None)

Wait for the results of a job and periodically print status

Parameters:
  • job_id – Job id
  • ping_time – How often to poll the server. Defaults to the value specified in the constructor. (0.1 seconds)
  • status_time – How often to print status, set to False to never print status. Defaults to the value specified in the constructor (2 seconds)
Returns:

Completed Job
class pyquil.api.CompilerConnection(device=None, sync_endpoint='https://api.rigetti.com', async_endpoint='https://job.rigetti.com/beta', api_key=None, user_id=None, use_queue=False, ping_time=0.1, status_time=2, isa_source=None, specs_source=None)

Bases: object

Represents a connection to the Quil compiler.

compile(quil_program)

Sends a Quil program to the Forest compiler and returns the resulting compiled Program.

Parameters:
  • quil_program (Program) – Quil program to be compiled.
  • isa (ISA) – ISA to target.
Returns:

The compiled Program object.
Return type:

Program
compile_async(quil_program)

Similar to compile except that it returns a job id and doesn’t wait for the program to be executed. See https://go.rigetti.com/connections for reasons to use this method.

get_job(job_id)

Given a job id, return information about the status of the job

Parameters:job_id (str) – job id
Returns:Job object with the status and potentially results of the job
Return type:Job
wait_for_job(job_id, ping_time=None, status_time=None)

Wait for the results of a job and periodically print status

Parameters:
  • job_id – Job id
  • ping_time – How often to poll the server. Defaults to the value specified in the constructor. (0.1 seconds)
  • status_time – How often to print status, set to False to never print status. Defaults to the value specified in the constructor (2 seconds)
Returns:

Completed Job
class pyquil.api.Job(raw, machine)

Bases: object

Represents the current status of a Job in the Forest queue.

Job statuses are initially QUEUED when QVM/QPU resources are not available They transition to RUNNING when they have been started Finally they are marked as FINISHED, ERROR, or CANCELLED once completed

compiled_quil()

If the Quil program associated with the Job was compiled (e.g., to translate it to the QPU’s natural gateset) return this compiled program.

Return type:Optional[Program]
decode()
estimated_time_left_in_queue()

If the job is queued, this will return how much time left (in seconds) is estimated before execution.

gate_depth()

If the job has metadata and this contains the gate depth, return this, otherwise None. The gate depth is a measure of how long a quantum program takes. On a non-fault-tolerant QPU programs with a low gate depth have a higher chance of succeeding.

Return type:Optional[int]
gate_volume()

If the job has metadata and this contains the gate volume, return this, otherwise None. On a non-fault-tolerant QPU programs with a low gate volume have a higher chance of succeeding. This is a less sensitive measure than gate depth.

Return type:Optional[int]
get()
is_compiling()

Is the job actively compiling?

is_done()

Has the job completed yet?

is_queued()

Is the job still in the Forest queue?

is_queued_for_compilation()

Is the job still in the Forest compilation queue?

is_running()

Is the job currently running?

job_id

Job id :rtype: str

multiqubit_gate_depth()

If the job has metadata and this contains the multiqubit gate depth, return this, otherwise None. The multiqubit gate depth is a measure of how inaccurately a quantum program will behave on nonideal hardware. On a non-fault-tolerant QPU programs with a low gate depth have a higher chance of succeeding.

Return type:Optional[int]
position_in_queue()

If the job is queued, this will return how many other jobs are ahead of it. If the job is not queued, this will return None

program_fidelity()

If the job has metadata and this contains a job program fidelity estimate, return this, otherwise None. This is a number between 0 and 1; a higher value means more likely odds of a meaningful answer.

Return type:Optional[float]
result()

The result of the job if available throws ValueError is result is not available yet throws ApiError if server returned an error indicating program execution was not successful or if the job was cancelled

topological_swaps()

If the program could not be mapped directly to the QPU because of missing links in the two-qubit gate connectivity graph, the compiler must insert topological swap gates. Return the number of such topological swaps.

Return type:Optional[int]
pyquil.api.get_devices(async_endpoint='https://job.rigetti.com/beta', api_key=None, user_id=None, as_dict=False)

Get a list of currently available devices. The arguments for this method are the same as those for QPUConnection. Note that this method will only work for accounts that have QPU access.

Returns:Set or Dictionary (keyed by device name) of all available devices.
Return type:Set|Dict