1# IonQ API Service 2 3IonQ's API provides a way to execute quantum circuits on IonQ's trapped ion quantum computers 4or on cloud based simulators. As of April 2021 this access is restricted to partners. 5See [Access and Authentication](access.md) for details of access. 6 7## Service class 8 9The main entrance for accessing IonQ's API are instances of the `cirq.ionq.Service` class. 10These objects need to be initialized with an api key, see 11[Access and Authentication](access.md) for details. 12 13The basic flow of running a quantum circuit in a blocking manner is 141. Create a circuit to run. 151. Create a `cirq.ionq.Service` with proper authentication and endpoints. 163. Submit this circuit to run on the service and await the results of this call. 17(Or alternatively use asynchronous jobs and processing) 184. Transform the results in a form that is most useful for your analysis. 19 20Here is a simple example of this flow 21```python 22import cirq 23import cirq.ionq as ionq 24 25# A circuit that applies a square root of NOT and then a measurement. 26qubit = cirq.LineQubit(0) 27circuit = cirq.Circuit( 28 cirq.X(qubit)**0.5, # Square root of NOT. 29 cirq.measure(qubit, key='x') # Measurement store in key 'x' 30) 31 32# Create a ionq.Service object. 33# Replace API_KEY with your api key. 34# Or alternatively if you have the IONQ_API_KEY environment 35# variables set, you can omit specifying thee api_key parameters. 36service = ionq.Service(api_key=API_KEY) 37 38# Run a program against the service. This method will block execution 39# until the result is returned and periodically polls the IonQ API. 40result = service.run(circuit=circuit, repetitions=100, target='qpu') 41 42# The return object of run is a cirq.Result object. 43# From this object you can get a histogram of results. 44histogram = result.histogram(key='x') 45print(f'Histogram: {histogram}') 46 47# Or the data as a pandas frame. 48print(f'Data:\n{result.data}') 49``` 50This produces output (will vary due to quantum randomness!) 51 52``` 53Histogram: Counter({0: 53, 1: 47}) 54Data: 55 x 560 0 571 0 582 0 593 0 604 0 61.. .. 6295 1 6396 1 6497 1 6598 1 6699 1 67 68[100 rows x 1 columns] 69``` 70 71## Service options 72 73In addition to the `remote_host` and `api_key` there are some other options which are 74useful for configuring the service. The most useful of these are 75 76* `default_target`: this is a string of either `simulator` or `qpu`. By setting this you 77do not have to specify a target every time you run a job using `run`, `create_job` 78or via the `sampler` interface. A helpful pattern is to create two services with 79defaults for the simulator and for the QPU separately. 80 81* `max_retry_seconds`: The API will pull with exponential backoff for completed jobs. 82By specifying this you can change the number of seconds before this retry gives up. 83It is common to set this to a very small number when, for example, wanting to fail 84fast, or to be set very long for long running jobs. 85 86## Next steps 87 88[Learn how to build circuits for the API](circuits.md) 89 90[How to use the service API](jobs.md) 91 92[Get information about QPUs from IonQ calibrations](calibrations.md) 93