{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# An overview of Gate Set Tomography"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `pygsti` package provides multiple levels of abstraction over the core Gate Set Tomography (GST) algorithms.  This tutorial will show you how to run Gate Set Tomography on some simulated (generated) data, hopefully giving you an overall sense of what it takes (and how easy it is!) to run GST.  For more details and options for running GST, see the [GST circuits tutorial](../objects/advanced/GSTCircuitConstruction.ipynb) and the [tutorial covering the different protocols for running GST](GST-Protocols.ipynb).\n",
    "\n",
    "There are three basic steps to running protocols in pyGSTi:\n",
    "\n",
    "## Step 1: create an experiment design\n",
    "The first step is creating an object that specifies what data (from the quantum processor) will be needed to perform GST, and how it should be taken.  This is called an \"experiment design\" in pyGSTi.\n",
    "\n",
    "To run GST, we need the following three inputs:\n",
    "1. a \"**target model**\" which describes the desired, or ideal, operations we want our experimental hardware to perform.  In the example below, we use the target model from one of pyGSTi's build-in \"model packs\" (see the [tutorial on model packs](objects/advanced/ModelPacks.ipynb)) - which acts on a single qubit with the following operations:\n",
    "    - three gates: the identity, and $\\pi/2$ rotations around the $x$- and $y$-axes.\n",
    "    - a single state preparation in the $|0\\rangle$ state.\n",
    "    - a 2-outcome measurement with the label \"0\" associated with measuring $|0\\rangle$ and \"1\" with measuring $|1\\rangle$.\n",
    "    \n",
    "2. a list of circuits tailored to the target model; essentially a list of what experiments we need to run.  Using a standard model makes things especially straightforward here, since the building blocks, called *germ* and *fiducial* circuits, needed to make good GST circuits have already been computed (see the [tutorial on GST circuits](../objects/advanced/GSTCircuitConstruction.ipynb)).  In the example below, the model pack also provides the necessary germ and fiducial lists, so that all that is needed is a list of \"maximum lengths\" describing how long (deep) the circuits should be.\n",
    "\n",
    "3. data, in the form of experimental outcome counts, for each of the required sequences.  In this example we'll generate \"fake\" or \"simulated\" data from a depolarized version of our ideal model.  For more information about `DataSet` objects, see the [tutorial on DataSets](../objects/DataSet.ipynb).\n",
    "\n",
    "The first two inputs form an \"experiment design\", as they describe the experiment that must be performed on a quantum processor (usually running some prescribed set of circuits) in order to run the GST protocol.  The third input - the data counts - is packaged with the experiment design to create a `ProtocolData`, or \"data\" object.  As we will see later, a data object serves as the input to the GST protocol.\n",
    "\n",
    "**The cell below creates an experiment design for running standard GST on the 1-qubit quantum process described by the gates above using circuits whose depth is at most 32.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pygsti\n",
    "from pygsti.modelpacks import smq1Q_XYI\n",
    "\n",
    "#Step 1: create an \"experiment design\" for doing GST on the std1Q_XYI gate set\n",
    "target_model = smq1Q_XYI.target_model()      # a Model object\n",
    "prep_fiducials = smq1Q_XYI.prep_fiducials()  # a list of Circuit objects\n",
    "meas_fiducials = smq1Q_XYI.meas_fiducials()  # a list of Circuit objects\n",
    "germs = smq1Q_XYI.germs()                    # a list of Circuit objects\n",
    "maxLengths = [1,2,4,8,16,32]\n",
    "exp_design = pygsti.protocols.StandardGSTDesign(target_model, prep_fiducials, meas_fiducials,\n",
    "                                                germs, maxLengths)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Pro tip:** the contents of the cell above (except the imports) could be replaced by the single line:\n",
    "\n",
    "```exp_design = smq1Q_XYI.get_gst_experiment_design(max_max_length=32)```\n",
    "\n",
    "\n",
    "## Step 2: collect data as specified by the experiment design\n",
    "Next, we just follow the instructions in the experiment design to collect data from the quantum processor (or the portion of the processor we're characterizing).  In this example, we'll generate the data using a depolarizing noise model since we don't have a real quantum processor lying around.  The call to `simulate_taking_data` should be replaced with the user filling out the empty \"template\" data set file with real data.  Note also that we set `clobber_ok=True`; this is so the tutorial can be run multiple times without having to manually remove the dataset.txt file - we recommend you leave this set to False (the default) when using it in your own scripts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def simulate_taking_data(data_template_filename):\n",
    "    \"\"\"Simulate taking 1-qubit data and filling the results into a template dataset.txt file\"\"\"\n",
    "    datagen_model = smq1Q_XYI.target_model().depolarize(op_noise=0.01, spam_noise=0.001)\n",
    "    pygsti.io.fill_in_empty_dataset_with_fake_data(datagen_model, data_template_filename, n_samples=1000, seed=1234)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pygsti.io.write_empty_protocol_data(exp_design, '../tutorial_files/test_gst_dir', clobber_ok=True)\n",
    "\n",
    "# -- fill in the dataset file in tutorial_files/test_gst_dir/data/dataset.txt --\n",
    "simulate_taking_data(\"../tutorial_files/test_gst_dir/data/dataset.txt\")  # REPLACE with actual data-taking\n",
    "\n",
    "data = pygsti.io.load_data_from_dir('../tutorial_files/test_gst_dir')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Run the GST protocol and create a report\n",
    "Now we just instantiate a `StandardGST` protocol and `.run` it on our data object.  This returns a results object that can be used to create a report."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#run the GST protocol and create a report \n",
    "gst_protocol = pygsti.protocols.StandardGST('TP,CPTP,Target')\n",
    "results = gst_protocol.run(data)\n",
    "\n",
    "report = pygsti.report.construct_standard_report(\n",
    "    results, title=\"GST Overview Tutorial Example Report\", verbosity=2)\n",
    "report.write_html(\"../tutorial_files/gettingStartedReport\", verbosity=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can now open the file [../tutorial_files/gettingStartedReport/main.html](../tutorial_files/gettingStartedReport/main.html) in your browser (Firefox works best) to view the report.  **That's it!  You've just run GST!** \n",
    "\n",
    "In the cell above, `results` is a `ModelEstimateResults` object, which is used to generate a HTML report.  For more information see the [Results object tutorial](../objects/advanced/Results.ipynb) and [report generation tutorial](../reporting/ReportGeneration.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}