Merge branch 'main' into dev_tutorial

.pre-commit-config.yaml

@@ -2,14 +2,14 @@ ci:
   autofix_prs: true
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
       - id: debug-statements
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 24.4.2
     hooks:
       - id: black
         args:
@@ -20,6 +20,6 @@ repos:
       - id: isort
         args: ["--profile", "black"]
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.15.0
+    rev: v3.15.2
     hooks:
       - id: pyupgrade

README.md

@@ -2,27 +2,59 @@
 
 ![Tests](https://github.com/qiboteam/qibochem/workflows/Tests/badge.svg)
 [![codecov](https://codecov.io/gh/qiboteam/qibochem/graph/badge.svg?token=2CMDZP1GU2)](https://codecov.io/gh/qiboteam/qibochem)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10473173.svg)](https://doi.org/10.5281/zenodo.10473173)
 
 Qibochem is a plugin to [Qibo](https://github.com/qiboteam/qibo) for quantum chemistry simulations.
 
-Qibochem key features
+Some of the features of Qibochem are:
 
-* General purpose Molecule class
-  * PySCF or Psi4 for calculation of 1- and 2-electron integrals
+* General purpose `Molecule` class
+  * PySCF for calculating the molecular  1- and 2-electron integrals
   * User defined orbital active space
 * Unitary Coupled Cluster Ansatz
 * Various Qibo backends (numpy, JIT, TN) for efficient simulation
 
-## Installation
+## Documentation
 
-Using poetry
+The Qibochem documentation can be found [here](https://qibo.science/qibochem/stable)
+
+## Minimum working example:
+
+An example of building the UCCD ansatz with a H2 molecule
 
 ```
-git clone https://github.com/qiboteam/qibochem.git
-cd qibochem
-poetry install
+import numpy as np
+from qibo.models import VQE
+
+from qibochem.driver.molecule import Molecule
+from qibochem.ansatz.hf_reference import hf_circuit
+from qibochem.ansatz.ucc import ucc_circuit
+
+# Define the H2 molecule and obtain its 1-/2- electron integrals with PySCF
+h2 = Molecule([('H', (0.0, 0.0, 0.0)), ('H', (0.0, 0.0, 0.7))])
+h2.run_pyscf()
+# Generate the molecular Hamiltonian
+hamiltonian = h2.hamiltonian()
+
+# Build a UCC circuit ansatz for running VQE
+circuit = hf_circuit(h2.nso, sum(h2.nelec))
+circuit += ucc_circuit(h2.nso, [0, 1, 2, 3])
+
+# Create and run the VQE, starting with random initial parameters
+vqe = VQE(circuit, hamiltonian)
+
+initial_parameters = np.random.uniform(0.0, 2*np.pi, 8)
+best, params, extra = vqe.minimize(initial_parameters)
 ```
 
+## Citation policy
+
+If you use the Qibochem plugin please refer to the documentation for citation instructions.
+
+## Contact
+
+For questions, comments and suggestions please contact us at [https://matrix.to/#/#qibo:matrix.org](url)
+
 ## Contributing
 
 Contributions, issues and feature requests are welcome.

doc/source/api-reference/ansatz.rst

@@ -2,12 +2,12 @@
 Ansatz
 ======
 
-This section covers the API reference for various chemistry ansatzes.
+This section covers the API reference for various chemistry circuit ansatzes.
 
 Hardware-efficient
 ------------------
 
-.. autofunction:: qibochem.ansatz.hardware_efficient.hea
+.. autofunction:: qibochem.ansatz.hardware_efficient.he_circuit
 
 
 Hartree-Fock
@@ -21,8 +21,9 @@ Unitary Coupled Cluster
 
 .. autofunction:: qibochem.ansatz.ucc.ucc_circuit
 
+.. autofunction:: qibochem.ansatz.ucc.ucc_ansatz
 
 Basis rotation
 --------------
 
-.. autofunction:: qibochem.ansatz.basis_rotation.br_circuit
+.. autofunction:: qibochem.ansatz.basis_rotation.basis_rotation_gates

doc/source/api-reference/measurement.rst

@@ -2,6 +2,24 @@
 Measurement
 ===========
 
-This section covers the API reference for obtaining the expectation value of some (molecular) Hamiltonian
+This section covers the API reference for obtaining the expectation value of a (molecular) Hamiltonian, either from a
+state vector simulation, or from sample measurements.
 
-.. autofunction:: qibochem.measurement.expectation.expectation
+Expectation value of Hamiltonian
+--------------------------------
+
+.. autofunction:: qibochem.measurement.result.expectation
+
+.. _expectation-samples:
+
+.. autofunction:: qibochem.measurement.result.expectation_from_samples
+
+Measurement cost reduction
+--------------------------
+
+The following functions are used for reducing and optimising the measurement cost of obtaining the Hamiltonian
+expectation value when sample measurements are used.
+
+.. autofunction:: qibochem.measurement.optimization.measurement_basis_rotations
+
+.. autofunction:: qibochem.measurement.optimization.allocate_shots

doc/source/appendix/citing-qibochem.rst

@@ -0,0 +1,22 @@
+Publications
+============
+
+If Qibochem has been significant in your research, and you would like to acknowledge
+the project in your academic publication, we suggest citing the following documents:
+
+Software References in Zenodo
+-----------------------------
+
+Wong Zicheng, Adrian Mak, Tan Le, Stefano Carrazza, Alessandro Candido, & Ye Jun. (2024). qiboteam/qibochem: Qibochem 0.0.1 (v0.0.1). Zenodo. https://doi.org/10.5281/zenodo.10473173
+
+Authorship Guideline
+--------------------
+
+In order to appear as an author of a Qibochem publication (paper, proceedings, etc)
+each author must fullfil the following requirements:
+
+* Participate to the official meetings.
+
+* Contribute to the code with documented commits.
+
+* Contribute to the manuscript elaboration.

doc/source/getting-started/index.rst

@@ -7,5 +7,5 @@ This section covers how to install Qibochem and a basic example presenting the f
 .. toctree::
     :maxdepth: 1
 
-    installation
     quickstart
+    installation

doc/source/getting-started/installation.rst

@@ -5,31 +5,48 @@ Supported operating systems
 ---------------------------
 
 At the moment, Qibochem is only actively supported on Linux and MacOS systems.
-In principle, it should be possible to install and run Qibochem on Windows, but with the caveat that the PySCF driver for obtaining molecular integrals is not available on Windows systems.
+In principle, it should be possible to install and run Qibochem on Windows as well (see below).
 
 .. note::
       Qibochem is supported for Python >= 3.9.
 
-..
-  TODO: update further when package released on pypi
+Installing with pip
+-------------------
+
+The latest PyPI release of Qibochem can be installed directly with ``pip``:
+
+.. code-block::
+
+    pip install qibochem
+
+The ``pip`` program will download and install all of the required dependencies for Qibochem.
+
+.. note::
+    For larger simulations, it may be desirable to install `other backend drivers <https://qibo.science/qibo/stable/getting-started/backends.html/>`_ for Qibo as well.
 
 Installing from source
 ----------------------
 
-Using ``pip install``:
+The latest (development) version of Qibochem can be installed directly from the source repository on Github:
 
 .. code-block::
 
     git clone https://github.com/qiboteam/qibochem.git
     cd qibochem
     pip install .
 
-Using ``poetry``:
+Installing on Windows
+---------------------
 
-.. code-block::
+The simplest way to get Qibochem on a Windows system is to use `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install/>`_, and install Linux on Windows.
+Qibochem can then be installed directly using ``pip`` as described above.
 
-    git clone https://github.com/qiboteam/qibochem.git
-    cd qibochem
-    poetry install
+Otherwise, Qibochem will have to be installed from source, and after some modifications to the source code.
+
+.. warning::
+
+    Native Windows systems are not actively supported, so in principle possible doesn't necessarily mean that the below instructions will yield a working version of Qibochem!
 
-For larger simulations, it may be desirable to install `other backend drivers <https://qibo.science/qibo/stable/getting-started/backends.html/>`_ for Qibo as well.
+First, but the PySCF driver for obtaining molecular integrals is not available on Windows systems, so the relevant line in ``pyproject.toml`` has to be commented out.
+The alternative driver for Windows is PSI4; after installing PSI4, uncomment out the ``run_psi4`` function in the ``Molecule`` class.
+After these changes, return to the ``qibochem`` folder and run ``pip install .``

doc/source/getting-started/quickstart.rst

@@ -1,18 +1,21 @@
 Quick start
 -----------
 
-..
-  TODO: Add pip install when package on pypi
+To quickly install and run Qibochem, open a terminal with ``python >= 3.9`` and type:
+
+.. code-block::
+
+   pip install qibochem
 
 Here is an example of building the UCCD ansatz with the H2 molecule to test your installation:
 
 .. testcode::
+
     import numpy as np
     from qibo.models import VQE
 
     from qibochem.driver.molecule import Molecule
-    from qibochem.ansatz.hf_reference import hf_circuit
-    from qibochem.ansatz.ucc import ucc_circuit
+    from qibochem.ansatz import hf_circuit, ucc_circuit
 
     # Define the H2 molecule and obtain its 1-/2- electron integrals with PySCF
     h2 = Molecule([('H', (0.0, 0.0, 0.0)), ('H', (0.0, 0.0, 0.7))])
@@ -21,7 +24,7 @@ Here is an example of building the UCCD ansatz with the H2 molecule to test your
     hamiltonian = h2.hamiltonian()
 
     # Build a UCC circuit ansatz for running VQE
-    circuit = hf_circuit(h2.nso, sum(h2.nelec))
+    circuit = hf_circuit(h2.nso, h2.nelec)
     circuit += ucc_circuit(h2.nso, [0, 1, 2, 3])
 
     # Create and run the VQE, starting with random initial parameters
@@ -30,6 +33,5 @@ Here is an example of building the UCCD ansatz with the H2 molecule to test your
     initial_parameters = np.random.uniform(0.0, 2*np.pi, 8)
     best, params, extra = vqe.minimize(initial_parameters)
 
-
 ..
   TODO: Another example with measurements

doc/source/index.rst

@@ -4,6 +4,9 @@
 What is Qibochem?
 =================
 
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.10473173.svg
+  :target: https://doi.org/10.5281/zenodo.10473173
+
 Qibochem is a plugin to Qibo for quantum chemistry simulations.
 
 Key features of Qibochem:
@@ -24,7 +27,7 @@ Welcome to the comprehensive documentation for ``Qibochem``! This guide will hel
 you navigate through the various sections and make the most of the resources
 available.
 
-1. **Installation and Setup**: Begin by referring to the
+1. **Getting started**: Begin by referring to the
    :doc:`/getting-started/index` guide to set up the ``Qibochem`` library in your environment.
 
 2. **Tutorials**: Explore the :doc:`/tutorials/index` section for a range of
@@ -54,6 +57,12 @@ Contents
     api-reference/index
     developer-guides/index
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Appendix
+
+    appendix/citing-qibochem
+
 .. toctree::
     :maxdepth: 1
     :caption: Documentation links
@@ -62,7 +71,7 @@ Contents
     Qibolab docs <https://qibo.science/qibolab/stable/>
     Qibocal docs <https://qibo.science/qibocal/stable/>
     Qibosoq docs <https://qibo.science/qibosoq/stable/>
-
+    Qibochem docs <https://qibo.science/qibochem/stable/>
 
 Indices and tables
 ==================