cirq_ionq.service.Service

A class to access IonQ's API.

cirq_ionq.service.Service(
    remote_host: (str | None) = None,
    api_key: (str | None) = None,
    default_target: (str | None) = None,
    api_version='v0.4',
    max_retry_seconds: int = 3600,
    job_settings: (dict | None) = None,
    verbose=False
)

To access the API, this class requires a remote host url and an API key. These can be specified in the constructor via the parameters remote_host and api_key. Alternatively these can be specified by setting the environment variables IONQ_REMOTE_HOST and IONQ_API_KEY.

remote_host The location of the api in the form of an url. If this is None, then this instance will use the environment variable IONQ_REMOTE_HOST. If that variable is not set, then this uses https://api.ionq.co/{api_version}, where {api_version} is the api_version specified below.
api_key A string key which allows access to the api. If this is None, then this instance will use the environment variable IONQ_API_KEY. If that variable is not set, then this will raise an EnvironmentError.
default_target Which target to default to using. If set to None, no default is set and target must always be specified in calls. If set, then this default is used, unless a target is specified for a given call. Supports either 'qpu' or 'simulator'.
api_version Version of the api. Defaults to 'v0.4'.
max_retry_seconds The number of seconds to retry calls for. Defaults to one hour.
job_settings A dictionary of settings which can override behavior for circuits when run on IonQ hardware.
verbose Whether to print to stdio and stderr on retriable errors.

OSError If the api_key is None and has no corresponding environment variable set. This is actually an EnvironmentError which is equal to an OSError.

Methods

create_batch_job

View source

create_batch_job(
    circuits: list[cirq.AbstractCircuit],
    repetitions: int = 100,
    name: (str | None) = None,
    target: (str | None) = None,
    compilation: (dict | None) = None,
    error_mitigation: (dict | None) = None,
    noise: (dict | None) = None,
    metadata: (dict | None) = None,
    dry_run: bool = False,
    extra_query_params: (dict | None) = None
) -> job.Job

Create a new job to run the given circuit.

Args
circuits The circuits to run.
repetitions The number of times to repeat the circuit. Defaults to 100.
name An optional name for the created job. Different from the job_id.
target Where to run the job. Can be 'qpu' or 'simulator'.
compilation dict

settings for compilation when creating a job, default values: {"opt": 0, "precision": "1E-3"}

error_mitigation dict

settings for error mitigation when creating a job. Defaults to None. Not available on all backends. Set by default on some hardware systems. See: API Job Creation <<a href="https://docs.ionq.com/api-reference/v0.4/jobs/create-job">https://docs.ionq.com/api-reference/v0.4/jobs/create-job</a>> and: Debiasing and Sharpening <<a href="https://ionq.com/resources/debiasing-and-sharpening">https://ionq.com/resources/debiasing-and-sharpening</a>> Valid keys include: debiasing False or True.

- 'debiasing': A boolean indicating whether to use the debiasing technique for
  aggregating results. This technique is used to reduce the bias in the results
  caused by measurement error and can improve the accuracy of the output.

sharpen A boolean that determines how to aggregate error mitigated. If True, apply majority vote mitigation; if False, apply average mitigation. See Debiasing and Sharpening <<a href="https://ionq.com/resources/debiasing-and-sharpening">https://ionq.com/resources/debiasing-and-sharpening</a>>
noise dict

{"model": str (required), "seed": int (optional)}. Defaults to None. Available noise models: ideal, aria-1, aria-2, forte-1, forte-enterprise-1

dry_run If True, the job will be submitted by the API client but not processed remotely. Useful for obtaining cost estimates. Defaults to False.
metadata dict

optional metadata to attach to the job. Defaults to None.

extra_query_params Specify any parameters to include in the request.

Returns
A cirq_ionq.IonQJob which can be queried for status or results.

Raises
IonQException If there was an error accessing the API.

create_job

View source

create_job(
    circuit: cirq.AbstractCircuit,
    repetitions: int = 100,
    name: (str | None) = None,
    target: (str | None) = None,
    compilation: (dict | None) = None,
    error_mitigation: (dict | None) = None,
    noise: (dict | None) = None,
    metadata: (dict | None) = None,
    dry_run: bool = False,
    extra_query_params: (dict | None) = None
) -> job.Job

Create a new job to run the given circuit.

Args
circuit The circuit to run.
repetitions The number of times to repeat the circuit. Defaults to 100.
name An optional name for the created job. Different from the job_id.
target Where to run the job. Can be 'qpu' or 'simulator'.
compilation dict

settings for compilation when creating a job, default values: {"opt": 0, "precision": "1E-3"}

error_mitigation dict

settings for error mitigation when creating a job. Defaults to None. Not available on all backends. Set by default on some hardware systems. See: API Job Creation <<a href="https://docs.ionq.com/api-reference/v0.4/jobs/create-job">https://docs.ionq.com/api-reference/v0.4/jobs/create-job</a>> and: Debiasing and Sharpening <<a href="https://ionq.com/resources/debiasing-and-sharpening">https://ionq.com/resources/debiasing-and-sharpening</a>> Valid keys include: debiasing False or True.

- 'debiasing': A boolean indicating whether to use the debiasing technique for
  aggregating results. This technique is used to reduce the bias in the results
  caused by measurement error and can improve the accuracy of the output.

sharpen A boolean that determines how to aggregate error mitigated. If True, apply majority vote mitigation; if False, apply average mitigation. See Debiasing and Sharpening <<a href="https://ionq.com/resources/debiasing-and-sharpening">https://ionq.com/resources/debiasing-and-sharpening</a>>
noise dict

{"model": str (required), "seed": int (optional)}. Defaults to None. Available noise models: ideal, aria-1, aria-2, forte-1, forte-enterprise-1

dry_run If True, the job will be submitted by the API client but not processed remotely. Useful for obtaining cost estimates. Defaults to False.
metadata dict

optional metadata to attach to the job. Defaults to None.

extra_query_params Specify any parameters to include in the request.

Returns
A cirq_ionq.IonQJob which can be queried for status or results.

Raises
IonQException If there was an error accessing the API.

get_current_calibration

View source

get_current_calibration() -> calibration.Calibration

Gets the most recent calbration via the API.

Note that currently there is only one target, so this returns the calibration of that target.

The calibration include device specification (number of qubits, connectivity), as well as fidelities and timings of gates.

Returns
A cirq_ionq.Calibration containing the device specification and calibrations.

Raises
IonQException If there was an error accessing the API.

get_job

View source

get_job(
    job_id: str
) -> job.Job

Gets a job that has been created on the IonQ API.

Args
job_id The UUID of the job. Jobs are assigned these numbers by the server during the creation of the job.

Returns
A cirq_ionq.IonQJob which can be queried for status or results.

Raises
IonQNotFoundException If there was no job with the given job_id.
IonQException If there was an error accessing the API.

list_calibrations

View source

list_calibrations(
    start: (datetime.datetime | None) = None,
    end: (datetime.datetime | None) = None,
    limit: int = 100,
    batch_size: int = 1000
) -> Sequence[calibration.Calibration]

List calibrations via the API.

Args
start If supplied, only calibrations after this date and time. Accurate to seconds.
end If supplied, only calibrations before this date and time. Accurate to seconds.
limit The maximum number of calibrations to return.
batch_size The size of the batches requested per http GET call.

Returns
A sequence of calibrations.

Raises
IonQException If there was an error accessing the API.

list_jobs

View source

list_jobs(
    status: (str | None) = None, limit: int = 100, batch_size: int = 1000
) -> Sequence[job.Job]

Lists jobs that have been created on the IonQ API.

Args
status If supplied will filter to only jobs with this status.
limit The maximum number of jobs to return.
batch_size The size of the batches requested per http GET call.

Returns
A sequence of jobs.

Raises
IonQException If there was an error accessing the API.

run

View source

run(
    circuit: cirq.Circuit,
    repetitions: int,
    name: (str | None) = None,
    target: (str | None) = None,
    param_resolver: cirq.ParamResolverOrSimilarType = cirq.ParamResolver({}),
    seed: cirq.RANDOM_STATE_OR_SEED_LIKE = None,
    compilation: (dict | None) = None,
    error_mitigation: (dict | None) = None,
    noise: (dict | None) = None,
    metadata: (dict | None) = None,
    dry_run: bool = False,
    sharpen: (bool | None) = None,
    extra_query_params: (dict | None) = None
) -> cirq.Result

Run the given circuit on the IonQ API.

Args
circuit The circuit to run.
repetitions The number of times to run the circuit.
name An optional name for the created job. Different from the job_id.
target Where to run the job. Can be 'qpu' or 'simulator'.
param_resolver A cirq.ParamResolver to resolve parameters in circuit.
seed If the target is simulation the seed for generating results. If None, this will be np.random, if an int, will be np.random.RandomState(int), otherwise must be a modulate similar to np.random.
compilation dict

settings for compilation when creating a job, default values: {"opt": 0, "precision": "1E-3"}

error_mitigation dict

settings for error mitigation when creating a job. Defaults to None. Not available on all backends. Set by default on some hardware systems. See: API Job Creation <https://docs.ionq.com/api-reference/v0.4/jobs/create-job> and: Debiasing and Sharpening <https://ionq.com/resources/debiasing-and-sharpening> Valid keys include: debiasing False or True.

- 'debiasing': A boolean indicating whether to use the debiasing technique for
  aggregating results. This technique is used to reduce the bias in the results
  caused by measurement error and can improve the accuracy of the output.

sharpen A boolean that determines how to aggregate error mitigated. If True, apply majority vote mitigation; if False, apply average mitigation. See: Debiasing and Sharpening <https://ionq.com/resources/debiasing-and-sharpening>
noise dict

{"model": str (required), "seed": int (optional)}. Defaults to None. Available noise models: ideal, aria-1, aria-2, forte-1, forte-enterprise-1

dry_run If True, the job will be submitted by the API client but not processed remotely. Useful for obtaining cost estimates. Defaults to False.
metadata dict

optional metadata to attach to the job. Defaults to None.

extra_query_params Specify any parameters to include in the request.

Returns
A cirq.Result for running the circuit.

run_batch

View source

run_batch(
    circuits: list[cirq.AbstractCircuit],
    repetitions: int,
    name: (str | None) = None,
    target: (str | None) = None,
    param_resolver: cirq.ParamResolverOrSimilarType = cirq.ParamResolver({}),
    seed: cirq.RANDOM_STATE_OR_SEED_LIKE = None,
    compilation: (dict | None) = None,
    error_mitigation: (dict | None) = None,
    noise: (dict | None) = None,
    metadata: (dict | None) = None,
    dry_run: bool = False,
    sharpen: (bool | None) = None,
    extra_query_params: (dict | None) = None
) -> list[cirq.Result]

Run the given circuits on the IonQ API.

Args
circuits The circuits to run.
repetitions The number of times to run each circuits.
name An optional name for the created job. Different from the job_id.
target Where to run the job. Can be 'qpu' or 'simulator'.
param_resolver A cirq.ParamResolver to resolve parameters in circuit.
seed If the target is simulation the seed for generating results. If None, this will be np.random, if an int, will be np.random.RandomState(int), otherwise must be a modulate similar to np.random.
compilation dict

settings for compilation when creating a job, default values: {"opt": 0, "precision": "1E-3"}

error_mitigation dict

settings for error mitigation when creating a job. Defaults to None. Not available on all backends. Set by default on some hardware systems. See: API Job Creation <https://docs.ionq.com/api-reference/v0.4/jobs/create-job> and: Debiasing and Sharpening <https://ionq.com/resources/debiasing-and-sharpening> Valid keys include: debiasing False or True.

- 'debiasing': A boolean indicating whether to use the debiasing technique for
  aggregating results. This technique is used to reduce the bias in the results
  caused by measurement error and can improve the accuracy of the output.

sharpen A boolean that determines how to aggregate error mitigated. If True, apply majority vote mitigation; if False, apply average mitigation. See Debiasing and Sharpening <https://ionq.com/resources/debiasing-and-sharpening>
noise dict

{"model": str (required), "seed": int (optional)}. Defaults to None. Available noise models: ideal, aria-1, aria-2, forte-1, forte-enterprise-1

dry_run If True, the job will be submitted by the API client but not processed remotely. Useful for obtaining cost estimates. Defaults to False.
metadata dict

optional metadata to attach to the job. Defaults to None.

extra_query_params Specify any parameters to include in the request.

Returns
A a list of cirq.Result for running the circuit.

sampler

View source

sampler(
    target: (str | None) = None, seed: cirq.RANDOM_STATE_OR_SEED_LIKE = None
)

Returns a cirq.Sampler object for accessing the sampler interface.

Args
target The target to sample against. Either this or default_target on this service must be specified. If this is None, uses the default_target. If both default_target and target are specified, uses target.
seed If the target is simulation the seed for generating results. If None, this will be np.random, if an int, will be np.random.RandomState(int), otherwise must be a modulate similar to np.random.

Returns
A cirq.Sampler for the IonQ API.