TopQAD™ API Tutorial

Welcome to the TopQAD API tutorial! This guide will help you interact with TopQAD functionalities using API calls. You will learn how to send requests, understand sample payloads, and execute a full example script.

Sending a cURL Request

cURL is a powerful tool for making HTTP requests. Below, we demonstrate how to use cURL to interact with our APIs.

Please note that access to these APIs requires a subscription. Please contact us for more information.

The main components we need to send any cURL request are:

Request type: Specifies the HTTP method (e.g., GET, POST, PUT, DELETE) to be used for the request.
Headers: Key-value pairs sent with the request to provide information such as the content type and authorization tokens.
URL: The endpoint of the API you are interacting with.
Data (optional): Payload required for POST, PUT, and PATCH requests, usually in JSON format. This is where you will specify your inputs. Refer to the API documentation for more details on the parameters that are specific to the endpoint you are trying to call.

Basic POST Request

Let's say we'd like to invoke the decomposer. Here's a command that we could use:

curl -X 'POST' \
  '<API_BASE_URL>/decompose' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "circuit_path": "/hansa_data/HH_0025_postSK-2024-03-12T17:19:42.433Z.qasm",
  "error_budget": 0.025
}'

Please contact us to receive the <API_BASE_URL> for each TopQAD service.

POST Response

Upon successful submission, you'll receive a request ID and a waiting status, indicating that the POST request was successful.

{
	"request_id": "a8bd63b4-3990-45d5-8456-d50021e8f251",
	"status": "waiting"
}

GET Request

To retrieve the solution details for a specific request ID, for example, for the job that we just requested, we can use the GET endpoint with the request_id that was returned by the POST endpoint:

curl -X 'GET' \
  '<API_BASE_URL>/decompose/a8bd63b4-3990-45d5-8456-d50021e8f251' \
  -H 'accept: application/json'

Please contact us to receive the <API_BASE_URL> for each TopQAD service.

GET Response

Upon successful completion, you'll receive the solution details including the SK circuit path and accumulated error.

{
	"request_id": "a8bd63b4-3990-45d5-8456-d50021e8f251",
	"status": "done",
	"sk_circuit_path": "/hansa_data/HH_0025_postSK-2024-03-12T17:19:42.433Z_post_sk.qasm",
	"accumulated_error": 0,
	"elapsed_time": 1.544,
	"message": null
}

If you'd like to delve deeper into the job log details, you can utilize the GET log endpoint.

GET Log Request

curl -X 'GET' \
  '<API_BASE_URL>/logs/a8bd63b4-3990-45d5-8456-d50021e8f251' \
  -H 'accept: application/json'

Please contact us to receive the <API_BASE_URL> for each TopQAD service.

GET Log Response

You'll receive detailed log entries providing insights into the processing of your job.

["[2024-05-15 22:06:34] [INFO] [decompose] (request={circuit_path='/hansa_data/HH_0025_postSK-2024-03-12T17:19:42.433Z.qasm' error_budget=0.025})",...,[2024-05-15T22:06:38.514] [Debug] [sk_node] Successfully updated result and status to done/failed in get request topic."]

API Reference Documentation

You can access comprehensive API documentation through the portal by visiting the reference pages linked in the description section of each tool.

Sample Payloads

To help you get started quickly, we provide sample payloads for each tool. You can use these payloads as templates and modify them to suit your specific needs. Below are the links to the sample payloads:

Decomposer: decomposer_payload.json
Optimizer: optimizer_payload.json
Scheduler: scheduler_payload.json
FTQC Emulator: ftqc_emulator_payload.json
PRE: pre_payload.json
QARE: qare_payload.json

Using Sample Payloads in Commands

When using the sample payloads in commands, such as sending a cURL request, you need to update certain fields, such as circuit_path, to match your own file paths. Here's an example of a sample payload for the decomposer tool:

Sample Payload (decomposer_payload.json)

{
	"circuit_path": "/your/own/path/to/circuit_file.qasm",
	"error_budget": 0.1
}

Using Sample Payloads in Python Code

When using the sample payloads in Python code, you have two options:

Modify Sample Payload Directly: You can directly modify the sample payload file by updating the necessary fields, such as the circuit_path or error_budget, to your desired values.
Modify Payload in Python Code: Alternatively, you can load the sample payload into a dictionary in your Python code and then update the necessary fields programmatically. Here's an example:

import json
import requests

API_BASE_URL = '<API_BASE_URL>' # Update with the API base URL

with open('sample_payload/decomposer_payload.json', 'r') as file:
    payload = json.load(file)

# Update the circuit_path to your own file path
payload['circuit_path'] = '/your/own/path/to/circuit_file.qasm'

# Send the request
response = requests.post(
    API_BASE_URL + '/decompose',
    headers={
        'accept': 'application/json',
        'Content-Type': 'application/json'
    },
    json=payload
)

print(response.json())

Please contact us to receive the <API_BASE_URL> for each TopQAD service.

Full Example Script

To run the entire end-to-end pipeline using our example Python script, please follow these instructions:

Prepare Payload Files: Before running the script, ensure that you have all six payload files ready in a folder of your choice. The payload files should be named as follows:

decomposer_payload.json
optimizer_payload.json
scheduler_payload.json
ftqc_emulator_payload.json
pre_payload.json
qare_payload.json

Update Payload Folder Path: Open the example script in a text editor. Locate the SAMPLE_PAYLOAD_FOLDER variable at the beginning of the script and update its value to the path where you have stored your payload files.
Ensure Correct API URLs: Make sure the API_URLS variable in the script matches the URLs provided to you at signup.
Prepare Test Circuit File: Before running the script, ensure you have a test circuit file ready. This file should be in the QASM format and represent the quantum circuit you want to analyze. Make note of the file path as you'll need to provide it as a command-line argument in the next step.
Run the Script: Execute the script with the path to your test circuit file as a command-line argument:

python e2e_script.py "/path/to/your/circuit_file.qasm"

The script will execute each tool in the pipeline and save the final report in an output folder relative to where you run the script. Feel free to modify the script or copy parts of it for your own use cases.