Merge main

docs/apidocs/index.rst

@@ -0,0 +1,12 @@
+**********************************
+``qiskit-addon-sqd`` API reference
+**********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   qiskit_addon_sqd.configuration_recovery
+   qiskit_addon_sqd.counts
+   qiskit_addon_sqd.fermion
+   qiskit_addon_sqd.qubit
+   qiskit_addon_sqd.subsampling

docs/apidocs/qiskit_addon_sqd.configuration_recovery.rst

@@ -1,10 +1,13 @@
-======================
-Configuration Recovery
-======================
-
-.. _qiskit_addon_sqd-configuration_recovery:
+=======================================================================
+Configuration recovery (:mod:`qiskit_addon_sqd.configuration_recovery`)
+=======================================================================
 
 .. automodule:: qiskit_addon_sqd.configuration_recovery
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.configuration_recovery
+
+.. autofunction:: post_select_by_hamming_weight
+.. autofunction:: recover_configurations

docs/apidocs/qiskit_addon_sqd.counts.rst

@@ -1,10 +1,15 @@
-======
-Counts
-======
-
-.. _qiskit_addon_sqd-counts:
+=======================================
+Counts (:mod:`qiskit_addon_sqd.counts`)
+=======================================
 
 .. automodule:: qiskit_addon_sqd.counts
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.counts
+
+.. autofunction:: counts_to_arrays
+.. autofunction:: generate_counts_uniform
+.. autofunction:: generate_counts_bipartite_hamming
+.. autofunction:: normalize_counts_dict

docs/apidocs/qiskit_addon_sqd.fermion.rst

@@ -1,10 +1,18 @@
-=======
-Fermion
-=======
-
-.. _qiskit_addon_sqd-fermion:
+=========================================
+Fermion (:mod:`qiskit_addon_sqd.fermion`)
+=========================================
 
 .. automodule:: qiskit_addon_sqd.fermion
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.fermion
+
+.. autofunction:: bitstring_matrix_to_ci_strs
+.. autofunction:: enlarge_batch_from_transitions
+.. autofunction:: flip_orbital_occupancies
+.. autofunction:: solve_fermion
+.. autofunction:: optimize_orbitals
+.. autofunction:: rotate_integrals
+.. autofunction:: bitstring_matrix_to_sorted_addresses

docs/apidocs/qiskit_addon_sqd.qubit.rst

@@ -1,10 +1,15 @@
-=====
-Qubit
-=====
-
-.. _qiskit_addon_sqd-qubit:
+=====================================
+Qubit (:mod:`qiskit_addon_sqd.qubit`)
+=====================================
 
 .. automodule:: qiskit_addon_sqd.qubit
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.qubit
+
+.. autofunction:: solve_qubit
+.. autofunction:: project_operator_to_subspace
+.. autofunction:: sort_and_remove_duplicates
+.. autofunction:: matrix_elements_from_pauli

docs/apidocs/qiskit_addon_sqd.subsampling.rst

@@ -1,10 +1,13 @@
-===========
-Subsampling
-===========
-
-.. _qiskit_addon_sqd-subsampling:
+=================================================
+Subsampling (:mod:`qiskit_addon_sqd.subsampling`)
+=================================================
 
 .. automodule:: qiskit_addon_sqd.subsampling
    :no-members:
    :no-inherited-members:
    :no-special-members:
+
+.. currentmodule:: qiskit_addon_sqd.subsampling
+
+.. autofunction:: subsample
+.. autofunction:: postselect_and_subsample

docs/conf.py

@@ -59,6 +59,7 @@
     "sphinx.ext.intersphinx",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_copybutton",
+    "sphinx_reredirects",
     "reno.sphinxext",
     "nbsphinx",
     "qiskit_sphinx_theme",
@@ -107,6 +108,41 @@
 plot_working_directory = "."
 plot_html_show_source_link = False
 
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+_inlined_apis = [
+    ("qiskit_addon_sqd.configuration_recovery", "post_select_by_hamming_weight"),
+    ("qiskit_addon_sqd.configuration_recovery", "recover_configurations"),
+    ("qiskit_addon_sqd.counts", "counts_to_arrays"),
+    ("qiskit_addon_sqd.counts", "generate_counts_uniform"),
+    ("qiskit_addon_sqd.counts", "generate_counts_bipartite_hamming"),
+    ("qiskit_addon_sqd.counts", "normalize_counts_dict"),
+    ("qiskit_addon_sqd.fermion", "bitstring_matrix_to_ci_strs"),
+    ("qiskit_addon_sqd.fermion", "enlarge_batch_from_transitions"),
+    ("qiskit_addon_sqd.fermion", "flip_orbital_occupancies"),
+    ("qiskit_addon_sqd.fermion", "solve_fermion"),
+    ("qiskit_addon_sqd.fermion", "optimize_orbitals"),
+    ("qiskit_addon_sqd.fermion", "rotate_integrals"),
+    ("qiskit_addon_sqd.fermion", "bitstring_matrix_to_sorted_addresses"),
+    ("qiskit_addon_sqd.qubit", "solve_qubit"),
+    ("qiskit_addon_sqd.qubit", "project_operator_to_subspace"),
+    ("qiskit_addon_sqd.qubit", "project_operator_to_subspace"),
+    ("qiskit_addon_sqd.qubit", "sort_and_remove_duplicates"),
+    ("qiskit_addon_sqd.qubit", "matrix_elements_from_pauli"),
+    ("qiskit_addon_sqd.subsampling", "subsample"),
+    ("qiskit_addon_sqd.subsampling", "postselect_and_subsample"),
+]
+
+redirects = {
+    "apidocs/qiskit_addon_sqd": "./index.html",
+    **{
+        f"stubs/{module}.{name}": f"../apidocs/{module}.html#{module}.{name}"
+        for module, name in _inlined_apis
+    },
+}
+
 # ----------------------------------------------------------------------------------
 # Source code links
 # ----------------------------------------------------------------------------------

docs/index.rst

@@ -97,6 +97,6 @@ References
    Installation Instructions <install>
    Tutorials <tutorials/index>
    How-To Guides <how_tos/index>
-   API Reference <apidocs/qiskit_addon_sqd>
+   API Reference <apidocs/index>
    GitHub <https://github.com/qiskit/qiskit-addon-sqd>
    Release Notes <release-notes>

pyproject.toml

@@ -55,7 +55,6 @@ style = [
 ]
 lint = [
     "qiskit-addon-sqd[style]",
-    "pydocstyle==6.3.0",
     "mypy==1.11.2",
     "pylint==3.3.1",
     "reno>=4.1",
@@ -76,6 +75,7 @@ docs = [
     "sphinx-design",
     "sphinx-autodoc-typehints",
     "sphinx-copybutton",
+    "sphinx_reredirects",
     "nbsphinx>=0.9.4",
     "reno>=4.1",
 ]
@@ -134,6 +134,7 @@ select = [
     "I",   # isort
     "E",   # pycodestyle
     "W",   # pycodestyle
+    "D",   # pydocstyle
     "F",   # pyflakes
     "RUF", # ruff
     "UP",  # pyupgrade
@@ -149,8 +150,12 @@ ignore = [
 max-args = 6
 
 [tool.ruff.lint.extend-per-file-ignores]
+"test/**.py" = [
+    "D",  # pydocstyle
+]
 "docs/**/*" = [
     "E402", # module level import not at top of file
+    "D",    # pydocstyle
 ]
 
 [tool.ruff.lint.flake8-copyright]
@@ -167,3 +172,6 @@ notice-rgx = """
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals\\.
 """
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

qiskit_addon_sqd/__init__.py

@@ -10,23 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-Primary SQD functionality.
-
-.. currentmodule:: qiskit_addon_sqd
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-Modules
-=======
-.. autosummary::
-   :toctree:
-
-   configuration_recovery
-   subsampling
-   counts
-   fermion
-   qubit
-"""
+# Warning: this module is not documented and it does not have an RST file.
+# If we ever publicly expose interfaces users can import from this module,
+# we should set up its RST file.
+"""Primary SQD functionality."""

qiskit_addon_sqd/configuration_recovery.py

@@ -10,18 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-Functions for performing self-consistent configuration recovery.
-
-.. currentmodule:: qiskit_addon_sqd.configuration_recovery
-
-.. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
-
-   post_select_by_hamming_weight
-   recover_configurations
-"""
+# Reminder: update the RST file in docs/apidocs when adding new interfaces.
+"""Functions for performing self-consistent configuration recovery."""
 
 from __future__ import annotations
 
@@ -34,8 +24,7 @@
 def post_select_by_hamming_weight(
     bitstring_matrix: np.ndarray, *, hamming_right: int, hamming_left: int
 ) -> np.ndarray:
-    """
-    Post-select bitstrings based on the hamming weight of each half.
+    """Post-select bitstrings based on the hamming weight of each half.
 
     Args:
         bitstring_matrix: A 2D array of ``bool`` representations of bit
@@ -45,6 +34,7 @@ def post_select_by_hamming_weight(
 
     Returns:
         A mask signifying which samples (rows) were selected from the input matrix.
+
     """
     if hamming_left < 0 or hamming_right < 0:
         raise ValueError("Hamming weights must be non-negative integers.")
@@ -66,8 +56,7 @@ def recover_configurations(
     num_elec_b: int,
     rand_seed: int | None = None,
 ) -> tuple[np.ndarray, np.ndarray]:
-    """
-    Refine bitstrings based on average orbital occupancy and a target hamming weight.
+    """Refine bitstrings based on average orbital occupancy and a target hamming weight.
 
     This function refines each bit in isolation in an attempt to transform the Hilbert space
     represented by the input ``bitstring_matrix`` into a space closer to that which supports
@@ -101,6 +90,7 @@ def recover_configurations(
     References:
         [1]: J. Robledo-Moreno, et al., `Chemistry Beyond Exact Solutions on a Quantum-Centric Supercomputer <https://arxiv.org/abs/2405.05068>`_,
              arXiv:2405.05068 [quant-ph].
+
     """
     if num_elec_a < 0 or num_elec_b < 0:
         raise ValueError("The numbers of electrons must be specified as non-negative integers.")
@@ -126,8 +116,7 @@ def recover_configurations(
 
 
 def _p_flip_0_to_1(ratio_exp: float, occ: float, eps: float = 0.01) -> float:  # pragma: no cover
-    """
-    Calculate the probability of flipping a bit from 0 to 1.
+    """Calculate the probability of flipping a bit from 0 to 1.
 
     This function will more aggressively flip bits which are in disagreement
     with the occupation information.
@@ -140,6 +129,7 @@ def _p_flip_0_to_1(ratio_exp: float, occ: float, eps: float = 0.01) -> float:  #
 
     Returns:
         The probability with which to flip the bit
+
     """
     # Occupancy is < than naive expectation.
     # Flip 0s to 1 with small (~eps) probability in this case
@@ -157,8 +147,7 @@ def _p_flip_0_to_1(ratio_exp: float, occ: float, eps: float = 0.01) -> float:  #
 
 
 def _p_flip_1_to_0(ratio_exp: float, occ: float, eps: float = 0.01) -> float:  # pragma: no cover
-    """
-    Calculate the probability of flipping a bit from 1 to 0.
+    """Calculate the probability of flipping a bit from 1 to 0.
 
     This function will more aggressively flip bits which are in disagreement
     with the occupation information.
@@ -171,6 +160,7 @@ def _p_flip_1_to_0(ratio_exp: float, occ: float, eps: float = 0.01) -> float:  #
 
     Returns:
         The probability with which to flip the bit
+
     """
     # Occupancy is < naive expectation.
     # The probability to flip the bit increases linearly from ``eps`` to
@@ -195,8 +185,7 @@ def _bipartite_bitstring_correcting(
     hamming_left: int,
     rand_seed: int | None = None,
 ) -> np.ndarray:
-    """
-    Use occupancy information and target hamming weight to correct a bitstring.
+    """Use occupancy information and target hamming weight to correct a bitstring.
 
     Args:
         bit_array: A 1D array of ``bool`` representations of bit values
@@ -207,6 +196,7 @@ def _bipartite_bitstring_correcting(
 
     Returns:
         A corrected bitstring
+
     """
     # This function must not mutate the input arrays.
     bit_array = bit_array.copy()