add some docstring

Author: refraction-ray

examples/H6_hamiltonian.npy examples/h6_hamiltonian.npy

@@ -11,7 +11,7 @@
 tc.set_backend("tensorflow")
 tc.set_dtype("complex128")
 
-h6h = np.load("./H6_hamiltonian.npy")  # reported in 0.99 A
+h6h = np.load("./h6_hamiltonian.npy")  # reported in 0.99 A
 hamiltonian = construct_matrix_v3(h6h.tolist())
 
 

examples/vqnhe_h6.py

@@ -912,6 +912,7 @@ def unitary_kraus(
     ) -> Tensor:
         """
         Apply unitary gates in ``kraus`` randomly based on corresponding ``prob``.
+        If ``prob`` is ``None``, this is reduced to kraus channel language.
 
         :param kraus: List of ``tc.gates.Gate`` or just Tensors
         :type kraus: Sequence[Gate]
@@ -1547,6 +1548,14 @@ def _expectation_ps(
     Shortcut for Pauli string expectation.
     x, y, z list are for X, Y, Z positions
 
+    :Example:
+
+    >>> c = tc.Circuit(2)
+    >>> c.X(0)
+    >>> c.H(1)
+    >>> c.expectation_ps(x=[1], z=[0])
+    array(-0.99999994+0.j, dtype=complex64)
+
     :param x: _description_, defaults to None
     :type x: Optional[Sequence[int]], optional
     :param y: _description_, defaults to None

tensorcircuit/circuit.py

@@ -27,6 +27,18 @@ def __init__(
         inputs: Optional[Tensor] = None,
         dminputs: Optional[Tensor] = None,
     ) -> None:
+        """
+        The density matrix simulator based on tensornetwork engine.
+
+        :param nqubits: Number of qubits
+        :type nqubits: int
+        :param empty: if True, nothing initialized, only for internal use, defaults to False
+        :type empty: bool, optional
+        :param inputs: the state input for the circuit, defaults to None
+        :type inputs: Optional[Tensor], optional
+        :param dminputs: the density matrix input for the circuit, defaults to None
+        :type dminputs: Optional[Tensor], optional
+        """
         if not empty:
             _prefix = "qb-"
             if (inputs is None) and (dminputs is None):
@@ -239,7 +251,17 @@ def apply(self: "DMCircuit", *index: int, **vars: float) -> None:
 
         return apply
 
-    def densitymatrix(self, check: bool = False, reuse: bool = True) -> tn.Node.tensor:
+    def densitymatrix(self, check: bool = False, reuse: bool = True) -> Tensor:
+        """
+        Return the output density matrix of the circuit.
+
+        :param check: check whether the final return is a legal density matrix, defaults to False
+        :type check: bool, optional
+        :param reuse: whether to reuse previous results, defaults to True
+        :type reuse: bool, optional
+        :return: The output densitymatrix in 2D shape tensor form
+        :rtype: Tensor
+        """
         nodes, _ = self._copy_dm_tensor(conj=False, reuse=reuse)
         # t = contractor(nodes, output_edge_order=d_edges)
         dm = backend.reshape(
@@ -254,6 +276,15 @@ def densitymatrix(self, check: bool = False, reuse: bool = True) -> tn.Node.tens
     def expectation(
         self, *ops: Tuple[tn.Node, List[int]], **kws: Any
     ) -> tn.Node.tensor:
+        """
+        Compute the expectation of corresponding operators.
+
+        :param ops: Operator and its position on the circuit,
+            eg. ``(tc.gates.z(), [1, ]), (tc.gates.x(), [2, ])`` is for operator :math:`Z_1X_2`.
+        :type ops: Tuple[tn.Node, List[int]]
+        :return: Tensor with one element
+        :rtype: Tensor
+        """
         # kws is reserved for unsupported feature such as reuse arg
         newdm, newdang = self._copy(self._nodes, self._rfront + self._lfront)
         occupied = set()

tensorcircuit/densitymatrix.py

@@ -1119,6 +1119,18 @@ def PauliStringSum2Dense(
         weight: Optional[Sequence[float]] = None,
         numpy: bool = False,
     ) -> Tensor:
+        """
+        Generate tensorflow dense matrix from Pauli string sum
+
+        :param ls: 2D Tensor, each row is for a Pauli string,
+            e.g. [1, 0, 0, 3, 2] is for :math:`X_0Z_3Y_4`
+        :type ls: Sequence[Sequence[int]]
+        :param weight: 1D Tensor, each element corresponds the weight for each Pauli string
+            defaults to None (all Pauli strings weight 1.0)
+        :type weight: Optional[Sequence[float]], optional
+        :return: the tensorflow dense matrix
+        :rtype: Tensor
+        """
         sparsem = PauliStringSum2COO_numpy(ls, weight)
         if numpy:
             return sparsem.todense()
@@ -1143,6 +1155,18 @@ def _numpy2tf_sparse(a: Tensor) -> Tensor:
     def PauliStringSum2COO_numpy(
         ls: Sequence[Sequence[int]], weight: Optional[Sequence[float]] = None
     ) -> Tensor:
+        """
+        Generate scipy sparse matrix from Pauli string sum
+
+        :param ls: 2D Tensor, each row is for a Pauli string,
+            e.g. [1, 0, 0, 3, 2] is for :math:`X_0Z_3Y_4`
+        :type ls: Sequence[Sequence[int]]
+        :param weight: 1D Tensor, each element corresponds the weight for each Pauli string
+            defaults to None (all Pauli strings weight 1.0)
+        :type weight: Optional[Sequence[float]], optional
+        :return: the scipy coo sparse matrix
+        :rtype: Tensor
+        """
         # numpy version is 3* faster!
 
         nterms = len(ls)
@@ -1165,6 +1189,18 @@ def PauliStringSum2COO_numpy(
     def PauliStringSum2COO(
         ls: Sequence[Sequence[int]], weight: Optional[Sequence[float]] = None
     ) -> Tensor:
+        """
+        Generate tensorflow sparse matrix from Pauli string sum
+
+        :param ls: 2D Tensor, each row is for a Pauli string,
+            e.g. [1, 0, 0, 3, 2] is for :math:`X_0Z_3Y_4`
+        :type ls: Sequence[Sequence[int]]
+        :param weight: 1D Tensor, each element corresponds the weight for each Pauli string
+            defaults to None (all Pauli strings weight 1.0)
+        :type weight: Optional[Sequence[float]], optional
+        :return: the tensorflow coo sparse matrix
+        :rtype: Tensor
+        """
         nterms = len(ls)
         n = len(ls[0])
         s = 0b1 << n
@@ -1184,6 +1220,18 @@ def PauliStringSum2COO(
 
     @compiled_jit
     def PauliString2COO(l: Sequence[int], weight: Optional[float] = None) -> Tensor:
+        """
+        Generate tensorflow sparse matrix from Pauli string sum
+
+        :param l: 1D Tensor representing for a Pauli string,
+            e.g. [1, 0, 0, 3, 2] is for :math:`X_0Z_3Y_4`
+        :type l: Sequence[int]
+        :param weight: the weight for the Pauli string
+            defaults to None (all Pauli strings weight 1.0)
+        :type weight: Optional[float], optional
+        :return: the tensorflow sparse matrix
+        :rtype: Tensor
+        """
         n = len(l)
         one = tf.constant(0b1, dtype=tf.int64)
         idx_x = tf.constant(0b0, dtype=tf.int64)

tensorcircuit/quantum.py

@@ -20,6 +20,16 @@
 
 
 def state_centric(f: Callable[..., Circuit]) -> Callable[..., Tensor]:
+    """
+    Function decorator wraps the function with the first input and output in the format of circuit,
+    the wrapped function has the first input and the output as the state tensor.
+
+    :param f: Function with the fist input and the output as ``Circuit`` object.
+    :type f: Callable[..., Circuit]
+    :return: Wrapped function with the first input and the output as the state tensor correspondingly.
+    :rtype: Callable[..., Tensor]
+    """
+
     @wraps(f)
     def wrapper(s: Tensor, *args: Any, **kws: Any) -> Tensor:
         n = backend.sizen(s)
@@ -97,6 +107,23 @@ def QAOA_block(
 def example_block(
     c: Circuit, param: Tensor, nlayers: int = 2, is_split: bool = False
 ) -> Circuit:
+    r"""
+    The circuit ansatz is firstly one layer of Hadamard gates and
+    then we have ``nlayers`` blocks of :math:`e^{i\theta Z_iZ_{i+1}}` two-qubit gate in ladder layout,
+    following rx gate.
+
+    :param c: The circuit
+    :type c: Circuit
+    :param param: paramter tensor with 2*nlayer*n elements
+    :type param: Tensor
+    :param nlayers: number of ZZ+RX blocks, defaults to 2
+    :type nlayers: int, optional
+    :param is_split: whether use SVD split to reduce ZZ gate bond dimension,
+        defaults to False
+    :type is_split: bool, optional
+    :return: The circuit with example ansatz attached
+    :rtype: Circuit
+    """
     # used for test and demonstrations
     if is_split:
         split_conf = {

tensorcircuit/templates/blocks.py

@@ -16,6 +16,7 @@ def amplitude_encoding(
     fig: Tensor, nqubits: int, index: Optional[Sequence[int]] = None
 ) -> Tensor:
     # non-batch version
+    # [WIP]
     fig = backend.reshape(fig, shape=[-1])
     norm = backend.norm(fig)
     fig = fig / norm

tensorcircuit/templates/dataset.py

@@ -59,7 +59,18 @@ def Even1D(n: int, s: int = 0) -> Graph:
 
 
 class Grid2DCoord:
+    """
+    Two-dimensional grid lattice
+    """
+
     def __init__(self, n: int, m: int):
+        """
+
+        :param n: number of rows
+        :type n: int
+        :param m: number of cols
+        :type m: int
+        """
         # row first
         self.m = m
         self.n = n
@@ -74,6 +85,15 @@ def two2one(self, x: int, y: int) -> int:
         return x * self.n + y
 
     def all_rows(self, pbc: bool = False) -> Sequence[Tuple[int, int]]:
+        """
+        return all row edge with 1d index encoding
+
+        :param pbc: whether to include pbc edges (periodic boundary condition),
+            defaults to False
+        :type pbc: bool, optional
+        :return: list of row edge
+        :rtype: Sequence[Tuple[int, int]]
+        """
         r = []
         for i in range(self.mn):
             if (i + 1) % self.n != 0:
@@ -83,6 +103,15 @@ def all_rows(self, pbc: bool = False) -> Sequence[Tuple[int, int]]:
         return r
 
     def all_cols(self, pbc: bool = False) -> Sequence[Tuple[int, int]]:
+        """
+        return all col edge with 1d index encoding
+
+        :param pbc: whether to include pbc edges (periodic boundary condition),
+            defaults to False
+        :type pbc: bool, optional
+        :return: list of col edge
+        :rtype: Sequence[Tuple[int, int]]
+        """
         r = []
         for i in range(self.mn):
             if i + self.n < self.mn:
@@ -92,6 +121,15 @@ def all_cols(self, pbc: bool = False) -> Sequence[Tuple[int, int]]:
         return r
 
     def lattice_graph(self, pbc: bool = True) -> Graph:
+        """
+        Get the 2D grid lattice in ``nx.Graph`` format
+
+        :param pbc: whether to include pbc edges (periodic boundary condition),
+            defaults to True
+        :type pbc: bool, optional
+        :return: _description_
+        :rtype: Graph
+        """
         g = nx.Graph()
         for i in range(self.mn):
             g.add_node(i, weight=0)