@azure/quantum-jobs 1.0.0-beta.1 → 1.0.0-beta.2

package/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+Copyright (c) Microsoft Corporation.
 
-Copyright (c) 2021 Microsoft
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +12,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -2,12 +2,17 @@
 
 This package contains an isomorphic SDK for QuantumJobClient.
 
-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:
+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][source] | [API reference documentation](https://docs.microsoft.com/qsharp/api/) | [Product documentation](https://docs.microsoft.com/azure/quantum/) | [Samples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/quantum/quantum-jobs/samples)
+Key links:
+
+- [Source code][source]
+- [API reference documentation](https://learn.microsoft.com/qsharp/api/)
+- [Product documentation](https://learn.microsoft.com/azure/quantum/)
+- [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/quantum/quantum-jobs/samples)
 
 ## Getting started
 
@@ -23,15 +28,15 @@ npm install @azure/quantum-jobs
 
 ### Prerequisites
 
-- Node.js version 8.x.x or higher
+- [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule)
 - [Azure subscription](https://azure.microsoft.com/free/)
 - [Azure Quantum Workspace][workspaces]
 
 ### Authenticate the client
 
-To authenticate with the service, you can use [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity#defaultazurecredential) from the `@azure/identity` library. This will try different authentication mechanisms based on the environment (e.g. Environment Variables, ManagedIdentity, CachedTokens) and finally, it will fallback to InteractiveBrowserCredential.
+To authenticate with the service, you can use [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential) from the `@azure/identity` library. This will try different authentication mechanisms based on the environment (e.g. Environment Variables, ManagedIdentity, CachedTokens) and finally, it will fallback to InteractiveBrowserCredential.
 
-The client also allows the user to override the above behavior by passing their own implementations of the [TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/core/core-auth/src/tokenCredential.ts).
+The client also allows the user to override the above behavior by passing their own implementations of the [TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-auth/src/tokenCredential.ts).
 
 `TokenCredential` is the default Authentication mechanism used by Azure SDKs.
 
@@ -53,126 +58,260 @@ Create an instance of the QuantumJobClient by passing in these parameters:
 
 - [Subscription Id][subscriptions] - looks like XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX and can be found in your list of subscriptions on azure
 - [Resource Group Name][resource-groups] - a container that holds related resources for an Azure solution
-- [Workspace Name][workspaces] - a collection of assets associated with running quantum or optimization applications
+- [Workspace Name][workspaces] - a collection of assets associated with running quantum
 - [Location][location] - choose the best data center by geographical region
 - [Storage Container Name][blob-storage] - your blob storage
 - [Credential][credentials] - used to authenticate
 
-```Javascript Snippet
-    const credential = new DefaultAzureCredential();
-
-    // Create a QuantumJobClient
-    const subscriptionId = "your_subscription_id";
-    const resourceGroupName = "your_resource_group_name";
-    const workspaceName = "your_quantum_workspace_name";
-    const storageContainerName = "mycontainer";
-    const location = "westus"; //"your_location";
-    const endpoint = "https://" + location + ".quantum.azure.com";
-
-    const quantumJobClient = new QuantumJobClient(
-      credential,
-      subscriptionId,
-      resourceGroupName,
-      workspaceName,
-      {
-        endpoint: endpoint,
-        credentialScopes: "https://quantum.microsoft.com/.default"
-      }
-    );
+```ts snippet:ReadmeSampleCreateClient_TokenCredential
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+
+// Create a QuantumJobClient
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
 ```
 
 ### Get Container SAS URI
 
 Create a storage container to put your data.
 
-```Javascript Snippet
-    // Get container Uri with SAS key
-    const containerUri = (
-      await quantumJobClient.storage.sasUri({
-        containerName: storageContainerName
-      })
-    ).sasUri;
-
-    // Create container if not exists
-    const containerClient = new ContainerClient(containerUri);
-    await containerClient.createIfNotExists();
+```ts snippet:ReadmeSampleCreateContainer
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+import { ContainerClient } from "@azure/storage-blob";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const storageContainerName = "containername";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get container Uri with SAS key
+const containerUri = (
+  await quantumJobClient.storage.sasUri({
+    containerName: storageContainerName,
+  })
+).sasUri;
+
+// Create container if not exists
+const containerClient = new ContainerClient(containerUri);
+await containerClient.createIfNotExists();
 ```
 
+### Compile your quantum program into QIR
+
+This step can be done in multiple ways and it is not in scope for this sample.
+
+[Quantum Intermediate Representation (QIR)](https://github.com/qir-alliance/qir-spec) is a [QIR Alliance](https://www.qir-alliance.org/) specification to represent quantum programs within the [LLVM](https://llvm.org/) Intermediate Representation (IR).
+
+A few methods to compile or generate a quantum program into QIR:
+
+- [Q# compiler](https://github.com/microsoft/qsharp-compiler/): Can be used to [compile Q# Code into QIR](https://github.com/microsoft/qsharp-compiler/tree/main/src/QsCompiler/QirGeneration).
+- [PyQIR](https://github.com/qir-alliance/pyqir): PyQIR is a set of APIs for generating, parsing, and evaluating Quantum Intermediate Representation (QIR).
+- [IQ#](https://github.com/microsoft/iqsharp): Can be used to compile a Q# program into QIR with the [%qir](https://learn.microsoft.com/qsharp/api/iqsharp-magic/qir) magic command.
+
+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 (`BellState.bc` in the samples folder), compiled a Q# code (`BellState.qs` in the samples folder) targeting the `quantinuum.sim.h1-1e` target, with `AdaptiveExecution` target capability.
+
 ### 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](https://docs.microsoft.com/azure/quantum/optimization-overview-introduction)
-
-```Javascript Snippet
-    // Get input data blob Uri with SAS key
-    const blobName = "myjobinput.json";
-    const inputDataUri = (
-      await quantumJobClient.storage.sasUri({
-        containerName: storageContainerName,
-        blobName: blobName
-      })
-    ).sasUri;
-
-    // Upload input data to blob
-    const blobClient = new BlockBlobClient(inputDataUri);
-    const problemFilename = "problem.json";
-    const fileContent = fs.readFileSync(problemFilename, "utf8");
-    await blobClient.upload(fileContent, Buffer.byteLength(fileContent));
+Using the SAS URI, upload the QIR bitcode input data to the blob client.
+
+```ts snippet:ReadmeSampleUploadInputData
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+import { BlockBlobClient } from "@azure/storage-blob";
+import { readFileSync } from "node:fs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const storageContainerName = "containername";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get input data blob Uri with SAS key
+const blobName = "myjobinput.bc";
+const inputDataUri = (
+  await quantumJobClient.storage.sasUri({
+    containerName: storageContainerName,
+    blobName: blobName,
+  })
+).sasUri;
+
+// Upload input data to blob
+const blobClient = new BlockBlobClient(inputDataUri);
+const problemFilename = "BellState.bc";
+const fileContent = readFileSync(problemFilename, "utf8");
+const blobOptions = {
+  blobHTTPHeaders: {
+    blobContentType: "qir.v1",
+  },
+};
+await blobClient.upload(fileContent, Buffer.byteLength(fileContent), blobOptions);
 ```
 
 ### Create The Job
 
 Now that you've uploaded your problem definition to Azure Storage, you can use `jobs.create` to define an Azure Quantum job.
 
-```Javascript Snippet
-    const randomId = `${Math.floor(Math.random() * 10000 + 1)}`;
-
-    // Submit job
-    const jobId = `job-${randomId}`;
-    const jobName = `jobName-${randomId}`;
-    const inputDataFormat = "microsoft.qio.v2";
-    const outputDataFormat = "microsoft.qio-results.v2";
-    const providerId = "microsoft";
-    const target = "microsoft.paralleltempering-parameterfree.cpu";
-    const createJobDetails = {
-      containerUri: containerUri,
-      inputDataFormat: inputDataFormat,
-      providerId: providerId,
-      target: target,
-      id: jobId,
-      inputDataUri: inputDataUri,
-      name: jobName,
-      outputDataFormat: outputDataFormat
-    };
-    const createdJob = await quantumJobClient.jobs.create(jobId, createJobDetails);
+```ts snippet:ReadmeSampleCreateJob
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+const randomId = `${Math.floor(Math.random() * 10000 + 1)}`;
+
+// Submit job
+const jobId = `job-${randomId}`;
+const jobName = `jobName-${randomId}`;
+const inputDataFormat = "qir.v1";
+const outputDataFormat = "microsoft.quantum-results.v1";
+const providerId = "quantinuum";
+const target = "quantinuum.sim.h1-1e";
+const inputParams = {
+  entryPoint: "ENTRYPOINT__BellState",
+  arguments: [],
+  targetCapability: "AdaptiveExecution",
+};
+const createJobDetails = {
+  containerUri: "https://<container-uri>",
+  inputDataFormat: inputDataFormat,
+  providerId: providerId,
+  target: target,
+  id: jobId,
+  inputDataUri: "https://<input-data-url>",
+  name: jobName,
+  outputDataFormat: outputDataFormat,
+  inputParams: inputParams,
+};
+const createdJob = await quantumJobClient.jobs.create(jobId, createJobDetails);
 ```
 
 ### Get Job
 
 `GetJob` retrieves a specific job by its id.
 
-```Javascript Snippet
-    // Get the job that we've just created based on its jobId
-    const myJob = await quantumJobClient.jobs.get(jobId);
+```ts snippet:ReadmeSampleGetJob
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get the job that we've just created based on its jobId
+const myJob = await quantumJobClient.jobs.get("job-1234");
 ```
 
 ### Get Jobs
 
 To enumerate all the jobs in the workspace, use the `jobs.list` method.
 
-```Javascript Snippet
-    let jobListResult = await quantumJobClient.jobs.list();
-    let listOfJobs = await jobListResult.next();
-    while (!listOfJobs.done) {
-      let job = listOfJobs.value;
-      console.log(`  ${job.name}`);
-      listOfJobs = await jobListResult.next();
-    }
+```ts snippet:ReadmeSampleListJobs
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+const jobListResult = quantumJobClient.jobs.list();
+for await (const job of jobListResult) {
+  console.log(`Job Id: ${job.id} and Job Name: ${job.name}`);
+}
 ```
 
 ## Next steps
 
-- Visit our [Product documentation](https://docs.microsoft.com/azure/quantum/) to learn more about Azure Quantum.
+- Visit our [Product documentation](https://learn.microsoft.com/azure/quantum/) to learn more about Azure Quantum.
 
 ## Contributing
 
@@ -193,17 +332,27 @@ additional questions or comments.
 
 All Quantum Jobs service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.
 
+### Logging
+
+Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+
+```ts snippet:SetLogLevel
+import { setLogLevel } from "@azure/logger";
+
+setLogLevel("info");
+```
+
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
+
 <!-- LINKS -->
 
-[source]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/quantum/quantum-jobs/src
-[resource-groups]: https://docs.microsoft.com/azure/azure-resource-manager/management/manage-resource-groups-portal
-[workspaces]: https://docs.microsoft.com/azure/quantum/how-to-create-quantum-workspaces-with-the-azure-portal
+[source]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/quantum/quantum-jobs/src
+[resource-groups]: https://learn.microsoft.com/azure/azure-resource-manager/management/manage-resource-groups-portal
+[workspaces]: https://learn.microsoft.com/azure/quantum/how-to-create-quantum-workspaces-with-the-azure-portal
 [location]: https://azure.microsoft.com/global-infrastructure/services/?products=quantum
-[blob-storage]: https://docs.microsoft.com/azure/storage/blobs/storage-blobs-introduction
-[contributing]: https://github.com/Azure/azure-sdk-for-js/tree/master/CONTRIBUTING.md
+[blob-storage]: https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction
+[contributing]: https://github.com/Azure/azure-sdk-for-js/tree/main/CONTRIBUTING.md
 [subscriptions]: https://ms.portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade
-[credentials]: https://docs.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credentials
-[style-guide-msft]: https://docs.microsoft.com/style-guide/capitalization
+[credentials]: https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credentials
+[style-guide-msft]: https://learn.microsoft.com/style-guide/capitalization
 [style-guide-cloud]: https://aka.ms/azsdk/cloud-style-guide
-
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fappconfiguration%2Fapp-configuration%2FREADME.png)

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./models/index.js";
+export { QuantumJobClient } from "./quantumJobClient.js";
+export * from "./operationsInterfaces/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,cAAc,iCAAiC,CAAC"}

package/dist/browser/index.js

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT License.
+ *
+ * Code generated by Microsoft (R) AutoRest Code Generator.
+ * Changes may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+export * from "./models/index.js";
+export { QuantumJobClient } from "./quantumJobClient.js";
+export * from "./operationsInterfaces/index.js";
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,cAAc,iCAAiC,CAAC","sourcesContent":["/*\n * Copyright (c) Microsoft Corporation.\n * Licensed under the MIT License.\n *\n * Code generated by Microsoft (R) AutoRest Code Generator.\n * Changes may cause incorrect behavior and will be lost if the code is regenerated.\n */\n\nexport * from \"./models/index.js\";\nexport { QuantumJobClient } from \"./quantumJobClient.js\";\nexport * from \"./operationsInterfaces/index.js\";\n"]}