Standardize Docstrings and Enable Doctest Validation

- Refactor docstrings across the tnco package for consistency, improving
  clarity and technical accuracy according to the project's
  documentation standards.
- Add Examples sections to utility functions in `tnco.utils` and
  `tnco.app` to demonstrate usage and provide executable documentation.
- Update `.github/workflows/run_tests.yml` to automatically run doctests
  during the CI process, ensuring examples remain correct as the
  codebase evolves.
- Standardize the use of double backticks for variable names and
  technical terms throughout the documentation.
- Perform minor cleanup of imports and type hints in tnco and tests
  modules for better maintainability.

Author: s-mandra

.github/workflows/run_tests.yml

@@ -69,6 +69,13 @@ jobs:
         fi
         pip install .[parallel,testing] --config-settings=cmake.build-type=${{ matrix.target }} --verbose
 
+    - name: Run Doctests for ${{ matrix.os }}, with ${{ matrix.compiler }} and python==${{
+        matrix.python-version }} (${{ matrix.target }})
+      run: |
+        for f in $(grep -l ">>>" $(find tnco -name "*.py")); do
+          python3 -m doctest $f || exit 1
+        done
+
     - name: Run Tests for ${{ matrix.os }}, with ${{ matrix.compiler }} and python==${{
         matrix.python-version }} (${{ matrix.target }})
       if: matrix.os == 'ubuntu-latest' && matrix.compiler == 'g++' && matrix.python-version

tests/test_contraction.py

@@ -20,6 +20,7 @@
 
 import more_itertools as mit
 import pytest
+
 from tnco.ctree import ContractionTree
 from tnco.optimize.finite_width import Optimizer as FW_Optimizer
 from tnco.optimize.finite_width.cost_model import \

tests/test_core.py

@@ -23,6 +23,13 @@
 
 import more_itertools as mit
 import pytest
+from tnco_core import Bitset as Bitset_
+from tnco_core import ContractionTree as ContractionTree_
+from tnco_core import Node
+from tnco_core import Tree as Tree_
+from tnco_core import float1024
+from tnco_core.utils import all_close, all_logclose
+
 from tnco.bitset import Bitset
 from tnco.ctree import ContractionTree, traverse_tree
 from tnco.optimize.finite_width.cost_model import \
@@ -32,12 +39,6 @@
 from tnco.optimize.prob import BaseProbability, Greedy, MetropolisHastings
 from tnco.testing.utils import generate_random_inds, generate_random_tensors
 from tnco.utils.tn import get_random_contraction_path
-from tnco_core import Bitset as Bitset_
-from tnco_core import ContractionTree as ContractionTree_
-from tnco_core import Node
-from tnco_core import Tree as Tree_
-from tnco_core import float1024
-from tnco_core.utils import all_close, all_logclose
 
 # Initialize RNG
 rng = Random(

tnco/__init__.py

@@ -11,6 +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.
+"""Tensor Network Contraction Optimizer (tnco)."""
 
 from importlib import metadata
 

tnco/app/__init__.py

@@ -11,6 +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.
+"""Application module for tnco."""
 
 from tnco.app.app import Optimizer, dump_results, load_tn
 from tnco.app.tn import Tensor, TensorNetwork

tnco/app/app.py

@@ -19,7 +19,7 @@
 from collections import defaultdict
 from dataclasses import dataclass
 from random import Random
-from typing import Dict, FrozenSet, Iterable, Optional, Tuple, Union
+from typing import Any, Dict, FrozenSet, Iterable, Optional, Tuple, Union
 
 import autoray as ar
 import more_itertools as mit
@@ -37,14 +37,14 @@
 def is_classical_operation(m: Matrix) -> bool:
     """Check if given matrix is a classical operation.
 
-    Check if given matrix is a classical operation. An operation is classical
-    if 'm @ v' only permutes the elements of 'v' (excluding a change of phase).
+    An operation is classical if ``m @ v`` only permutes the elements of ``v``
+    (excluding a change of phase).
 
     Args:
         m: Matrix to check.
 
     Returns:
-        True if 'm' is a classical operation.
+        ``True`` if ``m`` is a classical operation.
     """
     m = ar.do('asarray', m)
     if m.ndim != 2 or m.shape[0] != m.shape[1] and int(math.log2(
@@ -104,56 +104,54 @@ def sample(
     qubit_order: Optional[Iterable[Qubit]] = None,
     normalize: Optional[bool] = True,
     return_intermediate_state_only: Optional[bool] = False,
-    dtype: Optional[any] = None,
+    dtype: Optional[Any] = None,
     optimization_backend: Optional[str] = None,
     contraction_backend: Optional[str] = None,
     seed: Optional[int] = None,
     verbose: Optional[int] = False,
     **optimize_params
 ) -> Union[Tuple[Dict[str, int], Tuple[Qubit]], SamplingIntermediateState]:
-    """Sample bitstring from a circuit.
+    """Sample bitstrings from a circuit.
 
-    Sample bitstring from a circuit using the Bravyi-Gosset-Liu algorithm
+    Sample bitstrings from a circuit using the Bravyi-Gosset-Liu algorithm
     presented in "How to Simulate Quantum Measurement without Computing
     Marginals", Phys. Rev. Lett. 128, 220503 (2022).
 
     Args:
-        circuit: The circuit to sample from. If a 'SamplingIntermediateState'
-            is passed insted, the optimization phase of the circuit is skipped
+        circuit: The circuit to sample from. If a ``SamplingIntermediateState``
+            is passed instead, the optimization phase of the circuit is skipped
             and the intermediate state is used to sample.
-        optimizer: The 'Optimizer' to use for the tensor network optimization.
+        optimizer: The ``Optimizer`` to use for the tensor network optimization.
         n_samples: The number of total samples to collect.
-        simplify: If 'True', gates that cancel each other will be simplified.
-        use_matrix_commutation: If 'True', gates will be commuted by performing
-            the actual matrix commutation while simplifying the circuit.
-        decompose_hyper_inds: If 'True', decompose gates to get hyper-indices.
-        fuse: Fuse tensors together up a width smaller than 'fuse'.  The width
+        simplify: If ``True``, gates that cancel each other will be simplified.
+        use_matrix_commutation: If ``True``, gates will be commuted by
+            performing the actual matrix commutation while simplifying the
+            circuit.
+        decompose_hyper_inds: If ``True``, decompose gates to get hyper-indices.
+        fuse: Fuse tensors together up a width smaller than ``fuse``.  The width
             is defined as sum of the logarithms of all the dimensions of a
             given tensor.
         qubit_order: If provided, the order of qubits to use.
-        normalize: If True, the total number of hits are divided by the number
-            of samples.
-        load_params: The parameters to pass to 'tnco.utils.circuit.load' to
-            convert circuit to a tensor.
-        optimizer_params: The parameters to pass to 'tnco.app.Optimizer' to
-            initialize a new optimizer.
+        normalize: If ``True``, the total number of hits are divided by the
+            number of samples.
         optimize_params: The parameters to pass to
-            'tnco.app.Optimizer.optimize' to optimize each partial contraction.
-        return_intermediate_state_only: If True, skip the sampling and return
-            the 'SamplingIntermediateState'.
+            ``tnco.app.Optimizer.optimize`` to optimize each partial
+            contraction.
+        return_intermediate_state_only: If ``True``, skip the sampling and
+            return the ``SamplingIntermediateState``.
         dtype: The type to use for the contraction.
         optimization_backend: The backend to use to manipulate arrays while
-            loading and optimazing the tensor network.
+            loading and optimizing the tensor network.
         contraction_backend: The backend to use for the contraction.
         seed: The seed to use for the sampling.
         verbose: Verbose output.
 
     Returns:
-        If 'return_intermediate_state_only', a 'SamplingIntermediateState' is
-        return to be reused multiple times. Othewise, it return a dictionary
-        with the fraction of hits for each bitstring sampled, and the order of
-        qubits. If 'normalize=False', the the number of hits is returned
-        instead of its fraction.
+        If ``return_intermediate_state_only``, a ``SamplingIntermediateState``
+        is returned to be reused multiple times. Otherwise, it returns a
+        dictionary with the fraction of hits for each bitstring sampled, and
+        the order of qubits. If ``normalize=False``, the number of hits is
+        returned instead of its fraction.
     """
 
     # Short for asarray
@@ -416,42 +414,30 @@ def _(circuit: qiskit.QuantumCircuit, *args, **kwargs):
 
 @dataclass(frozen=True)
 class Sampler:
-    """Sample bitstrings from circuit.
+    """Sample bitstrings from a circuit.
 
-    Sample bitstring from a circuit using the Bravyi-Gosset-Liu algorithm
+    Sample bitstrings from a circuit using the Bravyi-Gosset-Liu algorithm
     presented in "How to Simulate Quantum Measurement without Computing
     Marginals", Phys. Rev. Lett. 128, 220503 (2022).
 
     Args:
         max_width: Maximum width to use. The width is defined as sum of the
-            logarithms of all the dimensions of a given tensor.  Tensors are
+            logarithms of all the dimensions of a given tensor. Tensors are
             contracted so that the width of the contracted tensor is smaller
-            than 'max_width'.
+            than ``max_width``.
         n_jobs: Number of processes to use. By default, all available cores are
-            used. If 'n_jobs' is a positive number, 'n_jobs' processes will be
-            used. If 'n_jobs' is negative, 'n_cpus + n_jobs + 1' will be used.
-            If 'n_jobs' is zero, it will raise a 'ValueError'. (See:
-            'tnco.parallel.Parallel')
+            used. If ``n_jobs`` is a positive number, ``n_jobs`` processes will
+            be used. If ``n_jobs`` is negative, ``n_cpus + n_jobs + 1`` will be
+            used. If ``n_jobs`` is zero, it will raise a ``ValueError``. (See:
+            ``tnco.parallel.Parallel``)
         width_type: The type to use to represent the width. (See:
-            'tnco.optimize.finite_width.cost_model.SimpleCostModel')
+            ``tnco.optimize.finite_width.cost_model.SimpleCostModel``)
         cost_type: The type to use to represent the cost. (See:
-            'tnco.optimize.finite_width.cost_model.SimpleCostModel')
-        output_format: Format to use for the output. See Notes for more
-            details.
-        output_filename: If provided, dump the output to 'output_filename'. If
-            'output_filfename' has a '.gzip' or '.bz2' extension, it will be
-            compressed accordingly.
-        output_compression: If 'auto', the output will be compressed to the
-            format specified by 'output_compression'. Otherwise, the
-            compression format will be deduced from 'output_filename'. Valid
-            'output_compression' are 'none', 'bz2' and 'json'. If
-            'output_filename' is not provided, it will raise a 'ValueError'.
-        overwrite_output_file: If 'True', the 'output_filename' will be
-            overwritten if it exists.
-        atol: Absolute tollerance when checking for hyper-indices.
+            ``tnco.optimize.finite_width.cost_model.SimpleCostModel``)
+        atol: Absolute tolerance when checking for hyper-indices.
         dtype: The type to use for the arrays.
         optimization_backend: The backend to use to manipulate arrays while
-            loading and optimazing the tensor network.
+            loading and optimizing the tensor network.
         seed: Seed to use.
         verbose: Verbose output.
     """
@@ -460,7 +446,7 @@ class Sampler:
     width_type: Optional[str] = 'float32'
     cost_type: Optional[str] = 'float64'
     atol: Optional[float] = 1e-5
-    dtype: Optional[any] = None
+    dtype: Optional[Any] = None
     optimization_backend: Optional[str] = None
     seed: Optional[int] = None
     verbose: Optional[int] = False
@@ -501,48 +487,43 @@ def sample(
         contraction_backend: Optional[str] = None,
         **optimize_params
     ) -> Union[Tuple[Dict[str, int], Tuple[Qubit]], SamplingIntermediateState]:
-        """Sample bitstring from a circuit.
+        """Sample bitstrings from a circuit.
 
-        Sample bitstring from a circuit using the Bravyi-Gosset-Liu algorithm
+        Sample bitstrings from a circuit using the Bravyi-Gosset-Liu algorithm
         presented in "How to Simulate Quantum Measurement without Computing
         Marginals", Phys. Rev. Lett. 128, 220503 (2022).
 
         Args:
-            circuit: Circuit to sample from. If a 'SamplingIntermediateState'
-                is passed insted, the optimization phase of the circuit is
+            circuit: Circuit to sample from. If a ``SamplingIntermediateState``
+                is passed instead, the optimization phase of the circuit is
                 skipped and the intermediate state is used to sample.
             n_samples: The number of total samples to collect.
-            simplify: If 'True', gates that cancel each other will be
+            simplify: If ``True``, gates that cancel each other will be
                 simplified.
-            use_matrix_commutation: If 'True', gates will be commuted by
+            use_matrix_commutation: If ``True``, gates will be commuted by
                 performing the actual matrix commutation while simplifying the
                 circuit.
-            decompose_hyper_inds: If 'True', decompose gates to get
+            decompose_hyper_inds: If ``True``, decompose gates to get
                 hyper-indices.
-            fuse: Fuse tensors together up a width smaller than 'fuse'.  The
+            fuse: Fuse tensors together up a width smaller than ``fuse``.  The
                 width is defined as sum of the logarithms of all the dimensions
                 of a given tensor.
             qubit_order: If provided, the order of qubits to use.
-            normalize: If True, the total number of hits are divided by the
+            normalize: If ``True``, the total number of hits are divided by the
                 number of samples.
-            load_params: Parameters to pass to 'tnco.utils.circuit.load' to
-                convert circuit to a tensor.
-            optimizer_params: Parameters to pass to 'tnco.app.Optimizer' to
-                initialize a new optimizer.
-            optimize_params: Parameters to pass to 'tnco.app.Optimizer.optimize'
-                to optimize each partial contraction.
-            return_intermediate_state_only: If True, skip the sampling and
-                return the 'SamplingIntermediateState'.
+            return_intermediate_state_only: If ``True``, skip the sampling and
+                return the ``SamplingIntermediateState``.
             contraction_backend: The backend to use for the contraction.
             **optimize_params: Parameters to use to optimize the tensor network
-                contraction. (See 'tnco.app.Optimizer.optimize')
+                contraction. (See ``tnco.app.Optimizer.optimize``)
 
         Returns:
-            If 'return_intermediate_state_only', a 'SamplingIntermediateState'
-            is return to be reused multiple times. Othewise, it return a
-            dictionary with the fraction of hits for each bitstring sampled,
-            and the order of qubits. If 'normalize=False', the the number of
-            hits is returned instead of its fraction.
+            If ``return_intermediate_state_only``, a
+            ``SamplingIntermediateState`` is returned to be reused multiple
+            times. Otherwise, it returns a dictionary with the fraction of hits
+            for each bitstring sampled, and the order of qubits. If
+            ``normalize=False``, the number of hits is returned instead of its
+            fraction.
         """
 
         return sample(

tnco/app/circuit/sampling.py

@@ -11,6 +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.
+"""Command-line interface utilities."""
 
 from inspect import Parameter, Signature, signature
 from typing import Callable
@@ -22,10 +23,11 @@
 
 
 def wraps(fn: Callable) -> Callable:
-    """Apply 'fn' signature.
+    """Decorator to copy the signature and docstring from a function.
 
-    'wraps' is a decorator to add 'self' + 'fn' signature, and 'fn.__doc__' to
-    a function. Useful when a non-method function is added as a method.
+    ``wraps`` is a decorator to add ``self`` + ``fn`` signature, and
+    ``fn.__doc__`` to a function. Useful when a non-method function is added as
+    a method.
 
     Args:
         fn: Function to copy the signature and the docstring from.