Documentation adjustments (#5)

* Some fixes and alignments with the `qiskit-addon-utils` repo

* style

* Ignore slow notebooks, fix bad import

* ruff

* Add typos to externals and fix a typo

* Fix typos

* Remove typos

* Remove typos

* implement feedback

* rename dice solver how-to

* Fix references in tutorial 1

---------

Co-authored-by: Caleb Johnson <[email protected]>

README.md

@@ -1,3 +1,17 @@
+<!-- SHIELDS -->
+<div align="left">
+
+  [![Release](https://img.shields.io/pypi/v/qiskit-addon-sqd.svg?label=Release)](https://github.com/Qiskit/qiskit-addon-sqd/releases)
+  ![Platform](https://img.shields.io/badge/%F0%9F%92%BB%20Platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)
+  [![Python](https://img.shields.io/pypi/pyversions/qiskit-addon-sqd?label=Python&logo=python)](https://www.python.org/)
+  [![Qiskit](https://img.shields.io/badge/Qiskit%20-%20%3E%3D1.2%20-%20%236133BD?logo=Qiskit)](https://github.com/Qiskit/qiskit)
+<br />
+  [![Docs (stable)](https://img.shields.io/badge/%F0%9F%93%84%20Docs-stable-blue.svg)](https://qiskit.github.io/qiskit-addon-sqd/)
+  <!-- [![DOI](https://zenodo.org/badge/DOI/TODO](https://zenodo.org/doi/TODO -->
+  [![License](https://img.shields.io/github/license/Qiskit/qiskit-addon-sqd?label=License)](LICENSE.txt)
+  [![Downloads](https://img.shields.io/pypi/dm/qiskit-addon-sqd.svg?label=Downloads)](https://pypi.org/project/qiskit-addon-sqd/)
+  [![Tests](https://github.com/Qiskit/qiskit-addon-sqd/actions/workflows/test_latest_versions.yml/badge.svg)](https://github.com/Qiskit/qiskit-addon-sqd/actions/workflows/test_latest_versions.yml)
+
 # Qiskit addon: sample-based quantum diagonalization (SQD)
 
 ### Table of contents
@@ -68,13 +82,16 @@ We follow [semantic versioning](https://semver.org/) and are guided by the princ
 We may occasionally make breaking changes in order to improve the user experience.
 When possible, we will keep old interfaces and mark them as deprecated, as long as they can co-exist with the
 new ones.
-Each substantial improvement, breaking change, or deprecation will be documented in the release notes.
+Each substantial improvement, breaking change, or deprecation will be documented in the
+[release notes](https://qiskit.github.io/qiskit-addon-sqd/release-notes.html).
 
 ----------------------------------------------------------------------------------------------------
 
 ### Contributing
 
-The developer guide is located at [CONTRIBUTING.md](https://github.com/Qiskit/qiskit-addon-sqd/blob/main/CONTRIBUTING.md>)
+The source code is available [on GitHub](https://github.com/Qiskit/qiskit-addon-sqd).
+
+The developer guide is located at [CONTRIBUTING.md](https://github.com/Qiskit/qiskit-addon-sqd/blob/main/CONTRIBUTING.md)
 in the root of this project's repository.
 By participating, you are expected to uphold Qiskit's [code of conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md).
 

docs/conf.py

@@ -20,9 +20,11 @@
 # be documented.
 sys.path.insert(0, os.path.abspath(".."))
 
-project = "Sample-based Quantum Diagonalization"
+project = "Qiskit addon: sample-based quantum diagonalization (SQD)"
 project_copyright = "2024, Qiskit addons team"
-description = "Classically post-process noisy samples drawn from a quantum processor to produce more accurate energy estimations"
+description = (
+    "Classically postprocess noisy quantum samples to yield more accurate energy estimations"
+)
 author = "Qiskit addons team"
 language = "en"
 release = metadata_version("qiskit-addon-sqd")

docs/how_tos/choose_subspace_dimension.ipynb

@@ -112,12 +112,12 @@
    "outputs": [],
    "source": [
     "from qiskit_addon_sqd.configuration_recovery import recover_configurations\n",
-    "from qiskit_addon_sqd.subsampling import postselect_and_subsample\n",
-    "from qiskit_addon_sqd.utils.fermion import (\n",
+    "from qiskit_addon_sqd.fermion import (\n",
     "    bitstring_matrix_to_sorted_addresses,\n",
     "    flip_orbital_occupancies,\n",
     "    solve_fermion,\n",
     ")\n",
+    "from qiskit_addon_sqd.subsampling import postselect_and_subsample\n",
     "\n",
     "\n",
     "def configuration_recovery_loop(\n",

docs/how_tos/integrate_dice_solver.ipynb

@@ -5,7 +5,7 @@
    "id": "65adf860-4443-494f-ad90-5d8ea444ac4e",
    "metadata": {},
    "source": [
-    "# Scale past 30 orbitals with Dice solver\n",
+    "# Scale SQD chemistry workflows with Dice solver\n",
     "\n",
     "For information on how to install and use ``qiskit-addon-dice-solver``, [visit the docs](https://qiskit.github.io/qiskit-addon-dice-solver/).\n",
     "\n",
@@ -160,7 +160,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.12.4"
   }
  },
  "nbformat": 4,

docs/index.rst

@@ -91,3 +91,4 @@ References
    How-To Guides <how_tos/index>
    API Reference <apidocs/qiskit_addon_sqd>
    GitHub <https://github.com/qiskit/qiskit-addon-sqd>
+   Release Notes <release-notes>

docs/release-notes.rst

@@ -0,0 +1,3 @@
+.. _release notes:
+
+.. release-notes:: Release Notes

docs/tutorials/01_chemistry_hamiltonian.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Improving energy estimation of a Fermionic Hamiltonian with SQD\n",
     "\n",
-    "In this tutorial we implement a [Qiskit pattern](https://docs.quantum.ibm.com/guides/intro-to-patterns) showing how to post-process noisy quantum samples to find an approximation to the ground state of the $N_2$ molecule at equilibrium in the 6-31G basis set. We will use the sample-based quantum diagonalization (SQD) technique introduced by [Robledo-Moreno et al., 2024](https://arxiv.org/abs/2405.05068). In order to account for the effect of quantum noise, the self-configuration recovery technique is used.\n",
+    "In this tutorial we implement a [Qiskit pattern](https://docs.quantum.ibm.com/guides/intro-to-patterns) showing how to post-process noisy quantum samples to find an approximation to the ground state of the $N_2$ molecule at equilibrium in the 6-31G basis set. We will follow a sample-based quantum diagonalization approach [[1]](https://arxiv.org/abs/2405.05068) to process samples taken from a ``36``-qubit quantum circuit. In order to account for the effect of quantum noise, the self-configuration recovery technique is used.\n",
     "\n",
     "The pattern can be described in four steps:\n",
     "\n",
@@ -145,7 +145,7 @@
    "source": [
     "We will use the [ffsim](https://github.com/qiskit-community/ffsim/tree/main) package to create and initialize the ansatz with `t2` and `t1` amplitudes computed above. Since our molecule has a closed-shell Hartree-Fock state, we will use the spin-balanced variant of the UCJ ansatz, [UCJOpSpinBalanced](https://qiskit-community.github.io/ffsim/api/ffsim.html#ffsim.UCJOpSpinBalanced).\n",
     "\n",
-    "As our target IBM hardware has a heavy-hex topology, we will adopt the _zig-zag_ pattern used in [Motta et al., 2023](https://pubs.rsc.org/en/content/articlelanding/2023/sc/d3sc02516k) for qubit interactions. In this pattern, orbitals (represented by qubits) with the same spin are connected with a line topology (red and blue circles) where each line take a zig-zag shape due the heavy-hex connectivity of the target hardware. Again, due to the heavy-hex topology, orbitals for different spins have connections between every 4th orbital (0, 4, 8, etc.) (purple circles).\n",
+    "As our target IBM hardware has a heavy-hex topology, we will adopt the _zig-zag_ pattern used in [[2]](https://pubs.rsc.org/en/content/articlehtml/2023/sc/d3sc02516k) for qubit interactions. In this pattern, orbitals (represented by qubits) with the same spin are connected with a line topology (red and blue circles) where each line take a zig-zag shape due the heavy-hex connectivity of the target hardware. Again, due to the heavy-hex topology, orbitals for different spins have connections between every 4th orbital (0, 4, 8, etc.) (purple circles).\n",
     "\n",
     "![lucj_ansatz](../_static/images/lucj_ansatz_zig_zag_pattern.jpg)"
    ]
@@ -220,7 +220,7 @@
    "source": [
     "Next, we recommend the following steps to optimize the ansatz and make it hardware-compatible.\n",
     "\n",
-    "- Select physical qubits (`initial_layout`) from the target harware that adheres to the zig-zag pattern described above. Laying out qubits in this pattern leads to an efficient hardware-compatible circuit with less gates.\n",
+    "- Select physical qubits (`initial_layout`) from the target hardware that adheres to the zig-zag pattern described above. Laying out qubits in this pattern leads to an efficient hardware-compatible circuit with less gates.\n",
     "- Generate a staged pass manager using the [generate_preset_pass_manager](https://docs.quantum.ibm.com/api/qiskit/transpiler_preset#generate_preset_pass_manager) function from qiskit with your choice of `backend` and `initial_layout`.\n",
     "- Set the `pre_init` stage of your staged pass manager to `ffsim.qiskit.PRE_INIT`. `ffsim.qiskit.PRE_INIT` includes qiskit transpiler passes that decompose and merge orbitals resulting in fewer gates in the final circuit.\n",
     "- Run the pass manager on your circuit. "
@@ -516,6 +516,18 @@
     "plt.tight_layout()\n",
     "plt.show()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0264e5a8-6581-43f9-b13b-b9cfef3830bd",
+   "metadata": {},
+   "source": [
+    "### References\n",
+    "\n",
+    "[1] Robledo-Moreno, Javier, et al. [\"Chemistry beyond exact solutions on a quantum-centric supercomputer.\"](https://arxiv.org/abs/2405.05068) arXiv preprint arXiv:2405.05068 (2024).\n",
+    "\n",
+    "[2] Motta, Mario, et al. [\"Bridging physical intuition and hardware efficiency for correlated electronic states: the local unitary cluster Jastrow ansatz for electronic structure.\"](https://pubs.rsc.org/en/content/articlelanding/2023/sc/d3sc02516k) Chemical Science 14.40 (2023): 11213-11227."
+   ]
   }
  ],
  "metadata": {

docs/tutorials/02_qubit_hamiltonian.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Ground state energy estimation of a spin (qubit) Hamiltonian\n",
     "\n",
-    "In this tutorial we implement a [Qiskit pattern](https://docs.quantum.ibm.com/guides/intro-to-patterns) showing how to post-process quantum samples to compute an approximation to the ground state of a XX-Z spin-1/2 chain and two-point correlators. We will use the sample-based quantum diagonalization (SQD) technique introduced by [Robledo-Moreno et al., 2024](https://arxiv.org/abs/2405.05068).\n",
+    "In this tutorial we implement a [Qiskit pattern](https://docs.quantum.ibm.com/guides/intro-to-patterns) showing how to post-process quantum samples to compute an approximation to the ground state of a ``22``-site XX-Z spin-1/2 chain and two-point correlators. We will follow a sample-based quantum diagonalization approach[[1]](https://arxiv.org/abs/2405.05068).\n",
     "\n",
     "While a Qiskit pattern typically involves 4 steps, the aim of this tutorial is to focus on the post-processing of the samples obtained from a quantum circuit whose support coincides with that of the ground state. Consequently, we generate a synthetic set of bitstrings to define the subspace and do not design an ansatz nor sample from a quantum circuit in this tutorial.\n",
     "\n",
@@ -446,6 +446,15 @@
     "plt.ylabel(\"spin-spin correlators\")\n",
     "plt.show()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### References\n",
+    "\n",
+    "[1] Robledo-Moreno, Javier, et al. [\"Chemistry beyond exact solutions on a quantum-centric supercomputer.\"](https://arxiv.org/abs/2405.05068) arXiv preprint arXiv:2405.05068 (2024)."
+   ]
   }
  ],
  "metadata": {

pyproject.toml

@@ -6,8 +6,9 @@ build-backend = "hatchling.build"
 name = "qiskit-addon-sqd"
 version = "0.3.0"
 readme = "README.md"
+description = "Classically postprocess noisy quantum samples to yield more accurate energy estimations"
 license = {file = "LICENSE.txt"}
-classifiers = [ 
+classifiers = [
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: Apache Software License",
@@ -34,14 +35,17 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "qiskit-addon-sqd[test,nbtest,lint,docs]",
+    "tox>=4.4.3",
 ]
-test = [
-    "tox>=4.0",
+basetest = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
 ]
+test = [
+    "qiskit-addon-sqd[basetest]",
+]
 nbtest = [
-    "qiskit-addon-sqd[test]",
+    "qiskit-addon-sqd[basetest]",
     "nbmake>=1.5.0",
 ]
 style = [
@@ -50,9 +54,9 @@ style = [
 ]
 lint = [
     "qiskit-addon-sqd[style]",
+    "pydocstyle==6.3.0",
     "mypy==1.11.2",
-    "pylint>=3.2.7",
-    "pydocstyle==6.3",
+    "pylint==3.2.7",
     "reno>=4.1",
     "toml>=0.9.6",
 ]
@@ -75,6 +79,14 @@ docs = [
     "reno>=4.1",
 ]
 
+[tool.coverage.run]
+branch = true
+parallel = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
 [tool.hatch.build.targets.wheel]
 only-include = [
     "qiskit_addon_sqd",
@@ -114,7 +126,7 @@ testpaths = ["./qiskit_addon_sqd/", "./test/"]
 [tool.ruff]
 line-length = 100
 src = ["qiskit_addon_sqd", "test"]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = [
@@ -140,5 +152,16 @@ max-args = 6
     "E402", # module level import not at top of file
 ]
 
-[tool.typos.default.extend-words]
-IY = "IY"
+[tool.ruff.lint.flake8-copyright]
+notice-rgx = """
+# This code is a Qiskit project.
+
+# \\(C\\) Copyright IBM 2024\\.
+
+# This code is licensed under the Apache License, Version 2\\.0\\. You may
+# obtain a copy of this license in the LICENSE\\.txt file in the root directory
+# of this source tree or at http\\:\\/\\/www\\.apache\\.org\\/licenses\\/LICENSE\\-2\\.0\\.
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals\\.
+"""

qiskit_addon_sqd/configuration_recovery.py

@@ -91,7 +91,7 @@ def recover_configurations(
     # First, we need to flip the orbitals such that
 
     corrected_dict: dict[str, float] = {}
-    for bitstring, freq in zip(bitstring_matrix, probabilities):
+    for bitstring, freq in zip(bitstring_matrix, probabilities, strict=False):
         bs_corrected = _bipartite_bitstring_correcting(
             bitstring,
             avg_occupancies,

qiskit_addon_sqd/qubit.py

@@ -113,11 +113,11 @@ def project_operator_to_subspace(
     operator = coo_matrix((d, d), dtype="complex128")
 
     for i, pauli in enumerate(hamiltonian.paulis):
-        coefficent = hamiltonian.coeffs[i]
+        coefficient = hamiltonian.coeffs[i]
         if verbose:
             (
                 print(
-                    f"Projecting term {i+1} out of {hamiltonian.size}: {coefficent} * "
+                    f"Projecting term {i+1} out of {hamiltonian.size}: {coefficient} * "
                     + "".join(pauli.to_label())
                     + " ..."
                 )
@@ -127,7 +127,7 @@ def project_operator_to_subspace(
             bitstring_matrix, pauli
         )
 
-        operator += coefficent * coo_matrix((matrix_elements, (row_coords, col_coords)), (d, d))
+        operator += coefficient * coo_matrix((matrix_elements, (row_coords, col_coords)), (d, d))
 
     return operator
 

releasenotes/config.yaml

@@ -0,0 +1,4 @@
+---
+encoding: utf8
+default_branch: main
+unreleased_version_title: "Upcoming release"

test/README.md

@@ -47,7 +47,7 @@ These environments execute all tests using [pytest], which supports its own simp
 
 ## Notebook environments
 
-The `notebook` and `py##-notebook` environments invoke [nbmake] to ensure that all the Jupyter notebooks in the [`docs/`](/docs/tutorials) directory execute successfully.
+The `notebook` and `py##-notebook` environments invoke [nbmake] to ensure that all Jupyter notebooks in the [`docs/`](/docs/) directory execute successfully.
 
 ```sh
 $ tox -e py310-notebook

tox.ini

@@ -1,11 +1,9 @@
 [tox]
-minversion = 4.0
-envlist = py{39,310,311,312}{,-notebook}, lint
+minversion = 4.4.3
+envlist = py{310,311,312}{,-notebook}, lint, coverage, docs
 isolated_build = True
 
 [testenv]
-passenv =
-    SSH_AUTH_SOCK
 extras =
   test
 commands =
@@ -26,19 +24,26 @@ extras =
 commands =
   ruff format --check qiskit_addon_sqd/ docs/ test/
   ruff check qiskit_addon_sqd/ docs/ test/
+  ruff check --preview --select CPY001 --exclude "*.ipynb" qiskit_addon_sqd/ test/
   nbqa ruff docs/
+  pydocstyle qiskit_addon_sqd/
   mypy qiskit_addon_sqd/
-  #reno lint
   pylint -rn qiskit_addon_sqd/ test/
   nbqa pylint -rn docs/
-  pydocstyle qiskit_addon_sqd/
+  reno lint
 
-[testenv:{,py-,py3-,py39-,py310-,py311-,py312-}notebook]
+[testenv:{,py-,py3-,py310-,py311-,py312-}notebook]
 extras =
   nbtest
   notebook-dependencies
 commands =
-  pytest --nbmake --nbmake-timeout=3000 {posargs} docs/tutorials/
+  pytest --nbmake \
+         --nbmake-timeout=3000 \
+         --ignore=docs/how_tos/benchmark_pauli_projection.ipynb \
+         --ignore=docs/how_tos/integrate_dice_solver.ipynb \
+         --ignore=docs/how_tos/use_oo_to_optimize_hamiltonian_basis.ipynb \
+         --ignore=docs/how_tos/choose_subspace_dimension.ipynb \
+         {posargs} docs/
 
 [testenv:coverage]
 deps =
@@ -62,6 +67,5 @@ commands =
 skip_install = true
 allowlist_externals =
   rm
-  mypy
 commands =
   rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build/