sdk/quantum/Azure.Quantum.Jobs/README.md
Azure Quantum is a Microsoft Azure service that you can use to run quantum computing programs 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
This section should include everything a developer needs to do to install and create their first client connection very quickly.
Install the Azure Quantum Jobs client library for .NET with NuGet:
dotnet add package Azure.Quantum.Jobs --prerelease
Include a section after the install command that details any requirements that must be satisfied before a developer can authenticate and test all of the snippets in the Examples section. For example, for Cosmos DB:
You must have an Azure subscription, Cosmos DB account (SQL API), and Python 3.6+ to use this package.
To authenticate with the service, the workspace will use DefaultAzureCredential internally. This will try different authentication mechanisms based on the environment (e.g. Environment Variables, ManagedIdentity, CachedTokens) and finally it will fallback to InteractiveBrowserCredential.
Workspace will also allow the user to override the above behavior by passing their own TokenCredential.
TokenCredential is the default Authentication mechanism used by Azure SDKs.
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.
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
<!-- CLIENT COMMON BAR -->Create an instance of the QuantumJobClient by passing in these parameters:
// Create a QuantumJobClient
var subscriptionId = "your_subscription_id";
var resourceGroupName = "your_resource_group_name";
var workspaceName = "your_quantum_workspace_name";
var location = "your_location";
var storageContainerName = "your_container_name";
var credential = new DefaultAzureCredential(true);
var quantumJobClient =
new QuantumJobClient(
subscriptionId,
resourceGroupName,
workspaceName,
location,
credential);
Create a storage container where to put your data.
// Get container Uri with SAS key
var containerUri = (quantumJobClient.GetStorageSasUri(
new BlobDetails(storageContainerName))).Value.SasUri;
This step can be done in multiple ways and it is not in scope for this sample.
Quantum Intermediate Representation (QIR) is a QIR Alliance specification to represent quantum programs within the LLVM Intermediate Representation (IR).
A few methods to compile or generate a quantum program into QIR:
In this sample, we assume you already have a file with the QIR bitcode and you know the method name that you want to execute (entry point).
We will use the QIR bitcode sample (./samples/BellState.bc), compiled a Q# code (./samples/BellState.qs) targeting the quantinuum.sim.h1-1e target, with AdaptiveExecution target capability.
Using the SAS URI, upload the QIR bitcode input data to the blob client.
string qirFilePath = "./BellState.bc";
// Get input data blob Uri with SAS key
string blobName = Path.GetFileName(qirFilePath);
var inputDataUri = (quantumJobClient.GetStorageSasUri(
new BlobDetails(storageContainerName)
{
BlobName = blobName,
})).Value.SasUri;
// Upload QIR bitcode to blob storage
var blobClient = new BlobClient(new Uri(inputDataUri));
var blobHeaders = new BlobHttpHeaders
{
ContentType = "qir.v1"
};
var blobUploadOptions = new BlobUploadOptions { HttpHeaders = blobHeaders };
using (FileStream qirFileStream = File.OpenRead(qirFilePath))
{
blobClient.Upload(qirFileStream, options: blobUploadOptions);
}
Now that you've uploaded your QIR program bitcode to Azure Storage, you can use CreateJob to define an Azure Quantum job.
// Submit job
var jobId = $"job-{Guid.NewGuid():N}";
var jobName = $"jobName-{Guid.NewGuid():N}";
var inputDataFormat = "qir.v1";
var outputDataFormat = "microsoft.quantum-results.v1";
var providerId = "quantinuum";
var target = "quantinuum.sim.h1-1e";
var inputParams = new Dictionary<string, object>()
{
{ "entryPoint", "ENTRYPOINT__BellState" },
{ "arguments", new string[] { } },
{ "targetCapability", "AdaptiveExecution" },
};
var createJobDetails = new JobDetails(containerUri, inputDataFormat, providerId, target)
{
Id = jobId,
InputDataUri = inputDataUri,
Name = jobName,
InputParams = inputParams,
OutputDataFormat = outputDataFormat
};
JobDetails myJob = (quantumJobClient.CreateJob(jobId, createJobDetails)).Value;
GetJob retrieves a specific job by its id.
// Get the job that we've just created based on its jobId
myJob = (quantumJobClient.GetJob(jobId)).Value;
To enumerate all the jobs in the workspace, use the GetJobs method.
foreach (JobDetails job in quantumJobClient.GetJobs())
{
Console.WriteLine($"{job.Name}");
}
All Quantum Jobs service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.
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 https://cla.microsoft.com.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
<!-- LINKS -->