{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "# Gate String Tutorial\n",
    "This tutorial will show you how to create and use `GateString` objects, which represent an ordered sequence (or \"string\") of gate set operations.  In most cases, a `GateString` may optionally begin with a state-preparation label and end with a POVM label, and contains gate labels as all its other elements. In almost all cases, you'll be using a list (or even a list of lists!) of `GateString`s, so we'll often be talking about \"gate string lists\".\n",
    "\n",
    "A `GateString` object is nearly identical, and sometimes interchangeable, with a Python tuple of *gate labels* (i.e. the names beginning with `G` that label the gate operations in a `GateSet`) or *instrument labels* (beginning with `I`), sometimes sandwiched between a state preparation and POVM (measurement) label.  `GateString`s can be accessed and operated upon just as a standard Python tuple.  The primary difference between a `GateString` and a tuple is that a `GateString` also contains a \"string representation\" of the gate sequence.  This string representation gets carried along for the ride until it's needed, typically when writing a the gate string to a file.  The string representation must *evaluate*, using pyGSTi's allowed text format for gate strings (see below), to the tuple-of-gate-labels, or \"tuple representation\".  The string representation is intended to contain a compact and intuitive human-readable form of the gate sequence that is used for display purposes.  For example, the gate string `('Gx','Gx','Gx','Gx','Gx')` might have the string representation `\"Gx^5\"`.  If needed, the tuple and string representations of any `GateString`  `g` can be accessed via `g.tup` or `tuple(g)` and `g.str` or `str(g)` respectively.\n",
    "\n",
    "Gate strings are central to Gate Set Tomography, as they describe both real and \"simulated\" experiments.  A `GateString`'s ordered sequence tells the experimentalist which gates they must execute on their hardware and likewise what order to compose (i.e. multiply) the gate matrices contained in a `GateSet`.  When a state preparation or POVM label is omitted from the beginning or end of a gate string, respectively, one must be *inferred*.  This is currently only possible when the relevant `GateSet` object holds only a single state preparation or POVM.  The outcomes of an experiment are labeled by 1-tuples of the given (or inferred) POVM effect labels.  When the gate string contains instruments (which produce intermediate measurement outcomes), the \"outcome label\" is a tuple of length greater than one, where each element correponds to the outcome of a single instrument or the final POVM.  Thus, by repeating an experiment one obtains counts and thereby frequencies for each outcome label.  Given a `GateSet` one can obtain corresponding probabilities by muliplying gate matrices and contracting the product between a state preparation and POVM effect vector.  \n",
    "\n",
    "The **ordering direction** is important.  The elements of a `GateString` are read from **left-to-right**, meaning the first (left-most) gate label is performed first.  This is very natural for experiments since one can read the gate string as a script, executing each gate as one reads from left to right.  However, since we insist on \"normal\" matrix multiplication conventions, the ordering of the matrix product is *reversed* from that of the gate string.  For example, the gate string `('Ga','Gb','Gc')`, in which Ga is performed first, corresponds to the matrix product $G_c G_b G_a$.  The probability of this gate string for a SPAM label associated with the (column) vectors ($\\rho_0$,$E_0$) is given by $E_0^T G_c G_b G_a \\rho_0$, which can be interpreted as \"prepare state 0 first, then apply gate A, then B, then C, and finally measure effect 0\".  While this nuance is typically hidden from the user (the `GateSet` functions which compute products and probabilities from `GateString`s perform the order reversal internally), it becomes very important if you plan to perform such products by hand. \n",
    "\n",
    "We'll now go over some examples of how to create and use a single `GateString`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "from __future__ import print_function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import pygsti # the main pyGSTi module\n",
    "import pygsti.construction as pc  #shorthand\n",
    "from pygsti.construction import std1Q_XY #a standard gateset & peripherals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## A simple example: the single `GateString`\n",
    "The cell below show how to create a `GateString` object from a tuple, optionally with a corresponding string representation.  It demonstrates how to access the tuple and string representations directly, and the tuple-like operations that can be performed on a `GateString`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Printing\n",
      "s1 = GxGx\n",
      "s2 = Gx^2\n",
      "s3 = Gx^2\n",
      "\n",
      "Printing tuple(.)\n",
      "s1 = ('Gx', 'Gx')\n",
      "s2 = ('Gx', 'Gx')\n",
      "s3 = ('Gx', 'Gx')\n",
      "\n",
      "s1.tup = ('Gx', 'Gx') ,  s1.str =  GxGx\n",
      "tuple(s1) = ('Gx', 'Gx') ,  str(s1) =  GxGx\n",
      "\n",
      "s1 + s2 =  GxGxGx^2 , tuple =  ('Gx', 'Gx', 'Gx', 'Gx')\n",
      "s1*3    =  (GxGx)^3 , tuple =  ('Gx', 'Gx', 'Gx', 'Gx', 'Gx', 'Gx')\n",
      "\n"
     ]
    }
   ],
   "source": [
    "#Construction of a GateString\n",
    "s1 = pygsti.objects.GateString( ('Gx','Gx') ) # from a tuple\n",
    "s2 = pygsti.objects.GateString( ('Gx','Gx'), \"Gx^2\" ) # from tuple and string representations (must match!)\n",
    "s3 = pygsti.objects.GateString( None, \"Gx^2\" ) # from just a string representation\n",
    "\n",
    "#All of these are equivalent (even though their string representations aren't -- only tuples are compared)\n",
    "assert(s1 == s2 == s3)\n",
    "\n",
    "#Printing displays the string representation\n",
    "print(\"Printing\")\n",
    "print(\"s1 = %s\" % s1)\n",
    "print(\"s2 = %s\" % s2)\n",
    "print(\"s3 = %s\" % s3, end='\\n\\n')\n",
    "\n",
    "#Casting to tuple displays the tuple representation\n",
    "print(\"Printing tuple(.)\")\n",
    "print(\"s1 =\", tuple(s1))\n",
    "print(\"s2 =\", tuple(s2))\n",
    "print(\"s3 =\", tuple(s3), end='\\n\\n')\n",
    "\n",
    "#Access to tuple or string representation directly:\n",
    "print(\"s1.tup =\", s1.tup, \",  s1.str = \", s1.str)\n",
    "print(\"tuple(s1) =\", tuple(s1), \",  str(s1) = \", str(s1), end='\\n\\n')\n",
    "\n",
    "#Operations\n",
    "assert(s1 == ('Gx','Gx')) #can compare with tuples\n",
    "s4 = s1+s2 #addition (note this concatenates string reps)\n",
    "s5 = s1*3  #integer-multplication (note this exponentiates in string rep)\n",
    "print(\"s1 + s2 = \",s4, \", tuple = \", tuple(s4))\n",
    "print(\"s1*3    = \",s5, \", tuple = \", tuple(s5), end='\\n\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## List Construction Functions:  `pygsti.construction` and `create_gatestring_list`\n",
    "Usually you'll be working with entire lists of `GateString` objects which define some part of the experiments utilized by Gate Set Tomography.  pyGSTi provides several functions for constructing gate string lists, which we not demonstrate.\n",
    "\n",
    "The workhorse function is `pygsti.construction.create_gatestring_list`, which executes its positional arguments within a nested loop given by iterable keyword arguments.  That's a mouthful, so let's look at a few examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "list1 = [('a1',), ('a2',)]\n",
      "list2 = [GateString(a1b1b2), GateString(a1b3b4), GateString(a2b1b2), GateString(a2b3b4)]\n",
      "list3 = ['a1a1c', 'a2a2c']\n"
     ]
    }
   ],
   "source": [
    "As = [('a1',),('a2',)]\n",
    "Bs = [('b1','b2'), ('b3','b4')]\n",
    "\n",
    "def rep2(x):\n",
    "    return x+x\n",
    "\n",
    "list1 = pc.create_gatestring_list(\"a\", a=As)\n",
    "list2 = pc.create_gatestring_list(\"a+b\", a=As, b=Bs, order=['a','b'])\n",
    "list3 = pc.create_gatestring_list(\"R(a)+c\", a=As, c=[('c',)], R=rep2)\n",
    "\n",
    "print(\"list1 = %s\" % list(map(tuple, list1)))\n",
    "print(\"list2 = %s\" % list2)\n",
    "print(\"list3 = %s\" % list(map(str,list3)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Many of the gate sequences used by Gate Set Tomography are composed of three parts.  A \"preparation fiducial\" sequence is followed by a \"repeated germ\" sequence, which is followed by a \"measurement fiducial\" sequence.  We won't get into why this structure is used, but simply use this fact to motivate looking at gate strings of the form $f_1 + R(g) + f_2$, where the $f_1$ and $f_2$ fiducial sequences are simple short sequences are $R(g)$ is a possibly long sequence that is generated by repeating a short sequence $g$ called a \"germ\".\n",
    "\n",
    "It is possible to generate \"repeated germ\" sequences in several ways using the functions **`pygsti.construction.repeat_`*xxx* **.  In modern GST, germ sequences are always repeated an *integer* number of times rather than being truncated to a precise length, so `repeat_with_max_length` is used instead of `repeat_and_truncate`.  Below we demonstrate the use of these functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "('A', 'B', 'C', 'A', 'B')\n",
      "('A', 'B', 'C')\n",
      "1\n"
     ]
    }
   ],
   "source": [
    "print(pc.repeat_and_truncate(('A', 'B', 'C'), 5)) #args (x,N): repeat x until it is exactly length N\n",
    "\n",
    "print(pc.repeat_with_max_length(('A', 'B', 'C'), 5)) #args (x,N): repeat x the maximum integer number of times so len(x) < N\n",
    "\n",
    "print(pc.repeat_count_with_max_length(('A', 'B', 'C'), 5)) #args (x,N): the maximum integer number of times so len(x) < N"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "We can combine a repeated germ sequence between two fiducial sequences using `create_gatestring_list`.  This demonstrates the power of the `create_gatestring_list` to perform nested loops.  We also introduce the \"bulk-conversion\" function `gatestring_list`, which creates a list of `GateString` objects from a list of tuples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "gateStrings1 = \n",
      " Gf0(G0)^2Gf0\n",
      "Gf0(G0)^2Gf1\n",
      "Gf1(G0)^2Gf0\n",
      "Gf1(G0)^2Gf1\n",
      "Gf0(G1aG1b)^2Gf0\n",
      "Gf0(G1aG1b)^2Gf1\n",
      "Gf1(G1aG1b)^2Gf0\n",
      "Gf1(G1aG1b)^2Gf1 \n",
      "\n",
      "gateStrings2 = \n",
      " Gf0G0G0G0Gf0\n",
      "Gf0G0G0G0Gf1\n",
      "Gf1G0G0G0Gf0\n",
      "Gf1G0G0G0Gf1\n",
      "Gf0G1aG1bG1aGf0\n",
      "Gf0G1aG1bG1aGf1\n",
      "Gf1G1aG1bG1aGf0\n",
      "Gf1G1aG1bG1aGf1 \n",
      "\n",
      "gateStrings3 = \n",
      " Gf0(G0)^3Gf0\n",
      "Gf0(G0)^3Gf1\n",
      "Gf1(G0)^3Gf0\n",
      "Gf1(G0)^3Gf1\n",
      "Gf0(G1aG1b)Gf0\n",
      "Gf0(G1aG1b)Gf1\n",
      "Gf1(G1aG1b)Gf0\n",
      "Gf1(G1aG1b)Gf1 \n",
      "\n"
     ]
    }
   ],
   "source": [
    "fids  = pc.gatestring_list( [ ('Gf0',), ('Gf1',)    ] ) #fiducial strings\n",
    "germs = pc.gatestring_list( [ ('G0',), ('G1a','G1b')] ) #germ strings\n",
    "\n",
    "gateStrings1 = pc.create_gatestring_list(\"f0+germ*e+f1\", f0=fids, f1=fids,\n",
    "                                       germ=germs, e=2, order=[\"germ\",\"f0\",\"f1\"])\n",
    "print(\"gateStrings1 = \\n\", \"\\n\".join(map(str,gateStrings1)),\"\\n\")\n",
    "\n",
    "gateStrings2 = pc.create_gatestring_list(\"f0+T(germ,N)+f1\", f0=fids, f1=fids,\n",
    "                                        germ=germs, N=3, T=pc.repeat_and_truncate,\n",
    "                                        order=[\"germ\",\"f0\",\"f1\"])\n",
    "\n",
    "print(\"gateStrings2 = \\n\", \"\\n\".join(map(str,gateStrings2)),\"\\n\")\n",
    "\n",
    "gateStrings3 = pc.create_gatestring_list(\"f0+T(germ,N)+f1\", f0=fids, f1=fids,\n",
    "                                        germ=germs, N=3, T=pc.repeat_with_max_length,\n",
    "                                        order=[\"germ\",\"f0\",\"f1\"])\n",
    "print(\"gateStrings3 = \\n\", \"\\n\".join(map(str,gateStrings3)), \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "In addition to `create_gatestring_list`, the **`pygsti.construction.list_`*xxx* ** functions provide ways of constructing common gate string lists.  The example below shows how to construct all possible gate strings within a certain length range, as well as how to construct the set of gate strings needed to run Linear Gate Set Tomography given a set of fiducial strings. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "All strings using ['Gx', 'Gy'] up to length 2 = \n",
      " {}\n",
      "Gx\n",
      "Gy\n",
      "GxGx\n",
      "GxGy\n",
      "GyGx\n",
      "GyGy\n"
     ]
    }
   ],
   "source": [
    "myGates = [ 'Gx', 'Gy' ]  #gate labels -- often just gateset.gates.keys()\n",
    "allStringsInLengthRange = pc.list_all_gatestrings(myGates, minlength=0, maxlength=2)\n",
    "print(\"\\nAll strings using %s up to length 2 = \\n\" \\\n",
    "    % str(myGates), \"\\n\".join(map(str,allStringsInLengthRange)))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "LGST strings = \n",
      " Gf1\n",
      "Gf2\n",
      "Gf1Gf1\n",
      "Gf1Gf2\n",
      "Gf2Gf1\n",
      "Gf2Gf2\n",
      "Gf1(Gx)Gf1\n",
      "Gf1(Gx)Gf2\n",
      "Gf2(Gx)Gf1\n",
      "Gf2(Gx)Gf2\n",
      "Gf1(Gy)Gf1\n",
      "Gf1(Gy)Gf2\n",
      "Gf2(Gy)Gf1\n",
      "Gf2(Gy)Gf2\n"
     ]
    }
   ],
   "source": [
    "myFiducialList = pc.gatestring_list([ ('Gf1',), ('Gf2',) ])  #list of fiducials\n",
    "\n",
    "lgstStrings = pc.list_lgst_gatestrings(myFiducialList,myFiducialList,myGates)\n",
    "\n",
    "print(\"\\nLGST strings = \\n\",\"\\n\".join(map(str,lgstStrings)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Manipulating `GateStrings`\n",
    "Sometimes it is useful to manipulate a `GateString` (or a list of them) via find & replace operations.  The `manipulate_gatestring` and `manipulate_gatestring_list` functions take as input a set of replacement \"rules\" and process one or more `GateString` objects accordingly.  For example, the rules\n",
    "\n",
    "- ab $\\rightarrow$ AB' (if B follows A, prime B)\n",
    "- BA $\\rightarrow$ B''A (if B precedes A, double-prime B)\n",
    "- CA $\\rightarrow$ CA' (if A follows C, prime A)\n",
    "- BC $\\rightarrow$ BC' (if C follows B, prime C)\n",
    "\n",
    "are specified by the dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "sequenceRules = [\n",
    "        ((\"A\", \"B\"), (\"A\", \"B'\")),\n",
    "        ((\"B\", \"A\"), (\"B''\", \"A\")),\n",
    "        ((\"C\", \"A\"), (\"C\", \"A'\")),\n",
    "        ((\"B\", \"C\"), (\"B\", \"C'\"))]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Will produce the output:\n",
    "- BAB $\\rightarrow$ B''AB'\n",
    "- ABA $\\rightarrow$ AB'A  (frustrated!)\n",
    "- CAB $\\rightarrow$ CA'B'\n",
    "- ABC $\\rightarrow$ AB'C'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "B''AB'\n",
      "AB'A\n",
      "CA'B'\n",
      "AB'C'\n"
     ]
    }
   ],
   "source": [
    "from pygsti.objects import GateString\n",
    "from pygsti.construction import manipulate_gatestring\n",
    "\n",
    "print(manipulate_gatestring(GateString(tuple('BAB')), sequenceRules))\n",
    "print(manipulate_gatestring(GateString(tuple('ABA')), sequenceRules))\n",
    "print(manipulate_gatestring(GateString(tuple('CAB')), sequenceRules))\n",
    "print(manipulate_gatestring(GateString(tuple('ABC')), sequenceRules))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "B''AB'\n",
      "AB'A\n",
      "CA'B'\n",
      "AB'C'\n"
     ]
    }
   ],
   "source": [
    "# You can also process an entire list of gate strings in bulk\n",
    "orig_lst = pygsti.construction.gatestring_list([ tuple('BAB'), tuple('ABA'), tuple('CAB'), tuple('ABC')])\n",
    "lst = pygsti.construction.manipulate_gatestring_list(orig_lst, sequenceRules)\n",
    "print('\\n'.join([str(s) for s in lst]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Gate Label \"Aliases\"\n",
    "A similar but simpler type of manipulation called \"gate label aliasing\" is used in pyGSTi to map a gate label into another gate label **only for `DataSet` lookups**.  The mapping is similar to `manipulate_gatestring`'s find & replace functionality, except that (at least currently) the string to find can be only a single gate label  (and so isn't even a string at all). The support for gate label aliasing within pyGSTi's algorithms aids in mapping many `GateSet` models onto the same data (often with simpler gate labelling). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "#TODO: remove Aliasing or provide examples?"
   ]
  }
 ],
 "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.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}