pygsti.report.factory

Report generation functions.

Module Contents

Functions

_add_new_labels(running_lbls, current_lbls)

Simple routine to add current-labels to a list of

_add_new_estimate_labels(running_lbls, estimates, combine_robust)

Like _add_new_labels but perform robust-suffix processing.

_get_viewable_crf(est, est_lbl, mdl_lbl, verbosity=0)

create_offline_zip(output_dir='.')

Creates a zip file containing the a directory ("offline") of files need to display "offline" reports.

_set_toggles(results_dict, brevity, combine_robust)

_create_master_switchboard(ws, results_dict, confidence_level, nmthreshold, printer, fmt, combine_robust, idt_results_dict=None, embed_figures=True)

Creates the "master switchboard" used by several of the reports

_construct_idtresults(idt_idle_op, idt_pauli_dicts, gst_results_dict, printer)

Constructs a dictionary of idle tomography results, parallel

_create_single_metric_switchboard(ws, results_dict, b_gauge_inv, dataset_labels, est_labels=None, embed_figures=True)

create_general_report(results, filename, title='auto', confidence_level=None, linlog_percentile=5, errgen_type='logGTi', nmthreshold=50, precision=None, comm=None, ws=None, auto_open=False, cachefile=None, brief=False, connected=False, link_to=None, resizable=True, autosize='initial', verbosity=1)

DEPRECATED: use pygsti.report.create_standard_report(...)

create_standard_report(results, filename, title='auto', confidence_level=None, comm=None, ws=None, auto_open=False, link_to=None, brevity=0, advanced_options=None, verbosity=1)

Create a "standard" GST report, containing details about each estimate in results individually.

create_nqnoise_report(results, filename, title='auto', confidence_level=None, comm=None, ws=None, auto_open=False, link_to=None, brevity=0, advanced_options=None, verbosity=1)

Creates a report designed to display results containing for n-qubit noisy model estimates.

create_report_notebook(results, filename, title='auto', confidence_level=None, auto_open=False, connected=False, verbosity=0)

Create a "report notebook".

find_std_clifford_compilation(model, verbosity=0)

Returns the standard Clifford compilation for model, if one exists. Otherwise returns None.

construct_standard_report(results, title='auto', confidence_level=None, comm=None, ws=None, advanced_options=None, verbosity=1)

Create a "standard" GST report, containing details about each estimate in results individually.

construct_nqnoise_report(results, title='auto', confidence_level=None, comm=None, ws=None, advanced_options=None, verbosity=1)

Creates a report designed to display results containing for n-qubit noisy model estimates.

create_drift_report(results, title='auto', ws=None, verbosity=1)

Creates a Drift report.

Attributes

ROBUST_SUFFIX_LIST

DEFAULT_BAD_FIT_THRESHOLD

pygsti.report.factory.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']
pygsti.report.factory.DEFAULT_BAD_FIT_THRESHOLD = 2.0
pygsti.report.factory._add_new_labels(running_lbls, current_lbls)

Simple routine to add current-labels to a list of running-labels without introducing duplicates and preserving order as best we can.

pygsti.report.factory._add_new_estimate_labels(running_lbls, estimates, combine_robust)

Like _add_new_labels but perform robust-suffix processing.

In particular, if combine_robust == True then do not add labels which have a “.robust” counterpart.

pygsti.report.factory._get_viewable_crf(est, est_lbl, mdl_lbl, verbosity=0)
pygsti.report.factory.create_offline_zip(output_dir='.')

Creates a zip file containing the a directory (“offline”) of files need to display “offline” reports.

This offline directory is often generated by reports when connected=False is specified..

For offline reports to display, the “offline” folder must be placed in the same directory as the report’s HTML file. This function can be used to easily obtain a copy of the offline folder for the purpose of sharing offline reports with other people. If you’re just creating your own offline reports using pyGSTi, the offline folder is automatically copied into it’s proper position - so you don’t need to call this function.

Parameters

output_dir (str, optional) – The directory in which “offline.zip” should be place.

Returns

None

pygsti.report.factory._set_toggles(results_dict, brevity, combine_robust)
pygsti.report.factory._create_master_switchboard(ws, results_dict, confidence_level, nmthreshold, printer, fmt, combine_robust, idt_results_dict=None, embed_figures=True)

Creates the “master switchboard” used by several of the reports

pygsti.report.factory._construct_idtresults(idt_idle_op, idt_pauli_dicts, gst_results_dict, printer)

Constructs a dictionary of idle tomography results, parallel to the GST results in gst_results_dict, where possible.

pygsti.report.factory._create_single_metric_switchboard(ws, results_dict, b_gauge_inv, dataset_labels, est_labels=None, embed_figures=True)
pygsti.report.factory.create_general_report(results, filename, title='auto', confidence_level=None, linlog_percentile=5, errgen_type='logGTi', nmthreshold=50, precision=None, comm=None, ws=None, auto_open=False, cachefile=None, brief=False, connected=False, link_to=None, resizable=True, autosize='initial', verbosity=1)

DEPRECATED: use pygsti.report.create_standard_report(…)

Deprecated since version v0.9.9: create_general_report will be removed in the next major release of pyGSTi. It is replaced by construct_standard_report, which returns a Report object.

pygsti.report.factory.create_standard_report(results, filename, title='auto', confidence_level=None, comm=None, ws=None, auto_open=False, link_to=None, brevity=0, advanced_options=None, verbosity=1)

Create a “standard” GST report, containing details about each estimate in results individually.

Either a PDF or HTML report is generated, based on whether filename ends in “.pdf” or not. In the richer HTML-mode, switches (drop-down boxes, buttons, etc.) allow the viewer to choose which estimate is displayed. The estimates in multiple Results objects can be viewed by providing a dictionary of Results objects as the results argument. Note that when comparing many estimates it is often more convenient to view the report generated by create_comparison_report(), which is organized for this purpose.

In PDF-mode this interactivity is not possible and so results may contain just a single estimate. The chief advantage of this more limited mode is that is produces a highly-portable and self-contained PDF file.

Deprecated since version v0.9.9: create_standard_report will be removed in the next major release of pyGSTi. It is replaced by construct_standard_report, which returns a Report object.

Parameters
  • results (Results) – An object which represents the set of results from one or more GST estimation runs, typically obtained from running run_long_sequence_gst() or run_stdpractice_gst(), OR a dictionary of such objects, representing multiple GST runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable in the report.

  • filename (string, optional) – The output filename where the report file(s) will be saved. If None, then no output file is produced (but returned Workspace still caches all intermediate results).

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • confidence_level (int, optional) – If not None, then the confidence level (between 0 and 100) used in the computation of confidence regions/intervals. If None, no confidence regions or intervals are computed.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.

  • auto_open (bool, optional) – If True, automatically open the report in a web browser after it has been generated.

  • link_to (list, optional) – If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively. “tex” creates latex source files for tables; “pdf” renders PDFs of tables and plots ; “pkl” creates Python versions of plots (pickled python data) and tables (pickled pandas DataFrams).

  • brevity (int, optional) –

    Amount of detail to include in the report. Larger values mean smaller “more briefr” reports, which reduce generation time, load time, and disk space consumption. In particular:

    • 1: Plots showing per-sequences quantities disappear at brevity=1

    • 2: Reference sections disappear at brevity=2

    • 3: Germ-level estimate tables disappear at brevity=3

    • 4: Everything but summary figures disappears at brevity=4

  • advanced_options (dict, optional) –

    A dictionary of advanced options for which the default values are usually are fine. Here are the possible keys of advanced_options:

    • connectedbool, optional

      Whether output HTML should assume an active internet connection. If True, then the resulting HTML file size will be reduced because it will link to web resources (e.g. CDN libraries) instead of embedding them.

    • cachefilestr, optional

      filename with cached workspace results

    • linlogPercentilefloat, optional

      Specifies the colorscale transition point for any logL or chi2 color box plots. The lower (100 - linlogPercentile) percentile of the expected chi2 distribution is shown in a linear grayscale, and the top linlogPercentile is shown on a logarithmic colored scale.

    • errgen_type: {“logG-logT”, “logTiG”, “logGTi”}

      The type of error generator to compute. Allowed values are:

      • ”logG-logT” : errgen = log(gate) - log(target_op)

      • ”logTiG” : errgen = log( dot(inv(target_op), gate) )

      • ”logGTi” : errgen = log( dot(gate, inv(target_op)) )

    • nmthresholdfloat, optional

      The threshold, in units of standard deviations, that triggers the usage of non-Markovian error bars. If None, then non-Markovian error bars are never computed.

    • precisionint or dict, optional

      The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then {‘normal’: 6, ‘polar’: 3, ‘sci’: 0} is used.

    • resizablebool, optional

      Whether plots and tables are made with resize handles and can be resized within the report.

    • autosize{‘none’, ‘initial’, ‘continual’}

      Whether tables and plots should be resized, either initially – i.e. just upon first rendering (“initial”) – or whenever the browser window is resized (“continual”).

    • embed_figures: bool, optional

      Whether figures should be embedded in the generated report.

    • combine_robustbool, optional

      Whether robust estimates should automatically be combined with their non-robust counterpart when displayed in reports. (default is True).

    • confidence_interval_brevityint, optional

      Roughly specifies how many figures will have confidence intervals (when applicable). Defaults to ‘1’. Smaller values mean more tables will get confidence intervals (and reports will take longer to generate).

    • idt_basis_dictstuple, optional

      Tuple of (prepDict,measDict) pauli-basis dictionaries, which map between 1-qubit Pauli basis strings (e.g. ‘-X’ or ‘Y’) and tuples of gate names (e.g. (‘Gx’,’Gx’)). If given, idle tomography will be performed on the ‘Gi’ gate and included in the report.

    • idt_idle_oplabelLabel, optional

      The label identifying the idle gate (for use with idle tomography).

    • colorboxplot_bgcolorstr, optional

      Background color for the color box plots in this report. Can be common color names, e.g. “black”, or string RGB values, e.g. “rgb(255,128,0)”.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

Workspace – The workspace object used to create the report

pygsti.report.factory.create_nqnoise_report(results, filename, title='auto', confidence_level=None, comm=None, ws=None, auto_open=False, link_to=None, brevity=0, advanced_options=None, verbosity=1)

Creates a report designed to display results containing for n-qubit noisy model estimates.

Such models are characterized by the fact that gates and SPAM objects may not have dense representations (or it may be very expensive to compute them) , and that these models are likely CloudNoiseModel objects or have similar structure.

Deprecated since version v0.9.9: create_nqnoise_report will be removed in the next major release of pyGSTi. It is replaced by construct_standard_report, which returns a Report object.

Parameters
  • results (Results) – An object which represents the set of results from one or more GST estimation runs, typically obtained from running run_long_sequence_gst() or run_stdpractice_gst(), OR a dictionary of such objects, representing multiple GST runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable in the report.

  • filename (string, optional) – The output filename where the report file(s) will be saved. If None, then no output file is produced (but returned Workspace still caches all intermediate results).

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • confidence_level (int, optional) – If not None, then the confidence level (between 0 and 100) used in the computation of confidence regions/intervals. If None, no confidence regions or intervals are computed.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.

  • auto_open (bool, optional) – If True, automatically open the report in a web browser after it has been generated.

  • link_to (list, optional) – If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively. “tex” creates latex source files for tables; “pdf” renders PDFs of tables and plots ; “pkl” creates Python versions of plots (pickled python data) and tables (pickled pandas DataFrams).

  • brevity (int, optional) –

    Amount of detail to include in the report. Larger values mean smaller “more briefr” reports, which reduce generation time, load time, and disk space consumption. In particular:

    • 1: Plots showing per-sequences quantities disappear at brevity=1

    • 2: Reference sections disappear at brevity=2

    • 3: Germ-level estimate tables disappear at brevity=3

    • 4: Everything but summary figures disappears at brevity=4

  • advanced_options (dict, optional) –

    A dictionary of advanced options for which the default values are usually are fine. Here are the possible keys of advanced_options:

    • connectedbool, optional

      Whether output HTML should assume an active internet connection. If True, then the resulting HTML file size will be reduced because it will link to web resources (e.g. CDN libraries) instead of embedding them.

    • cachefilestr, optional

      filename with cached workspace results

    • linlogPercentilefloat, optional

      Specifies the colorscale transition point for any logL or chi2 color box plots. The lower (100 - linlogPercentile) percentile of the expected chi2 distribution is shown in a linear grayscale, and the top linlogPercentile is shown on a logarithmic colored scale.

    • nmthresholdfloat, optional

      The threshold, in units of standard deviations, that triggers the usage of non-Markovian error bars. If None, then non-Markovian error bars are never computed.

    • precisionint or dict, optional

      The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then {‘normal’: 6, ‘polar’: 3, ‘sci’: 0} is used.

    • resizablebool, optional

      Whether plots and tables are made with resize handles and can be resized within the report.

    • autosize{‘none’, ‘initial’, ‘continual’}

      Whether tables and plots should be resized, either initially – i.e. just upon first rendering (“initial”) – or whenever the browser window is resized (“continual”).

    • combine_robustbool, optional

      Whether robust estimates should automatically be combined with their non-robust counterpart when displayed in reports. (default is True).

    • confidence_interval_brevityint, optional

      Roughly specifies how many figures will have confidence intervals (when applicable). Defaults to ‘1’. Smaller values mean more tables will get confidence intervals (and reports will take longer to generate).

    • colorboxplot_bgcolorstr, optional

      Background color for the color box plots in this report. Can be common color names, e.g. “black”, or string RGB values, e.g. “rgb(255,128,0)”.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

Workspace – The workspace object used to create the report

pygsti.report.factory.create_report_notebook(results, filename, title='auto', confidence_level=None, auto_open=False, connected=False, verbosity=0)

Create a “report notebook”.

A Jupyter ipython notebook file which, when its cells are executed, will generate similar figures to those contained in an html report (via create_standard_report()).

A notebook report allows the user to interact more flexibly with the data underlying the figures, and to easily generate customized variants on the figures. As such, this type of report will be most useful for experts who want to tinker with the standard analysis presented in the static HTML or LaTeX format reports.

Deprecated since version v0.9.9: create_report_notebook will be removed in the next major release of pyGSTi. It is replaced by the Report.write_notebook

Parameters
  • results (Results) – An object which represents the set of results from one or more GST estimation runs, typically obtained from running run_long_sequence_gst() or run_stdpractice_gst(), OR a dictionary of such objects, representing multiple GST runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable (via setting Python variables) in the report.

  • filename (string, optional) – The output filename where the report file(s) will be saved. Must end in “.ipynb”.

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • confidence_level (int, optional) – If not None, then the confidence level (between 0 and 100) used in the computation of confidence regions/intervals. If None, no confidence regions or intervals are computed.

  • auto_open (bool, optional) – If True, automatically open the report in a web browser after it has been generated.

  • connected (bool, optional) – Whether output notebook should assume an active internet connection. If True, then the resulting file size will be reduced because it will link to web resources (e.g. CDN libraries) instead of embedding them.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

None

pygsti.report.factory.find_std_clifford_compilation(model, verbosity=0)

Returns the standard Clifford compilation for model, if one exists. Otherwise returns None.

Parameters
  • model (Model) – The ideal (target) model of primitive gates.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

dict or None – The Clifford compilation dictionary (if one can be found).

pygsti.report.factory.construct_standard_report(results, title='auto', confidence_level=None, comm=None, ws=None, advanced_options=None, verbosity=1)

Create a “standard” GST report, containing details about each estimate in results individually.

Parameters
  • results (Results) – An object which represents the set of results from one or more GST estimation runs, typically obtained from running run_long_sequence_gst() or run_stdpractice_gst(), OR a dictionary of such objects, representing multiple GST runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable in the report.

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • confidence_level (int, optional) – If not None, then the confidence level (between 0 and 100) used in the computation of confidence regions/intervals. If None, no confidence regions or intervals are computed.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.

  • advanced_options (dict, optional) –

    A dictionary of advanced options for which the default values are usually are fine. Here are the possible keys of advanced_options:

    • linlogPercentilefloat, optional

      Specifies the colorscale transition point for any logL or chi2 color box plots. The lower (100 - linlogPercentile) percentile of the expected chi2 distribution is shown in a linear grayscale, and the top linlogPercentile is shown on a logarithmic colored scale.

    • nmthresholdfloat, optional

      The threshold, in units of standard deviations, that triggers the usage of non-Markovian error bars. If None, then non-Markovian error bars are never computed.

    • embed_figures: bool, optional

      Whether figures should be embedded in the generated report.

    • combine_robustbool, optional

      Whether robust estimates should automatically be combined with their non-robust counterpart when displayed in reports. (default is True).

    • idt_basis_dictstuple, optional

      Tuple of (prepDict,measDict) pauli-basis dictionaries, which map between 1-qubit Pauli basis strings (e.g. ‘-X’ or ‘Y’) and tuples of gate names (e.g. (‘Gx’,’Gx’)). If given, idle tomography will be performed on the ‘Gi’ gate and included in the report.

    • idt_idle_oplabelLabel, optional

      The label identifying the idle gate (for use with idle tomography).

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

Workspace – The workspace object used to create the report

pygsti.report.factory.construct_nqnoise_report(results, title='auto', confidence_level=None, comm=None, ws=None, advanced_options=None, verbosity=1)

Creates a report designed to display results containing for n-qubit noisy model estimates.

Such models are characterized by the fact that gates and SPAM objects may not have dense representations (or it may be very expensive to compute them) , and that these models are likely CloudNoiseModel objects or have similar structure.

Parameters
  • results (Results) – An object which represents the set of results from one or more GST estimation runs, typically obtained from running run_long_sequence_gst() or run_stdpractice_gst(), OR a dictionary of such objects, representing multiple GST runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable in the report.

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • confidence_level (int, optional) – If not None, then the confidence level (between 0 and 100) used in the computation of confidence regions/intervals. If None, no confidence regions or intervals are computed.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.

  • ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.

  • advanced_options (dict, optional) –

    A dictionary of advanced options for which the default values are usually are fine. Here are the possible keys of advanced_options:

    • linlogPercentilefloat, optional

      Specifies the colorscale transition point for any logL or chi2 color box plots. The lower (100 - linlogPercentile) percentile of the expected chi2 distribution is shown in a linear grayscale, and the top linlogPercentile is shown on a logarithmic colored scale.

    • nmthresholdfloat, optional

      The threshold, in units of standard deviations, that triggers the usage of non-Markovian error bars. If None, then non-Markovian error bars are never computed.

    • combine_robustbool, optional

      Whether robust estimates should automatically be combined with their non-robust counterpart when displayed in reports. (default is True).

    • confidence_interval_brevityint, optional

      Roughly specifies how many figures will have confidence intervals (when applicable). Defaults to ‘1’. Smaller values mean more tables will get confidence intervals (and reports will take longer to generate).

    • embed_figures: bool, optional

      Whether figures should be embedded in the generated report.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

class:Report : A constructed report object

pygsti.report.factory.create_drift_report(results, title='auto', ws=None, verbosity=1)

Creates a Drift report.

Parameters
  • results (StabilityAnalysisResults) – The drift-analysis results to create the report from.

  • title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).

  • ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.

  • verbosity (int, optional) – How much detail to send to stdout.

Returns

Report (A constructed report object)