pyquil.api

Module for facilitating connections to the QVM / QPU.

class pyquil.api.JobConnection(endpoint=None, api_key=None, user_id=None, gate_noise=None, measurement_noise=None, num_retries=3, random_seed=None)

Bases: object

Represents a connection to the QVM.

bit_string_probabilities(quil_program)

Simulate a Quil program and get outcome probabilities back.

Parameters:quil_program (Program) – A Quil program.
Returns:A dictionary with outcomes as keys and probabilities as values.
Return type:dict
expectation(prep_prog, operator_programs=None)

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

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

get_job(job_result)
Parameters:job_result (JobResult) –
Returns:fills in the result in the JobResult object
ping()

Ping Forest.

Returns:Should get “ok” back.
Return type:string
post_job(program, headers=None)

Post a Job to the Forest endpoint.

Parameters:
  • program
  • headers
Returns:

A non-error response.

post_json(jd, headers=None, route='')

Post JSON to the Forest endpoint.

Parameters:
  • jd (dict) – JSON.
  • headers (dict) – The headers for the post request.
  • route (str) – The route to append to the endpoint, e.g. “/job”
Returns:

A non-error response.

process_response(res)
Parameters:res – A response object from a request
Returns:A JobResult filled in with the response data
Return type:JobResult
process_wavefunction_response(res, payload)

Wavefunctions are processed differently as they are byte encoded. :param res: A response object from a request :param payload: The payload that was used to make that request :return: A WavefunctionResult with the response data filled in :rtype: WavefunctionResult

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

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

A list of a list of bits.

Return type:

list

version()

Query the QVM version.

Returns:None
wavefunction(quil_program, classical_addresses=None)

Simulate a Quil program and get the wavefunction back.

Parameters:
  • quil_program (Program) – A Quil program.
  • classical_addresses (list) – 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:

tuple

wrap_payload_into_message(payload)

Wraps the payload into a Forest query.

Parameters:payload (dict) –
Returns:A JSON dictionary to post as a Forest query.
class pyquil.api.SyncConnection(endpoint=None, api_key=None, user_id=None, gate_noise=None, measurement_noise=None, num_retries=3, random_seed=None)

Bases: pyquil.api.JobConnection

The SyncConnection makes a synchronous connection to the Forest API.

get_job(job_result)
ping()

Ping the QVM. :return: Should get “pong” back. :rtype: string

post_job(program, headers=None)

Post a synchronous Job to the QVM endpoint.

Parameters:
  • program
  • headers
Returns:

A non-error response.

process_response(res)
Parameters:res – A response object from a request
Returns:The json dictionary of the response
Return type:dict
process_wavefunction_response(res, payload)
Parameters:res – A response object from a request
Returns:The json dictionary of the response
Return type:dict
version()

Query the QVM version. :return: The current version of the QVM. :rtype: string

pyquil.api.add_noise_to_payload(payload, gate_noise, measurement_noise)

Set the gate noise and measurement noise of a payload.

Parameters:
  • payload (dict) – Dictionary of run information.
  • gate_noise – Probability of a noise gate being applied at each time step.
  • measurement_noise – Probability of a noise gate being applied before measurement.
pyquil.api.add_rng_seed_to_payload(payload, seed)

Add a random seed to the payload.

Parameters:
  • payload – JSON payload.
  • seed (int) – A non-negative integer.
pyquil.api.validate_run_items(run_items)

Check the validity of classical addresses / qubits for the payload.

Parameters:run_items (list) – List of classical addresses or qubits to be validated.