pygsti.report.factory

Report generation functions.

Module Contents

Functions

create_offline_zip([output_dir])	Creates a zip file containing the a directory ("offline") of files need to display "offline" reports.
create_general_report(results, filename[, title, ...])	DEPRECATED: use pygsti.report.create_standard_report(...)
create_standard_report(results, filename[, title, ...])	Create a "standard" GST report, containing details about each estimate in results individually.
create_nqnoise_report(results, filename[, title, ...])	Creates a report designed to display results containing for n-qubit noisy model estimates.
create_report_notebook(results, filename[, title, ...])	Create a "report notebook".
find_std_clifford_compilation(model[, verbosity])	Returns the standard Clifford compilation for model, if one exists. Otherwise returns None.
construct_standard_report(results[, title, ...])	Create a "standard" GST report, containing details about each estimate in results individually.
construct_nqnoise_report(results[, title, ...])	Creates a report designed to display results containing for n-qubit noisy model estimates.
create_drift_report(results[, title, ws, verbosity])	Creates a Drift report.

Attributes

ROBUST_SUFFIX_LIST
DEFAULT_NONMARK_ERRBAR_THRESHOLD

pygsti.report.factory.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']

pygsti.report.factory.DEFAULT_NONMARK_ERRBAR_THRESHOLD = 100000.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_dirstr, optional

The directory in which “offline.zip” should be place.

Returns

None

pygsti.report.factory.create_general_report(results, filename, title='auto', confidence_level=None, linlog_percentile=5, errgen_type='logGTi', nmthreshold=DEFAULT_NONMARK_ERRBAR_THRESHOLD, 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

resultsResults

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.

filenamestring, 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).

titlestring, optional

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

confidence_levelint, 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.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

wsWorkspace, 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_openbool, optional

If True, automatically open the report in a web browser after it has been generated.

link_tolist, 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).

brevityint, 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_optionsdict, 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)”.

verbosityint, 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

resultsResults

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.

filenamestring, 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).

titlestring, optional

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

confidence_levelint, 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.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

wsWorkspace, 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_openbool, optional

If True, automatically open the report in a web browser after it has been generated.

link_tolist, 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).

brevityint, 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_optionsdict, 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)”.

verbosityint, 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

resultsResults

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.

filenamestring, optional

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

titlestring, optional

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

confidence_levelint, 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_openbool, optional

If True, automatically open the report in a web browser after it has been generated.

connectedbool, 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.

verbosityint, 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

modelModel

The ideal (target) model of primitive gates.

verbosityint, 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

resultsResults

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.

titlestring, optional

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

confidence_levelint, 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.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

wsWorkspace, 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_optionsdict, 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).

verbosityint, 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

resultsResults

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.

titlestring, optional

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

confidence_levelint, 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.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator for distributing the computation across multiple processors.

wsWorkspace, 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_optionsdict, 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.

verbosityint, 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

resultsStabilityAnalysisResults

The drift-analysis results to create the report from.

titlestring, optional

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

wsWorkspace, 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.

verbosityint, optional

How much detail to send to stdout.

Returns

Report : A constructed report object