Azure Quantum Jobs client library for Java - version 1.0.0-beta.1

  • Article

Azure Quantum is a Microsoft Azure service that you can use to run quantum computing programs or solve optimization problems in the cloud. Using the Azure Quantum tools and SDKs, you can create quantum programs and run them against different quantum simulators and machines. You can use the Azure.Quantum.Jobs client library to:

  • Create, enumerate, and cancel quantum jobs
  • Enumerate provider status and quotas

Source code | API reference documentation | Product documentation

Getting started

This section should include everything a developer needs to do to install and create their first client connection very quickly.

Install the package

Install the Azure Quantum Jobs client library for Java by adding the following to your pom.xml file:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-quantum-jobs</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

Prerequisites: You must have an Azure subscription, Azure Quantum workspace, Azure storage account, and a Java Development Kit (JDK) of version 8 or later.

Authenticate the client

To authenticate with the service, you will have to pass a TokenCredential to the client builder as described below.

TokenCredential is the default Authentication mechanism used by Azure SDKs.

Key concepts

QuantumJobClient is the root class to be used to authenticate and create, enumerate, and cancel jobs.

JobDetails contains all the properties of a job.

ProviderStatus contains status information for a provider.

QuantumJobQuota contains quota properties.

Examples

Create the client

Create an instance of the client of your choice by passing the following values to QuantumClientBuilder and then calling the appropriate build method.

  • Subscription - looks like XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX and can be found in your list of subscriptions on azure
  • Resource Group - a container that holds related resources for an Azure solution
  • Workspace - a collection of assets associated with running quantum or optimization applications
  • Host - the host endpoint is "https://{location}.quantum.azure.com". Choose the best data center location by geographical region
  • StorageContainerName - your blob storage
  • Credential - used to authenticate
JobsClient jobsClient = new QuantumClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .host("{endpoint}")
    .subscriptionId("{subscriptionId}")
    .resourceGroupName("{resourceGroup}")
    .workspaceName("{workspaceName}")
    .buildJobsClient();

StorageClient storageClient = new QuantumClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .host("{endpoint}")
    .subscriptionId("{subscriptionId}")
    .resourceGroupName("{resourceGroup}")
    .workspaceName("{workspaceName}")
    .buildStorageClient();

Get Container SAS URI

Create a storage container to put your data in.

// Get container URI with SAS key
String containerName = "{storageContainerName}";

// Create container if it doesn't already exist
BlobContainerClient containerClient = new BlobContainerClientBuilder()
    .containerName(containerName)
    .endpoint(containerUri)
    .buildClient();
if (!containerClient.exists()) {
    containerClient.create();
}

// Get connection string to the container
String containerUri = storageClient.sasUri(
    new BlobDetails().setContainerName(containerName)
).getSasUri();

Upload Input Data

Using the SAS URI, upload the json input data to the blob client. This contains the parameters to be used with Quantum Inspired Optimizations

// Get input data blob Uri with SAS key
String blobName = "{blobName}";
BlobDetails blobDetails = new BlobDetails()
    .setContainerName(containerName)
    .setBlobName(blobName);
String inputDataUri = storageClient.sasUri(blobDetails).getSasUri();

// Upload input data to blob
BlobClient blobClient = new BlobClientBuilder()
    .endpoint(inputDataUri)
    .buildClient();
String problemFilePath = FileSystems.getDefault().getPath("src/samples/resources/problem.json").toString();
blobClient.uploadFromFile(problemFilePath);

Create The Job

Now that you've uploaded your problem definition to Azure Storage, you can use the create() method in JobsClient or JobsAsyncClient, or the createWithResponse() method in JobsAsyncClient to define an Azure Quantum job.

String jobId = String.format("job-%s", UUID.randomUUID());
JobDetails createJobDetails = new JobDetails()
    .setContainerUri(containerUri)
    .setId(jobId)
    .setInputDataFormat("microsoft.qio.v2")
    .setOutputDataFormat("microsoft.qio-results.v2")
    .setProviderId("microsoft")
    .setTarget("microsoft.paralleltempering-parameterfree.cpu")
    .setName("{jobName}");
JobDetails jobDetails = jobsClient.create(jobId, createJobDetails);

Get Job

To retrieve a specific job by its ID, you can use get() from JobsClient or JobsAsyncClient, or getWithResponse() in JobsAsyncClient.

// Get the job that we've just created based on its jobId
JobDetails myJob = jobsClient.get(jobId);

List Jobs

To enumerate all the jobs in the workspace, use the list() method from JobClient or JobAsyncClient, or from JobAsyncClient use listSinglePage() or listNextPage().

PagedIterable<JobDetails> jobs = jobsClient.list();
jobs.forEach(job -> {
    System.out.println(job.getName());
});

Troubleshooting

All Quantum Jobs service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.

Next steps

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions