adding simons algorithm tutorial

tutorials/ExploringSimonsAlgorithm/ExploringSimonsAlgorithm.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <PlatformTarget>x64</PlatformTarget>
+    <RootNamespace>Quantum.Kata.ExploringSimonsAlgorithm</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Quantum.Standard" Version="0.11.2003.3107" />
+    <PackageReference Include="Microsoft.Quantum.Development.Kit" Version="0.11.2003.3107" />
+    <PackageReference Include="Microsoft.Quantum.Xunit" Version="0.11.2003.3107" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="15.3.0" />
+    <PackageReference Include="xunit" Version="2.3.1" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.3.1" />
+    <DotNetCliToolReference Include="dotnet-xunit" Version="2.3.1" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="README.md" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\utilities\Common\Common.csproj" />
+  </ItemGroup>  
+</Project>

tutorials/ExploringSimonsAlgorithm/ExploringSimonsAlgorithmClassicalPart.ipynb

@@ -0,0 +1,218 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Exploring Simon's Periodicity Algorithm: Classical Component\n",
+    "\n",
+    "This is a companion notebook to the [Exploring Simon's Periodicity Algorithm: Quantum Component](./ExploringSimonsAlgorithmQuantumPart.ipynb) tutorial. It will teach you about the classical post-processing component of Simon's Algorithm."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Classical Post-Processing for Simon's Algorithm\n",
+    "\n",
+    "The quantum circuit we ran at the end of the companion tutorial output the binary string $\\mathbf{j}$ with length $n$, where $\\mathbf{j} \\in\\ \\{0, 1\\}^n$ and satisfies $\\mathbf{s} \\cdot\\ \\mathbf{j} = 0$. Is this enough information to solve for $\\mathbf{s}$?\n",
+    "\n",
+    "The answer is yes, but with caveats. We need to run the quantum circuit $n - 1$ times to produce $n - 1$ binary strings $\\mathbf{j_{1}}, ... , \\mathbf{j_{n-1}}$ such that\n",
+    "\n",
+    "$$\\mathbf{j_{1}} \\cdot\\ \\mathbf{s} = 0$$\n",
+    "$$\\mathbf{j_{2}} \\cdot\\ \\mathbf{s} = 0$$\n",
+    "$$.$$\n",
+    "$$.$$\n",
+    "$$.$$\n",
+    "$$\\mathbf{j_{n-1}} \\cdot\\ \\mathbf{s} = 0$$\n",
+    "\n",
+    "However, we still have a non-trivial chance of failure. To arrive at a solution, $\\mathbf{j_{1}}, ... , \\mathbf{j_{n-1}}$ must be linearly independent and we must also be lucky.\n",
+    "\n",
+    "If we have linear independence, we can solve the under-determined system of $n-1$ equations and $n$ unknowns to get a candidate solution $\\mathbf{s'}$. We can then test this candidate solution, and if we find that $f(0^n) = f(\\mathbf{s'})$, we know that $\\mathbf{s} = \\mathbf{s'}$. The problem is solved!\n",
+    "\n",
+    "A standard way to solve this system employs [Gaussian elimination with back substitution](http://mathonline.wikidot.com/gaussian-elimination-and-back-substitution). Links to resources are provided if you need a refresher on concepts like [Gaussian elimination](https://en.wikipedia.org/wiki/Gaussian_elimination). Let's practice writing functions in Python to help us achieve our goal!\n",
+    "\n",
+    "> **Note:** The [linear algebra tutorial](https://github.com/microsoft/QuantumKatas/blob/master/tutorials/LinearAlgebra/LinearAlgebra.ipynb) notebook contains example implementations of some linear algebra functions in Python.\n",
+    "\n",
+    "Let's start by setting up a few things necessary for testing the exercises. **Do not skip this step.**\n",
+    "\n",
+    "Click the cell with code below this block of text and press `Ctrl+Enter` (`shift+return` on Mac)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Success!\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Run this cell using Ctrl+Enter (shift+return on Mac).\n",
+    "from tests import exercise\n",
+    "from typing import List\n",
+    "\n",
+    "Matrix = List[List[float]]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Recall that the goal of Gaussian elimination is to transform a matrix to [row echelon form](https://en.wikipedia.org/wiki/Row_echelon_form); i.e. into an [upper triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix). To achieve this form, there are three types of elementary row operations we can perform:\n",
+    "* Swapping two rows,\n",
+    "* Multiplying a row by a nonzero number, and\n",
+    "* Adding a multiple of one row to another row.\n",
+    "\n",
+    "Let's try using these operations to transform a matrix to row echelon form in Python.\n",
+    "\n",
+    "## Exercise 3. Row echelon form of a matrix\n",
+    "\n",
+    "**Input:**\n",
+    "\n",
+    "* A matrix $\\mathbf{J}$ of dimensions $n-1$ x $n$\n",
+    "\n",
+    "**Output:**\n",
+    "\n",
+    "* [Upper triangular form](https://en.wikipedia.org/wiki/Triangular_matrix) of the matrix $\\mathbf{J}$\n",
+    "\n",
+    "**Example:**\n",
+    "\n",
+    "$\\begin{bmatrix} 0 & 1 & 1 \\\\ 1 & 1 & 1 \\end{bmatrix}$ should be transformed to $\\begin{bmatrix} 1 & 1 & 1 \\\\ 0 & 1 & 1 \\end{bmatrix}$\n",
+    "\n",
+    "> **Note:** Beware of [singular matrices](https://en.wikipedia.org/wiki/Singular_matrix)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@exercise\n",
+    "def row_echelon_form(J : Matrix) -> Matrix:    \n",
+    "    # ...\n",
+    "    \n",
+    "    return ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The final step in Gaussian elimination is to solve the system using [back substitution](https://algowiki-project.org/en/Backward_substitution).\n",
+    "\n",
+    "The matrix $\\begin{bmatrix} 1 & 1 & 1 \\\\ 0 & 1 & 1 \\end{bmatrix}$ can be represented as the system of equations\n",
+    "\n",
+    "$$x_0 + x_1 = 1$$\n",
+    "$$      x_1 = 1$$\n",
+    "\n",
+    "Substituting $x_1 = 1$ into the first equation yields the result $x_0 = 0$ and our system is solved. We can return $[x_0, x_1] = [0, 1]$.\n",
+    "\n",
+    "Next, try implementing a Python function to perform back substitution.\n",
+    "\n",
+    "## Exercise 4. Back substitution\n",
+    "\n",
+    "**Input:**\n",
+    "\n",
+    "* A matrix $\\mathbf{J}$ in row echelon form that contains a unique solution\n",
+    "\n",
+    "**Output:**\n",
+    "\n",
+    "* The unique solution as a list $[x_0, ..., x_n]$"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@exercise\n",
+    "def back_substitution(J : Matrix) -> List:    \n",
+    "    # ...\n",
+    "    \n",
+    "    return ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We learned earlier that the output of our quantum circuit is some $\\mathbf{j}$ that satisfied the property $\\mathbf{s} \\cdot\\ \\mathbf{j} = 0$. This property is more accurately described as $\\mathbf{s} \\cdot\\ \\mathbf{j} = 0$ modulo $2$.\n",
+    "\n",
+    "Now let's implement a Python function to compute the [dot product](https://en.wikipedia.org/wiki/Dot_product) mod 2.\n",
+    "\n",
+    "## Exercise 5: Dot product modulo 2\n",
+    "\n",
+    "**Inputs:**\n",
+    "\n",
+    "1. A vector $\\mathbf{a} = [a_0, ... , a_n]$\n",
+    "2. A vector $\\mathbf{b} = [b_0, ... , b_n]$\n",
+    "\n",
+    "**Output:**\n",
+    "\n",
+    "The scalar value that represents the dot product of $\\mathbf{a}$ and $\\mathbf{b}$ mod $2$\n",
+    "\n",
+    "**Examples:**\n",
+    "\n",
+    "* If $\\mathbf{a} = [1, 0, 0, 1]$ and $\\mathbf{b} = [1, 0, 1, 0]$, the function should output $1$\n",
+    "* If $\\mathbf{a} = [1, 1, 1]$ and $\\mathbf{b} = [0, 1, 1]$, the function should output $0$\n",
+    "\n",
+    "> **Hint:** This function should only output 0 or 1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@exercise\n",
+    "def dot_product(a : Matrix, b : Matrix) -> float:\n",
+    "    # ...\n",
+    "    \n",
+    "    return ..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "At this stage you have learned the tools necessary for the classical post-processing part of Simon's algorithm. This concludes the discussion of Simon's peridocity algorithm.\n",
+    "\n",
+    "# What's next?\n",
+    "\n",
+    "We hope you've enjoyed this tutorial and learned a lot from it! If you're looking to learn more about quantum computing and Q#, here are some suggestions:\n",
+    "* The [Quantum Katas](https://github.com/microsoft/QuantumKatas/) are sets of programming exercises on quantum computing that can be solved using Q#. They cover a variety of topics, from the basics like the concepts of superposition and measurements to more interesting algorithms like Grover's search.\n",
+    "* In particular, [SimonsAlgorithm quantum kata](https://github.com/microsoft/QuantumKatas/tree/master/SimonsAlgorithm) offers more exercises on quantum oracles and a different presentation of Simon's algorithm."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}