%azure.execute

Warning

This documentation refers to the Classic QDK, which has been replaced by the Modern QDK.

The Modern QDK only supports the '%%qsharp' magic command.

Summary

Submits a job to an Azure Quantum workspace and waits for completion.

Description

This magic command allows for submitting a Q# operation or function to be run on the specified target in the current Azure Quantum workspace. The command waits a specified amount of time for the job to complete before returning.

The Azure Quantum workspace must have been previously initialized using the %azure.connect magic command, and an execution target for the job must have been specified using the %azure.target magic command.

Required parameters

• Q# operation or function name. This must be the first parameter, and must be a valid Q# operation or function name that has been defined either in the notebook or in a Q# file in the same folder.
• Arguments for the Q# operation or function must also be specified as key=value pairs.

Optional parameters

• jobName=<string>: Friendly name to identify this job. If not specified, the Q# operation or function name will be used as the job name.
• jobParams=<JSON key:value pairs>: Provider-specific job parameters expressed in JSON as one or more key:value pairs to be passed to the execution target. Values must be strings.
• shots=<integer> (default=500): Number of times to repeat execution of the specified Q# operation or function.
• timeout=<integer> (default=300): Time to wait (in seconds) for job completion before the magic command returns.
• poll=<integer> (default=5): Interval (in seconds) to poll for job status while waiting for job execution to complete.

Possible errors

• NotConnected: Not connected to any Azure Quantum workspace.
• NoTarget: No execution target has been configured for Azure Quantum job submission.
• NoOperationName: No Q# operation name was specified for Azure Quantum job submission.
• InvalidTarget: The specified target is not enabled in this workspace. Please make sure the target name is valid and that the associated provider is added to your workspace. To add a provider to your quantum workspace in the Azure Portal, see https://aka.ms/AQ/Docs/AddProvider
• UnrecognizedOperationName: The specified Q# operation name was not recognized.
• InvalidEntryPoint: The specified Q# operation cannot be used as an entry point for Azure Quantum job submission.
• JobSubmissionFailed: Failed to submit the job to the Azure Quantum workspace.
• JobNotCompleted: The specified Azure Quantum job has not yet completed.
• JobOutputDownloadFailed: Failed to download results for the specified Azure Quantum job.
• JobFailedOrCancelled: The specified Azure Quantum job failed or was cancelled.

Examples for %azure.execute

Example 1

Run a Q# operation defined as operation MyOperation(a : Int, b : Int) : Result on the active target in the current Azure Quantum workspace:

In []: %azure.execute MyOperation a=5 b=10
Out[]: Submitting MyOperation to target provider.qpu...
       Job successfully submitted for 500 shots.
          Job name: MyOperation
          Job ID: <Azure Quantum job ID>
       Waiting up to 300 seconds for Azure Quantum job to complete...
       [1:23:45 PM] Current job status: Waiting
       [1:23:50 PM] Current job status: Executing
       [1:23:55 PM] Current job status: Succeeded
       <detailed results of completed job>

Example 2

Run a Q# operation defined as operation MyOperation(a : Int, b : Int) : Result on the active target in the current Azure Quantum workspace, specifying a custom job name, number of shots, timeout, polling interval, and provider-specific job parameters:

In []: %azure.submit MyOperation a=5 b=10 jobName="My job" shots=100 timeout=60 poll=10 jobParams={"Key1":"Val1","Key2":"Val2"}
Out[]: Submitting MyOperation to target provider.qpu...
       Job successfully submitted for 100 shots.
          Job name: My job
          Job ID: <Azure Quantum job ID>
       Waiting up to 60 seconds for Azure Quantum job to complete...
       [1:23:45 PM] Current job status: Waiting
       [1:23:55 PM] Current job status: Waiting
       [1:24:05 PM] Current job status: Executing
       [1:24:15 PM] Current job status: Succeeded
       <detailed results of completed job>