Merge pull request #39 from qiboteam/dev/docs

Merging current progress of docs to main

.gitignore

@@ -163,3 +163,6 @@ cython_debug/
 # Psi4
 timer.dat
 psi4_output.dat
+
+# vscode
+.vscode/

README.md

@@ -13,6 +13,16 @@ Qibochem key features
 
 ## Installation
 
+Using poetry (recommended)
+
+```
+git clone https://github.com/qiboteam/qibochem.git
+cd qibochem
+poetry install
+```
+
+Using pip
+
 ```
 git clone https://github.com/qiboteam/qibochem.git
 cd qibochem

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api-reference/ansatz.rst

@@ -0,0 +1,4 @@
+Ansatz
+======
+
+This section covers the API reference for the ansatz module.

docs/source/api-reference/driver.rst

@@ -0,0 +1,13 @@
+Driver
+======
+
+Qibochem provides the Molecule class to store the data structure of a molecule object, and to drive the classical quantum chemistry calculation to obtain necessary quantities for subsequent quantum compute calculations.
+
+.. _api driver molecule class:
+
+Molecule class
+--------------
+
+.. autoclass:: qibochem.driver.molecule.Molecule
+    :members:
+    :member-order: bysource

docs/source/api-reference/index.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+In this section we document the main Qibochem components and primitives in the public API.
+
+.. toctree::
+    :maxdepth: 1
+
+    driver
+    ansatz
+    measurement

docs/source/api-reference/measurement.rst

@@ -0,0 +1,2 @@
+Measurement
+===========

docs/source/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "qibochem"
+copyright = "2023, qiboteam"
+author = "qiboteam"
+release = "0.0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinxcontrib.katex",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# custom title
+html_title = "Version " + release
+
+# custom html theme options (colors and font)
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "#6400FF",
+        "color-brand-secondary": "#6400FF",
+        "color-brand-content": "#6400FF",
+    }
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+
+html_static_path = ["_static"]

docs/source/developer-guides/index.rst

@@ -0,0 +1,4 @@
+Developer Guides
+================
+
+This section provides code overview and contribution guidelines for developers.

docs/source/getting-started/ansatz.rst

@@ -0,0 +1,40 @@
+======
+Ansatz
+======
+
+A quantum circuit consisting of parameterized gates RX(theta), RY(theta) and RZ(theta), represents a unitary transformation :math:`U(\theta)` that transforms the initial quantum state into an Ansatz state :math:`|\psi(\theta)\rangle`.
+
+Hardware Efficient Ansatz
+-------------------------
+
+Qibochem provides a hardware efficient ansatz that simply consists of a layer of single qubit rotation gates followed by a layer of two-qubit gates that entangle the qubits. For the H\ :sub:`2` case discussed in previous sections, a possible hardware efficient ansatz can be constructed as such:
+
+.. image:: qibochem_doc_ansatz_hardware-efficient.svg
+
+Example
+^^^^^^^
+
+Placeholder for hardware-efficient ansatz example
+
+
+Unitary Coupled Cluster Ansatz
+------------------------------
+
+The Unitary Coupled Cluster ansatz [#f1]_ [#f2]_ is a variant of the popular gold standard Coupled Cluster ansatz [#f3]_ of quantum chemistry. The unitary coupled cluster wave function is a parameterized unitary transformation of a reference wave function, of which a common choice is the Hartree-Fock wave function.
+
+.. math::
+
+    |\psi_{\mathrm{UCC}}\rangle = U(\theta)|\psi_{\mathrm{ref}}\rangle
+
+Example
+^^^^^^^
+
+Placeholder for UCCD example
+
+.. rubric:: References
+
+.. [#f1] Whitfield, J. D. et al., 'Simulation of electronic structure Hamiltonians using quantum computers', Mol. Phys. 109 (2011) 735.
+
+.. [#f2] Anand. A. et al., 'A quantum computing view on unitary coupled cluster theory', Chem. Soc. Rev. 51 (2022) 1659.
+
+.. [#f3] Crawford, T. D. et al., 'An Introduction to Coupled Cluster Theory for Computational Chemists', in Reviews in Computational Chemistry 14 (2007) 33.

docs/source/getting-started/hamiltonian.rst

@@ -0,0 +1,104 @@
+===========
+Hamiltonian
+===========
+
+Central to quantum chemical calculations for molecules is the fermionic two-body Hamiltonian in second quantized form.
+
+TODO: spinfree, nonrelativistic, without external fields, without nuclear-repulsion energy
+
+.. math::
+    \hat{H} = \sum_{pq} h_{pq} a^\dagger_p a_q + \frac12 \sum_{pqrs} g_{pqrs} a^\dagger_p a^\dagger_r a_s a_q
+
+
+
+The integrals :math:`h_{pq}` and :math:`g_{pqrs}` are one- and two-electron integrals in atomic units. For spinorbitals :math:`\phi_j` that make up the basis, the integrals are [#f1]_:
+
+.. math::
+
+    h_{pq} = \int \phi^*_p(\mathbf{x}_1)\left( -\frac12 \nabla^2 - \sum_A \frac{Z_A}{r_{A}} \right) \phi_q(\mathbf{x}_1) d\mathbf{x}_1
+
+.. math::
+
+    g_{pqrs} = \int \int \phi^*_p(\mathbf{x}_1)\phi^*_r(\mathbf{x}_2) \frac{1}{r_{12}} \phi_s(\mathbf{x}_2)\phi_q(\mathbf{x}_1) dx_1 dx_2
+
+These integral quantities are obtained from the PySCF driver program, and can be accessed via the :doc:`Molecule class<molecule>`. Qibochem then uses these integrals and OpenFermion to construct the second quantized fermionic Hamiltonian for the molecular system in terms of creation and annihilation operators, with coefficients from these integral quantities.
+
+
+Example
+-------
+
+.. code-block:: python
+
+    from qibochem.driver.molecule import Molecule
+    mol = Molecule([('H', (0.0, 0.0, 0.0)), ('H', (0.0, 0.0, 0.74804))])
+    mol.run_pyscf()
+    mol_ferm_ham = mol.hamiltonian("ferm") # or mol.hamiltonian("f")
+    print(mol_ferm_ham.terms)
+
+Output:
+
+.. code-block:: output
+
+    {(): 0.7074183344740923, ((0, 1), (0, 0)): -1.248461959132892, ((1, 1), (1, 0)): -1.248461959132892, ((2, 1), (2, 0)): -0.48007161818330846, ((3, 1), (3, 0)): -0.48007161818330846, ((0, 1), (0, 1), (0, 0), (0, 0)): 0.3366109237586995, ((0, 1), (0, 1), (2, 0), (2, 0)): 0.09083064962340165, ((0, 1), (1, 1), (1, 0), (0, 0)): 0.3366109237586995, ((0, 1), (1, 1), (3, 0), (2, 0)): 0.09083064962340165, ((0, 1), (2, 1), (0, 0), (2, 0)): 0.09083064962340165, ((0, 1), (2, 1), (2, 0), (0, 0)): 0.33115823068165495, ((0, 1), (3, 1), (1, 0), (2, 0)): 0.09083064962340165, ((0, 1), (3, 1), (3, 0), (0, 0)): 0.33115823068165495, ((1, 1), (0, 1), (0, 0), (1, 0)): 0.3366109237586995, ((1, 1), (0, 1), (2, 0), (3, 0)): 0.09083064962340165, ((1, 1), (1, 1), (1, 0), (1, 0)): 0.3366109237586995, ((1, 1), (1, 1), (3, 0), (3, 0)): 0.09083064962340165, ((1, 1), (2, 1), (0, 0), (3, 0)): 0.09083064962340165, ((1, 1), (2, 1), (2, 0), (1, 0)): 0.33115823068165495, ((1, 1), (3, 1), (1, 0), (3, 0)): 0.09083064962340165, ((1, 1), (3, 1), (3, 0), (1, 0)): 0.33115823068165495, ((2, 1), (0, 1), (0, 0), (2, 0)): 0.3311582306816552, ((2, 1), (0, 1), (2, 0), (0, 0)): 0.09083064962340165, ((2, 1), (1, 1), (1, 0), (2, 0)): 0.3311582306816552, ((2, 1), (1, 1), (3, 0), (0, 0)): 0.09083064962340165, ((2, 1), (2, 1), (0, 0), (0, 0)): 0.09083064962340165, ((2, 1), (2, 1), (2, 0), (2, 0)): 0.348087115228365, ((2, 1), (3, 1), (1, 0), (0, 0)): 0.09083064962340165, ((2, 1), (3, 1), (3, 0), (2, 0)): 0.348087115228365, ((3, 1), (0, 1), (0, 0), (3, 0)): 0.3311582306816552, ((3, 1), (0, 1), (2, 0), (1, 0)): 0.09083064962340165, ((3, 1), (1, 1), (1, 0), (3, 0)): 0.3311582306816552, ((3, 1), (1, 1), (3, 0), (1, 0)): 0.09083064962340165, ((3, 1), (2, 1), (0, 0), (1, 0)): 0.09083064962340165, ((3, 1), (2, 1), (2, 0), (3, 0)): 0.348087115228365, ((3, 1), (3, 1), (1, 0), (1, 0)): 0.09083064962340165, ((3, 1), (3, 1), (3, 0), (3, 0)): 0.348087115228365}
+
+
+Additional information about the data structure of the second quantized fermionic Hamiltonian can be found `here <https://quantumai.google/openfermion/tutorials/intro_to_openfermion>`_.
+
+Fermion to Qubit mapping
+------------------------
+
+The fermionic Hamiltonian can then be mapped into qubit Hamiltonians in OpenFermion form.
+
+.. code-block::
+
+    mol_qubit_ham = mol.hamiltonian("qubit") # or mol.hamiltonian("q")
+    mol_sym_ham = mol.hamiltonian("sym")     # or mol.hamiltonian("s")
+
+
+
+Supported mapping schemes are the Jordan-Wigner and Bravyi-Kitaev schemes, as implemented in OpenFermion.
+
+
+Example
+-------
+
+The mapping scheme can be specified using the keyword :code:`ferm_qubit_map` as follows:
+
+
+.. code-block:: python
+
+    mol_qubit_ham = mol.hamiltonian("qubit", ferm_qubit_map="jw")
+    print(mol_qubit_ham.terms)
+
+Output:
+
+.. code-block:: output
+
+    {(): -0.10728041160866736, ((0, 'Z'),): 0.17018261181714206, ((1, 'Z'),): 0.17018261181714206, ((2, 'Z'),): -0.21975065439248248, ((3, 'Z'),): -0.21975065439248248, ((0, 'Z'), (1, 'Z')): 0.16830546187934975, ((0, 'Z'), (2, 'Z')): 0.1201637905291267, ((0, 'Z'), (3, 'Z')): 0.16557911534082753, ((1, 'Z'), (2, 'Z')): 0.16557911534082753, ((1, 'Z'), (3, 'Z')): 0.1201637905291267, ((2, 'Z'), (3, 'Z')): 0.1740435576141825, ((0, 'X'), (1, 'X'), (2, 'Y'), (3, 'Y')): -0.045415324811700825, ((0, 'X'), (1, 'Y'), (2, 'Y'), (3, 'X')): 0.045415324811700825, ((0, 'Y'), (1, 'X'), (2, 'X'), (3, 'Y')): 0.045415324811700825, ((0, 'Y'), (1, 'Y'), (2, 'X'), (3, 'X')): -0.045415324811700825}
+
+Additional information about the data structure of the qubit Hamiltonian can be found `here <https://quantumai.google/openfermion/tutorials/intro_to_openfermion>`_.
+
+
+Symbolic Hamiltonian
+--------------------
+
+To carry out quantum simulations of the electronic structure in molecules using methods such as VQE and time evolution using Qibo, the Hamiltonian has to be defined either in the full matrix form, or a more efficient term representation using :code:`sympy` form:
+
+.. code-block:: python
+
+    mol_sym_ham = mol.hamiltonian("sym")     # or mol.hamiltonian("s")
+    print(mol_sym_ham.form)
+
+.. code-block:: output
+
+    -0.107280411608667 - 0.0454153248117008*X0*X1*Y2*Y3 + 0.0454153248117008*X0*Y1*Y2*X3 + 0.0454153248117008*Y0*X1*X2*Y3 - 0.0454153248117008*Y0*Y1*X2*X3 + 0.170182611817142*Z0 + 0.16830546187935*Z0*Z1 + 0.120163790529127*Z0*Z2 + 0.165579115340828*Z0*Z3 + 0.170182611817142*Z1 + 0.165579115340828*Z1*Z2 + 0.120163790529127*Z1*Z3 - 0.219750654392482*Z2 + 0.174043557614182*Z2*Z3 - 0.219750654392482*Z3
+
+
+By default, the symbolic Hamiltonian is returned, i.e. if no arguments are given for :code:`mol.hamiltonian()`.
+
+
+
+
+.. rubric:: References
+
+.. [#f1] Helgaker, T., Jørgensen, P., Olsen, J. Molecular Electronic Structure Theory 2000, Wiley, Chichester, England

docs/source/getting-started/index.rst

@@ -0,0 +1,14 @@
+Getting started
+===============
+
+This section covers the basics of qibochem. More details are given in the following subsections.
+
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    molecule
+    hamiltonian
+    ansatz
+    measurement

docs/source/getting-started/installation.rst

@@ -0,0 +1,18 @@
+Installation
+============
+
+Using pip install:
+
+.. code-block::
+
+    git clone https://github.com/qiboteam/qibochem.git
+    cd qibochem
+    pip install .
+
+Using poetry:
+
+.. code-block::
+
+    git clone https://github.com/qiboteam/qibochem.git
+    cd qibochem
+    poetry install

docs/source/getting-started/measurement.rst

@@ -0,0 +1,2 @@
+Measurement
+===========