add leakage subpackage to the API docs. Update README.md to emphasize the distinction between building notebooks and building the web docs. Change a comment in gaugeopt.py following decision to close GitHub issue #820.

Author: rileyjmurray

README.md

@@ -8,7 +8,7 @@
 
 pyGSTi
 ------
-**pyGSTi** is an open-source software for *modeling and characterizing noisy quantum information processors*
+**pyGSTi** is open-source software for *modeling and characterizing noisy quantum information processors*
 (QIPs), i.e., systems of one or more qubits.  It is licensed under the Apache License, Version 2.0.
 Copyright information can be found in ``NOTICE``, and the license itself in ``LICENSE``.
 
@@ -17,9 +17,9 @@ There are three main objects in pyGSTi:
 - `Model`: a description of a QIP's gate and SPAM operations (a noise model).
 - `DataSet`: a dictionary-like container holding experimental data.
 
-You can do various things by with these objects:
+You can do various things with these objects:
 
-- **Circuit simulation**: compute a the outcome probabilities of a `Circuit` using a `Model`.
+- **Circuit simulation**: compute the outcome probabilities of a `Circuit` using a `Model`.
 - **Data simulation**: simulate experimental data (a `DataSet`) using a `Model`.
 - **Model testing**: Test whether a given `Model` fits the data in a `DataSet`.
 - **Model estimation**: Estimate a `Model` from a `DataSet` (e.g. using GST).
@@ -32,10 +32,10 @@ In particular, there are a number of characterization protocols currently implem
  quality of a QIP in an average sense.  PyGSTi implements standard "Clifford" RB
  as well as the more scalable "Direct" RB methods.
 - **Robust Phase Estimation (RPE)** is a method designed for quickly learning
- a few noise parameters of a QIP that particularly useful for tuning up qubits.
+ a few noise parameters of a QIP that are particularly useful for tuning up qubits.
 
 PyGSTi is designed with a modular structure so as to be highly customizable
-and easily integrated to new or existing python software.  It runs using
+and easily integrated with new or existing python software.  It runs using
 python 3.10 or higher.  To facilitate integration with software for running
 cloud-QIP experiments, pyGSTi `Circuit` objects can be converted to IBM's
 **OpenQASM** and Rigetti Quantum Computing's **Quil** circuit description languages.
@@ -51,10 +51,7 @@ To install pyGSTi and only its required dependencies run:
 
 ``pip install pygsti[complete]``
 
-The disadvantage to these approaches is that the numerous tutorials
-included in the package will then be buried within your Python's
-`site_packages` directory, which you'll likely want to access later on.
-**Alternatively**, you can **locally install** pyGSTi using the following commands:
+**Alternatively**, you can install pyGSTi from source using the following commands:
 
 ~~~
 cd <install_directory>
@@ -63,17 +60,10 @@ cd pyGSTi
 pip install -e .[complete]
 ~~~
 
-As above, you can leave off the `.[complete]` if you only went the minimal
-set of dependencies installed.  You could also replace the `git clone ...`
-command with `unzip pygsti-0.9.x.zip` where the latter file is a downloaded
-pyGSTi source archive.  Any of the above installations *should* build
-the set of optional Cython extension modules if a working C/C++ compiler
-and the `Cython` package are present.  If, however, compilation fails or
-you later decided to add Cython support, you can rebuild the extension
-modules (without reinstalling) if you've followed the local installation
-approach above using the command:
+Any of the above installations *should* build the set of optional Cython extension modules if a working C/C++ compiler and the `Cython` package are present.
 
-`python setup.py build_ext --inplace`
+If you installed from source then you have the option of (re)building Cython extensions at any time.
+You can do that by running `python setup.py build_ext --inplace`.
 
 Finally, [Jupyter notebook](http://jupyter.org/) is highly recommended as
 it is generally convenient and the format of the included tutorials and
@@ -82,14 +72,14 @@ it can be installed separately.
 
 Getting Started
 ---------------
-Here's a couple of simple examples to get you started.
+Here are a couple of simple examples to get you started.
 
 #### Circuit simulation
 To compute the outcome probabilities of a circuit, you just need to create
 a `Circuit` object (describing your circuit) and a `Model` object containing
 the operations contained in your circuit.  Here we use a "stock" single-qubit `Model`
-containing *Idle*, *X(&pi;/2)*, and *Y(&pi;/2)* gates labelled `Gi`, `Gx`,
-and `Gy`, respectively:
+containing an unlabeled *Idle* gate along with *X(&pi;/2)* and *Y(&pi;/2)* gates
+labelled `Gxpi2` and `Gypi2`, respectively:
 ~~~
 import pygsti
 from pygsti.modelpacks import smq1Q_XYI
@@ -106,20 +96,20 @@ hardware designed to implement a (small) system of quantum bits (qubits).
 Here's the basic idea:
 
   1. you tell pyGSTi what gates you'd ideally like to perform
-  2. pyGSTi tells you what circuits it want's data for
+  2. pyGSTi tells you what circuits it wants data for
   3. you perform the requested experiments and place the resulting
-     data (outcome counts) into a text file that looks something like:
+     data (outcome counts) into a text file that looks something like this:
 
      ```
      ## Columns = 0 count, 1 count
      {} 0 100  # the empty sequence (just prep then measure)
-     Gx 10 90  # prep, do a X(pi/2) gate, then measure
-     GxGy 40 60  # prep, do a X(pi/2) gate followed by a Y(pi/2), then measure
+     Gx 10 90  # prep, do an X(pi/2) gate, then measure
+     GxGy 40 60  # prep, do an X(pi/2) gate followed by a Y(pi/2), then measure
      Gx^4 20 80  # etc...
      ```
 
-  4. pyGSTi takes the data file and outputs a "report" - currently a
-     HTML web page.
+  4. pyGSTi takes the data file and outputs a "report" - currently
+     an HTML web page.
 
 In code, running GST looks something like this:
 ~~~
@@ -154,35 +144,27 @@ report.write_html("myReport", auto_open=True, verbosity=1) # Can also write out
 
 Documentation
 -------------
-There are numerous tutorials (meant to be pedagogical) and examples (meant to be demonstrate
-how to do some particular thing) in the `pyGSTi/docs` directory. These are stored as MyST Markdown
+There are numerous tutorials and examples in the `pyGSTi/docs` directory. These are stored as MyST Markdown
 for version control convenience, but can be converted to Jupyter notebooks as needed using Jupytext.
 
-#### Viewing the documentation *online*
+### Viewing the documentation *online*
 The recommended way to view the documentation is on [ReadTheDocs](https://pygsti.readthedocs.io/en/latest/),
 although the raw Markdown files can also be looked at on [GitHub](https://github.com/sandialabs/pyGSTi/blob/master/docs/markdown/intro.md).
 
 The site renders the source MyST Markdown without executing notebook cells, so you won't see outputs (plots, tables) inline.
-Each rendered page offers two ways to run the notebook yourself:
+You can download the notebooks or run them on the cloud with buttons in the upper-right of the given page.
 
-- **Rocket icon → Binder or Colab:** launches a fully-provisioned notebook environment in your browser with no local install.
-- **Cloud/download icon → "Download this page" dropdown:** grab the `.ipynb` (or the `.md` source) and run it in your own Jupyter setup.
+- **Download icon → ipynb, md, or pdf.** If you just click the `.ipynb` or `.md` options then the source will open as raw text in a new tab.
+If you want to save those files you need to **right click the desired format and select `Save Link As ...`**, then enter the file name with the appropriate extension.
+Here's a screenshot of what that can look like.
 
-#### Building the documentation *locally*
-The docs are built using [Jupyter Book v1](https://jupyterbook.org). Note: v2 is a separate product (MyST Engine + Node.js)
-that doesn't support our autodoc-based API reference yet, so we pin `jupyter-book<2`.
+  <img src="docs/download-notebook-save-as.png" width="250">
 
-To install the build dependencies along with pyGSTi:
-    ``pip install -e .[docs]``
-
-then build:
-    ``jb build docs``
+- **Rocket icon → Binder or Colab:** launches a fully-provisioned notebook environment in your browser with no local install. Right now this is clunky and not recommended.
 
-Then open `docs/_build/html/index.html` in a web browser to look through the documentation.
-
-#### Running notebooks *locally*
-It can also be convenient to build and run the tutorials locally. We can do this using Jupytext
-for conversion and then start a Jupyter notebook or JupyterLab server to run the notebooks.
+### Running notebooks *locally*
+It can be convenient to just build and run the tutorials locally.
+We can do this using Jupytext for conversion and then start a Jupyter notebook or JupyterLab server to run the notebooks.
 Assuming you've followed the *local installation* directions above:
 
 * Change to the docs directory, by running:
@@ -199,7 +181,21 @@ where you can start the first `markdown/intro.ipynb` notebook.  Note that the ke
 command to execute a cell within the Jupyter notebook is ``Shift+Enter``, not
 just ``Enter``.
 
-#### Contributing notebook changes
+### Building the web documentation *locally*
+The web docs are built using [Jupyter Book v1](https://jupyterbook.org). Note: v2 is a separate product that doesn't support our autodoc-based API reference yet, so we pin `jupyter-book<2`.
+
+**WARNING.** Building the web docs takes a LONG TIME, because they include a very large **API Reference**.
+If you only want to read or work with the tutorials and examples, don't do a full build — just convert and [run the notebooks directly](#running-notebooks-locally).
+
+To install the build dependencies along with pyGSTi:
+    ``pip install -e .[docs]``
+
+then build:
+    ``jb build docs``
+
+Then open `docs/_build/html/index.html` in a web browser to look through the documentation.
+
+### Contributing notebook changes
 **Only the `docs/markdown/*.md` files are version-controlled.** The paired `.ipynb` files — generated next to
 each `.md` under `docs/markdown/` — are gitignored build artifacts. The canonical source is the `.md` file, and
 edits there "win" on the next sync. So:

docs/api.rst

@@ -208,6 +208,22 @@ Circuit/COPA layouts that organize (and distribute) the computation behind forwa
    pygsti.layouts.prefixtable
    pygsti.layouts.termlayout
 
+``pygsti.leakage``
+~~~~~~~~~~~~~~~~~~
+
+Leakage-aware modeling, gauge optimization, metrics, and reporting for QIPs with leakage levels.
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   pygsti.leakage.core
+   pygsti.leakage.gaugeopt
+   pygsti.leakage.metrics
+   pygsti.leakage.models
+   pygsti.leakage.reports
+
 ``pygsti.modelmembers``
 ~~~~~~~~~~~~~~~~~~~~~~~
 

docs/download-notebook-save-as.png

@@ -665,9 +665,9 @@ def _objective_fn(gauge_group_el, oob_check):
             return ret
 
         if "frobenius" in spam_metric:
-            # SPAM and gates can have different choices for squared vs non-squared.
-            #
-            # TODO: remove support for this codepath. It's ridiculous.
+            # Need this path in case gates DON'T use a Frobenius-based penalty.
+            # This path has a secondary use of allowing SPAM and gates to make
+            # different choices as to squared vs plain Frobenius norm.
             wts = item_weights.copy(); wts['gates'] = 0.0
             for k in wts:
                 if k in mdl_ops or k in mdl.instruments: