pyquil.api

Module for facilitating connections to the QVM / QPU.

class pyquil.api.QVMConnection(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)

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.
Returns:

Expectation value of the operators.

Return type:

float

expectation_async(prep_prog, operator_programs=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)

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.
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)

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.
Returns:

A list of a list of bits.

Return type:

list

run_and_measure_async(quil_program, qubits, trials=1)

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)

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)

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.
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)

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_name=None, async_endpoint='https://job.rigetti.com/beta', api_key=None, user_id=None, ping_time=0.1, status_time=2)

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)

Run a pyQuil program on the QPU. This functionality is in beta.

Parameters:
  • quil_program (Program) – Quil program to run on the QPU
  • classical_addresses (list|range) – Currently unused
  • trials (int) – Number of shots to take
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)

Run a pyQuil program on the QPU multiple times, measuring all the qubits in the QPU simultaneously at the end of the program each time. This functionality is in beta.

Parameters:
  • quil_program (Program) – A Quil program.
  • qubits (list|range) – The list of qubits to measure
  • trials (int) – Number of shots to collect.
Returns:

A list of a list of bits.

Return type:

list

run_and_measure_async(quil_program, qubits, trials)

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)

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.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()
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]
get()
is_done()

Has the job completed yet?

is_queued()

Is the job still in the Forest queue?

is_running()

Is the job currently running?

job_id

Job id :rtype: str

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

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)

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 of online and offline devices
Return type:set