Another round of sphinx docstring updates

Another batch of docstring fixes.

pygsti/algorithms/compilers.py

@@ -2937,7 +2937,7 @@ def compile_conditional_symplectic(s, pspec, qubit_labels=None, calg='COiCAGE',
     1. C1 is a CNOT circuit
     2. C2 is a circuit with the form 1-qubit-gates -- CNOT circuit -- 1-qubit gates.
     3. The symplectic rep of the circuit consisting of C1 followed by C2 has the form ((.,B)(.,D))
-    when s has the form ((A,B),(C,D)).
+       when s has the form ((A,B),(C,D)).
 
     Therefore, the circuit C2 acting on `|0,0,0,...>` generates the same stabilizer state (up to Paulis)
     as a circuit that has the symplectic rep (s,p) for any valid p. The circuit is only "conditionally"

pygsti/algorithms/gaugeopt.py

@@ -252,8 +252,11 @@ def gaugeopt_custom(model, objective_fn, gauge_group=None,
 
     Returns
     -------
-    model                            if return_all == False
-    (goodnessMin, gaugeMx, model)    if return_all == True
+    model                            
+        if return_all == False
+    
+    (goodnessMin, gaugeMx, model)    
+        if return_all == True
         where goodnessMin is the minimum value of the goodness function (the best 'goodness')
         found, gaugeMx is the gauge matrix used to transform the model, and model is the
         final gauge-transformed model.

pygsti/algorithms/germselection.py

@@ -607,7 +607,7 @@ def compute_composite_germ_set_score(score_fn, threshold_ac=1e6, init_n=1,
 
     eps : float, optional
         Used when calculating `partial_deriv_dagger_deriv` to determine if two
-        eigenvalues are equal (see :func:`_bulk_twirled_deriv` for details). Not
+        eigenvalues are equal (see :func:`~pygsti.algorithms.germselection._bulk_twirled_deriv` for details). Not
         used if `partial_deriv_dagger_deriv` is provided.
 
     op_penalty : float, optional
@@ -940,7 +940,7 @@ def test_germs_list_completeness(model_list, germs_list, score_func, threshold,
         models around a model of interest.
 
     germs_list : list
-        A list of the germ :class:`Circuit`s (the "germ set") to test for completeness.
+        A list of the germ :class:`Circuit` objects (the "germ set") to test for completeness.
 
     score_func : {'all', 'worst'}
         Sets the objective function for scoring the eigenvalues. If 'all',
@@ -1584,7 +1584,7 @@ def find_germs_breadthfirst(model_list, germs_list, randomize=True,
     Parameters
     ----------
     model_list : Model or list
-        The model or list of `Model`s to select germs for.
+        The model or list of `Model` objects to select germs for.
 
     germs_list : list of Circuit
         The list of germs to contruct a germ set from.

pygsti/algorithms/randomcircuit.py

@@ -57,7 +57,7 @@ def sample_random_clifford_one_qubit_unitary_parameters():
 def sample_compiled_haar_random_one_qubit_gates_zxzxz_circuit(pspec, zname='Gzr', xname='Gxpi2', qubit_labels=None):
     """
     TODO: docstring  #generate layer of random unitaries and make a series of circuit layers with the compiled versions
-     of these
+    of these
     """
     if qubit_labels is not None:
         n = len(qubit_labels)
@@ -86,7 +86,7 @@ def sample_compiled_haar_random_one_qubit_gates_zxzxz_circuit(pspec, zname='Gzr'
 def sample_compiled_random_clifford_one_qubit_gates_zxzxz_circuit(pspec, zname='Gzr', xname='Gxpi2', qubit_labels=None):
     """
     TODO: docstring  #generate layer of random unitaries and make a series of circuit layers with the compiled versions
-     of these
+    of these
     """
     if qubit_labels is not None:
         n = len(qubit_labels)
@@ -2433,7 +2433,7 @@ def create_mirror_rb_circuit(pspec, absolute_compilation, length, qubit_labels=N
         by the first half.
 
         If `paulirandomize` is True and `localclifford` is False, the depth of the circuits is
-        2*length+1 with odd-indexed layers sampled according to the sampler specified by `sampler, and
+        2*length+1 with odd-indexed layers sampled according to the sampler specified by `sampler`, and
         the the zeroth layer + the even-indexed layers consisting of random 1-qubit Pauli gates.
 
         If `paulirandomize` and `localclifford` are True, the depth of the circuits is

pygsti/algorithms/robust_phase_estimation.py

@@ -19,8 +19,9 @@ class RobustPhaseEstimation(object):
 
     Runs the non-adaptive RPE algorithm using a dictionary of measurement results,
     `Q.raw_angles`, containing the angles calculated from the probabilities:
-        `P^{γ'γ}_{Nₖs} = |<γ' y| U^Nₖ |γ x>|² = |<γ' x| U^Nₖ |-γ y>|² = (1 ± sin(θ))/2`
-        `P^{γ'γ}_{Nₖc} = |<γ' x| U^Nₖ |γ x>|² = |<γ' y| U^Nₖ | γ y>|² = (1 ± cos(θ))/2`
+    
+    `P^{γ'γ}_{Nₖs} = |<γ' y| U^Nₖ |γ x>|² = |<γ' x| U^Nₖ |-γ y>|² = (1 ± sin(θ))/2`
+    `P^{γ'γ}_{Nₖc} = |<γ' x| U^Nₖ |γ x>|² = |<γ' y| U^Nₖ | γ y>|² = (1 ± cos(θ))/2`
 
     Expect `measured[Nₖ] = θ`.
 

pygsti/baseobjs/basisconstructors.py

@@ -709,17 +709,22 @@ def qsim_matrices(matrix_dim):
     The returned matrices are given in the QuantumSim representation of the
     density matrix space, and are thus kronecker products of
     the standard representation of the QuantumSim matrices:
-        '0' == [[1, 0],[0,0]]
-        'X' == [[0, 1],[1,0]]
-        'Y' == [[0,-1.j],[1.j,0]]
-        '1' == [[0, 0],[0,1]]
+    
+    * `'0' == [[1, 0],[0,0]]`
+    * `'X' == [[0, 1],[1,0]]`
+    * `'Y' == [[0,-1.j],[1.j,0]]`
+    * `'1' == [[0, 0],[0,1]]`
+    
     The normalization is such that the resulting basis is orthonormal
     under the trace inner product:
-        Tr( dot(Mi,Mj) ) == delta_ij.
+    
+    `Tr( dot(Mi,Mj) ) == delta_ij`.
+    
     In the returned list, the right-most factor of the kronecker product
     varies the fastest, so, for example, when matrix_dim == 4 the
     returned list is:
-        [ 00,0X,0Y,01,X0,XX,XY,X1,Y0,Y0,YX,YY,Y1,10,1X,1Y,11 ].
+        
+    `[ 00,0X,0Y,01,X0,XX,XY,X1,Y0,Y0,YX,YY,Y1,10,1X,1Y,11 ]`.
 
     Parameters
     ----------

pygsti/baseobjs/errorgenbasis.py

@@ -67,6 +67,11 @@ def elemgen_supports_and_matrices(self):
     def label_index(self, label, ok_if_missing=False):
         """
         TODO: docstring
+        
+        Parameters
+        ----------
+        label
+        
         ok_if_missing : bool
            If True, then returns `None` instead of an integer when the given label is not present.
         """
@@ -447,6 +452,11 @@ def elemgen_supports_and_matrices(self):
     def label_index(self, elemgen_label, ok_if_missing=False):
         """
         TODO: docstring
+        
+        Parameters
+        ----------
+        elemgen_label
+        
         ok_if_missing : bool
            If True, then returns `None` instead of an integer when the given label is not present.
         """

pygsti/baseobjs/label.py

@@ -187,7 +187,7 @@ def expand_subcircuits(self):
         -------
         tuple
             A tuple of component Labels (none of which should be
-            :class:`CircuitLabel`s).
+            :class:`CircuitLabel` objects).
         """
         return (self,)  # most labels just expand to themselves
 
@@ -1157,7 +1157,7 @@ def expand_subcircuits(self):
         -------
         tuple
             A tuple of component Labels (none of which should be
-            :class:`CircuitLabel`s).
+            :class:`CircuitLabel` objects).
         """
         ret = []
         expanded_comps = [x.expand_subcircuits() for x in self.components]
@@ -1426,7 +1426,7 @@ def expand_subcircuits(self):
         -------
         tuple
             A tuple of component Labels (none of which should be
-            :class:`CircuitLabel`s).
+            :class:`CircuitLabel` objects).
         """
         ret = []
         expanded_comps = [x.expand_subcircuits() for x in self.components]
@@ -1721,7 +1721,7 @@ def expand_subcircuits(self):
         -------
         tuple
             A tuple of component Labels (none of which should be
-            :class:`CircuitLabel`s).
+            :class:`CircuitLabel` objects).
         """
         return tuple(_itertools.chain(*[x.expand_subcircuits() for x in self.components])) * self.reps
 

pygsti/baseobjs/mongoserializable.py

@@ -40,7 +40,7 @@ def _create_obj_from_doc_and_mongodb(cls, doc, mongodb, **kwargs):
 
     def _add_auxiliary_write_ops_and_update_doc(self, doc, write_ops, mongodb, collection_name, overwrite_existing,
                                                 **kwargs):
-        """ Add to `write_ops` and update `doc` so that all of `self`'s data is serialized """
+        """ Add to `write_ops` and update `doc` so that all of `self` 's data is serialized """
         raise NotImplementedError("Subclasses must implement this!")
 
     @classmethod
@@ -487,13 +487,13 @@ def prepare_doc_for_existing_doc_check(doc, existing_doc, set_id=True, convert_t
     Prepares a to-be inserted document for comparison with an existing document.
 
     Optionally (see parameters):
-    1) sets _id of `doc` to that of `existing_doc`.  This is useful in cases where the _id
+    1. sets _id of `doc` to that of `existing_doc` .  This is useful in cases where the _id
        field is redundant with other uniquely identifying fields in the document, and so inserted
        documents don't need to match this field.
-    2) converts all of `doc`'s tuples to lists, as the existing_doc is typically read from a MongoDB
+    2. converts all of `doc` 's tuples to lists, as the existing_doc is typically read from a MongoDB
        which only stores lists and doesn't distinguish between lists and tuples.
-    3) converts numpy datatypes to native python types
-    4) rounds floating point values
+    3. converts numpy datatypes to native python types
+    4. rounds floating point values
 
     Parameters
     ----------

pygsti/baseobjs/polynomial.py

@@ -1138,7 +1138,7 @@ def bulk_load_compact_polynomials(vtape, ctape, keep_compact=False, max_num_vars
 
     ctape : numpy.ndarray
         A 1D array of coefficients that, together with `vtape`, specify an
-       efficient means for evaluating a set of polynoials.
+        efficient means for evaluating a set of polynoials.
 
     keep_compact : bool, optional
         If True the returned list has elements which are (vtape,ctape) tuples

pygsti/circuits/circuit.py

@@ -212,7 +212,7 @@ class Circuit(object):
         to a Label objects.  For example, any of the following are allowed:
 
         - `['Gx','Gx']` : X gate on each of 2 layers
-        - `[Label('Gx'),Label('Gx')] : same as above
+        - `[Label('Gx'),Label('Gx')]` : same as above
         - `[('Gx',0),('Gy',0)]` : X then Y on qubit 0 (2 layers)
         - `[[('Gx',0),('Gx',1)],[('Gy',0),('Gy',1)]]` : parallel X then Y on qubits 0 & 1
 
@@ -362,7 +362,7 @@ def __init__(self, layer_labels=(), line_labels='auto', num_lines=None, editable
             to a Label objects.  For example, any of the following are allowed:
 
             - `['Gx','Gx']` : X gate on each of 2 layers
-            - `[Label('Gx'),Label('Gx')] : same as above
+            - `[Label('Gx'),Label('Gx')]` : same as above
             - `[('Gx',0),('Gy',0)]` : X then Y on qubit 0 (2 layers)
             - `[[('Gx',0),('Gx',1)],[('Gy',0),('Gy',1)]]` : parallel X then Y on qubits 0 & 1
 

pygsti/circuits/circuitlist.py

@@ -138,7 +138,7 @@ def apply_aliases(self):
         Returns
         -------
         list
-            A list of :class:`Circuit`s.
+            A list of :class:`Circuit` objects.
         """
         return _lt.apply_aliases_to_circuits(self._circuits, self.op_label_aliases)
 

pygsti/circuits/circuitparser/__init__.py

@@ -116,45 +116,58 @@ def make_label(s):
 
     @staticmethod
     def t_GATE(t):                                                                       # noqa
-        r'G[a-z0-9_]+(;[a-zQ0-9_\./]+)*(:[a-zQ0-9_]+)*(![0-9\.]+)?'
+        """
+        ``'G[a-z0-9_]+(;[a-zQ0-9_\./]+)*(:[a-zQ0-9_]+)*(![0-9\.]+)?'``
+        """
+
         #Note: Q is only capital letter allowed in qubit label
         #Note: don't need to convert parts[1],etc, to integers (if possible) as Label automatically does this
         lbl = CircuitLexer.make_label(t.value)
         t.value = lbl,  # make it a tuple
         return t
 
     @staticmethod
-    def t_INSTRMT(t):                                                                    # noqa
-        r'I[a-z0-9_]+(![0-9\.]+)?'
+    def t_INSTRMT(t):                                                               # noqa
+        """
+        ``'I[a-z0-9_]+(![0-9\.]+)?'``
+        """
         #Note: don't need to convert parts[1],etc, to integers (if possible) as Label automatically does this
         lbl = CircuitLexer.make_label(t.value)
         t.value = lbl,  # make it a tuple
         return t
 
     @staticmethod
     def t_PREP(t):                                                                       # noqa
-        r'rho[a-z0-9_]+(![0-9\.]+)?'
+        """
+        ``'rho[a-z0-9_]+(![0-9\.]+)?'``
+        """
         #Note: don't need to convert parts[1],etc, to integers (if possible) as Label automatically does this
         lbl = CircuitLexer.make_label(t.value)
         t.value = lbl,  # make it a tuple
         return t
 
     @staticmethod
     def t_POVM(t):                                                                       # noqa
-        r'M[a-z0-9_]+(![0-9\.]+)?'
+        """
+        ``'M[a-z0-9_]+(![0-9\.]+)?'``
+        """
         #Note: don't need to convert parts[1],etc, to integers (if possible) as Label automatically does this
         lbl = CircuitLexer.make_label(t.value)
         t.value = lbl,  # make it a tuple
         return t
 
     @staticmethod
     def t_STRINGIND(t):                                                                  # noqa
-        r'S(?=\s*\<)'
+        """
+        ``'S(?=\s*\<)'``
+        """
         return t
 
     @staticmethod
     def t_REFLBL(t):                                                                     # noqa
-        r'<\s*[a-zA-Z0-9_]+\s*>'
+        """
+        ``'<\s*[a-zA-Z0-9_]+\s*>'``
+        """
         t.value = t.value[1:-1].strip()
         return t
 
@@ -171,13 +184,17 @@ def t_REFLBL(t):
 
     @staticmethod
     def t_NOP(t):                                                                        # noqa
-        r'\{\}'
+        """
+        ``'\{\}'``
+        """
         t.value = tuple()
         return t
 
     @staticmethod
     def t_INTEGER(t):                                                                    # noqa
-        r'\d+'
+        """
+        ``'\d+'``
+        """
         t.value = int(t.value)
         return t
 

pygsti/circuits/circuitstructure.py

@@ -626,7 +626,7 @@ def cast(cls, circuits_or_structure):
         circuits_or_structure : list or CircuitList
             The object to convert.  If a :class:`PlaquetteGridCircuitStructure`,
             then the object is simply returned.  Lists of circuits (including
-            :class:`CircuitList`s are converted to structures having no
+            :class:`CircuitList` objects are converted to structures having no
             plaquettes.
 
         Returns

pygsti/data/datacomparator.py

@@ -530,32 +530,32 @@ def run(self, significance=0.05, per_circuit_correction='Hochberg',
             value for the `localcorrections` input parameter of the HypothesisTest object. This includes:
 
             * 'Hochberg'. This implements the Hochberg multi-test compensation technique. This
-            is strictly the best method available in the code, if you wish to control the FWER,
-            and it is the method described in "Probing context-dependent errors in quantum processors",
-            by Rudinger et al.
+              is strictly the best method available in the code, if you wish to control the FWER,
+              and it is the method described in "Probing context-dependent errors in quantum processors",
+              by Rudinger et al.
             * 'Holms'. This implements the Holms multi-test compensation technique. This
-            controls the FWER, and it results in a strictly less powerful test than the Hochberg
-            correction.
+              controls the FWER, and it results in a strictly less powerful test than the Hochberg
+              correction.
             * 'Bonferroni'. This implements the well-known Bonferroni multi-test compensation
-            technique. This controls the FWER, and it results in a strictly less powerful test than
-            the Hochberg correction.
+              technique. This controls the FWER, and it results in a strictly less powerful test than
+              the Hochberg correction.
             * 'none'. This implements no multi-test compensation for the per-sequence comparsions,
-            so they are all implemented at a "local" signifincance level that is altered from `significance`
-            only by the (inbuilt) Bonferroni-like correction between the "aggregate" test and the per-sequence
-            tests. This option does *not* control the FWER, and many sequences may be flagged up as context
-            dependent even if none are.
+              so they are all implemented at a "local" signifincance level that is altered from `significance`
+              only by the (inbuilt) Bonferroni-like correction between the "aggregate" test and the per-sequence
+              tests. This option does *not* control the FWER, and many sequences may be flagged up as context
+              dependent even if none are.
             * 'Benjamini-Hochberg'. This implements the Benjamini-Hockberg multi-test compensation
-            technique. This does *not* control the FWER, and instead controls the "False Detection Rate"
-            (FDR); see, for example, https://en.wikipedia.org/wiki/False_discovery_rate. That means that
-            the global significance is maintained for the test of "Is there any context dependence?". I.e.,
-            one or more tests will trigger when there is no context dependence with at most a probability of `significance`. 
-            But, if one or more per-sequence tests trigger then we are only guaranteed that (in expectation) no 
-            more than a fraction of "local-signifiance" of the circuits that have been flagged up as context dependent actually aren't.
-            Here, "local-significance" is the  significance at which the per-sequence tests are, together,
-            implemented, which is `significance`*(1 - `aggregate_test_weighting`) if the aggregate test doesn't
-            detect context dependence and `significance` if it does (as long as `pass_alpha` is True). This
-            method is strictly more powerful than the Hochberg correction, but it controls a different, weaker
-            quantity.
+              technique. This does *not* control the FWER, and instead controls the "False Detection Rate"
+              (FDR); see, for example, https://en.wikipedia.org/wiki/False_discovery_rate. That means that
+              the global significance is maintained for the test of "Is there any context dependence?". I.e.,
+              one or more tests will trigger when there is no context dependence with at most a probability of `significance`. 
+              But, if one or more per-sequence tests trigger then we are only guaranteed that (in expectation) no 
+              more than a fraction of "local-signifiance" of the circuits that have been flagged up as context dependent actually aren't.
+              Here, "local-significance" is the  significance at which the per-sequence tests are, together,
+              implemented, which is `significance`*(1 - `aggregate_test_weighting`) if the aggregate test doesn't
+              detect context dependence and `significance` if it does (as long as `pass_alpha` is True). This
+              method is strictly more powerful than the Hochberg correction, but it controls a different, weaker
+              quantity.
 
         aggregate_test_weighting : float in [0,1], optional (default is 0.5)
             The weighting, in a generalized Bonferroni correction, to put on the "aggregate test", that jointly