terminal
Docs

How to run your first program on IonQ cloud

Last updated: January 18, 2024
IonQ Staff

This guide will walk you through the basics of using the IonQ Quantum Cloud to write and run quantum programs , including using the Quantum Cloud API and Quantum Cloud Console to create an API key, specify a quantum circuit and submit it as a job, and then access the results via the command line or the Quantum Cloud Console.

To keep things simple, this example is written using direct calls to the API using curl and our language-agnostic JSON circuit representation. In practice, it may be easier to use one of the many quantum programming languages and SDKs we support. Have a look at our docs page for a full list and guides for getting started with each.

About the IonQ Quantum Cloud

The IonQ Quantum Cloud is a cloud quantum computing platform for optimizing, running and simulating quantum programs. It combines access to our trapped-ion systems via the Quantum Cloud API with web-based tools for inspecting and understanding your quantum jobs, as well as a powerful, proprietary optimization and compilation pipeline that ensures you’re always getting the best out of our hardware.

It also powers the most language, SDK and partner quantum cloud integrations of any quantum hardware provider — whatever tools or cloud you use for quantum computing, the IonQ Quantum Cloud will allow you to use them with IonQ’s high-performance hardware.

The Quantum Cloud API

The core of the IonQ Quantum Cloud is the Quantum Cloud API. It’s a RESTful API that allows you to run quantum programs on our hardware just like you’d call out to any other remote resource, with resource-oriented URLs, HTTP verbs and status codes, and the rest. We’ll get into some of the specifics of the API and its usage over the course of this guide, and you can read the full API reference here.

The Quantum Cloud Console

The Quantum Cloud Console, available at cloud.ionq.com, provides a web-based interface for managing your API credentials and interactively exploring the programs you’ve submitted, including their status, API response, and results. In this guide, we’ll use it to create an API key and then look at the results of our job once it’s complete.

The Life of A Quantum Job

In the IonQ Quantum Cloud, the base unit of quantum computation is a job. A job is a single quantum circuit, run some number of times (shots), on a single target, either a simulator or a quantum processing unit or QPU, which is what we call our cloud hardware.

The basic life cycle of a job in the IonQ Quantum Cloud looks something like this:

  1. The end user (that’s you!) creates a quantum circuit, using the tool of their choice.

  2. They then submit that job to the IonQ Cloud API, either directly or via one of our many partner SDKs and clouds. If submitted successfully, the API returns a Job ID and a status of ready.

  3. The job is then optimized and compiled in the cloud from its circuit representation into a native gate representation optimized for maximum performance on our trapped-ion hardware.

  4. The optimized job is then put into a fair, throughput-optimized job queue for running on hardware.

  5. When it’s at the front of the line, the job is then sent to the computer, where it’s converted into an even lower-level representation to modulate laser pulses, run and returned to the cloud.

  6. The cloud formats the results and places them at the resource path associated with the Job ID, where the user can then retrieve and further post-process them as needed.

From your perspective as an end user, this is even simpler — create a job, submit it to the API, and then wait a while while we run it. You can poll intermittently for the job’s status, or simply wait a while, and once it’s done, the API will return the statuscomplete as well as the results of the job. Jobs are generally run and returned in a few minutes, but may take up to several hours depending on user demand, calibration, maintenance, reserved time slots for partners, and similar. You can get a sense of the current wait time from status.ionq.co.

Running a Quantum Program

Now that you have a basic understanding of the cloud platform and the lifecycle of a quantum program, let’s go step by step to actually create and run one, and then look at the results.

Get an API Key

To run anything on the IonQ Quantum Cloud, you’ll need to generate an API key. The easiest way to do this is via the console:

First, click on the user menu in the top right, and then on API Keys.

Once on the API Keys page, generate a new key by giving it a descriptive name and hitting Generate key. You can make as many keys as you like.

Once your key is created, you can click show and then copy to copy the key to your clipboard.

Remember to keep this key safe! It’s a fully-privileged credential tied to your billing account that will let you run and retrieve any job on the API. If you do accidentally expose your key, hit the revoke button and create a new one.

To follow our examples below export your copied API key into environment variable.

export KEY="your-api-key"

Write a Quantum Circuit

Next, we’ll need to create a quantum circuit to submit as your first job. Let’s use a simple GHZ state using three qubits, first applying a Hadamard gate to a single qubit, and then using it as the control qubit for a series of controlled-not gates on the other two.

Diagrammed, a three-qubit GHZ circuit looks like this:

https://images.ctfassets.net/hqm865gc1xfs/1o83qPIdyK5ffP9mTCm48Z/4e6cd0ce4e262a6479fe4d65265047a1/ghz-circuit.png

In IonQ’s language-agnostic JSON circuit representation, the circuit looks like this:

{
  "qubits": 3,
  "circuit": [
    {
      "gate": "h",
      "target": 0
    },
    {
      "gate": "cnot",
      "control": 0,
      "target": 1
    },
    {
      "gate": "cnot",
      "control": 0,
      "target": 2
    },
  ]
}

Submit Your Quantum Circuit as a Job

Now we're ready to submit this circuit as a job. To keep it simple we'll use `curl` on the command line, but in the real world example, you'd likely want to use a more-fully featured quantum programming SDK, or else use python, javascript, or another programming language or library that has more mature HTTP request handling.

To submit the job, we need to add a few additional parameters to our circuit — the language, the number of shots, where we want the job to run (`simulator`, `qpu.harmony`, or `qpu.aria-1`) and, optionally, a name. You can read about this more here.

{
  "lang": "json",
  "shots": 1024,
  "name": "hello many worlds",
  "target": "qpu.harmony",
  "body": {
    "qubits": 3,
    "circuit": [
      {
        "gate": "h",
        "target": 0
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 1
      },
      {
        "gate": "cnot",
        "control": 0,
        "target": 2
      }
    ]
  }
}

Paste or retype this in your text editor of choice and then save it using a memorable name — something like ghz-job.json

Now, we're ready to submit our job to the IonQ Cloud API. To do that, we'll `POST` our JSON job body to the job creation route, with two headers: one for authorization with the API key we created earlier, and one to tell the API that our job body is JSON formatted

curl -X POST "https://api.ionq.co/v0.3/jobs" \
-H "Authorization: apiKey $KEY" \
-H "Content-Type: application/json" \
-d @ghz-job.json
{"id":"51bac456-36c7-430e-95bf-0c7fd36e937f",
"status":"ready",
"request":1623266536}

Retrieve The Results

To retrieve the job, we can now `GET` it at its own resource URL, determined by the job id:

curl "https://api.ionq.co/v0.3/jobs/51bac456-36c7-430e-95bf-0c7fd36e937f" \
-H "Authorization: apiKey $KEY"
{"status":"ready",
"children":[],
"name":"hello many worlds",
"target":"qpu.harmony",
"shots":1024,
"predicted_execution_time":7518,
"id":"51bac456-36c7-430e-95bf-0c7fd36e937f",
"qubits":3,
"request":1623266536,
"gate_counts":{"1q":1,"2q":2},
"error_mitigation":{"debias":false}}

Because we made this request just a moment ago, it hasn't run yet, although we can see that the cloud has now fully processed the job body and is echoing its parameters back

After waiting a few minutes and running the same `curl`, we get:

curl "https://api.ionq.co/v0.3/jobs/51bac456-36c7-430e-95bf-0c7fd36e937f" \
-H "Authorization: apiKey $KEY"
{"status":"running",
"children":[],
"name":"hello many worlds",
"target":"qpu.harmony",
"shots":1024,
"predicted_execution_time":7518,
"id":"51bac456-36c7-430e-95bf-0c7fd36e937f",
"qubits":3,
"request":1623266536,
"gate_counts":{"1q":1,"2q":2},
"error_mitigation":{"debias":false}}

The job is running! In practice, we'd recommend setting up some sort of periodic polling, where a script checks the job's status every ~30 seconds or so, rather than wait-and-retry, but for this demo, we'll simply wait a few more minutes and then make the request one more time:

curl "https://api.ionq.co/v0.3/jobs/51bac456-36c7-430e-95bf-0c7fd36e937f" \
-H "Authorization: apiKey $KEY"
{"status":"completed",
"children":[],
"name":"hello many worlds",
"target":"qpu.harmony",
"shots":1024,
"predicted_execution_time":7518,
"execution_time":7247,
"id":"91f6c952-0b90-48de-ab67-76665e77a01e",
"qubits":3,
"request":1623266536,
"start":1623266613,
"response":1623266619,
"gate_counts":{"1q":1,"2q":2},
"error_mitigation":{"debias":false},
"results_url":"/v0.3/jobs/51bac456-36c7-430e-95bf-0c7fd36e937f/results"}

Now that the job has completed, we can retrieve the results using the URL provided in the output.

curl "https://api.ionq.co/v0.3/jobs/51bac456-36c7-430e-95bf-0c7fd36e937f/results" \
-H "Authorization: apiKey $KEY"
{"0":0.4921875,
"1":0.0009765625,
"2":0.0068359375,
"3":0.0009765625,
"4":0.0078125,
"5":0.005859375,
"6":0.005859375,
"7":0.4794921875}

The results request contains the histogram output of the probabilities of each measured state across all 1024 shots. Two things to note here: the output is sparse, that is, it only shows data for outcomes that were actually measured, and the output keys are formatted as big-endian integers, i.e. 0 is 0002 is 0103 is 011, and so-on, where the leftmost bit is the qubit with index zero from our submitted program.

View Jobs In The Console

Viewing raw JSON from an API is not very fun or easy to quickly parse, so let's now look at this same job on the Cloud Console.

Here, you'll see a list of all of your submitted jobs, including ones that haven't been run yet. Clicking on a job shows a quick output histogram, and clicking on view job details shows a full details page with job parameters, any provided metadata (something we didn't cover in this guide but you can read about in the API Reference), the submitted program, a visualization of the program, and the full JSON output you'd get from the API.

Additional Resources

If you're working on your own tools to interact with the API, the full API Reference has details on HTTP verbs and endpoints, expected response formats, and other features not covered in this guide.

If you'd rather work with the IonQ Quantum Cloud at a higher level of abstraction, check out our docs and guides for quickstart guides on using one of the many quantum SDKs and cloud providers that we support, including Amazon Braket, Azure Quantum's Q#, IBM's Qiskit, Google's Cirq, ProjectQ and more.

Additionally, our best practices page provides detailed instructions for getting the most out of our trapped-ion systems, and our support center is always available to help you solve any problems you might run into.