Update chemistry documentation

.pylintdict

@@ -217,6 +217,7 @@ ifortvars
 ign
 ignis
 ij
+ijkl
 ijkm
 ikmj
 imag
@@ -255,6 +256,7 @@ jt
 jth
 jw
 kaicher
+kanav
 ket
 killoran
 kingma
@@ -273,6 +275,7 @@ lih
 lijh
 lin
 linearpaulirotations
+ljik
 lmin
 lnot
 loglikelihood
@@ -377,6 +380,7 @@ outpath
 overfit
 params
 parentname
+pascual
 pauli
 pauli's
 paulis
@@ -481,6 +485,7 @@ sdg
 sdk
 seealso
 seeley
+sergey
 setia
 sgn
 shanno
@@ -507,6 +512,7 @@ subspaces
 succ
 sudo
 superclass
+superfast
 suzuki
 svm
 sx
@@ -590,6 +596,7 @@ xuxv
 xyz
 yao
 yc
+yu
 yy
 zi
 zmatrix

docs/conf.py

@@ -89,6 +89,7 @@
 
 autodoc_default_options = {
     'inherited-members': None,
+    'show-inheritance': None,
 }
 
 

qiskit/chemistry/__init__.py

@@ -11,14 +11,115 @@
 # 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.
-"""
+r"""
 ==============================================================
 Chemistry application stack for Aqua (:mod:`qiskit.chemistry`)
 ==============================================================
-This is the chemistry domain logic....
 
 .. currentmodule:: qiskit.chemistry
 
+This is the chemistry application stack for Aqua that provides for experimentation with chemistry
+domain problems such as ground state energy and excited state energies of molecules.
+
+Overview
+========
+
+This is an overview of the workings of the chemistry stack and how it may be used. There
+are different levels of exposure to its functionality, allowing for experimentation at different
+abstractions. The outline below starts with the flow that provides the most control of the
+process.
+
+A classical chemistry driver is first instantiated, from the available :mod:`~.drivers`,
+by means of a molecule specification, along with other configuration such as basis set and method
+(RHF, ROHF, UHF). This configuration may include custom settings for the specific driver for more
+custom control over the driver's behavior. When the driver is run the output is a mostly driver
+independent :class:`~.QMolecule`. This contains various quantities that were
+computed including one and two-body electron integrals that are used as input
+:class:`~qiskit.chemistry.FermionicOperator`. Mostly driver independent means that these integrals,
+for example, will be there from every driver but the values may differ due to how each underlying
+chemistry library/program computes them. Also some fields in the QMolecule may not be populated by
+all drivers, for instance dipole integrals are not output from the PyQuante driver, and hence the
+dipole moment cannot be computed by qiskit.chemistry when using this driver. The FermionicOperator
+once created can then be converted/mapped to a qubit operator for use as input to an Aqua
+algorithms. The operator must be in qubit form at this stage since the execution target of the
+algorithm will be a quantum device, or simulator ,comprised of qubits and the mapping is needed as
+qubits behave differently than fermions. Once the algorithm is run it will compute the electronic
+part of the quantity, such as the electronic ground state energy. To get the total ground state
+energy this can be combined with the nuclear repulsion energy in the QMolecule.
+
+Instead of using the FermionicOperator the :class:`.core.Hamiltonian` may be used. This
+itself uses the FermionicOperator but provides a higher level of function to simplify use. For
+instance the FermionicOperator supports particle-hole transformation and different mappings. And to
+compute dipole moments each of the X, Y and Z dipole integrals must be prepared, as individual
+FermionicOperators, in a like manner to the main electronic energy one, i.e. same transformations,
+and eventually same qubit mapping. The core.Hamiltonian class does all this and more, such as
+orbital reductions, frozen core and automatic symmetry reduction. When run with a QMolecule output
+from a driver it produces qubit operators that can be given directly to Aqua algorithms for
+the computation. Also available are several properties, such as number of particles and number of
+orbitals, that are needed to correctly instantiate chemistry specific components such as
+:class:`~.components.variational_forms.UCCSD` and :class:`~.components.initial_states.HartreeFock`.
+Using the FermionicOperator directly requires taking the initial values for the QMolecule and then
+keeping track of any changes based on any orbital elimination and/or freezing, and/or Z2Symmetry
+reductions that are done. Once the output qubit operators have been used with an Aqua algorithm,
+to compute the electronic result, this result can be fed back to the core.Hamiltonian, to
+:meth:`~.core.Hamiltonian.process_algorithm_result` which will then compute a final total result
+including a user friendly formatted text result that may be printed.
+
+Lastly the chemistry :mod:`~.applications` may be used. These are given a chemistry driver and,
+in the case of :class:`~applications.MolecularGroundStateEnergy` an optional instance of an Aqua
+:class:`~qiskit.aqua.algorithms.MinimumEigensolver`, such as :class:`~qiskit.aqua.algorithms.VQE`.
+Optional since components such as :class:`~.components.variational_forms.UCCSD` need certain
+information that may be unknown at this point. So alternatively, when its method
+:meth:`~applications.MolecularGroundStateEnergy.compute_energy` is run a callback can be provided
+which will later be passed information, such as number of particles and orbitals, and allow a
+complete MinimumEigensolver to be built using say UCCSD with HartreeFock, and subsequently returned
+to the application and run. MinimumEigensolver itself uses the core.Hamiltonian class wrapping
+it to form this high level application.
+
+Mappings
+++++++++
+To map the FermionicOperator to a qubit operator Qiskit Chemistry supports the following mappings:
+
+Jordan Wigner
+    The `Jordan-Wigner transformation <https://rd.springer.com/article/10.1007%2FBF01331938>`__,
+    maps spin operators onto fermionic creation and annihilation operators.
+    It was proposed by Ernst Pascual Jordan and Eugene Paul Wigner
+    for one-dimensional lattice models,
+    but now two-dimensional analogues of the transformation have also been created.
+    The Jordan–Wigner transformation is often used to exactly solve 1D spin-chains
+    by transforming the spin operators to fermionic operators and then diagonalizing
+    in the fermionic basis.
+
+Parity
+    The `parity-mapping transformation <https://arxiv.org/abs/1701.08213>`__.
+    optimizes encodings of fermionic many-body systems by qubits
+    in the presence of symmetries.
+    Such encodings eliminate redundant degrees of freedom in a way that preserves
+    a simple structure of the system Hamiltonian enabling quantum simulations with fewer qubits.
+
+Bravyi-Kitaev
+    Also known as *binary-tree-based qubit mapping*, the `Bravyi-Kitaev transformation
+    <https://www.sciencedirect.com/science/article/pii/S0003491602962548>`__
+    is a method of mapping the occupation state of a
+    fermionic system onto qubits. This transformation maps the Hamiltonian of :math:`n`
+    interacting fermions to an :math:`\mathcal{O}(\log n)`
+    local Hamiltonian of :math:`n` qubits.
+    This is an improvement in locality over the Jordan–Wigner transformation, which results
+    in an :math:`\mathcal{O}(n)` local qubit Hamiltonian.
+    The Bravyi–Kitaev transformation was proposed by Sergey B. Bravyi and Alexei Yu. Kitaev.
+
+Bravyi-Kitaev Superfast
+    `Bravyi-Kitaev Superfast (BKSF) <https://aip.scitation.org/doi/10.1063/1.5019371>`__ algorithm
+    is a mapping from fermionic operators to qubit operators. BKSF algorithm defines an abstract
+    model where the fermionic modes are mapped to vertices of an interaction graph. The edges of
+    the graph correspond to the interaction between the modes. The graph can be constructed from
+    the Hamiltonian. The simulation is done by putting qubits on the edges of the graph. Each
+    fermionic operator costs :math:`\mathcal{O}(d)` qubit operations, where :math:`d` is the
+    degree of the interaction graph. The BKSF was proposed by Kanav Setia and James D. Whitfield.
+
+
+The classes and submodules of qiskit.chemistry are now listed for reference:
+
 Chemistry Error
 ===============
 

qiskit/chemistry/algorithms/__init__.py

@@ -15,30 +15,37 @@
 """
 Chemistry specific Aqua algorithms (:mod:`qiskit.chemistry.algorithms`)
 =======================================================================
-These are chemistry specific Aqua algorithms where they inherit from
-:class:`QuantumAlgorithm`. As they rely on chemistry specific knowledge
-and/or functions they live here rather than in Aqua.
+These are chemistry specific algorithms for Aqua. As they rely on chemistry
+specific knowledge and/or function they are here in chemistry rather than in Aqua.
 
 .. currentmodule:: qiskit.chemistry.algorithms
 
-Chemistry Quantum Algorithms
-============================
+Chemistry Algorithms
+====================
+These are algorithms configured and/or functioning using chemistry specific knowledge. See also
+the Aqua :mod:`~qiskit.aqua.algorithms` for other algorithms in these categories which may also
+be used for chemistry problems such as :class:`~qiskit.aqua.algorithms.VQE`.
+
+Eigensolvers
+++++++++++++
+Algorithms that can find the eigenvalues of an operator, i.e. excited states for chemistry.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
    QEomVQE
-   VQEAdapt
+   QEomEE
 
-Chemistry Classical Algorithms
-==============================
+Minimum Eigensolvers
+++++++++++++++++++++
+Algorithms that can find the minimum eigenvalue of an operator, i.e. ground state for chemistry.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-   QEomEE
+   VQEAdapt
 
 """
 

qiskit/chemistry/algorithms/eigen_solvers/q_eom_ee.py

@@ -27,7 +27,7 @@
 
 
 class QEomEE(NumPyMinimumEigensolver):
-    """ QEomEE algorithm """
+    """ QEomEE algorithm (classical) """
 
     def __init__(self, operator: BaseOperator, num_orbitals: int,
                  num_particles: Union[List[int], int],

qiskit/chemistry/drivers/__init__.py

@@ -15,14 +15,36 @@
 """
 Chemistry Drivers (:mod:`qiskit.chemistry.drivers`)
 =========================================================
-Chemistry drivers take a molecule configuration as input, and run classical
-software to produce a :class:`QMolecule` containing information the
-chemistry stacks needs to produce input for a Quantum Algorithm. Such information
-includes one and two-body electronic integrals, dipole integrals, nuclear
-repulsion energy and more.
-
 .. currentmodule:: qiskit.chemistry.drivers
 
+Qiskit Chemistry requires a computational chemistry program or library, accessed via a chemistry
+*driver*, to be installed on the system for the electronic-structure computation of a given
+molecule. A driver is created with a molecular configuration, passed in the format compatible with
+that particular driver. This allows custom configuration specific to each computational chemistry
+program or library to be passed.
+
+Qiskit Chemistry thus allows the user to configure a chemistry problem in a way that a chemist
+already using the underlying chemistry program or library will be familiar with. The driver is
+used to compute some intermediate data, which later will be used to form the input to an Aqua
+algorithm.  Such intermediate data, is populated into a :class:`~qiskit.chemistry.QMolecule`
+object and includes the following for example:
+
+1. One- and two-body integrals in Molecular Orbital (MO) basis
+2. Dipole integrals
+3. Molecular orbital coefficients
+4. Hartree-Fock energy
+5. Nuclear repulsion energy
+
+Once extracted, the structure of this intermediate data is independent of the driver that was
+used to compute it.  However the values and level of accuracy of such data will depend on the
+underlying chemistry program or library used by the specific driver.
+
+Qiskit Chemistry offers the option to serialize the Qmolecule data in a binary format known as
+`Hierarchical Data Format 5 (HDF5) <https://support.hdfgroup.org/HDF5/>`__.
+This is done to allow chemists to reuse the same input data in the future and to enable researchers
+to exchange input data with each other --- which is especially useful to researchers who may not
+have particular computational chemistry drivers installed on their computers.
+
 Driver Base Class
 =================
 
@@ -60,21 +82,26 @@
 
    qiskit.chemistry.drivers.gaussiand
    qiskit.chemistry.drivers.psi4d
-   qiskit.chemistry.drivers.pyscfd
    qiskit.chemistry.drivers.pyquanted
+   qiskit.chemistry.drivers.pyscfd
 
-The :class:`HDF5Driver` reads and writes molecular data from a file and is not dependent
-on any external chemistry program/library and needs no special install.
+The :class:`HDF5Driver` reads molecular data from a pre-existing HDF5 file, as saved from a
+:class:`~qiskit.chemistry.QMolecule`, and is not dependent on any external chemistry
+program/library and needs no special install.
+
+The :class:`FCIDumpDriver` likewise reads from a pre-existing file in this case a standard
+FCIDump file and again needs no special install.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
    GaussianDriver
-   HDF5Driver
    PSI4Driver
    PyQuanteDriver
    PySCFDriver
+   HDF5Driver
+   FCIDumpDriver
 
 """
 from ._basedriver import BaseDriver, UnitsType, HFMethodType

qiskit/chemistry/drivers/_basedriver.py

@@ -2,7 +2,7 @@
 
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018, 2019.
+# (C) Copyright IBM 2018, 2020.
 #
 # 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
@@ -19,6 +19,8 @@
 from abc import ABC, abstractmethod
 from enum import Enum
 
+from qiskit.chemistry import QMolecule
+
 
 class UnitsType(Enum):
     """ Units Type Enum """
@@ -35,15 +37,19 @@ class HFMethodType(Enum):
 
 class BaseDriver(ABC):
     """
-    Base class for Drivers.
-
+    Base class for Qiskit Chemistry Drivers.
     """
 
     @abstractmethod
     def __init__(self):
         pass
 
     @abstractmethod
-    def run(self):
-        """ runs driver """
+    def run(self) -> QMolecule:
+        """
+        Runs driver to produce a QMolecule output.
+
+        Returns:
+            A QMolecule containing the molecular data.
+        """
         pass

qiskit/chemistry/drivers/fcidumpd/fcidumpdriver.py

@@ -22,7 +22,8 @@
 
 
 class FCIDumpDriver(BaseDriver):
-    """Python implementation of an FCIDump driver.
+    """
+    Qiskit chemistry driver reading an FCIDump file.
 
     The FCIDump format is partially defined in Knowles1989.