pygsti.report.merge_helpers

Helper functions for creating HTML documents by “merging” with a template

Module Contents

Functions

_read_contents(filename)

Read the contents from filename as a string.

insert_resource(connected, online_url, offline_filename, integrity=None, crossorigin=None)

Return the HTML used to insert a resource into a larger HTML file.

rsync_offline_dir(output_dir)

Copy the pyGSTi 'offline' directory into output_dir.

load_and_preprocess_template(template_filename, toggles)

Load a HTML template from a file and perform an preprocessing.

clear_dir(path)

If path is a directory, remove all the files within it

create_empty_dir(dirname)

Ensure that dirname names an empty directory

_render_as_html(value, render_options, link_to)

Render an object as HTML.

render_as_html(qtys, render_options, link_to, verbosity)

Render the workspace quantities (outputs and switchboards) in the qtys dictionary as HTML.

render_as_latex(qtys, render_options, verbosity)

Render the workspace quantities (outputs; not switchboards) in the qtys dictionary as LaTeX.

_make_jinja_env(static_path, template_dir=None, render_options=None, link_to=None)

Build a jinja2 environment for generating pyGSTi reports

merge_jinja_template(qtys, output_filename, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', verbosity=0)

Renders qtys and merges them into a single HTML file output_filename.

merge_jinja_template_dir(qtys, output_dir, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', embed_figures=True, verbosity=0)

Renders qtys and merges them into the HTML files under template_dir, saving the output under output_dir.

process_call(call)

Use subprocess to run call.

evaluate_call(call, stdout, stderr, returncode, printer)

Run call and raise CalledProcessError if exit code > 0

merge_latex_template(qtys, template_filename, output_filename, toggles=None, precision=None, verbosity=0)

Renders qtys and merges them into the LaTeX file template_filename, saving the output under output_filename.

compile_latex_report(report_filename, latex_call, printer, auto_open)

Compile a PDF report from a TeX file. Will compile twice automatically.

to_pdfinfo(list_of_keyval_tuples)

Convert a list of (key,value) pairs to a "pdfinfo" string.

Attributes

_Undefined

pygsti.report.merge_helpers._Undefined = []
pygsti.report.merge_helpers._read_contents(filename)

Read the contents from filename as a string.

Parameters

filename (str) – File to read.

Returns

str

pygsti.report.merge_helpers.insert_resource(connected, online_url, offline_filename, integrity=None, crossorigin=None)

Return the HTML used to insert a resource into a larger HTML file.

When connected==True, an internet connection is assumed and online_url is used if it’s non-None; otherwise offline_filename (assumed to be relative to the “templates/offline” folder within pyGSTi) is inserted inline. When connected==False an offline folder is assumed to be present in the same directory as the larger HTML file, and a reference to offline_filename is inserted.

Parameters
  • connected (bool) – Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.

  • online_url (str) – The url of the inserted resource as available from the internet. None if there is no such availability.

  • offline_filename (str) – The filename of the resource relative to the templates/offline pyGSTi folder.

  • integrity (str, optional) – The “integrity” attribute string of the <script> tag used to reference a *.js (javascript) file on the internet.

  • crossorigin (str, optional) – The “crossorigin” attribute string of the <script> tag used to reference a *.js (javascript) file on the internet.

Returns

str

pygsti.report.merge_helpers.rsync_offline_dir(output_dir)

Copy the pyGSTi ‘offline’ directory into output_dir.

This creates or updates any non-existent or outdated files as needed.

Parameters

output_dir (str) – The output directory

Returns

None

pygsti.report.merge_helpers.load_and_preprocess_template(template_filename, toggles)

Load a HTML template from a file and perform an preprocessing.

Preprocessing directives are “#iftoggle(name)”, “#elsetoggle”, and “#endtoggle”.

Parameters
  • template_filename (str) – filename (no relative directory assumed).

  • toggles (dict) – A dictionary of toggle_name:bool pairs specifying how to preprocess the template.

Returns

str

pygsti.report.merge_helpers.clear_dir(path)

If path is a directory, remove all the files within it

Parameters

path (str) – The path to clear.

Returns

None

pygsti.report.merge_helpers.create_empty_dir(dirname)

Ensure that dirname names an empty directory

Parameters

dirname (str) – The directory path.

Returns

str – The directory name.

pygsti.report.merge_helpers._render_as_html(value, render_options, link_to)

Render an object as HTML.

pygsti.report.merge_helpers.render_as_html(qtys, render_options, link_to, verbosity)

Render the workspace quantities (outputs and switchboards) in the qtys dictionary as HTML.

Parameters
  • qtys (dict) – A dictionary of workspace quantities to render.

  • render_options (dict) – a dictionary of render options to set via the WorkspaceOutput.set_render_options method of workspace output objects.

  • link_to (tuple) – 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.

  • verbosity (int) – How much detail to print to stdout.

Returns

dict – With the same keys as qtys and values which contain the objects rendered as strings.

pygsti.report.merge_helpers.render_as_latex(qtys, render_options, verbosity)

Render the workspace quantities (outputs; not switchboards) in the qtys dictionary as LaTeX.

Parameters
  • qtys (dict) – A dictionary of workspace quantities to render.

  • render_options (dict) – a dictionary of render options to set via the WorkspaceOutput.set_render_options method of workspace output objects.

  • verbosity (int) – How much detail to print to stdout.

Returns

dict – With the same keys as qtys and values which contain the objects rendered as strings.

pygsti.report.merge_helpers._make_jinja_env(static_path, template_dir=None, render_options=None, link_to=None)

Build a jinja2 environment for generating pyGSTi reports

pygsti.report.merge_helpers.merge_jinja_template(qtys, output_filename, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', verbosity=0)

Renders qtys and merges them into a single HTML file output_filename.

This functions parameters are the same as those of merge_jinja_template_dir().

Parameters
  • qtys (dict) – A dictionary of workspace quantities (switchboards and outputs).

  • output_filename (str) – The output filename.

  • template_dir (str, optional) – The template filename, relative to pyGSTi’s templates directory.

  • template_name (str, optional) – The name of the template file within template_dir.

  • auto_open (bool, optional) – Whether the output file should be automatically opened in a web browser.

  • precision (int 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 a default is used.

  • 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.

  • connected (bool, optional) – Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.

  • toggles (dict, optional) – A dictionary of toggle_name:bool pairs specifying how to preprocess the template.

  • render_math (bool, optional) – Whether math should be rendered.

  • resizable (bool, optional) – Whether figures should be resizable.

  • 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”).

  • verbosity (int, optional) – Amount of detail to print to stdout.

Returns

None

pygsti.report.merge_helpers.merge_jinja_template_dir(qtys, output_dir, template_dir=None, template_name='main.html', auto_open=False, precision=None, link_to=None, connected=False, toggles=None, render_math=True, resizable=True, autosize='none', embed_figures=True, verbosity=0)

Renders qtys and merges them into the HTML files under template_dir, saving the output under output_dir.

Parameters
  • qtys (dict) – A dictionary of workspace quantities (switchboards and outputs).

  • output_dir (str) – The merged-output directory..

  • template_dir (str, optional) – The template filename, relative to pyGSTi’s templates directory.

  • template_name (str, optional) – The name of the template file within template_dir.

  • auto_open (bool, optional) – Whether the output file should be automatically opened in a web browser.

  • precision (int 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 a default is used.

  • 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.

  • connected (bool, optional) – Whether an internet connection should be assumed. If False, then an ‘offline’ folder is assumed to be present in the output HTML’s folder.

  • toggles (dict, optional) – A dictionary of toggle_name:bool pairs specifying how to preprocess the template.

  • render_math (bool, optional) – Whether math should be rendered.

  • resizable (bool, optional) – Whether figures should be resizable.

  • 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. If False, figures will be written to a ‘figures’ directory in the output directory, and will be loaded dynamically via AJAX. This may be useful for reducing the size of the generated report if the report includes relatively many figures. Note that all major web browsers will block AJAX requests from an HTML document loaded from the filesystem. If this option is set to False, the generated report will fail to load from the filesystem, and must be served up by a webserver. Python’s http.server module works fine.

  • verbosity (int, optional) – Amount of detail to print to stdout.

Returns

None

pygsti.report.merge_helpers.process_call(call)

Use subprocess to run call.

Parameters

call (list) – A list of exec name and args, e.g. [‘ls’,’-l’,’myDir’]

Returns

  • stdout (str)

  • stderr (str)

  • return_code (int)

pygsti.report.merge_helpers.evaluate_call(call, stdout, stderr, returncode, printer)

Run call and raise CalledProcessError if exit code > 0

Parameters
Returns

None

pygsti.report.merge_helpers.merge_latex_template(qtys, template_filename, output_filename, toggles=None, precision=None, verbosity=0)

Renders qtys and merges them into the LaTeX file template_filename, saving the output under output_filename.

Parameters
  • qtys (dict) – A dictionary of workspace quantities (outputs).

  • template_filename (str) – The template filename, relative to pyGSTi’s templates directory.

  • output_filename (str) – The merged-output filename.

  • toggles (dict, optional) – A dictionary of toggle_name:bool pairs specifying how to preprocess the template.

  • precision (int 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 a default is used.

  • verbosity (int, optional) – Amount of detail to print to stdout.

Returns

None

pygsti.report.merge_helpers.compile_latex_report(report_filename, latex_call, printer, auto_open)

Compile a PDF report from a TeX file. Will compile twice automatically.

Parameters
  • report_filename (string) – The full file name, which may (but need not) include a “.tex” or “.pdf” extension, of the report input tex and output pdf files.

  • latex_call (list of string) – List containing the command and flags in the form that :function:`subprocess.check_call` uses.

  • printer (VerbosityPrinter) – Printer to handle logging.

  • auto_open (bool, optional) – Whether the generated report file should be opened by the OS right before this function exists.

Returns

None

Raises

subprocess.CalledProcessException – If the call to the process comiling the PDF returns non-zero exit status.

pygsti.report.merge_helpers.to_pdfinfo(list_of_keyval_tuples)

Convert a list of (key,value) pairs to a “pdfinfo” string.

The returned string is in the format expected for a latex document’s “pdfinfo” directive (for setting PDF file meta information).

Parameters

list_of_keyval_tuples (list) – A list of (key,value) tuples.

Returns

str