Improve ansatz generation API docs

docs/index.rst

@@ -43,4 +43,5 @@ Contents
    Explanatory Material <explanation/index>
    API Reference <apidocs/index>
    How-To Guides <how-tos/index>
+   GitHub <https://github.com/Qiskit/qiskit-addon-aqc-tensor>
    Release Notes <release-notes>

qiskit_addon_aqc_tensor/ansatz_generation.py

@@ -121,20 +121,73 @@ def generate_ansatz_from_circuit(
     qubits_initially_zero: bool = False,
     parameter_name: str = "theta",
 ) -> tuple[QuantumCircuit, list[float]]:
-    """Generate an ansatz from the two-qubit connectivity structure of a circuit.
+    r"""Generate an ansatz from the two-qubit connectivity structure of a circuit.
 
-    See explanatatory material for motivation.
+    See the `explanatatory material
+    <https://qiskit.github.io/qiskit-addon-aqc-tensor/explanation/index.html#ansatz-generation-motivation>`__
+    for motivation.
 
     Args:
         qc: A circuit, which is assumed to be unitary.  Barriers are ignored.
         qubits_initially_zero: If ``True``, the first Z rotation on each qubit
-            is removed from the ansatz under the assumption that it has no effect.
+            is fixed to zero because such a rotation has no effect on the state
+            :math:`|0\rangle`.
         parameter_name: Name for the :class:`~qiskit.circuit.ParameterVector`
             representing the free parameters in the returned ansatz circuit.
 
     Returns:
         ``(ansatz, parameter_values)`` such that ``ansatz.assign_parameters(parameter_values)``
         is equivalent to ``qc`` up to a global phase.
+
+    Example:
+    ========
+
+    Consider the following circuit as an example:
+
+    .. plot::
+       :alt: Circuit diagram output by the previous code.
+       :include-source:
+       :context: reset
+
+       from qiskit import QuantumCircuit
+
+       qc = QuantumCircuit(6)
+       qc.rx(0.4, 0)
+       qc.ryy(0.2, 2, 3)
+       qc.h(2)
+       qc.rz(0.1, 2)
+       qc.rxx(0.3, 0, 1)
+       qc.rzz(0.3, 0, 1)
+       qc.cx(2, 1)
+       qc.s(1)
+       qc.h(4)
+       qc.draw("mpl")
+
+    If the above circuit is passed to :func:`.generate_ansatz_from_circuit`, it will return an ansatz with parametrized two-qubit KAK rotations in the same locations as the input:
+
+    .. plot::
+       :alt: Circuit diagram output by the previous code.
+       :include-source:
+       :context: close-figs
+
+       from qiskit_addon_aqc_tensor import generate_ansatz_from_circuit
+
+       ansatz, initial_params = generate_ansatz_from_circuit(
+           qc, qubits_initially_zero=True, parameter_name="x"
+       )
+       ansatz.draw("mpl")
+
+    Note that in the generated ansatz, all consecutive single-qubit gates are collapsed into the same ZXZ block, and all consecutive two-qubit gates are collapsed into a single KAK block, up to single-qubit rotations.
+
+    Further, the :func:`.generate_ansatz_from_circuit` function provides parameters which, when bound to the ansatz, will result in a circuit equivalent to the original one, up to a global phase:
+
+    .. plot::
+       :alt: Circuit diagram output by the previous code.
+       :include-source:
+       :context: close-figs
+
+       ansatz.assign_parameters(initial_params).draw("mpl")
+
     """
     # FIXME: handle classical bits, measurements, resets, and barriers.  maybe
     # conditions too?

qiskit_addon_aqc_tensor/simulation/abstract.py

@@ -20,6 +20,12 @@
 from plum import dispatch
 from qiskit.circuit import Gate, QuantumCircuit
 
+# NOTE: This file contains abstract classes and functions.  The functions in
+# this file are implemented differently for each tensor-network backend, and
+# the backend method is chosen dynamically based on the type(s) passed to the
+# function.  Dispatch is powered by plum-dispatch, a multiple dispatch library
+# for Python.
+
 
 class TensorNetworkState:
     """Abstract tensor network state."""