From 6ae50ef98666e806a1f38ec9f47b712c953cc8f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Zaragoza=20Cort=C3=A9s?=
 <cesar.zaragoza@outlook.com>
Date: Mon, 4 May 2020 15:11:10 -0700
Subject: [PATCH 1/2] Removed type parameters from IQuantumMachine interface.
 (#185)

* Removed type parameters from IQuantumMachine interface.

* Addressed Sarah's feedback.

* Update src/Simulation/Core/IQuantumMachineOutput.cs

Co-authored-by: Sarah Marshall <33814365+samarsha@users.noreply.github.com>

Co-authored-by: Sarah Marshall <33814365+samarsha@users.noreply.github.com>
(cherry picked from commit 1b53a81693d15189d734de2d6400d0691c1595b0)
---
 src/Simulation/Core/IQuantumMachine.cs       | 15 +++---
 src/Simulation/Core/IQuantumMachineJob.cs    | 57 ++++++++++++++++++++
 src/Simulation/Core/IQuantumMachineOutput.cs | 30 +++++++++++
 3 files changed, 93 insertions(+), 9 deletions(-)
 create mode 100644 src/Simulation/Core/IQuantumMachineJob.cs
 create mode 100644 src/Simulation/Core/IQuantumMachineOutput.cs

diff --git a/src/Simulation/Core/IQuantumMachine.cs b/src/Simulation/Core/IQuantumMachine.cs
index abe2c4538f0..5593572ef16 100644
--- a/src/Simulation/Core/IQuantumMachine.cs
+++ b/src/Simulation/Core/IQuantumMachine.cs
@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-using System;
 using System.Threading.Tasks;
 using Microsoft.Quantum.Simulation.Core;
 
@@ -10,9 +9,7 @@ namespace Microsoft.Quantum.Runtime
     /// <summary>
     /// Interface that a quantum machine must implement.
     /// </summary>
-    /// <typeparam name="TJob">Type of job that handles the execution of a program in the quantum machine.</typeparam>
-    /// <typeparam name="TRawResult">Type of result the quantum machine returns.</typeparam>
-    public interface IQuantumMachine<TJob, TRawResult>
+    public interface IQuantumMachine
     {
         /// <summary>
         /// Gets the ID of the quantum machine provider.
@@ -29,14 +26,14 @@ public interface IQuantumMachine<TJob, TRawResult>
         /// <summary>
         /// Executes a Q# program.
         /// Submits a job to execute it and continuously checks whether it has been completed.
-        /// Once its execution completes, returns its output.
+        /// Once its execution completes, returns an object that implements the IQuantumMachineOutput interface through which the execution output can be obtained.
         /// </summary>
         /// <param name="info">Information about the Q# program</param>
         /// <param name="input">Input for the Q# program</param>
         /// <typeparam name="TInput">Type of input the quantum program receives.</typeparam>
         /// <typeparam name="TOutput">Type of output the quantum program returns.</typeparam>
-        /// <returns>Sampled output of the quantum program</returns>
-        Task<Tuple<TOutput, TRawResult>> ExecuteAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input);
+        /// <returns>An object that implements the IQuantumMachineOutput interface.</returns>
+        Task<IQuantumMachineOutput<TOutput>> ExecuteAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input);
 
         /// <summary>
         /// Submits a job to execute a Q# program.
@@ -46,7 +43,7 @@ public interface IQuantumMachine<TJob, TRawResult>
         /// <param name="input">Input for the Q# program</param>
         /// <typeparam name="TInput">Type of input the quantum program receives.</typeparam>
         /// <typeparam name="TOutput">Type of output the quantum program returns.</typeparam>
-        /// <returns>A Job instance. Status and results from the execution can be retrieved from this instance.</returns>
-        Task<TJob> SubmitAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input);
+        /// <returns>An object that implements the IQuantumMachineJob interface through which data about the job can be obtained.</returns>
+        Task<IQuantumMachineJob> SubmitAsync<TInput, TOutput>(EntryPointInfo<TInput, TOutput> info, TInput input);
     }
 }
diff --git a/src/Simulation/Core/IQuantumMachineJob.cs b/src/Simulation/Core/IQuantumMachineJob.cs
new file mode 100644
index 00000000000..8e5ab684ba4
--- /dev/null
+++ b/src/Simulation/Core/IQuantumMachineJob.cs
@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Quantum.Runtime
+{
+    /// <summary>
+    /// Interface to track a job submitted to a quantum machine.
+    /// </summary>
+    public interface IQuantumMachineJob
+    {
+        /// <summary>
+        /// Gets whether job execution failed.
+        /// </summary>
+        bool Failed { get; }
+
+        /// <summary>
+        /// Gets the ID of submitted job.
+        /// </summary>
+        string Id { get; }
+
+        /// <summary>
+        /// Gets whether job execution is in progress.
+        /// </summary>
+        bool InProgress { get; }
+
+        /// <summary>
+        /// Gets the status of the submitted job.
+        /// </summary>
+        string Status { get; }
+
+        /// <summary>
+        /// Gets whether the job execution completed successfully.
+        /// </summary>
+        bool Succeeded { get;  }
+
+        /// <summary>
+        /// Gets an URI to access the job.
+        /// </summary>
+        Uri Uri { get; }
+
+        /// <summary>
+        /// Cancels the job.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token for the cancel operation.</param>
+        Task CancelAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Refreshes the state of the job.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token for the refresh operation.</param>
+        Task RefreshAsync(CancellationToken cancellationToken = default);
+    }
+}
diff --git a/src/Simulation/Core/IQuantumMachineOutput.cs b/src/Simulation/Core/IQuantumMachineOutput.cs
new file mode 100644
index 00000000000..204765d50f4
--- /dev/null
+++ b/src/Simulation/Core/IQuantumMachineOutput.cs
@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Collections.Generic;
+
+namespace Microsoft.Quantum.Runtime
+{
+    /// <summary>
+    /// Interface to access the results of a program executed in a quantum machine.
+    /// <typeparam name="TOutput">Type of output the quantum program returns.</typeparam>
+    /// </summary>
+    public interface IQuantumMachineOutput<TOutput>
+    {
+        /// <summary>
+        /// Gets a histogram of outputs.
+        /// The key is the output and the value is its frequency.
+        /// </summary>
+        IReadOnlyDictionary<TOutput, double> Histogram { get; }
+
+        /// <summary>
+        /// Gets the job associated to the output.
+        /// </summary>
+        IQuantumMachineJob Job { get; }
+
+        /// <summary>
+        /// Gets the number of times the program was executed.
+        /// </summary>
+        int Shots { get; }
+    }
+}

From 2bbe8c0528119fab1c628b5bd5d0ee48276ed022 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9sar=20Zaragoza=20Cort=C3=A9s?=
 <cesar.zaragoza@outlook.com>
Date: Fri, 8 May 2020 16:24:14 -0700
Subject: [PATCH 2/2] Update src/Simulation/Core/IQuantumMachineJob.cs

Co-authored-by: Sarah Marshall <33814365+samarsha@users.noreply.github.com>
---
 src/Simulation/Core/IQuantumMachineJob.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Simulation/Core/IQuantumMachineJob.cs b/src/Simulation/Core/IQuantumMachineJob.cs
index 8e5ab684ba4..e715a216053 100644
--- a/src/Simulation/Core/IQuantumMachineJob.cs
+++ b/src/Simulation/Core/IQuantumMachineJob.cs
@@ -35,7 +35,7 @@ public interface IQuantumMachineJob
         /// <summary>
         /// Gets whether the job execution completed successfully.
         /// </summary>
-        bool Succeeded { get;  }
+        bool Succeeded { get; }
 
         /// <summary>
         /// Gets an URI to access the job.