WIP: Sphinx build of full documentation (not just API references) (#31)

* Fix cutting notebooks to work locally so they can be added to CI and tutorials * Enable nbsphinx * Initial successful documentation build * Add sphinx-copybutton * Git rid of LaTeX in notebook titles as Sphinx doesn't use Mathjax on the TOC pages * Add blurb to front page of Sphinx site * Fix docstring typo * Capitalize Schmidt everywhere in docstrings * Flip the doc structure so the top-level is the four Diataxis modes * Add placeholders for how-tos, explanation, and install instructions * Number the circuit cutting tutorials * Add cutting API reference docs * Float as a python type should be lowercase * Add utility functions * Improve sphinx output of WireCutter description * Fint lint * Remove private attributes from knitter docstring * Add INSTALL.rst placeholder * Move installation instructions to INSTALL.rst * Update links from install doc to source files * Link directly to full version of cplex optimization studio * Remove shell prompt This will work better with sphinx-copybutton * Tweaks to INSTALL.rst * Migrate the explanatory material from prototype-entanglement-forging There are still a few outdated references, such as to `EntanglementForgedConfig`. Co-authored-by: Aggie Branczyk <[email protected]> * Tweak the install page * Fix display of notebook galleries gallery.css is taken from qiskit-optimization, and has an additional line added at the top * Flesh out the first entanglement forging tutorial * Update copyright information in each EF tutorial notebook * Fix a typo * Flesh out EF tutorial #3 * New location for `reduce_bitstrings` * Internal links now use RST syntax * Add a newline so Sphinx displays the tutorial correctly * Make the circuit cutting notebooks look correct when rendered by Sphinx * Make the intro a bit more brief; mention Quantum Serverless sooner * Remove the EF w/ quantum serverless tutorial ... which did not actually use quantum serverless * Adjust EF tutorials to use the Qiskit Runtime Primitives * Add EF images Co-authored-by: Aggie Branczyk <[email protected]>
Qiskit · Oct 27, 2022 · 6782153 · 6782153
1 parent e4df4cc
commit 6782153
Show file tree

Hide file tree

Showing 34 changed files with 990 additions and 563 deletions.
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -0,0 +1,76 @@
+#########################
+Installation Instructions
+#########################
+
+There are two options: installing locally or using within a Docker
+container.
+
+- If you are using Linux or macOS with an Intel chip (i.e., not the
+  new M1 or M2 chips), everything should work natively, so we
+  recommend the first option.
+- All users on ARM chips, as well as all Windows users, will have to
+  use the toolbox within Docker (the second option) for everything to
+  work as designed.
+
+Option 1: Local installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-  **OPTIONAL** If a user wishes to use the circuit cutting tool to
+   automatically find optimized wire cuts for a circuit too large for
+   the free version of CPLEX, they should acquire a license and install
+   the `full
+   version <https://www.ibm.com/products/ilog-cplex-optimization-studio>`__.
+
+-  Enter a Python environment and install the software
+
+.. code:: sh
+
+    git clone [email protected]:Qiskit-Extensions/circuit-knitting-toolbox.git
+    cd circuit-knitting-toolbox
+    python3 -m venv venv
+    source venv/bin/activate
+    pip install --upgrade pip
+    pip install tox notebook -e '.[notebook-dependencies]'
+    jupyter notebook
+
+-  Navigate to the notebooks in the ``docs/tutorials/`` directory to run the
+   tutorials.
+
+Option 2: Use within Docker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We have provided a `Dockerfile <https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/blob/main/Dockerfile>`__, which can be used to
+build a Docker image, as well as a
+`docker-compose.yml <https://github.com/Qiskit-Extensions/circuit-knitting-toolbox/blob/main/docker-compose.yml>`__ file, which allows one
+to use the Docker image with just a few simple commands. If you have
+Docker installed but not `Docker
+Compose <https://pypi.org/project/docker-compose/>`__, the latter can be
+installed by first running ``pip install docker-compose``.
+
+.. code:: sh
+
+    git clone [email protected]:Qiskit-Extensions/circuit-knitting-toolbox.git
+    cd circuit-knitting-toolbox
+    docker-compose build
+    docker-compose up
+
+Depending on your system configuration, you may need to type ``sudo``
+before each ``docker-compose`` command.
+
+Once the container is running, you should see a message like this:
+
+::
+
+    notebook_1  |     To access the server, open this file in a browser:
+    notebook_1  |         file:///home/jovyan/.local/share/jupyter/runtime/jpserver-7-open.html
+    notebook_1  |     Or copy and paste one of these URLs:
+    notebook_1  |         http://e4a04564eb39:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
+    notebook_1  |      or http://127.0.0.1:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
+
+Locate the *last* URL in your terminal (the one that includes
+``127.0.0.1``), and navigate to that URL in a web browser to access the
+Jupyter notebook interface.
+
+The home directory includes a subdirectory named ``persistent-volume``.
+All work you’d like to save should be placed in this directory, as it is
+the only one that will be saved across different container runs.
diff --git a/README.md b/README.md
@@ -40,52 +40,7 @@ The toolbox currently contains the following tools:
 
 ### Installation
 
-There are two options: installing locally or using within a Docker container.  If you are using macOS or Linux with an Intel chip (i.e., not the new M1 or M2 chips), everything should work natively, so we recommend the first option.  All users on ARM chips, as well as all Windows users, will have to use the toolbox within Docker (the second option) for everything to work as designed.
-
-#### Option 1: Local installation
-
-* **OPTIONAL** If a user wishes to use the circuit cutting tool to automatically find optimized wire cuts for a circuit too large for the free version of CPLEX, they should acquire a license and install the [full version](https://www.googleadservices.com/pagead/aclk?sa=L&ai=DChcSEwjuq9OM1M75AhVoFNQBHWqGBW4YABAAGgJvYQ&ohost=www.google.com&cid=CAESauD2CglQCoRYTsgQCH50ip7Y_PCiHfnYyojivn_Od4YBaoXY74TyZYrKZNZuL0H9je0pzRNWut7uutUNmRc2x-P0nuTbQLAaC2p2fI3PTD87BbRBI07uzMo0ZTSmkyWQiGb9C3Hkv1bbawk&sig=AOD64_0oLk3SUhEbH-EQ35AWeP5_94a45A&q&adurl&ved=2ahUKEwiA1MmM1M75AhXXrmoFHdAcCVQQ0Qx6BAgEEAE&nis=2).
-
-* Enter a Python environment and install the software
-
-```sh
-$ git clone [email protected]:Qiskit-Extensions/circuit-knitting-toolbox.git
-$ cd circuit-knitting-toolbox
-$ python3 -m venv venv
-$ source venv/bin/activate
-$ pip install --upgrade pip
-$ pip install tox notebook -e '.[notebook-dependencies]'
-$ jupyter notebook
-```
-
-* Navigate to the notebooks in the `docs/` directory to run the tutorials.
-
-#### Option 2: Use within Docker
-
-We have provided a [`Dockerfile`](Dockerfile), which can be used to build a Docker image, as well as a [`docker-compose.yml`](docker-compose.yml) file, which allows one to use the Docker image with just a few simple commands.  If you have Docker installed but not [Docker Compose](https://pypi.org/project/docker-compose/), the latter can be installed by first running `pip install docker-compose`.
-
-```sh
-$ git clone [email protected]:Qiskit-Extensions/circuit-knitting-toolbox.git
-$ cd circuit-knitting-toolbox
-$ docker-compose build
-$ docker-compose up
-```
-
-Depending on your system configuration, you may need to type `sudo` before each `docker-compose` command.
-
-Once the container is running, you should see a message like this:
-
-```
-notebook_1  |     To access the server, open this file in a browser:
-notebook_1  |         file:///home/jovyan/.local/share/jupyter/runtime/jpserver-7-open.html
-notebook_1  |     Or copy and paste one of these URLs:
-notebook_1  |         http://e4a04564eb39:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
-notebook_1  |      or http://127.0.0.1:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
-```
-
-Locate the _last_ URL in your terminal (the one that includes `127.0.0.1`), and navigate to that URL in a web browser to access the Jupyter notebook interface.
-
-The home directory includes a subdirectory named `persistent-volume`.  All work you'd like to save should be placed in this directory, as it is the only one that will be saved across different container runs.
+See [`INSTALL.rst`](INSTALL.rst)
 
 ----------------------------------------------------------------------------------------------------
 

diff --git a/circuit_knitting_toolbox/circuit_cutting/__init__.py b/circuit_knitting_toolbox/circuit_cutting/__init__.py
@@ -9,6 +9,16 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Code to initialize the WireCutter import."""
+"""
+Circuit Cutting (:mod:`circuit_knitting_toolbox.circuit_cutting`).
+
+.. currentmodule:: circuit_knitting_toolbox.circuit_cutting
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   WireCutter
+"""
 
 from .wire_cutting.wire_cutter import WireCutter
diff --git a/circuit_knitting_toolbox/circuit_cutting/wire_cutting/wire_cutter.py b/circuit_knitting_toolbox/circuit_cutting/wire_cutting/wire_cutter.py
@@ -50,10 +50,8 @@ def __init__(
         service: Optional[Union[QiskitRuntimeService, Dict[str, Any]]] = None,
         options: Optional[Options] = None,
         backend_names: Optional[Sequence[str]] = None,
-    ):
+    ):  # noqa: D205, D400
         """
-        Assign the necessary member variable.
-
         Args:
             - circuit (QuantumCircuit): original quantum circuit to be
                 cut into subcircuits

diff --git a/circuit_knitting_toolbox/entanglement_forging/__init__.py b/circuit_knitting_toolbox/entanglement_forging/__init__.py
@@ -14,8 +14,8 @@
 
 .. currentmodule:: circuit_knitting_toolbox.entanglement_forging
 
-Entanglement Forging Classes
-=============================
+Classes
+=======
 
 .. autosummary::
    :toctree: ../stubs/

diff --git a/circuit_knitting_toolbox/entanglement_forging/entanglement_forging_knitter.py b/circuit_knitting_toolbox/entanglement_forging/entanglement_forging_knitter.py
@@ -31,24 +31,24 @@ class EntanglementForgingKnitter:
     """Container for Knitter class functions and attributes.
 
     A class which performs entanglement forging and returns the
-    ground state energy and schmidt coefficients found for given
-    ansatz parameters and schmidt coefficients.
-
-    Attributes:
-        - _ansatz (EntanglementForgingAnsatz): the ansatz containing the
-            information for the circuit structure and bitstrings to be used
-        - _backend_names (List[str]): the names of the backends to use
-        - _service (QiskitRuntimeService): the service used to access backends
-        - _tensor_circuits_u (List[QuantumCircuit]): the set of circuits used for the first
-            operator that have the same Schmidt values
-        - _superposition_circuits_u ()List[QuantumCircuit]: the set of circuits used for
-            the first operator that have different Schmidt values
-        - _tensor_circuits_v (List[QuantumCircuit]): the set of circuits used for the second
-            operator that have the same Schmidt values
-        - _superposition_circuits_v (List[QuantumCircuit]): the set of circuits used for
-            the second operator that have different Schmidt values
+    ground state energy and Schmidt coefficients found for given
+    ansatz parameters and Schmidt coefficients.
     """
 
+    # Attributes:
+    #     - _ansatz (EntanglementForgingAnsatz): the ansatz containing the
+    #         information for the circuit structure and bitstrings to be used
+    #     - _backend_names (List[str]): the names of the backends to use
+    #     - _service (QiskitRuntimeService): the service used to access backends
+    #     - _tensor_circuits_u (List[QuantumCircuit]): the set of circuits used for the first
+    #         operator that have the same Schmidt values
+    #     - _superposition_circuits_u (List[QuantumCircuit]): the set of circuits used for
+    #         the first operator that have different Schmidt values
+    #     - _tensor_circuits_v (List[QuantumCircuit]): the set of circuits used for the second
+    #         operator that have the same Schmidt values
+    #     - _superposition_circuits_v (List[QuantumCircuit]): the set of circuits used for
+    #         the second operator that have different Schmidt values
+
     def __init__(
         self,
         ansatz: EntanglementForgingAnsatz,
@@ -208,8 +208,8 @@ def __call__(
 
         Returns:
             - (Tuple[float, NDArray[Shape["*"], Float], NDArray[Shape["*, *"], Float]]): a tuple
-                containing the energy (i.e. forged expectation value), the schmidt coefficients,
-                and the full schmidt decomposition matrix
+                containing the energy (i.e. forged expectation value), the Schmidt coefficients,
+                and the full Schmidt decomposition matrix
         """
         # For now, we only assign the parameters to a copy of the ansatz
         circuit_u = self._ansatz.circuit_u.bind_parameters(ansatz_parameters)

diff --git a/circuit_knitting_toolbox/utils/__init__.py b/circuit_knitting_toolbox/utils/__init__.py
@@ -9,7 +9,18 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Code to initialize imports for utils."""
+"""
+Utility functions.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   conversion
+   metrics
+   integral_driver.IntegralDriver
+   orbital_reduction.reduce_bitstrings
+"""
 
 from .integral_driver import IntegralDriver
 from .orbital_reduction import reduce_bitstrings
diff --git a/circuit_knitting_toolbox/utils/metrics.py b/circuit_knitting_toolbox/utils/metrics.py
@@ -35,7 +35,7 @@ def chi2_distance(target, obs):  # noqa: D301
         - obs (NDArray): the actually observed feature vector
 
     Returns:
-        - (Float): the computed distance
+        - (float): the computed distance
 
     Raises:
         - Exception: if the target is not a numpy array or dictionary, an exception
@@ -81,7 +81,7 @@ def MSE(target, obs):  # noqa: D301
         - obs (NDArray): the actually observed feature vector
 
     Returns:
-        - (Float): the computed MSE
+        - (float): the computed MSE
 
     Raises:
         - Exception: if the target is not a dict, or if the target and obs are not
@@ -132,7 +132,7 @@ def MAPE(target, obs):  # noqa: D301
         - obs (NDArray): the actually observed feature vector
 
     Returns:
-        - (Float): the computed MAPE
+        - (float): the computed MAPE
 
     Raises:
         - Exception: if the target is not a dict, or if the target and obs are not
@@ -191,7 +191,7 @@ def cross_entropy(target, obs):  # noqa: D301
         - obs (NDArray): the actually observed feature vector
 
     Returns:
-        - (Float): the computed cross entropy
+        - (float): the computed cross entropy
 
     Raises:
         - Exception: if the target is not a dict, or if the target and obs are not
@@ -240,7 +240,7 @@ def HOP(target, obs):
         - obs (NDArray): the actually observed feature vector
 
     Returns:
-        - (Float): the computed HOP
+        - (float): the computed HOP
     """
     target = copy.deepcopy(target)
     obs = copy.deepcopy(obs)