Skip to content

Minor updates for the IonQ Service page #5607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 24, 2022
Merged

Minor updates for the IonQ Service page #5607

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
468afc2
Minor updates for the IonQ Service page
dstrain115 Jun 24, 2022
ba312fe
Merge branch 'master' into docs_ionq
dstrain115 Jun 24, 2022
14e679e
Merge branch 'master' into docs_ionq
CirqBot Jun 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions docs/hardware/ionq/service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# IonQ API Service

IonQ's API provides a way to execute quantum circuits on IonQ's trapped ion quantum computers
or on cloud based simulators. As of April 2021 this access is restricted to partners.
or on cloud based simulators. As of April 2021, this access is restricted to partners.
See [Access and Authentication](access.md) for details of access.

## Service class
Expand All @@ -10,14 +10,16 @@ The main entrance for accessing IonQ's API are instances of the `cirq_ionq.Servi
These objects need to be initialized with an api key, see
[Access and Authentication](access.md) for details.

The basic flow of running a quantum circuit in a blocking manner is
The basic steps for running a quantum circuit in a blocking manner are:

1. Create a circuit to run.
1. Create a `cirq_ionq.Service` with proper authentication and endpoints.
2. Create a `cirq_ionq.Service` with proper authentication and endpoints.
3. Submit this circuit to run on the service and await the results of this call.
(Or alternatively use asynchronous jobs and processing)
4. Transform the results in a form that is most useful for your analysis.

Here is a simple example of this flow
Here is a simple example of this flow:

```python
import cirq
import cirq_ionq as ionq
Expand All @@ -31,20 +33,20 @@ circuit = cirq.Circuit(

# Create a ionq.Service object.
# Replace API_KEY with your api key.
# Or alternatively if you have the IONQ_API_KEY environment
# variables set, you can omit specifying thee api_key parameters.
# Alternatively, if you have the IONQ_API_KEY environment
# variable set, you can omit specifying this api_key parameters.
service = ionq.Service(api_key=API_KEY)

# Run a program against the service. This method will block execution
# until the result is returned and periodically polls the IonQ API.
# Run a program against the service. This method will block execution until
# the result is returned (determined by periodically polling the IonQ API).
result = service.run(circuit=circuit, repetitions=100, target='qpu')

# The return object of run is a cirq.Result object.
# From this object you can get a histogram of results.
# From this object, you can get a histogram of results.
histogram = result.histogram(key='x')
print(f'Histogram: {histogram}')

# Or the data as a pandas frame.
# You can also get the data as a pandas frame.
print(f'Data:\n{result.data}')
```
This produces output (will vary due to quantum randomness!)
Expand All @@ -70,18 +72,16 @@ Data:

## Service options

In addition to the `remote_host` and `api_key` there are some other options which are
useful for configuring the service. The most useful of these are

* `default_target`: this is a string of either `simulator` or `qpu`. By setting this you
do not have to specify a target every time you run a job using `run`, `create_job`
or via the `sampler` interface. A helpful pattern is to create two services with
defaults for the simulator and for the QPU separately.
In addition to the `api_key`, there are some other options which are
useful for configuring the service. These are passed as arguments
when creating a `cirq_ionq.Service` object.

* `max_retry_seconds`: The API will pull with exponential backoff for completed jobs.
By specifying this you can change the number of seconds before this retry gives up.
It is common to set this to a very small number when, for example, wanting to fail
fast, or to be set very long for long running jobs.
* `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}`.
* `default_target`: this is a string of either `simulator` or `qpu`. By setting this you do not have to specify a target every time you run a job using `run`, `create_job` or via the `sampler` interface. A helpful pattern is to create two services with defaults for the simulator and for the QPU separately.
* `api_version`: Version of the api. Defaults to 'v0.1'.
* `max_retry_seconds`: The API will pull with exponential backoff for completed jobs. By specifying this you can change the number of seconds before this retry gives up. It is common to set this to a very small number when, for example, wanting to fail fast, or to be set very long for long running jobs.

## Next steps

Expand Down