diff --git a/.github/workflows/docs-dev.yml b/.github/workflows/docs-dev.yml new file mode 100644 index 0000000..342e7f3 --- /dev/null +++ b/.github/workflows/docs-dev.yml @@ -0,0 +1,32 @@ +name: Build and deploy documentation for development branch + +on: + workflow_dispatch: + push: + branches: + - main + +jobs: + build_and_deploy_docs: + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: "3.12" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install tox + sudo apt update + sudo apt install -y pandoc + - name: Build docs + run: | + tox run -e docs + - name: Deploy docs + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html/ + target-folder: dev/ diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml new file mode 100644 index 0000000..a3c2df3 --- /dev/null +++ b/.github/workflows/docs-release.yml @@ -0,0 +1,34 @@ +name: Build and deploy documentation for release version + +on: + workflow_dispatch: + push: + tags: + - "*" + +jobs: + build_and_deploy_docs: + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: "3.12" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install tox + sudo apt update + sudo apt install -y pandoc + - name: Build docs + run: | + tox run -e docs + - name: Deploy docs + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html/ + clean-exclude: | + stable/* + dev/* diff --git a/.github/workflows/docs-stable.yml b/.github/workflows/docs-stable.yml new file mode 100644 index 0000000..9d03b6e --- /dev/null +++ b/.github/workflows/docs-stable.yml @@ -0,0 +1,35 @@ +name: Build and deploy documentation for stable version + +on: + workflow_dispatch: + push: + tags: + - "*" + +jobs: + build_and_deploy_docs: + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: "3.12" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install tox + sudo apt update + sudo apt install -y pandoc + - name: Build docs + run: | + tox run -e docs + - name: Set current version + run: | + echo "version=$(git describe --tags)" >> "$GITHUB_ENV" + - name: Deploy docs + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html/ + target-folder: stable/${{ env.version }} diff --git a/README.md b/README.md index 7647259..86c9849 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,21 @@ # qiskit-quimb + + Simulate [Qiskit](https://www.ibm.com/quantum/qiskit) circuits using [quimb](https://quimb.readthedocs.io/en/latest/). + + ## Installation + + ```bash pip install qiskit-quimb ``` + + ## Usage The `qiskit_quimb` module exposes two functions: @@ -15,7 +23,9 @@ The `qiskit_quimb` module exposes two functions: - `quimb_circuit`: Converts a Qiskit circuit to a quimb circuit. This is probably the function you want to use. - `quimb_gates`: Converts a Qiskit circuit to a list of quimb gates, which is a bit more flexible. -## Example code +## Code example + + ```python import quimb.tensor @@ -48,3 +58,5 @@ print(samples) ['00', '00', '11', '00', '11', '00', '11', '00', '11', '11'] ['11', '11', '00', '00', '11', '00', '11', '11', '11', '00'] ``` + + diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..8285849 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,7 @@ +# API reference + +```{toctree} +:maxdepth: 2 + +qiskit_quimb +``` diff --git a/docs/api/qiskit_quimb.rst b/docs/api/qiskit_quimb.rst new file mode 100644 index 0000000..c170ea1 --- /dev/null +++ b/docs/api/qiskit_quimb.rst @@ -0,0 +1,6 @@ +ffsim +===== + +.. automodule:: qiskit_quimb + :members: + :show-inheritance: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..4ef1c90 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,47 @@ +# (C) Copyright IBM 2023. +# +# 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. + +"""Sphinx configuration.""" + +import importlib.metadata + +project = "qiskit-quimb" +copyright = "2024, IBM" +author = "Kevin J. Sung" +release = importlib.metadata.version("qiskit-quimb") + +extensions = [ + "sphinx.ext.napoleon", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.extlinks", + "sphinx_autodoc_typehints", + "myst_parser", + "nbsphinx", + "qiskit_sphinx_theme", +] + +exclude_patterns = ["_build", "**.ipynb_checkpoints"] + +# HTML output options +html_theme = "qiskit-ecosystem" +html_title = f"{project} {release}" +html_theme_options = { + "source_repository": "https://github.com/qiskit-community/qiskit-quimb/", + "source_branch": "main", + "source_directory": "docs/", + "sidebar_qiskit_ecosystem_member": True, +} + +# nbsphinx options (for tutorials) +nbsphinx_timeout = 300 +nbsphinx_execute = "always" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..35f9b83 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,32 @@ +# ffsim + +```{include} ../README.md +:start-after: +:end-before: +``` + +## Installation + +```{include} ../README.md +:start-after: +:end-before: +``` + +## Code example + +```{include} ../README.md +:start-after: +:end-before: +``` + +## Contents + +```{toctree} +:maxdepth: 2 + +tutorials/index +api/index +GitHub +Release notes +Development branch docs +``` diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 0000000..9d14a2e --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,7 @@ +# Tutorials + +```{toctree} +:maxdepth: 1 + +quimb-circuit +``` diff --git a/docs/tutorials/quimb-circuit.ipynb b/docs/tutorials/quimb-circuit.ipynb new file mode 100644 index 0000000..c018784 --- /dev/null +++ b/docs/tutorials/quimb-circuit.ipynb @@ -0,0 +1,74 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Simulating Qiskit circuits with quimb" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "['00', '00', '11', '00', '11', '00', '11', '00', '11', '11']\n", + "['11', '11', '00', '00', '11', '00', '11', '11', '11', '00']\n" + ] + } + ], + "source": [ + "import quimb.tensor\n", + "from qiskit.circuit import QuantumCircuit, QuantumRegister\n", + "\n", + "from qiskit_quimb import quimb_circuit\n", + "\n", + "# Build a Qiskit circuit\n", + "qubits = QuantumRegister(2)\n", + "circuit = QuantumCircuit(qubits)\n", + "a, b = qubits\n", + "circuit.h(a)\n", + "circuit.cx(a, b)\n", + "\n", + "# Convert it to a quimb circuit\n", + "quimb_circ = quimb_circuit(circuit)\n", + "\n", + "# Sample 10 bitstrings\n", + "samples = list(quimb_circ.sample(10, seed=1234))\n", + "print(samples)\n", + "\n", + "# You can specify the quimb Circuit subclass and keyword arguments for the constructor\n", + "quimb_circ = quimb_circuit(\n", + " circuit, quimb_circuit_class=quimb.tensor.CircuitMPS, max_bond=20\n", + ")\n", + "samples = list(quimb_circ.sample(10, seed=1234))\n", + "print(samples)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "qiskit-quimb", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.9" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/pyproject.toml b/pyproject.toml index 6b9ee22..dd90a1f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,19 @@ classifiers = [ dependencies = ["qiskit", "quimb"] [project.optional-dependencies] -dev = ["coverage", "mypy", "pytest", "qiskit[visualization]", "ruff"] +dev = [ + "coverage", + "mypy", + "myst-parser", + "nbmake", + "nbsphinx", + "pytest", + "qiskit[visualization]", + "qiskit-sphinx-theme", + "ruff", + "sphinx", + "sphinx-autodoc-typehints", +] [project.urls] Homepage = "https://github.com/qiskit-community/qiskit-quimb" diff --git a/tox.ini b/tox.ini index 073575e..dbdce20 100644 --- a/tox.ini +++ b/tox.ini @@ -44,3 +44,14 @@ extras = dev commands = ruff format --check + +[testenv:docs] +description = build docs +extras = + dev +setenv = + SPHINX_APIDOC_OPTIONS = members,show-inheritance +commands = + python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "stubs", ignore_errors=True)' + python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "_build" / "html" / ".doctrees", ignore_errors=True)' + sphinx-build -b html -W {posargs} docs/ docs/_build/html