Updates to docstrings and doc setup (#395)

* Updates to docstrings and doc setup

* Correct black errors

* Fixed no-module found error for C extension stim

---------

Co-authored-by: grace-harper <[email protected]>

docs/apidocs/index.rst

@@ -13,11 +13,9 @@ Qiskit QEC API Reference
    circuits
    codes
    decoders
-   extensions
    geometry
    info
    linear
-   models
    operators
    structures
    utils

docs/conf.py

@@ -42,7 +42,7 @@
 templates_path = ["_templates"]
 numfig = True
 numfig_format = {"table": "Table %s"}
-language = None
+language = "en"
 pygments_style = "colorful"
 add_module_names = False
 modindex_common_prefix = ["qiskit_qec."]

src/qiskit_qec/circuits/__init__.py

@@ -23,8 +23,11 @@
 .. autosummary::
     :toctree: ../stubs/
 
+    CodeCircuit
     RepetitionCodeCircuit
-    CSSCircuit
+    ArcCircuit
+    SurfaceCodeCircuit
+    CSSCodeCircuit
 """
 
 from .code_circuit import CodeCircuit

src/qiskit_qec/circuits/code_circuit.py

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 # This code is part of Qiskit.
 #
 # (C) Copyright IBM 2019.
@@ -11,16 +10,14 @@
 # Any modifications or derivative works of this code must retain this
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
-
 # pylint: disable=invalid-name
 
 """Class that manage circuits for codes."""
 from abc import ABC, abstractmethod
 
 
 class CodeCircuit(ABC):
-    """
-    Abstract class to manage circuits for codes, as well
+    """Abstract class to manage circuits for codes, as well
     as other fault-tolerant circuits.
 
     A CodeCircuit requires the methods `string2nodes`,
@@ -29,15 +26,16 @@ class CodeCircuit(ABC):
     """
 
     def __init__(self):
-        """
-        Initialization of classes that inherent from CodeCircuit can
+        """Initialization of classes that inherent from CodeCircuit can
         be done in various ways, depending on the code or code family
         to be initialized. In all cases, the initialization must define
         the following attributes:
+
+        Args:
             circuit (dict): A dictionary with circuits as values, and
-            labels (typically strings) as keys.
+                labels (typically strings) as keys.
             base (string) The label for the above regarded as the base case,
-            used in decoding graph generation.
+                used in decoding graph generation.
             d (int): Code distance.
             T (int): number of syndrome measurement rounds.
         """

src/qiskit_qec/circuits/css_code.py

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 # This code is part of Qiskit.
 #
 # (C) Copyright IBM 2019.
@@ -12,12 +11,12 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-# pylint: disable=invalid-name, disable=no-name-in-module
-
-"""Generates circuits for CSS codes."""
+"""Class that manage circuits for CSS codes."""
+# pylint: disable=invalid-name
 from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
 from qiskit_aer.noise import depolarizing_error, pauli_error
 
+# pylint: disable=no-name-in-module
 from stim import Circuit as StimCircuit
 from stim import target_rec as StimTarget_rec
 
@@ -35,18 +34,17 @@
 
 
 class CSSCodeCircuit(CodeCircuit):
-    """
-    CodeCircuit class for generic CSS codes.
-    """
+    """CodeCircuit class for generic CSS codes."""
 
     def __init__(
         self, code, T: int, basis: str = "z", round_schedule: str = "zx", noise_model=None
     ):
-        """
+        """CSSCodeCircuit init method
+
         Args:
             code: A CSS code class which is either
-                a) StabSubSystemCode
-                b) a class with the following methods:
+                    a) StabSubSystemCode
+                    b) a class with the following methods:
                     'x_gauges' (as a list of list of qubit indices),
                     'z_gauges',
                     'x_stabilizers',
@@ -58,17 +56,18 @@ def __init__(
             basis: basis for encoding ('x' or 'z')
             round_schedule: Order in which to measureme gauge operators ('zx' or 'xz')
             noise_model: Pauli noise model used in the construction of noisy circuits.
-            If a tuple, a pnenomological noise model is used with the entries being
-            probabity of depolarizing noise on code qubits between rounds and
-            probability of measurement errors, respectively.
+                If a tuple, a pnenomological noise model is used with the entries being
+                probabity of depolarizing noise on code qubits between rounds and
+                probability of measurement errors, respectively.
+
         Examples:
             The QuantumCircuit of a memory experiment for the distance-3 HeavyHEX code
             >>> from qiskit_qec.codes.hhc import HHC
             >>> from qiskit_qec.circuits.css_code import CSSCodeCircuit
             >>> code = CSSCodeCircuit(HHC(3),T=3,basis='x',noise_model=(0.01,0.01),round_schedule='xz')
             >>> code.circuit['0']
-        """
 
+        """
         super().__init__()
 
         self.code = code
@@ -241,6 +240,7 @@ def string2nodes(self, string, **kwargs):
         """
         Convert output string from circuits into a set of nodes for
         `DecodingGraph`.
+
         Args:
             string (string): Results string to convert.
             kwargs (dict): Any additional keyword arguments.

src/qiskit_qec/circuits/repetition_code.py

@@ -285,14 +285,14 @@ def _process_string(self, string):
         return new_string
 
     def string2nodes(self, string, **kwargs):
-        """
-        Convert output string from circuits into a set of nodes.
+        """Convert output string from circuits into a set of nodes.
+
         Args:
             string (string): Results string to convert.
             kwargs (dict): Additional keyword arguments.
-                logical (str): Logical value whose results are used ('0' as default).
-                all_logicals (bool): Whether to include logical nodes
-                irrespective of value. (False as default).
+                    logical (str): Logical value whose results are used ('0' as default).
+                    all_logicals (bool): Whether to include logical nodes
+                    irrespective of value. (False as default).
 
         Returns:
             dict: List of nodes corresponding to to the non-trivial
@@ -1063,13 +1063,15 @@ def string2raw_logicals(self, string):
         return _separate_string(self._process_string(string))[0]
 
     def string2nodes(self, string, **kwargs) -> List[DecodingGraphNode]:
-        """
-        Convert output string from circuits into a set of nodes.
+        """Convert output string from circuits into a set of nodes.
+
         Args:
             string (string): Results string to convert.
-            kwargs (dict): Additional keyword arguments.
-                all_logicals (bool): Whether to include logical nodes
-                irrespective of value. (False as default).
+            kwargs (dict): Additional keyword arguments. See below.
+
+        kwargs:
+            all_logicals (bool): Whether to include logical nodes irrespective
+                of value. (False as default).
         Returns:
             dict: List of nodes corresponding to to the non-trivial
             elements in the string.

src/qiskit_qec/circuits/surface_code.py

@@ -24,13 +24,11 @@
 
 class SurfaceCodeCircuit(CodeCircuit):
 
-    """
-    Implementation of a distance d rotated surface code, implemented over
-    T syndrome measurement rounds.
-    """
+    """Distance d rotated surface code with  T syndrome measurement rounds."""
 
     def __init__(self, d: int, T: int, basis: str = "z", resets=True):
-        """
+        """Creates the circuits corresponding to logical basis states.
+
         Creates the circuits corresponding to logical basis states encoded
         using a rotated surface code.
 
@@ -168,8 +166,8 @@ def get_circuit_list(self):
         return circuit_list
 
     def x(self, logs=("0", "1"), barrier=False):
-        """
-        Applies a logical x to the circuits for the given logical values.
+        """Applies a logical x to the circuits for the given logical values.
+
         Args:
             logs (list or tuple): List or tuple of logical values expressed as
                 strings.
@@ -183,8 +181,8 @@ def x(self, logs=("0", "1"), barrier=False):
                 self.circuit[log].barrier()
 
     def z(self, logs=("0", "1"), barrier=False):
-        """
-        Applies a logical z to the circuits for the given logical values.
+        """Applies a logical z to the circuits for the given logical values.
+
         Args:
             logs (list or tuple): List or tuple of logical values expressed as
                 strings.
@@ -198,12 +196,11 @@ def z(self, logs=("0", "1"), barrier=False):
                 self.circuit[log].barrier()
 
     def syndrome_measurement(self, final=False, barrier=False):
-        """
-        Application of a syndrome measurement round.
-        Args:
+        """Application of a syndrome measurement round.
 
+        Args:
             final (bool): Whether to disregard the reset (if applicable) due to this
-            being the final syndrome measurement round.
+                being the final syndrome measurement round.
             barrier (bool): Boolean denoting whether to include a barrier at the end.
 
         """
@@ -364,22 +361,25 @@ def _separate_string(self, string):
         return separated_string
 
     def string2nodes(self, string, **kwargs):
-        """
-        Convert output string from circuits into a set of nodes.
+        """Convert output string from circuits into a set of nodes.
+
         Args:
             string (string): Results string to convert.
-            kwargs (dict): Additional keyword arguments.
-                logical (str): Logical value whose results are used ('0' as default).
-                all_logicals (bool): Whether to include logical nodes
+            kwargs (dict): Additional keyword arguments. See below:
+
+        kwargs:
+            logical (str): Logical value whose results are used ('0' as default).
+            all_logicals (bool): Whether to include logical nodes
                 irrespective of value. (False as default).
+
         Returns:
             dict: List of nodes corresponding to to the non-trivial
-            elements in the string.
+                elements in the string.
 
         Additional information:
-        Strings are read right to left, but lists*
-        are read left to right. So, we have some ugly indexing
-        code whenever we're dealing with both strings and lists.
+            Strings are read right to left, but lists*
+            are read left to right. So, we have some ugly indexing
+            code whenever we're dealing with both strings and lists.
         """
 
         all_logicals = kwargs.get("all_logicals")

src/qiskit_qec/decoders/hdrg_decoders.py

@@ -619,18 +619,22 @@ def peeling(self, erasure: PyGraph) -> List[int]:
         return [erasure.edges()[edge].qubits[0] for edge in edges if erasure.edges()[edge].qubits]
 
     def neighbouring_edges(self, node_index) -> List[Tuple[int, int, DecodingGraphEdge]]:
-        """
-        Returns all of the neighbouring edges of a node in the decoding graph.
+        """Returns all of the neighbouring edges of a node in the decoding graph.
+
         Args:
             node_index (int): The index of the node in the graph.
 
         Returns:
             neighbouring_edges (List[Tuple[int, int, DecodingGraphEdge]]): List of neighbouring edges
-            in following format: (
-                index of edge in graph,
-                index of neighbour node in graph,
-                data payload of the edge
-            )
+
+            In following format::
+
+                {
+                    index of edge in graph,
+                    index of neighbour node in graph,
+                    data payload of the edge
+                }
+
         """
         return [
             (edge, neighbour, data)

src/qiskit_qec/geometry/shape.py

@@ -124,6 +124,8 @@ def rect(
     ) -> "Shape":
         r"""Create a rectangle on a manifold
 
+        A rect has the following lables::
+
                       r2
                       o
                   /       \