Support several parameters for IQ# Azure Quantum job execution

src/AzureClient/AzureClient.cs

@@ -173,7 +173,7 @@ public async Task<ExecutionResult> GetConnectionStatusAsync(IChannel channel)
             return ValidExecutionTargets.ToExecutionResult();
         }
 
-        private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, string operationName, Dictionary<string, string> inputParameters, bool execute)
+        private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, AzureSubmissionContext submissionContext, bool execute)
         {
             if (ActiveWorkspace == null)
             {
@@ -187,7 +187,7 @@ private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, st
                 return AzureClientError.NoTarget.ToExecutionResult();
             }
 
-            if (string.IsNullOrEmpty(operationName))
+            if (string.IsNullOrEmpty(submissionContext.OperationName))
             {
                 var commandName = execute ? "%azure.execute" : "%azure.submit";
                 channel.Stderr($"Please pass a valid Q# operation name to {commandName}.");
@@ -202,40 +202,42 @@ private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, st
                 return AzureClientError.InvalidTarget.ToExecutionResult();
             }
 
-            channel.Stdout($"Submitting {operationName} to target {ActiveTarget.TargetId}...");
+            channel.Stdout($"Submitting {submissionContext.OperationName} to target {ActiveTarget.TargetId}...");
 
             IEntryPoint? entryPoint = null;
             try
             {
-                entryPoint = EntryPointGenerator.Generate(operationName, ActiveTarget.TargetId);
+                entryPoint = EntryPointGenerator.Generate(submissionContext.OperationName, ActiveTarget.TargetId);
             }
             catch (UnsupportedOperationException e)
             {
-                channel.Stderr($"{operationName} is not a recognized Q# operation name.");
+                channel.Stderr($"{submissionContext.OperationName} is not a recognized Q# operation name.");
                 return AzureClientError.UnrecognizedOperationName.ToExecutionResult();
             }
             catch (CompilationErrorsException e)
             {
-                channel.Stderr($"The Q# operation {operationName} could not be compiled as an entry point for job execution.");
+                channel.Stderr($"The Q# operation {submissionContext.OperationName} could not be compiled as an entry point for job execution.");
                 foreach (var message in e.Errors) channel.Stderr(message);
                 return AzureClientError.InvalidEntryPoint.ToExecutionResult();
             }
 
             try
             {
-                var job = await entryPoint.SubmitAsync(machine, inputParameters);
-                channel.Stdout($"Job {job.Id} submitted successfully.");
+                var job = await entryPoint.SubmitAsync(machine, submissionContext);
+                channel.Stdout($"Job successfully submitted for {submissionContext.Shots} shots.");
+                channel.Stdout($"   Job name: {submissionContext.FriendlyName}");
+                channel.Stdout($"   Job ID: {job.Id}");
                 MostRecentJobId = job.Id;
             }
             catch (ArgumentException e)
             {
-                channel.Stderr($"Failed to parse all expected parameters for Q# operation {operationName}.");
+                channel.Stderr($"Failed to parse all expected parameters for Q# operation {submissionContext.OperationName}.");
                 channel.Stderr(e.Message);
                 return AzureClientError.JobSubmissionFailed.ToExecutionResult();
             }
             catch (Exception e)
             {
-                channel.Stderr($"Failed to submit Q# operation {operationName} for execution.");
+                channel.Stderr($"Failed to submit Q# operation {submissionContext.OperationName} for execution.");
                 channel.Stderr(e.InnerException?.Message ?? e.Message);
                 return AzureClientError.JobSubmissionFailed.ToExecutionResult();
             }
@@ -245,18 +247,16 @@ private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, st
                 return await GetJobStatusAsync(channel, MostRecentJobId);
             }
 
-            var timeoutInSeconds = 30;
-            channel.Stdout($"Waiting up to {timeoutInSeconds} seconds for Azure Quantum job to complete...");
+            channel.Stdout($"Waiting up to {submissionContext.ExecutionTimeout} seconds for Azure Quantum job to complete...");
 
-            using (var cts = new System.Threading.CancellationTokenSource(TimeSpan.FromSeconds(30)))
+            using (var cts = new System.Threading.CancellationTokenSource(TimeSpan.FromSeconds(submissionContext.ExecutionTimeout)))
             {
                 CloudJob? cloudJob = null;
                 do
                 {
                     // TODO: Once jupyter-core supports interrupt requests (https://github.com/microsoft/jupyter-core/issues/55),
                     //       handle Jupyter kernel interrupt here and break out of this loop 
-                    var pollingIntervalInSeconds = 5;
-                    await Task.Delay(TimeSpan.FromSeconds(pollingIntervalInSeconds));
+                    await Task.Delay(TimeSpan.FromSeconds(submissionContext.ExecutionPollingInterval));
                     if (cts.IsCancellationRequested) break;
                     cloudJob = await GetCloudJob(MostRecentJobId);
                     channel.Stdout($"[{DateTime.Now.ToLongTimeString()}] Current job status: {cloudJob?.Status ?? "Unknown"}");
@@ -268,12 +268,12 @@ private async Task<ExecutionResult> SubmitOrExecuteJobAsync(IChannel channel, st
         }
 
         /// <inheritdoc/>
-        public async Task<ExecutionResult> SubmitJobAsync(IChannel channel, string operationName, Dictionary<string, string> inputParameters) =>
-            await SubmitOrExecuteJobAsync(channel, operationName, inputParameters, execute: false);
+        public async Task<ExecutionResult> SubmitJobAsync(IChannel channel, AzureSubmissionContext submissionContext) =>
+            await SubmitOrExecuteJobAsync(channel, submissionContext, execute: false);
 
         /// <inheritdoc/>
-        public async Task<ExecutionResult> ExecuteJobAsync(IChannel channel, string operationName, Dictionary<string, string> inputParameters) =>
-            await SubmitOrExecuteJobAsync(channel, operationName, inputParameters, execute: true);
+        public async Task<ExecutionResult> ExecuteJobAsync(IChannel channel, AzureSubmissionContext submissionContext) =>
+            await SubmitOrExecuteJobAsync(channel, submissionContext, execute: true);
 
         /// <inheritdoc/>
         public async Task<ExecutionResult> GetActiveTargetAsync(IChannel channel)

src/AzureClient/AzureSubmissionContext.cs

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.Quantum.IQSharp.Jupyter;
+using Microsoft.Quantum.Runtime;
+
+namespace Microsoft.Quantum.IQSharp.AzureClient
+{
+    /// <summary>
+    /// Represents the configuration settings for a job submission to Azure Quantum.
+    /// </summary>
+    public sealed class AzureSubmissionContext : IQuantumMachineSubmissionContext
+    {
+        private static readonly int DefaultShots = 500;
+        private static readonly int DefaultExecutionTimeoutInSeconds = 30;
+        private static readonly int DefaultExecutionPollingIntervalInSeconds = 5;
+
+        internal static readonly string ParameterNameOperationName = "__operationName__";
+        internal static readonly string ParameterNameJobName = "jobName";
+        internal static readonly string ParameterNameShots = "shots";
+        internal static readonly string ParameterNameTimeout = "timeout";
+        internal static readonly string ParameterNamePollingInterval = "poll";
+
+        /// <inheritdoc/>
+        public string FriendlyName { get; set; } = string.Empty;
+
+        /// <inheritdoc/>
+        public int Shots { get; set; } = DefaultShots;
+
+        /// <summary>
+        ///     The Q# operation name to be executed as part of this job.
+        /// </summary>
+        public string OperationName { get; set; } = string.Empty;
+
+        /// <summary>
+        ///     The input parameters to be provided to the specified Q# operation.
+        /// </summary>
+        public Dictionary<string, string> InputParameters { get; set; } = new Dictionary<string, string>();
+
+        /// <summary>
+        ///     The execution timeout for the job, expressed in seconds.
+        /// </summary>
+        /// <remarks>
+        ///     This setting only applies to %azure.execute. It is ignored for %azure.submit.
+        ///     The timeout determines how long the IQ# kernel will wait for the job to complete;
+        ///     the Azure Quantum job itself will continue to execute until it is completed.
+        /// </remarks>
+        public int ExecutionTimeout { get; set; } = DefaultExecutionTimeoutInSeconds;
+
+        /// <summary>
+        ///     The polling interval, in seconds, to check for job status updates
+        ///     while waiting for an Azure Quantum job to complete execution.
+        /// </summary>
+        /// <remarks>
+        ///     This setting only applies to %azure.execute. It is ignored for %azure.submit.
+        /// </remarks>
+        public int ExecutionPollingInterval { get; set; } = DefaultExecutionPollingIntervalInSeconds;
+
+        /// <summary>
+        ///     Parses the input from a magic command into an <see cref="AzureSubmissionContext"/> object
+        ///     suitable for job submission via <see cref="IAzureClient"/>.
+        /// </summary>
+        public static AzureSubmissionContext Parse(string inputCommand)
+        {
+            var inputParameters = AbstractMagic.ParseInputParameters(inputCommand, firstParameterInferredName: ParameterNameOperationName);
+            var operationName = inputParameters.DecodeParameter<string>(ParameterNameOperationName);
+            var jobName = inputParameters.DecodeParameter<string>(ParameterNameJobName, defaultValue: operationName);
+            var shots = inputParameters.DecodeParameter<int>(ParameterNameShots, defaultValue: DefaultShots);
+            var timeout = inputParameters.DecodeParameter<int>(ParameterNameTimeout, defaultValue: DefaultExecutionTimeoutInSeconds);
+            var pollingInterval = inputParameters.DecodeParameter<int>(ParameterNamePollingInterval, defaultValue: DefaultExecutionPollingIntervalInSeconds);
+
+            var decodedParameters = inputParameters.ToDictionary(
+                item => item.Key,
+                item => inputParameters.DecodeParameter<string>(item.Key));
+
+            return new AzureSubmissionContext()
+            {
+                FriendlyName = jobName,
+                Shots = shots,
+                OperationName = operationName,
+                InputParameters = decodedParameters,
+                ExecutionTimeout = timeout,
+                ExecutionPollingInterval = pollingInterval,
+            };
+        }
+    }
+}

src/AzureClient/EntryPoint/EntryPoint.cs

@@ -39,18 +39,18 @@ public EntryPoint(object entryPointInfo, Type inputType, Type outputType, Operat
         }
 
         /// <inheritdoc/>
-        public Task<IQuantumMachineJob> SubmitAsync(IQuantumMachine machine, Dictionary<string, string> inputParameters)
+        public Task<IQuantumMachineJob> SubmitAsync(IQuantumMachine machine, AzureSubmissionContext submissionContext)
         {
             var parameterTypes = new List<Type>();
             var parameterValues = new List<object>();
             foreach (var parameter in OperationInfo.RoslynParameters)
             {
-                if (!inputParameters.ContainsKey(parameter.Name))
+                if (!submissionContext.InputParameters.ContainsKey(parameter.Name))
                 {
                     throw new ArgumentException($"Required parameter {parameter.Name} was not specified.");
                 }
 
-                string rawParameterValue = inputParameters[parameter.Name];
+                string rawParameterValue = submissionContext.InputParameters[parameter.Name];
                 object? parameterValue = null;
                 try
                 {
@@ -73,17 +73,18 @@ public Task<IQuantumMachineJob> SubmitAsync(IQuantumMachine machine, Dictionary<
             };
 
             // Find and invoke the method on IQuantumMachine that is declared as:
-            // Task<IQuantumMachineJob> SubmitAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input)
+            // Task<IQuantumMachineJob> SubmitAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input, SubmissionContext context)
             var submitMethod = typeof(IQuantumMachine)
                 .GetMethods()
                 .Single(method =>
                     method.Name == "SubmitAsync"
                     && method.IsGenericMethodDefinition
-                    && method.GetParameters().Length == 2
+                    && method.GetParameters().Length == 3
                     && method.GetParameters()[0].ParameterType.GetGenericTypeDefinition() == EntryPointInfo.GetType().GetGenericTypeDefinition()
-                    && method.GetParameters()[1].ParameterType.IsGenericMethodParameter)
+                    && method.GetParameters()[1].ParameterType.IsGenericMethodParameter
+                    && method.GetParameters()[2].ParameterType == typeof(IQuantumMachineSubmissionContext))
                 .MakeGenericMethod(new Type[] { InputType, OutputType });
-            var submitParameters = new object[] { EntryPointInfo, entryPointInput };
+            var submitParameters = new object[] { EntryPointInfo, entryPointInput, submissionContext };
             return (Task<IQuantumMachineJob>)submitMethod.Invoke(machine, submitParameters);
         }
     }

src/AzureClient/EntryPoint/IEntryPoint.cs

@@ -21,8 +21,8 @@ public interface IEntryPoint
         /// Submits the entry point for execution to Azure Quantum.
         /// </summary>
         /// <param name="machine">The <see cref="IQuantumMachine"/> object representing the job submission target.</param>
-        /// <param name="inputParameters">The provided input parameters to the entry point operation.</param>
+        /// <param name="submissionContext">The <see cref="AzureSubmissionContext"/> object representing the submission context for the job.</param>
         /// <returns>The details of the submitted job.</returns>
-        public Task<IQuantumMachineJob> SubmitAsync(IQuantumMachine machine, Dictionary<string, string> inputParameters);
+        public Task<IQuantumMachineJob> SubmitAsync(IQuantumMachine machine, AzureSubmissionContext submissionContext);
     }
 }

src/AzureClient/IAzureClient.cs

@@ -128,7 +128,7 @@ public Task<ExecutionResult> ConnectAsync(IChannel channel,
         /// <returns>
         /// Details of the submitted job, or an error if submission failed.
         /// </returns>
-        public Task<ExecutionResult> SubmitJobAsync(IChannel channel, string operationName, Dictionary<string, string> inputParameters);
+        public Task<ExecutionResult> SubmitJobAsync(IChannel channel, AzureSubmissionContext submissionContext);
 
         /// <summary>
         /// Executes the specified Q# operation as a job to the currently active target
@@ -137,7 +137,7 @@ public Task<ExecutionResult> ConnectAsync(IChannel channel,
         /// <returns>
         /// The result of the executed job, or an error if execution failed.
         /// </returns>
-        public Task<ExecutionResult> ExecuteJobAsync(IChannel channel, string operationName, Dictionary<string, string> inputParameters);
+        public Task<ExecutionResult> ExecuteJobAsync(IChannel channel, AzureSubmissionContext submissionContext);
 
         /// <summary>
         /// Sets the specified target for job submission.

src/AzureClient/Magic/ExecuteMagic.cs

@@ -3,6 +3,7 @@
 
 #nullable enable
 
+using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using Microsoft.Jupyter.Core;
@@ -15,8 +16,6 @@ namespace Microsoft.Quantum.IQSharp.AzureClient
     /// </summary>
     public class ExecuteMagic : AzureClientMagicBase
     {
-        private const string ParameterNameOperationName = "operationName";
-
         /// <summary>
         /// Initializes a new instance of the <see cref="ExecuteMagic"/> class.
         /// </summary>
@@ -59,16 +58,7 @@ The Azure Quantum workspace must previously have been initialized
         /// </summary>
         public override async Task<ExecutionResult> RunAsync(string input, IChannel channel)
         {
-            var inputParameters = ParseInputParameters(input, firstParameterInferredName: ParameterNameOperationName);
-            var operationName = inputParameters.DecodeParameter<string>(ParameterNameOperationName);
-
-            var decodedParameters = new Dictionary<string, string>();
-            foreach (var key in inputParameters.Keys)
-            {
-                decodedParameters[key] = inputParameters.DecodeParameter<string>(key);
-            }
-
-            return await AzureClient.ExecuteJobAsync(channel, operationName, decodedParameters);
+            return await AzureClient.ExecuteJobAsync(channel, AzureSubmissionContext.Parse(input));
         }
     }
 }

src/AzureClient/Magic/OutputMagic.cs

@@ -17,7 +17,7 @@ namespace Microsoft.Quantum.IQSharp.AzureClient
     /// </summary>
     public class OutputMagic : AzureClientMagicBase
     {
-        private const string ParameterNameJobId = "jobId";
+        private const string ParameterNameJobId = "id";
 
         /// <summary>
         /// Initializes a new instance of the <see cref="OutputMagic"/> class.

src/AzureClient/Magic/StatusMagic.cs

@@ -17,7 +17,7 @@ namespace Microsoft.Quantum.IQSharp.AzureClient
     /// </summary>
     public class StatusMagic : AzureClientMagicBase
     {
-        private const string ParameterNameJobId = "jobId";
+        private const string ParameterNameJobId = "id";
 
         /// <summary>
         /// Initializes a new instance of the <see cref="StatusMagic"/> class.

src/AzureClient/Magic/SubmitMagic.cs

@@ -15,8 +15,6 @@ namespace Microsoft.Quantum.IQSharp.AzureClient
     /// </summary>
     public class SubmitMagic : AzureClientMagicBase
     {
-        private const string ParameterNameOperationName = "operationName";
-
         /// <summary>
         /// Initializes a new instance of the <see cref="SubmitMagic"/> class.
         /// </summary>
@@ -56,16 +54,7 @@ The Azure Quantum workspace must previously have been initialized
         /// </summary>
         public override async Task<ExecutionResult> RunAsync(string input, IChannel channel)
         {
-            var inputParameters = ParseInputParameters(input, firstParameterInferredName: ParameterNameOperationName);
-            var operationName = inputParameters.DecodeParameter<string>(ParameterNameOperationName);
-
-            var decodedParameters = new Dictionary<string, string>();
-            foreach (var key in inputParameters.Keys)
-            {
-                decodedParameters[key] = inputParameters.DecodeParameter<string>(key);
-            }
-
-            return await AzureClient.SubmitJobAsync(channel, operationName, decodedParameters);
+            return await AzureClient.SubmitJobAsync(channel, AzureSubmissionContext.Parse(input));
         }
     }
 }

src/Jupyter/Extensions.cs

@@ -187,7 +187,7 @@ public static T DecodeParameter<T>(this Dictionary<string, string> parameters, s
             {
                 return defaultValue;
             }
-            return (T)(JsonConvert.DeserializeObject(parameterValue)) ?? defaultValue;
+            return (T)System.Convert.ChangeType(JsonConvert.DeserializeObject(parameterValue), typeof(T)) ?? defaultValue;
         }
     }
 }