Hybrid QAOA

.gitignore

@@ -329,4 +329,3 @@ __pycache__/
 *.btm.cs
 *.odx.cs
 *.xsd.cs
-

Build/build.ps1

@@ -40,6 +40,9 @@ Build-One 'publish' '../MachineLearning.sln'
 Write-Host "##[info]Build Jupyter magic library"
 Build-One 'publish' '../Magic.sln'
 
+Write-Host "##[info]Build QAOA library"
+Build-One 'publish' '../Qaoa.sln'
+
 if (-not $all_ok) {
     throw "At least one test failed execution. Check the logs."
 }

Build/manifest.ps1

@@ -8,14 +8,16 @@
         "Microsoft.Quantum.Standard",
         "Microsoft.Quantum.Chemistry",
         "Microsoft.Quantum.Numerics",
-        "Microsoft.Quantum.MachineLearning"
+        "Microsoft.Quantum.MachineLearning",
+        "Microsoft.Quantum.Qaoa"
     );
     Assemblies = @(
         ".\Standard\src\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Standard.dll",
         ".\Numerics\src\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Numerics.dll",
         ".\MachineLearning\src\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.MachineLearning.dll",
         ".\Chemistry\src\DataModel\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Chemistry.DataModel.dll",
         ".\Chemistry\src\Runtime\bin\$Env:BUILD_CONFIGURATION\netstandard2.1\Microsoft.Quantum.Chemistry.Runtime.dll",
-        ".\Chemistry\src\Tools\bin\$Env:BUILD_CONFIGURATION\netcoreapp3.1\qdk-chem.dll"
+        ".\Chemistry\src\Tools\bin\$Env:BUILD_CONFIGURATION\netcoreapp3.1\qdk-chem.dll",
+        ".\Qaoa\src\bin\$Env:BUILD_CONFIGURATION\netcoreapp3.1\Microsoft.Quantum.Qaoa.dll"
     ) | ForEach-Object { Get-Item (Join-Path $PSScriptRoot ".." $_) };
 } | Write-Output;

Build/pack.ps1

@@ -72,6 +72,9 @@ if ($Env:ENABLE_PYTHON -eq "false") {
     Pack-Wheel '../Python/qsharp'
 }
 
+Write-Host "##[info]Pack QAOA library"
+Pack-One '../QAOA/src/Qaoa.csproj'
+
 if (-not $all_ok) {
     throw "At least one test failed execution. Check the logs."
 }

Build/test.ps1

@@ -40,6 +40,15 @@ Test-One '../Chemistry/tests/JupyterTests/JupyterTests.csproj'
 Write-Host "##[info]Testing Numerics/tests/NumericsTests.csproj"
 Test-One '../Numerics/tests/NumericsTests.csproj'
 
+Write-Host "##[info]Testing Qaoa/tests/QaoaTests/QaoaTests.csproj"
+Test-One '../Qaoa/tests/QaoaTests/QaoaTests.csproj'
+
+Write-Host "##[info]Testing Qaoa/tests/HybridQaoaTests/HybridQaoaTests.csproj"
+Test-One '../Qaoa/tests/HybridQaoaTests/HybridQaoaTests.csproj'
+
+Write-Host "##[info]Testing Qaoa/tests/JupyterTests/JupyterTests.csproj"
+Test-One '../Qaoa/tests/JupyterTests/JupyterTests.csproj'
+
 if (-not $all_ok) {
     throw "At least one test failed execution. Check the logs."
 }

QAOA.sln

@@ -0,0 +1,53 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 16
+VisualStudioVersion = 16.0.29920.165
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Qaoa", "QAOA\src\Qaoa.csproj", "{159D83BF-56A2-41B7-951B-35292F5A9F23}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "HybridQaoaTests", "QAOA\tests\HybridQaoaTests\HybridQaoaTests.csproj", "{1623F038-210A-4BA2-8D4E-9AF611610829}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "JupyterTests", "QAOA\tests\JupyterTests\JupyterTests.csproj", "{3C8B4AF6-5495-4F23-B7B2-634E5A667837}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "QaoaTests", "QAOA\tests\QaoaTests\QaoaTests.csproj", "{208C0012-D62F-4F29-8738-394A62BBE842}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{AD73B607-0EF5-4C11-8832-22D584939780}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{80082123-4392-4F0E-8F87-26183C620693}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{159D83BF-56A2-41B7-951B-35292F5A9F23}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{159D83BF-56A2-41B7-951B-35292F5A9F23}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{159D83BF-56A2-41B7-951B-35292F5A9F23}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{159D83BF-56A2-41B7-951B-35292F5A9F23}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1623F038-210A-4BA2-8D4E-9AF611610829}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1623F038-210A-4BA2-8D4E-9AF611610829}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1623F038-210A-4BA2-8D4E-9AF611610829}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1623F038-210A-4BA2-8D4E-9AF611610829}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3C8B4AF6-5495-4F23-B7B2-634E5A667837}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3C8B4AF6-5495-4F23-B7B2-634E5A667837}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3C8B4AF6-5495-4F23-B7B2-634E5A667837}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3C8B4AF6-5495-4F23-B7B2-634E5A667837}.Release|Any CPU.Build.0 = Release|Any CPU
+		{208C0012-D62F-4F29-8738-394A62BBE842}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{208C0012-D62F-4F29-8738-394A62BBE842}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{208C0012-D62F-4F29-8738-394A62BBE842}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{208C0012-D62F-4F29-8738-394A62BBE842}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{159D83BF-56A2-41B7-951B-35292F5A9F23} = {AD73B607-0EF5-4C11-8832-22D584939780}
+		{1623F038-210A-4BA2-8D4E-9AF611610829} = {80082123-4392-4F0E-8F87-26183C620693}
+		{3C8B4AF6-5495-4F23-B7B2-634E5A667837} = {80082123-4392-4F0E-8F87-26183C620693}
+		{208C0012-D62F-4F29-8738-394A62BBE842} = {80082123-4392-4F0E-8F87-26183C620693}
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {09481F99-E1AC-44CE-A892-7331820661DF}
+	EndGlobalSection
+EndGlobal

QAOA/README.md

@@ -0,0 +1,31 @@
+# Microsoft Quantum QAOA Library
+
+This library provides a hybrid quantum-classical algorithm for solving optimization problems. 
+It includes a Q# implementation of the Quantum Approximate Optimization Algorithm ([QAOA](https://arxiv.org/abs/1411.4028)) together with a classical optimizer in C#.
+The classical optimizer uses a quantum objective function to choose hopefully optimal parameters for running the QAOA.
+The quantum objective function is currently evaluated on a simulator backend provided by Q#.
+
+## Building and testing ##
+
+The quantum QAOA library consists of a cross-platform project built using [.NET Core](https://docs.microsoft.com/en-us/dotnet/core/):
+
+- **Qaoa.csproj**: Q# and C# sources used to encode combinatorial optimization problems and run QAOA and hybrid QAOA algorithms.
+
+The high-level diagram of the implementation (notation comes from the [QAOA paper](https://arxiv.org/abs/1411.4028)):
+
+[![QAOA diagram](https://i.postimg.cc/sgryqr80/IMG-0202.jpg)](https://postimg.cc/XpQTBTnw)
+
+Once .NET Core is installed, you may build and run its tests by executing the following from a command line:
+
+```bash
+dotnet test tests
+```
+
+For more details about creating and running tests in Q#,
+see the [Testing and debugging](https://docs.microsoft.com/quantum/quantum-techniques-testinganddebugging)
+section of the [developer's guide](https://docs.microsoft.com/quantum).
+
+Dependencies:
+
+1) [Q# and Microsoft Quantum Libraries](https://docs.microsoft.com/en-us/quantum/language/)
+2) [C# Accord Math library](http://accord-framework.net/docs/html/N_Accord_Math.htm)

QAOA/src/Jupyter/HybridQaoaMagic.cs

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.Qaoa.Jupyter
+{
+    using System;
+    using System.Threading.Tasks;
+    using Microsoft.Jupyter.Core;
+    using Microsoft.Quantum.Qaoa.QaoaHybrid;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// This class makes it possible to run the hybrid QAOA with user-defined input parameters in languages other than C# that are supported by this mechanism.
+    /// </summary>
+    public class HybridQaoaRunMagic : MagicSymbol
+    {
+
+        public HybridQaoaRunMagic()
+        {
+            this.Name = $"%qaoa.hybridqaoa.run";
+            this.Documentation = new Documentation()
+            {
+                Summary = "Runs a hybrid QAOA algorithm with a classical optimizer that chooses input angles. QAOA parameters are provided as JSON input. Initial beta and gamma coefficients are provided by a user."
+            };
+            this.Kind = SymbolKind.Magic;
+            this.Execute = this.Run;
+        }
+
+        /// <summary>
+        /// List of arguments
+        /// </summary>
+        public class Arguments
+        {
+            /// <summary>
+            /// Number of iterations in the fidelity sampling.
+            /// </summary>
+            [JsonProperty(PropertyName = "number_of_iterations")]
+            public int NumberOfIterations { get; set; }
+
+            /// <summary>
+            /// A parameter related to the depth of a QAOA circuit.
+            /// </summary>
+            [JsonProperty(PropertyName = "NHamiltonianApplications")]
+            public int NHamiltonianApplications { get; set; }
+
+            /// <summary>
+            /// Description of a combinatorial problem to be solved.
+            /// </summary>
+            [JsonProperty(PropertyName = "problem_instance")]
+            public QaoaProblemInstance QaoaProblemInstance { get; set; }
+
+            /// <summary>
+            /// Initial QAOA parameters (beta and gamma angles).
+            /// </summary>
+            [JsonProperty(PropertyName = "initial_qaoa_parameters")]
+            public QaoaParameters InitialQaoaParameters { get; set; }
+
+            /// <summary>
+            /// Flag whether optimization should be logged into a file.
+            /// </summary>
+            [JsonProperty(PropertyName = "should_log")]
+            public Boolean ShouldLog { get; set; } = false;
+        }
+
+        /// <summary>
+        /// Runs a hybrid QAOA.
+        /// </summary>
+        public async Task<ExecutionResult> Run(string input, IChannel channel)
+        {
+            if (string.IsNullOrWhiteSpace(input))
+            {
+                channel.Stderr("Please provide correct arguments");
+                return ExecuteStatus.Error.ToExecutionResult();
+            }
+
+            var args = JsonConvert.DeserializeObject<Arguments>(input);
+
+            var hybridQaoa = new HybridQaoa(args.NumberOfIterations, args.NHamiltonianApplications, args.QaoaProblemInstance, args.ShouldLog);
+
+            return hybridQaoa.RunOptimization(args.InitialQaoaParameters).ToExecutionResult();
+        }
+    }
+
+    /// <summary>
+    /// This class makes it possible to run the hybrid QAOA with randomly initialized input parameters in languages other than C# that are supported by this mechanism.
+    /// </summary>
+    public class HybridQaoaWithRandomParametersRunMagic : MagicSymbol
+    {
+
+        public HybridQaoaWithRandomParametersRunMagic()
+        {
+            this.Name = $"%qaoa.hybridqaoa.random.params.run";
+            this.Documentation = new Documentation()
+            {
+                Summary = "Runs a hybrid QAOA algorithm with a classical optimizer that chooses input angles. QAOA parameters are provided as a JSON. Initial beta and gamma parameters are chosen randomly."
+            };
+            this.Kind = SymbolKind.Magic;
+            this.Execute = this.Run;
+        }
+
+        /// <summary>
+        /// List of arguments
+        /// </summary>
+        public class Arguments
+        {
+            /// <summary>
+            /// Number of iterations in the fidelity sampling.
+            /// </summary>
+            [JsonProperty(PropertyName = "number_of_iterations")]
+            public int NumberOfIterations { get; set; }
+
+            /// <summary>
+            /// A parameter related to the depth of a QAOA circuit.
+            /// </summary>
+            [JsonProperty(PropertyName = "NHamiltonianApplications")]
+            public int NHamiltonianApplications { get; set; }
+
+            /// <summary>
+            /// Description of a combinatorial problem to be solved.
+            /// </summary>
+            [JsonProperty(PropertyName = "problem_instance")]
+            public QaoaProblemInstance QaoaProblemInstance { get; set; }
+
+            /// <summary>
+            /// Number of random starting points in the angles parameters spaces.
+            /// </summary>
+            [JsonProperty(PropertyName = "number_of_random_starting_points")]
+            public int NumberOfRandomStartingPoints { get; set; } = 1;
+
+            /// <summary>
+            /// Flag whether optimization should be logged into a file.
+            /// </summary>
+            [JsonProperty(PropertyName = "should_log")]
+            public Boolean ShouldLog { get; set; } = false;
+        }
+
+        /// <summary>
+        /// Runs a hybrid QAOA.
+        /// </summary>
+        public async Task<ExecutionResult> Run(string input, IChannel channel)
+        {
+            if (string.IsNullOrWhiteSpace(input))
+            {
+                channel.Stderr("Please provide correct arguments");
+                return ExecuteStatus.Error.ToExecutionResult();
+            }
+
+            var args = JsonConvert.DeserializeObject<Arguments>(input);
+
+            var hybridQaoa = new HybridQaoa(args.NumberOfIterations, args.NHamiltonianApplications, args.QaoaProblemInstance, args.ShouldLog);
+
+            return hybridQaoa.RunOptimization(args.NumberOfRandomStartingPoints).ToExecutionResult();
+        }
+    }
+}

QAOA/src/Jupyter/HybridQaoaParametersMagic.cs

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Quantum.Qaoa.Jupyter
+{
+    using System.Threading.Tasks;
+    using Microsoft.Jupyter.Core;
+    using Microsoft.Quantum.Qaoa.QaoaHybrid;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// This class makes it possible to initialize hybrid QAOA input parameters in languages other than C# that are supported by this mechanism.
+    /// </summary>
+    public class HybridQaoaParametersMagic : MagicSymbol
+    {
+        public HybridQaoaParametersMagic()
+        {
+            this.Name = $"%qaoa.hybridqaoa.create.parameters";
+            this.Documentation = new Documentation()
+            {
+                Summary = "Prepares a QAOA parameters object that serves as one of arguments to %qaoa.hybridqaoa.run."
+            };
+            this.Kind = SymbolKind.Magic;
+            this.Execute = this.Run;
+        }
+
+        /// <summary>
+        /// List of arguments.
+        /// </summary>
+        public class Arguments
+        {
+            /// <summary>
+            /// Betas QAOA coefficients.
+            /// </summary>
+            [JsonProperty(PropertyName = "beta")]
+            public double[] Beta { get; set; }
+
+            /// <summary>
+            /// Gammas QAOA coefficients.
+            /// </summary>
+            [JsonProperty(PropertyName = "gamma")]
+            public double[] Gamma { get; set; }
+        }
+
+        /// <summary>
+        /// Prepares a QaoaParameters object for a hybrid QAOA.
+        /// </summary>
+        public async Task<ExecutionResult> Run(string input, IChannel channel)
+        {
+            if (string.IsNullOrWhiteSpace(input))
+            {
+                channel.Stderr("Please provide correct arguments");
+                return ExecuteStatus.Error.ToExecutionResult();
+            }
+
+            var args = JsonConvert.DeserializeObject<Arguments>(input);
+
+            var qaoaParameters = new QaoaParameters(args.Beta, args.Gamma);
+
+            return qaoaParameters.ToExecutionResult();
+        }
+    }
+}