Add module docstrings and fix formatting (#3589)

* Add module docstrings and fix formatting - Many modules were missing docstrings. Added simple ones for all modules. - Also fixed various formatting issues. -- Many matrices were not protected by code blocks, so fixed them -- circuits docstring gets mangled by markdown, so tried to fix it with lists.
quantumlib · Dec 7, 2020 · 8f9d859 · 8f9d859
1 parent 3a095e9
commit 8f9d859
Show file tree

Hide file tree

Showing 18 changed files with 171 additions and 75 deletions.
diff --git a/cirq/circuits/circuit.py b/cirq/circuits/circuit.py
@@ -73,29 +73,30 @@ class AbstractCircuit(abc.ABC):
 
     These methods return information about the circuit, and can be called on
     either Circuit or FrozenCircuit objects:
-        next_moment_operating_on
-        prev_moment_operating_on
-        next_moments_operating_on
-        operation_at
-        all_qubits
-        all_operations
-        findall_operations
-        findall_operations_between
-        findall_operations_until_blocked
-        findall_operations_with_gate_type
-        reachable_frontier_from
-        has_measurements
-        are_all_matches_terminal
-        are_all_measurements_terminal
-        unitary
-        final_state_vector
-        to_text_diagram
-        to_text_diagram_drawer
-        qid_shape
-        all_measurement_keys
-        to_quil
-        to_qasm
-        save_qasm
+
+    *   next_moment_operating_on
+    *   prev_moment_operating_on
+    *   next_moments_operating_on
+    *   operation_at
+    *   all_qubits
+    *   all_operations
+    *   findall_operations
+    *   findall_operations_between
+    *   findall_operations_until_blocked
+    *   findall_operations_with_gate_type
+    *   reachable_frontier_from
+    *   has_measurements
+    *   are_all_matches_terminal
+    *   are_all_measurements_terminal
+    *   unitary
+    *   final_state_vector
+    *   to_text_diagram
+    *   to_text_diagram_drawer
+    *   qid_shape
+    *   all_measurement_keys
+    *   to_quil
+    *   to_qasm
+    *   save_qasm
     """
 
     @property
@@ -1209,61 +1210,73 @@ class Circuit(AbstractCircuit):
 
     Methods returning information about the circuit (inherited from
     AbstractCircuit):
-        next_moment_operating_on
-        prev_moment_operating_on
-        next_moments_operating_on
-        operation_at
-        all_qubits
-        all_operations
-        findall_operations
-        findall_operations_between
-        findall_operations_until_blocked
-        findall_operations_with_gate_type
-        reachable_frontier_from
-        has_measurements
-        are_all_matches_terminal
-        are_all_measurements_terminal
-        unitary
-        final_state_vector
-        to_text_diagram
-        to_text_diagram_drawer
-        qid_shape
-        all_measurement_keys
-        to_quil
-        to_qasm
-        save_qasm
+
+    *   next_moment_operating_on
+    *   prev_moment_operating_on
+    *   next_moments_operating_on
+    *   operation_at
+    *   all_qubits
+    *   all_operations
+    *   findall_operations
+    *   findall_operations_between
+    *   findall_operations_until_blocked
+    *   findall_operations_with_gate_type
+    *   reachable_frontier_from
+    *   has_measurements
+    *   are_all_matches_terminal
+    *   are_all_measurements_terminal
+    *   unitary
+    *   final_state_vector
+    *   to_text_diagram
+    *   to_text_diagram_drawer
+    *   qid_shape
+    *   all_measurement_keys
+    *   to_quil
+    *   to_qasm
+    *   save_qasm
 
     Methods for mutation:
-        insert
-        append
-        insert_into_range
-        clear_operations_touching
-        batch_insert
-        batch_remove
-        batch_insert_into
-        insert_at_frontier
+
+    *   insert
+    *   append
+    *   insert_into_range
+    *   clear_operations_touching
+    *   batch_insert
+    *   batch_remove
+    *   batch_insert_into
+    *   insert_at_frontier
 
     Circuits can also be iterated over,
+
+    ```
         for moment in circuit:
             ...
+    ```
+
     and sliced,
-        circuit[1:3] is a new Circuit made up of two moments, the first being
-            circuit[1] and the second being circuit[2];
-        circuit[:, qubit] is a new Circuit with the same moments, but with only
-            those operations which act on the given Qubit;
-        circuit[:, qubits], where 'qubits' is list of Qubits, is a new Circuit
+
+    *   `circuit[1:3]` is a new Circuit made up of two moments, the first being
+            `circuit[1]` and the second being `circuit[2]`;
+    *   `circuit[:, qubit]` is a new Circuit with the same moments, but with
+            only those operations which act on the given Qubit;
+    *   `circuit[:, qubits]`, where 'qubits' is list of Qubits, is a new Circuit
             with the same moments, but only with those operations which touch
             any of the given qubits;
-        circuit[1:3, qubit] is equivalent to circuit[1:3][:, qubit];
-        circuit[1:3, qubits] is equivalent to circuit[1:3][:, qubits];
+    *   `circuit[1:3, qubit]` is equivalent to `circuit[1:3][:, qubit]`;
+    *   `circuit[1:3, qubits]` is equivalent to `circuit[1:3][:, qubits]`;
+
     and concatenated,
-        circuit1 + circuit2 is a new Circuit made up of the moments in circuit1
-            followed by the moments in circuit2;
+
+    *    `circuit1 + circuit2` is a new Circuit made up of the moments in
+            circuit1 followed by the moments in circuit2;
+
     and multiplied by an integer,
-        circuit * k is a new Circuit made up of the moments in circuit repeated
+
+    *    `circuit * k` is a new Circuit made up of the moments in circuit repeated
             k times.
+
     and mutated,
-        circuit[1:7] = [Moment(...)]
+    *    `circuit[1:7] = [Moment(...)]`
     """
 
     def __init__(

diff --git a/cirq/circuits/qasm_output.py b/cirq/circuits/qasm_output.py
@@ -146,6 +146,17 @@ def __repr__(self) -> str:
 
 
 class QasmOutput:
+    """Representation of a circuit in QASM (quantum assembly) format.
+
+    Please note that the QASM importer is in an experimental state and
+    currently only supports a subset of the full OpenQASM spec.
+    Amongst others, classical control, arbitrary gate definitions,
+    and even some of the gates that don't have a one-to-one representation
+    in Cirq, are not yet supported.
+
+    QASM output can be saved to a file using the save method.
+    """
+
     valid_id_re = re.compile(r'[a-z][a-zA-Z0-9_]*\Z')
 
     def __init__(

diff --git a/cirq/devices/__init__.py b/cirq/devices/__init__.py
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Types for devices, device-specific qubits, and noise models."""
 from cirq.devices.device import (
     Device,
 )

diff --git a/cirq/experiments/__init__.py b/cirq/experiments/__init__.py
@@ -1,3 +1,18 @@
+# Copyright 2020 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Package containing characterization tools and experiments."""
+
 from cirq.experiments.google_v2_supremacy_circuit import (
     generate_boixo_2018_supremacy_circuits_v2,
     generate_boixo_2018_supremacy_circuits_v2_bristlecone,

diff --git a/cirq/google/__init__.py b/cirq/google/__init__.py
@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Classes for working with Google's Quantum Engine API."""
+
 from cirq.google import api
 
 from cirq.google.arg_func_langs import (

diff --git a/cirq/neutral_atoms/__init__.py b/cirq/neutral_atoms/__init__.py
@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Device classes and tools specific to a neutral atom quantum processor."""
+
 from cirq.neutral_atoms.neutral_atom_devices import (
     NeutralAtomDevice,
 )

diff --git a/cirq/ops/common_gates.py b/cirq/ops/common_gates.py
@@ -1359,8 +1359,10 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
     The `exponent=1` instance of `cirq.HPowGate`.
 
     Matrix:
+    ```
         [[s, s],
          [s, -s]]
+    ```
         where s = sqrt(0.5).
     """,
 )
@@ -1373,8 +1375,10 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
     The `exponent=0.5` instance of `cirq.ZPowGate`.
 
     Matrix:
+    ```
         [[1, 0],
          [0, i]]
+    ```
     """,
 )
 
@@ -1386,8 +1390,10 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
     The `exponent=0.25` instance of `cirq.ZPowGate`.
 
     Matrix:
+    ```
         [[1, 0]
          [0, exp(i pi / 4)]]
+    ```
     """,
 )
 
@@ -1399,11 +1405,12 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
     The `exponent=1` instance of `cirq.CZPowGate`.
 
     Matrix:
-
+    ```
         [[1 . . .],
          [. 1 . .],
          [. . 1 .],
          [. . . -1]]
+    ```
     """,
 )
 
@@ -1416,10 +1423,11 @@ def cphase(rads: value.TParamVal) -> CZPowGate:
     The `exponent=1` instance of `cirq.CXPowGate`.
 
     Matrix:
-
+    ```
         [[1 . . .],
          [. 1 . .],
          [. . . 1],
          [. . 1 .]]
+    ```
     """,
 )
diff --git a/cirq/ops/identity.py b/cirq/ops/identity.py
@@ -177,9 +177,10 @@ def _from_json_dict_(cls, num_qubits, qid_shape=None, **kwargs):
     """The one qubit identity gate.
 
     Matrix:
-
+    ```
         [[1, 0],
          [0, 1]]
+    ```
     """,
 )
 

diff --git a/cirq/ops/moment.py b/cirq/ops/moment.py
@@ -58,9 +58,10 @@ class Moment:
     in a moment should be completed before beginning the next moment.
 
     Moment can be indexed by qubit or list of qubits:
-        moment[qubit] returns the Operation in the moment which touches the
+
+    *   `moment[qubit]` returns the Operation in the moment which touches the
             given qubit, or throws KeyError if there is no such operation.
-        moment[qubits] returns another Moment which consists only of those
+    *   `moment[qubits]` returns another Moment which consists only of those
             operations which touch at least one of the given qubits. If there
             are no such operations, returns an empty Moment.
     """

diff --git a/cirq/ops/raw_types.py b/cirq/ops/raw_types.py
@@ -510,9 +510,11 @@ def validate_args(self, qubits: Sequence['cirq.Qid']):
 
 @value.value_equality
 class TaggedOperation(Operation):
-    """A specific operation instance that has been identified with a set
-    of Tags for special processing.  This can be initialized with
-    Using Operation.with_tags(tag) or by TaggedOperation(op, tag).
+    """Operation annotated with a set of Tags.
+
+    These Tags can be used for special processing.  TaggedOperations
+    can be initialized with using Operation.with_tags(tag)
+    or by using TaggedOperation(op, tag).
 
     Tags added can be of any type, but they should be Hashable in order
     to allow equality checking.  If you wish to serialize operations into

diff --git a/cirq/ops/swap_gates.py b/cirq/ops/swap_gates.py
@@ -285,10 +285,12 @@ def riswap(rads: value.TParamVal) -> ISwapPowGate:
 
     Matrix:
 
+    ```
         [[1, 0, 0, 0],
          [0, 0, 1, 0],
          [0, 1, 0, 0],
          [0, 0, 0, 1]]
+    ```
     """,
 )
 
@@ -298,10 +300,11 @@ def riswap(rads: value.TParamVal) -> ISwapPowGate:
     """The iswap gate.
 
     Matrix:
-
+    ```
         [[1, 0, 0, 0],
          [0, 0, i, 0],
          [0, i, 0, 0],
          [0, 0, 0, 1]]
+    ```
     """,
 )
diff --git a/cirq/pasqal/__init__.py b/cirq/pasqal/__init__.py
@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""Devices, qubits, and sampler for Pasqal's neutrali atom device."""
 from cirq.pasqal.pasqal_qubits import (
     ThreeDQubit,
     TwoDQubit,

diff --git a/cirq/protocols/__init__.py b/cirq/protocols/__init__.py
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Methods and classes that define cirq's protocols."""
 
 from cirq.protocols.act_on_protocol import (
     act_on,

diff --git a/cirq/qis/__init__.py b/cirq/qis/__init__.py
@@ -1,3 +1,19 @@
+# Copyright 2020 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tools and methods for quantum information science."""
+
 from cirq.qis.measures import (
     fidelity,
     von_neumann_entropy,