qSonify_HelloWorld.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# qSonify Hello World: Hearing Algorithms to Aid Algorithmic Abstraction\n",
    "#### https://github.com/jiosue/qSonify"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will show how to use qSonify to recognize patterns in quantum algorithms in order to help us understand their decomposition and/or abstraction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import qSonify"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For our example, let's define two algorithms. Firstly, qSonify gives the ability to represent certain supported gates as strings, for example \"cx(0, 2)\" for a controlled-not gate from qubit 0 to 2. But for unitary transformations which are not by default supported, we can instead input a qSonify.Gate object, which takes in a unitary matrix and a tuple of qubits that the unitary will be applied to. An algorithm is a list of these gates, either string gates or qSonify.Gate objects.\n",
    "\n",
    "For example, a Hadamard gate on qubit 2 can be created in any of the following ways (let n = 1 / sqrt(2)):\n",
    "\n",
    "    H2 = qSonify.gates.H(2)\n",
    "    H2 = \"H(2)\"\n",
    "    H2 = qSonify.Gate([[n, n], [n, -n]], (2,))\n",
    "    \n",
    "For simple, common gates this is redundant. However, for more general unitary transformations, the first two will not work. For examle, consider a gate operating on qubits 1 and 3 with some arbitrary 4x4 unitary matrix U, ie something of the form:\n",
    "\n",
    "    U = [[_, _, _, _],\n",
    "         [_, _, _, _],\n",
    "         [_, _, _, _],\n",
    "         [_, _, _, _]]\n",
    "     \n",
    " This gate can only be represented as:\n",
    " \n",
    "     G = qSonify.Gate(U, (1, 3))\n",
    "     \n",
    "Note that when using qSonify.Gate, it will NOT check to be sure that the matrix you provide is indeed unitary.\n",
    "     \n",
    "Now let's define our two algorithms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alg1 = [\"h(0)\", \"cx(0, 1)\", \"cx(0, 2)\", \"cx(0, 3)\", \"cx(0, 4)\"]\n",
    "alg2 = ['h(0)', 'rz(pi, 2)', \n",
    "        qSonify.Gate([[0.5, 0.75**0.5], [-0.75**0.5, 0.5]], (4,)), 'rx(pi/2, 2)', 'cx(0, 3)']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we have to choose a mapping from output to midi file. Many mappings require us to choose a set of notes to use, let's define ours here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "notes = \"c4\", \"d4\", \"e4\", \"f4\", \"g4\", \"a4\", \"b4\", \"c5\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's define/choose our mapping. We can either define our own mapping or choose one of the one's already implemented. Choosing a mapping is really the essence of sonification. I have chosen to map the outputs to MIDI notes because it allows for simple implementation. I encourage anyone to try out all these mappings and define your own, as well as try mappings to representations other than MIDI (not supported by qSonify :( ). I have found the grandpiano mapping to sound quite nice on this particular example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#mapping = qSonify.maps.fermionic(notes=notes)\n",
    "#mapping = qSonify.maps.scale(notes=notes)\n",
    "mapping = qSonify.maps.grandpiano(low_notes=(\"c3\", \"d3\", \"e3\", \"f3\", \"g3\"), high_notes=notes)\n",
    "#mapping = qSonify.maps.stringquartet()\n",
    "#mapping = qSonify.maps.frequencymapping(low_freq=300, base=4)\n",
    "\n",
    "# user_defined mapping must be of this form.\n",
    "# as an examle, this particular user defined mapping is\n",
    "# the same as qSonify.frequencymapping(low_freq=300, base=4).\n",
    "# To see more details of how to add more tracks, etc, see the\n",
    "# `maps` folder.\n",
    "# def mapping(res, name, tempo):\n",
    "#     \"\"\"\n",
    "#     res: list of strings, outputs of the quantum computer run, ie\n",
    "#          ['10010', '01101', ...]\n",
    "#     name: str, name of the song.\n",
    "#     tempo: int, tempo of the song.\n",
    "#     return: qSonify.Song object.\n",
    "#     \"\"\"\n",
    "#     s = qSonify.Song(name=name, tempo=tempo, num_tracks=1)\n",
    "#     for x in res:\n",
    "#         note = qSonify.freq_to_note(int(x, base=4) + 300)\n",
    "#         s.addNote(note, duration=.5) # eigth notes\n",
    "#     return s"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's run it! We use the function with the following keyword arguments:\n",
    "\n",
    "    qSonify.alg_to_song(algorithm, num_qubits=None, num_samples=40, mapping=maps.default_map, name=\"alg\", tempo=100):\n",
    "        \"\"\"\n",
    "        Make a song from an algorithm. Markovian sample the algorithm, then map\n",
    "        to a Song object.\n",
    "\n",
    "        algorithm: list of Gate objects and/or string gates. Example:\n",
    "                      [\"cx(0, 1)\", \n",
    "                       \"x(0)\", \n",
    "                       qSonify.Gate(unitary=[[...], ...], qubits=(1, 2))\n",
    "                      ]\n",
    "        num_qubits: int, number of qubits to run each algorithm on. If num_qubits\n",
    "                         is None, then it will run on the minimum required.\n",
    "        num_samples: int, number of samples to take from the quantum computer,\n",
    "                          for most mappings this is equal to the number of beats.\n",
    "        mapping: function, which mapping from output to sound to use. Can either \n",
    "                           use the ones already defined (ie maps.[map name](args)), \n",
    "                           or create your own mapping function. mapping must take\n",
    "                           a list of outputs from the qc, a name of the song, and\n",
    "                           a tempo of the song, and return a Song object.\n",
    "        name: str, name of song.\n",
    "        tempo: int, tempo of song.\n",
    "\n",
    "        returns: qSonify.Song object\n",
    "        \"\"\"\n",
    "\n",
    "Markovian sampling is inputting the output of the previous run in as the input to the next run. This lets us explore more of the transformation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kwargs = dict(num_samples=40, mapping=mapping, tempo=150)\n",
    "\n",
    "s1 = qSonify.alg_to_song(alg1, name=\"HelloWorld_alg1\", **kwargs)\n",
    "s2 = qSonify.alg_to_song(alg2, name=\"HelloWorld_alg2\", **kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's listen to them! *Note the play function only works on Windows right now, because it just calls the system to open the midi file, which Windows by default opens in Windows Media Player. To play the files on your computer if it is non Windows, go to the folder output/ and open the saved .mid file however you want.*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s1.play('outputs/')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2.play('outputs/')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's see if we can still \"hear\" these algorithms when they are embedded within another circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alg1_emb = [\"h(4)\", \"rz(pi/8, 2)\"] + alg1 + [\"h(1)\"]\n",
    "alg2_emb = [\"h(2)\", \"rz(pi/4, 0)\"] + alg2 + [\"h(0)\"]\n",
    "# alg2_emb = [\"h(4)\", \"rz(pi/8, 2)\"] + alg2 + [\"h(1)\"]\n",
    "\n",
    "s1_emb = qSonify.alg_to_song(alg1_emb, name=\"HelloWorld_alg1_emb\", **kwargs)\n",
    "s2_emb = qSonify.alg_to_song(alg2_emb, name=\"HelloWorld_alg2_emb\", **kwargs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s1_emb.play('outputs/') # compare to s1.play()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2_emb.play('outputs/') # compare to s2.play()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Can you hear the similarities? Do you hear the original algorithm embedded within the new one? Now let's try one more thing. Let see if we can hear both algorithm1 and algorithm2 when they are performed in the same algorithm and embedded within other gate sequences."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alg12_emb = alg1_emb + alg2_emb + alg2_emb + alg1_emb\n",
    "s12_emb = qSonify.alg_to_song(alg12_emb, name=\"HelloWorld_alg12_emb\", **kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's listen to it. Try and compare `s12_emb` to `s1`, `s2`, `s1_emb`, and `s2_emb`, and try to see if you can hear the original `alg1` and `alg2`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s12_emb.play('outputs/')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So did you hear it? Sonifying quantum algorithms in this way could help researchers \"decompile\" algorithms that are represented in terms of elementary gate operations that are generally hard to abstract from. Try testing some different mappings or defining your own! All the midi file outputs from `s.play()` or `s.writeFile(path)` are saved in the path directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I encourage anyone to use a software to convert the MIDI files into sheet music and check it out. Do you think it is easier to \"see\" the embedded algorithms or \"hear\" them? Sonification is a powerful tool because our ears can often hear patterns that are difficult for our eyes to pick out."
   ]
  }
 ],
 "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.6.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}