<h1>How to use this report</h1>
<p>Welcome to a pyGSTi report! This HTML document provides an interactive view onto a lot of information about one or more gateset tomography (GST) experiments that were analyzed using the pyGSTi software. This <q>Help</q> tab should help you use this report&apos;s interactive features, figure out where to find things, and access the context-sensitive help features embedded throughout the report.</p>


<h2>Background</h2>
<p>PyGSTi&apos;s primary purpose is to ingest GST datasets and find a good estimate of the gateset that generated that data. But pyGSTi can also produce a lot of detailed analyses and visualizations of the estimates that it generates. That&apos;s what you&apos;ll find in this report. You can inspect the raw estimated gateset too, but if you want to do your own calculations with it &mdash; e.g., to simulate experiments or calculate interesting quantities that the pyGSTi authors haven&apos;t thought of &mdash; then the best way to do that is by using pyGSTi itself in a Jupyter or iPython notebook.</p>


<h2>This report&apos;s structure</h2>
<p>PyGSTi uses HTML for reporting because it&apos;s pretty portable and supports interactivity. Interactivity makes it possible to embed a lot of different perspectives and analyses, without overwhelming you with too much information at once or requiring you to scroll through long static (e.g. PDF) documents. In this report, actual content is displayed in the <b>main panel</b>, while navigation tools that let you decide what content to examine are collected in a <b>sidebar</b> on the left. The tables and figures in the main panel are also somewhat interactive (see "Interacting with content" below). Most of them dynamically change what they show depending on the positions of one or more <em>switches</em> - dropdown-menus, button-sets, or sliders.  Most switches are located on the sidebar, but some appear in the main panel beneath the figure or table that they control.  Note that some content is generated on the fly, so there may be a lag the very first time you view a given tab, while your browser makes plots or renders math formulas.</p>

<h2>Choosing what to see via the sidebar</h2>
<p>The sidebar provides two distinct ways to control what you see. First, the data analysis is broken up into different <b>tabs</b> that are listed on the sidebar.  Use the sidebar to hop between them. Each tab collects a particular category of analysis, presented as tables and figures. Second, if the report contains multiple analyses, the sidebar displays <em>switches</em> that allow you to pick which analysis to display in the main panel.  A report can contain: (1) multiple distinct datasets; (2) the results of different estimators (each associated with a given dataset); and (3) multiple distinct but equivalent representations (gauges) for each estimate. You can choose between these options using the drop down menus labeled <q>Dataset</q> and <q>Estimate</q>, and the <q>Gauge-Opt.</q> button group at the bottom of the sidebar.  If a switch is missing, the report doesn&apos;t contain multiple options of that type.  You can hide the sidebar (or make is sticky) by clicking the &#8859; symbol in its upper right corner.</p>

<p>Due to the large amount of data a report can contain, there are options that allow one to omit some of the (usually larger or more data-dense) figures from the report at its creation time.  This will result in the report having fewer tabs in the sidebar and/or the word <b>OMITTED</b> being displayed instead of a figure.  To see missing tabs or omitted figures, you should ask whoever generated this report to re-generate it with a lower <q>brevity</q> setting.</p>


<h2>Interacting with content</h2>
<p>Each tab presents a (hopefully manageable) amount of content arranged into objects &mdash; figures and tables &mdash; that have some interactive properties. Here are some general tips and rules.
    <ul>
        <li><b>Resizing:</b> Each object can be resized by dragging its lower right corner.</li>
        <li><b>Zooming:</b> You can zoom in on plots&apos; axes by clicking and dragging within the figure. Double-clicking, or tapping the house icon that pops up in the upper right when the pointer is over a figure, will reset the axes.</li>
        <li><b>Exporting:</b> Plots can be <b>saved in PNG</b> format by tapping the <b>camera icon</b>, which only appears when the pointer is over a plot). (<em>User beware:</em> this is a builtin feature of the Plotly library, and we find that sometimes the saved PNG does not look like the original plot, especially in aspect ratio.) Depending on what options were selected when the report was constructed, there may also be links to download plots and tables as PDF, Python <q>pickle</q> files, and/or LaTeX (tables only).  Plots will have additional download icons next to the camera icon, and tables will have <b>PDF</b>, <b>PKL</b>, and/or <b>TEX</b> links beneath them.  PKL files downloaded from plots contain a pickled dictionary of the plotted data, while those downloaded from tables contain a pickled Pandas DataFrame object.</li>
        <li><b>Full descriptive captions</b> for figures and tables can be revealed by clicking on the object&apos;s <em>Figure XX</em> or <em>Table XX</em> title.</li>
        <li><b>Hovering</b> over a colored bar or box will often reveal a tool tip showing the exact number that bar or box represents.  Hovering over table headings will bring up descriptive text.  In the plots that show per-sequence model violation, hovering over any data point will bring up fairly extensive details about the datum that generated it.</li>
        <li><b>Clickable pigs:</b> If you see the pyGSTi logo, it&apos;s a placeholder for a plot that wasn&apos;t automatically generated (usually because this might take a little while); click on the logo to generate the plot.
    </ul>
    The example table below demonstrates some of this functionality.
</p>

<figure id="example_table" class='tbl' style="float: none;">
    <figcaption><span class="captiontitle">Click this title to see my full caption.</span> <span class="captiondetail">This is an example table which demonstrates some of the functionality found in the other tables and figures of this report.  Hovering over the column headers displays descriptive tooltips, and clicking on the pyGSTi logo will cause a plot to be generated.  Hovering over the colored boxes of the plot will display the value of that box, potentially with additional information (in this case, error bars).  Math formulas like <span class="math">\sqrt{x^2 + y^2} = \frac{1}{4}</span> can be displayed in captions but not in tooltips, so sometimes the column-header tooltips simply refer to material in the captions.</span></figcaption>
    {{ example_table|render }}
</figure>


<h2>Quick guide to Datasets, Estimates, and Gauge Optimizations</h2>
<p>The single biggest change from the old PDF report format is the ability to report simultaneously on &mdash; and compare &mdash; multiple gateset estimates. This report may contain an unlimited number of distinct gatesets. Although they&apos;re often all derived from the same dataset, they may not be. For example, a single report could contain:</p>
<ol>
    <li> datasets from separate GST experiments on each qubit on a chip;</li>
    <li> datasets from two identical GST experiments done at different times;</li>
    <li> datasets from GST experiments on the same system, but with gate implementations;</li>
    <li> a 2-qubit GST dataset together with 1-qubit GST datasets extracted from it;</li>
    <li> many other possibilities.</li>
</ol>
<p>The sidebar&apos;s <q>Dataset</q> dropdown menu (if present) lets you select a dataset. Then, the <q>Estimate</q> dropdown (if present) will list all the different estimates that are available for <em>any of the datasets</em> in the report.  If you choose an estimate that was <em>not</em> generated for the current dataset (but is listed because it was generated for another dataset), unavailable plots and figures will turn into big "N/A" labels.  Different estimates are usually generated by different statistical estimators. PyGSTi usually provides maximum likelihood estimates (although others are certainly possible!), but it can do MLE with no constraints at all (<q>Full</q>), or constrained to trace-preserving maps (<q>TP</q>), or constrained to completely positive maps (<q>CPTP</q>).  Some reports include separate <q>*.robust</q> variations of those estimators in which poorly-fit data were deprecated, and some reports include the target gates themselves (<q>Target</q>) as an option.</p>

<p>Finally, in order to analyze each estimated gateset, pyGSTi has to choose a representation &mdash; a <b>gauge</b> &mdash; for it.  Since pyGSTi does this gauge-fixing internally by defining an objective function and then finding the gauge that optimizes it, the choice-of-representation is referred to as <q>Gauge Optimization</q>.  A description of the objective function used to generate this gateset appears at the bottom of the sidebar.  If the report contains multiple gauge optimizations, you can choose between them by pushing the appropriate button. Choosing a good gauge is hard, and neither pyGSTi nor its users always get it right. If something reported in the <q>Summary</q> or <q>Gauge-dependent error metrics</q> tabs looks startling or implausible, it might be due to a poorly chosen gauge. Try a different gauge-optimization choice, or cross-validate whatever you see against things from the <q>Gauge-invariant error metrics</q> tabs.</p>


<h2>What to look at first (and second)</h2>
<p>If you&apos;re new to pyGSTi reports, this is probably all a bit overwhelming. <em>Don&apos;t panic!</em> There&apos;s a lot of context-sensitive help, and the pyGSTi authors are always happy to answer questions like <q>What does this mean?</q>, or <q>Why would I care about this?</q> But since these reports do contain a lot of stuff, here&apos;s a get-started-quickly guide.</p>

<p><b>Start with the <q>Summary</q> tab</b>. It will tell you two critical things. First, in Table 3: how close do the gates seem to be to the ideal targets that were specified? Are you doing pretty well, or all messed up for some reason? If whoever did the analysis chose to produce error bars (this can take a lot of computation), they&apos;ll appear in this table. Second, the <q>model violation</q> plots will tell you whether the system seems to be stable and Markovian, or not (in which case, take the metrics in Table 3 with a grain of salt). Don&apos;t forget to flip through the available datasets, estimates, and gauge-optimization choices &mdash; or at least the ones you care about &mdash; while looking at this tab.</p>

<p><b>Next, you probably want to know one of two things</b>. Either the GST model was NOT badly violated, in which case you want to know more about the errors in the gates.. or it WAS badly violated, in which case you want to know more about what&apos;s going wrong.</p>

<p>If you want to know more about the errors, start with <q>Gauge Dependent Error Metrics: Overview</q>, then take a quick look at <q>Raw Estimates</q> to confirm that the process matrices look about right, and then spend some quality time with <q>Gate Decompositions</q> and <q>Gate Error Generators</q> if you want to really understand what GST thinks that each individual gate is doing. If at any point you see something weird that might be due to a bad choice of gauge (examples include wildly nonpositive SPAM operations, implausibly high diamond norm errors in gates that you strongly believe to be better than that, and significantly negative elements in the Pauli stochastic part of the error generators), try a different gauge optimization. Or, go to the <q>Gauge-invariant error metrics</q> tabs and try to figure out whether there&apos;s something here that confirms or denies whatever effect is bugging you (e.g., if an estimated gate has an eigenvalue bigger than 1, that will produce crazy negative probabilities, and it&apos;s not a gauge problem).</p>

<p>On the other hand, if there&apos;s a lot of model violation, then you probably want to understand why. The information on the error metrics tabs may or may not be useful &mdash; you should be much more cautious about drawing conclusions from them if there&apos;s a lot of model violation. To dig into model violation (aka "non-Markovianity"), start with the <q>Model Violation: Overview</q> tab, which will give you the numbers behind the bar chart from the Summary tab, and also show you whether longer circuits violate the GST model more. (If they do, it&apos;s probably non-Markovianity in the gates. If they don&apos;t, it&apos;s probably something nastier like bistability, slow drift in SPAM operations, or corrupted data). Next, take a deep breath and dig into the "Per-sequence detail" tab, which will show you the (quantitative) inconsistency of every individual circuit with this estimate. Interpreting these charts is a bit of an art, but clusters of red boxes usually indicate that something related to the location of the cluster was suffering drift and/or non-Markovianity.</p>
