diff --git a/README.md b/README.md index 1662d09..f6e1a11 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,17 @@ + +
+ + [![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) +
+ [![Docs (stable)](https://img.shields.io/badge/%F0%9F%93%84%20Docs-stable-blue.svg)](https://qiskit.github.io/qiskit-addon-sqd/) + + [![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). diff --git a/docs/conf.py b/docs/conf.py index 421ba88..29f08b9 100644 --- a/docs/conf.py +++ b/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") diff --git a/docs/how_tos/choose_subspace_dimension.ipynb b/docs/how_tos/choose_subspace_dimension.ipynb index bb9557f..271a9c2 100644 --- a/docs/how_tos/choose_subspace_dimension.ipynb +++ b/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", diff --git a/docs/how_tos/integrate_dice_solver.ipynb b/docs/how_tos/integrate_dice_solver.ipynb index 02417e5..daef6dd 100644 --- a/docs/how_tos/integrate_dice_solver.ipynb +++ b/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, diff --git a/docs/index.rst b/docs/index.rst index 217155e..6fe0784 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -91,3 +91,4 @@ References How-To Guides API Reference GitHub + Release Notes diff --git a/docs/release-notes.rst b/docs/release-notes.rst new file mode 100644 index 0000000..9523d94 --- /dev/null +++ b/docs/release-notes.rst @@ -0,0 +1,3 @@ +.. _release notes: + +.. release-notes:: Release Notes diff --git a/docs/tutorials/01_chemistry_hamiltonian.ipynb b/docs/tutorials/01_chemistry_hamiltonian.ipynb index 3db838b..faf6eeb 100644 --- a/docs/tutorials/01_chemistry_hamiltonian.ipynb +++ b/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": { diff --git a/docs/tutorials/02_qubit_hamiltonian.ipynb b/docs/tutorials/02_qubit_hamiltonian.ipynb index 1e390b5..60e769c 100644 --- a/docs/tutorials/02_qubit_hamiltonian.ipynb +++ b/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": { diff --git a/pyproject.toml b/pyproject.toml index 12b33d4..85b3883 100644 --- a/pyproject.toml +++ b/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\\. +""" diff --git a/qiskit_addon_sqd/configuration_recovery.py b/qiskit_addon_sqd/configuration_recovery.py index e2ba2ae..f8fa7cc 100644 --- a/qiskit_addon_sqd/configuration_recovery.py +++ b/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, diff --git a/qiskit_addon_sqd/qubit.py b/qiskit_addon_sqd/qubit.py index f58efb0..f946fdc 100644 --- a/qiskit_addon_sqd/qubit.py +++ b/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 diff --git a/releasenotes/config.yaml b/releasenotes/config.yaml new file mode 100644 index 0000000..0d7e51e --- /dev/null +++ b/releasenotes/config.yaml @@ -0,0 +1,4 @@ +--- +encoding: utf8 +default_branch: main +unreleased_version_title: "Upcoming release" diff --git a/releasenotes/notes/.gitkeep b/releasenotes/notes/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/test/README.md b/test/README.md index 30e619e..36bba7d 100644 --- a/test/README.md +++ b/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 diff --git a/tox.ini b/tox.ini index 0508dd3..b83ee6b 100644 --- a/tox.ini +++ b/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/