Fix broken docstrings in bindings and minor API docs updates (#920)

* fix RenameQubitsPass docs * try to fix ZZPhaseToRz, RoutingPass and CustomRoutingPass * try to fix RoundAngles * finally fix ZZPhaseToRz * fix spacing * fix RingArch and to_dict * fix QubitPauliString * fix spacing * fix spacing in ZZPhaseToRz * use sphinx-autodoc-typehints * fix broken getting_started links * fix mistake in ZZPhaseToRz docstring * use sphinx_autodoc_annotation again * update ZZPhaseToRz docstring * fix conf.py * fix duplicate link warning * update pytket.qasm docs * minor wording * remove extra lines from pytket.qasm docs * more pytket.qasm edits * use half-turns instead of radians * fix Bit.to_list() docstring * fix minor formatting issues in pytket.placement and pytket.zx
CQCL · Jul 24, 2023 · 67b323d · 67b323d
1 parent 1b25d79
commit 67b323d
Show file tree

Hide file tree

Showing 9 changed files with 50 additions and 34 deletions.
diff --git a/pytket/binders/architecture.cpp b/pytket/binders/architecture.cpp
@@ -79,8 +79,8 @@ PYBIND11_MODULE(architecture, m) {
       .def(
           "to_dict", [](const Architecture &arch) { return json(arch); },
           "Return a JSON serializable dict representation of "
-          "the Architecture.\n"
-          ":return: dict containing nodes and links.")
+          "the Architecture."
+          "\n\n:return: dict containing nodes and links.")
       .def_static(
           "from_dict", [](const json &j) { return j.get<Architecture>(); },
           "Construct Architecture instance from JSON serializable "
@@ -160,8 +160,8 @@ PYBIND11_MODULE(architecture, m) {
       .def(
           py::init<const unsigned, const std::string>(),
           "The constructor for a RingArchitecture with some undirected "
-          "connectivity between qubits.\n\n:param number of qubits\n:param "
-          "label: Name for Node in RingArch Architecture",
+          "connectivity between qubits.\n\n:param number of qubits:"
+          "\n:param label: Name for Node in RingArch Architecture",
           py::arg("nodes"), py::arg("label") = "ringNode")
       .def(
           "__deepcopy__",
@@ -177,7 +177,8 @@ PYBIND11_MODULE(architecture, m) {
       .def(
           py::init<unsigned, const std::string>(),
           "Construct a fully-connected architecture."
-          "\n\n:param n: number of qubits\n:param label: Name for Node in "
+          "\n\n:param n: number of qubits"
+          "\n:param label: Name for Node in "
           "FullyConnected Architecture",
           py::arg("n"), py::arg("label") = "fcNode")
       .def(
@@ -196,7 +197,8 @@ PYBIND11_MODULE(architecture, m) {
       .def(
           "to_dict", [](const FullyConnected &arch) { return json(arch); },
           "JSON-serializable dict representation of the architecture."
-          "\n\n:return: dict containing nodes")
+          "\n\n"
+          ":return: dict containing nodes")
       .def_static(
           "from_dict", [](const json &j) { return j.get<FullyConnected>(); },
           "Construct FullyConnected instance from dict representation.");

diff --git a/pytket/binders/circuit/unitid.cpp b/pytket/binders/circuit/unitid.cpp
@@ -188,8 +188,8 @@ void init_unitid(py::module &m) {
       .def(
           "to_list", [](const Bit &b) { return json(b); },
           "Return a JSON serializable list representation of "
-          "the Bit.\n"
-          ":return: list containing register name and index")
+          "the Bit."
+          "\n\n:return: list containing register name and index")
       .def_static(
           "from_list", [](const json &j) { return j.get<Bit>(); },
           "Construct Bit instance from JSON serializable "

diff --git a/pytket/binders/passes.cpp b/pytket/binders/passes.cpp
@@ -465,7 +465,7 @@ PYBIND11_MODULE(passes, m) {
       "Removes gate-inverse pairs, merges rotations, removes identity "
       "rotations, and removes redundant gates before measurement. Does not "
       "add any new gate types.\n\n"
-      "When merging rotations with the same op group name, the merged"
+      "When merging rotations with the same op group name, the merged "
       "operation keeps the same name.");
   m.def(
       "SynthesiseHQS", &SynthesiseHQS,
@@ -611,8 +611,9 @@ PYBIND11_MODULE(passes, m) {
   m.def(
       "CustomRoutingPass", &gen_routing_pass,
       "Construct a pass to route to the connectivity graph of an "
-      ":py:class:`Architecture`. Edge direction is ignored."
-      "\n:return: a pass that routes to the given device architecture",
+      ":py:class:`Architecture`. Edge direction is ignored. "
+      "\n\n"
+      ":return: a pass that routes to the given device architecture ",
       py::arg("arc"), py::arg("config"));
 
   m.def(
@@ -621,7 +622,8 @@ PYBIND11_MODULE(passes, m) {
       ":py:class:`Architecture`. Edge direction is ignored. "
       "Uses :py:class:`LexiLabellingMethod` and "
       ":py:class:`LexiRouteRoutingMethod`."
-      "\n:return: a pass that routes to the given device architecture",
+      "\n\n"
+      ":return: a pass that routes to the given device architecture",
       py::arg("arc"));
 
   m.def(
@@ -647,8 +649,10 @@ PYBIND11_MODULE(passes, m) {
       py::arg("label") = q_default_reg());
 
   m.def(
-      "RenameQubitsPass", &gen_rename_qubits_pass, "Rename some or all qubits.",
-      "\n\n:param qubit_map: map from old to new qubit names",
+      "RenameQubitsPass", &gen_rename_qubits_pass,
+      "Rename some or all qubits. "
+      "\n\n"
+      ":param qubit_map: map from old to new qubit names ",
       py::arg("qubit_map"));
 
   m.def(
@@ -855,8 +859,12 @@ PYBIND11_MODULE(passes, m) {
 
   m.def(
       "ZZPhaseToRz", &ZZPhaseToRz,
-      "Converts ZZPhase gates with angle pi or -pi to two Rz gates with"
-      "angle pi.\n:return: a pass to convert ZZPhase gates to Rz");
+      "Converts all ZZPhase gates in a circuit with angle 1 or -1 (half-turns) "
+      "into two Rz gates each with a parameter value of 1 (half-turns). "
+      "ZZPhase gates with parameter values other than 1 or -1 "
+      "(half-turns) are left "
+      "unchanged.\n\n"
+      ":return: a pass to convert ZZPhase gates to Rz.");
 
   m.def(
       "CnXPairwiseDecomposition", &CnXPairwiseDecomposition,
@@ -866,9 +874,9 @@ PYBIND11_MODULE(passes, m) {
 
   m.def(
       "RoundAngles", &RoundAngles,
-      "Round angles to the nearest :math:`\\pi / 2^n`."
-      "\n\n:param n: precision parameter, must be >= 0 and < 32",
-      "\n\n:param only_zeros: if True, only round angles less than "
+      "Round angles to the nearest :math:`\\pi / 2^n`. "
+      "\n\n:param n: precision parameter, must be >= 0 and < 32 "
+      "\n:param only_zeros: if True, only round angles less than "
       ":math:`\\pi / 2^{n+1}` to zero, leave other angles alone (default "
       "False)",
       py::arg("n"), py::arg("only_zeros") = false);
@@ -889,6 +897,7 @@ PYBIND11_MODULE(passes, m) {
       "\n\n"
       ":param transform: function taking a :py:class:`Circuit` as an argument "
       "and returning a new transformed circuit"
+      "\n"
       ":param label: optional label for the pass"
       "\n:return: a pass to perform the transformation",
       py::arg("transform"), py::arg("label") = "");

diff --git a/pytket/binders/pauli.cpp b/pytket/binders/pauli.cpp
@@ -36,7 +36,7 @@ PYBIND11_MODULE(pauli, m) {
 
   py::class_<QubitPauliString>(
       m, "QubitPauliString",
-      "A string of Pauli letters from the alphabet {I, X, Y, Z},"
+      "A string of Pauli letters from the alphabet {I, X, Y, Z}, "
       "implemented as a sparse list, indexed by qubit.")
       .def(py::init<>(), "Constructs an empty QubitPauliString.")
       .def(
@@ -70,8 +70,8 @@ PYBIND11_MODULE(pauli, m) {
             json j = qps;
             return j;
           },
-          "A JSON-serializable representation of the QubitPauliString. "
-          "\n:return: a list of :py:class:`Qubit`-to-:py:class:`Pauli` "
+          "A JSON-serializable representation of the QubitPauliString.\n\n"
+          ":return: a list of :py:class:`Qubit`-to-:py:class:`Pauli` "
           "entries, "
           "represented as dicts.")
       .def_static(

diff --git a/pytket/binders/placement.cpp b/pytket/binders/placement.cpp
@@ -100,8 +100,8 @@ PYBIND11_MODULE(placement, m) {
             .def(
                 "to_dict", [](const Placement::Ptr &placement) { return json(placement); },
                 "Return a JSON serializable dict representation of "
-                "the Placement.\n"
-                ":return: dict representing the Placement.")
+                "the Placement."
+                "\n\n:return: dict representing the Placement.")
             .def_static(
                 "from_dict", [](const json &j) { return j.get<Placement::Ptr>(); },
                 "Construct Placement instance from JSON serializable "

diff --git a/pytket/binders/zx/diagram.cpp b/pytket/binders/zx/diagram.cpp
@@ -139,7 +139,7 @@ void ZXDiagramPybind::init_zxdiagram(py::module& m) {
           ":param type: :py:class:`ZXType` to filter by, from "
           "{:py:meth:`ZXType.Input`, :py:meth:`ZXType.Output`, "
           ":py:meth:`ZXType.Open`, None}. Defaults to None."
-          ":param qtype: :py:class:`QuantumType` to filter by, from "
+          "\n\n:param qtype: :py:class:`QuantumType` to filter by, from "
           "{:py:meth:`QuantumType.Quantum`, :py:meth:`QuantumType.Classical`, "
           "None}. Defaults to None.",
           py::arg("type") = std::nullopt, py::arg("qtype") = std::nullopt)

diff --git a/pytket/docs/display.rst b/pytket/docs/display.rst
@@ -21,7 +21,7 @@ Example usage:
     from pytket.circuit.display import get_circuit_renderer
 
     circuit_renderer = get_circuit_renderer() # Instantiate a circuit renderer
-    circuit_renderer.set_render_options(zx_style=False) # Configure render options
+    circuit_renderer.set_render_options(zx_style=True) # Configure render options
     circuit_renderer.condense_c_bits = False # You can also set the properties on the instance directly
     print("Render options:")
     print(circuit_renderer.get_render_options()) # View currently set render options

diff --git a/pytket/docs/getting_started.rst b/pytket/docs/getting_started.rst
@@ -93,7 +93,7 @@ This prints out a summary of readouts (the final values of the classical bits) a
 
 Each pytket :py:class:`Backend` comes with its own default compilation method. This is a recommended sequence of optimisation passes to meet the requirements of the specific :py:class:`Backend`. 
 
-The following code snippet will show how to compile a circuit to run on an IBM device. This requires setting up IBM credentials (see `this page <https://cqcl.github.io/pytket-qiskit/api/index.html#access-and-credentials>`).
+The following code snippet will show how to compile a circuit to run on an IBM device. This requires setting up IBM credentials (see the `credentials guide <https://cqcl.github.io/pytket-qiskit/api/index.html#access-and-credentials>`_).
 
 ::
 
@@ -106,7 +106,7 @@ The following code snippet will show how to compile a circuit to run on an IBM d
     compiled_circ = belem_device.get_compiled_circuit(circ)
     result = backend.run_circuit(compiled_circ, n_shots=100)
 
-Here the default compilation pass is applied by :py:meth:`IBMQBackend.get_compiled_circuit`. See `this page <https://cqcl.github.io/pytket-qiskit/api/index.html>`_ for more details.
+Here the default compilation pass is applied by :py:meth:`IBMQBackend.get_compiled_circuit`. See `this page <https://cqcl.github.io/pytket-qiskit/api/index.html#default-compilation>`_ for more details.
 
 As an alternative, We can experiment with constructing our own circuit compilation routines in pytket. Passes from the :py:mod:`pytket.passes` module can be applied individually or composed in sequence. 
 See the section of the user manual on `circuit compilation <https://cqcl.github.io/pytket/manual/manual_compiler.html>`_ and the corresponding `notebook example <https://github.com/CQCL/pytket/blob/main/examples/compilation_example.ipynb>`_ for more.
diff --git a/pytket/docs/qasm.rst b/pytket/docs/qasm.rst
@@ -1,17 +1,22 @@
 pytket.qasm
 ==================================
 :py:class:`Circuit` objects can be converted to and from OpenQASM, although we do not support all operations.
-In particular, we do not currently support:
 
-1) Importing from libraries other than "qelib1"
-2) Ability to interpret gates acting on a whole register in the OpenQASM style
+However, we do support symbolic parameters of gates, both on import and export.
 
-Any pytket :py:class:`Circuit` that is exported to this format should be valid for importing again as a :py:class:`Circuit`, making this a convenient file format
+Any pytket :py:class:`Circuit` that is exported to OpenQASM format with ``pytket.qasm`` should be valid for importing again as a :py:class:`Circuit`, making this a convenient file format
 to save your :py:class:`Circuit` objects.
 
-However, we do support symbolic parameters of gates, both on import and export.
+In addition to the default ``qelib1`` qasm header, the ``hqslib1`` header is also supported.
+We can set the ``header`` argument in the qasm conversion functions as follows.
+
+::
+    
+    from pytket.qasm import circuit_to_qasm_str
+
+    qasm_str = circuit_to_qasm_str(circ, header="hqslib1")
 
-.. note:: Unlke pytket backends the qasm converters do not handle `implicit qubit permutations <https://cqcl.github.io/pytket/manual/manual_circuit.html#implicit-qubit-permutations>`_ . In other words if a circuit containing an implicit qubit permutation is converted to a qasm file the implicit permutation will not be accounted for and the circuit will be missing this permutation when reimported.
+.. note:: Unlike pytket backends, the qasm converters do not handle `implicit qubit permutations <https://cqcl.github.io/pytket/manual/manual_circuit.html#implicit-qubit-permutations>`_. In other words if a circuit containing an implicit qubit permutation is converted to a qasm file the implicit permutation will not be accounted for and the circuit will be missing this permutation when reimported.
 
 .. automodule:: pytket.qasm
     :members: circuit_from_qasm, circuit_from_qasm_wasm, circuit_to_qasm, circuit_from_qasm_str, circuit_to_qasm_str, circuit_from_qasm_io, circuit_to_qasm_io