..
DOCUMENTATION BUILT FROM RELEASE: 2.0.2 (Jun 30, 2017)
..
: HORTON: Helpful Open-source Research TOol for N-fermion systems.
: Copyright (C) 2011-2016 The HORTON Development Team
:
: This file is part of HORTON.
:
: HORTON is free software; you can redistribute it and/or
: modify it under the terms of the GNU General Public License
: as published by the Free Software Foundation; either version 3
: of the License, or (at your option) any later version.
:
: HORTON is distributed in the hope that it will be useful,
: but WITHOUT ANY WARRANTY; without even the implied warranty of
: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
: GNU General Public License for more details.
:
: You should have received a copy of the GNU General Public License
: along with this program; if not, see
:
: --
Orbital entanglement analysis
#############################
.. _orbital_entanglement:
Orbital entanglement and orbital correlation
============================================
In quantum chemistry, the interaction between orbitals is commonly used to
understand chemical processes. For example, molecular orbital diagrams, frontier
orbital theory, and ligand field theory all use orbitals to understand and justify
chemical phenomenon. The interaction between orbitals can be quantified through
ideas in entanglement.
Specifically, the interaction between one orbital and all the other orbitals can be
measured by the single-orbital entropy :math:`s(1)_i` (or one-orbital entropy).
It is calculated from the eigenvalues :math:`\omega_{\alpha,i}` of the
one-orbital reduced density matrix (RDM)
.. math::
s(1)_i = -\sum_{\alpha=1}^4 \omega_{\alpha,i}\ln \omega_{\alpha,i}.
The one-orbital RDM is obtained from the N-particle RDM by tracing out all
other orbital degrees of freedom except those of orbital *i*. This leads to an
RDM whose dimension is equal to the dimension of the one-orbital Fock space. For
spatial orbitals, the one-orbital Fock space has a dimension of 4 (one for unoccupied,
one for doubly occupied and two for singly occupied).
Similarly, the two-orbital entropy :math:`s(2)_{i,j}` quantifies the interaction
of an orbital pair :math:`i,j` and all other orbitals. It is calculated from the
eigenvalues of the two-orbital RDM :math:`\omega_{\alpha, i, j}` (with 16
possible states for spatial orbitals)
.. math::
s(2)_{i,j} =-\sum_{\alpha=1}^{16} \omega_{\alpha, i, j} \ln \omega_{\alpha, i, j}.
The total amount of correlation between any pair of orbitals :math:`(i,j)` can
be evaluated from the orbital-pair mutual information. The orbital-pair mutual
information is calculated using the single- and two-orbital entropy and thus
requires the one- and two-orbital RDMs,
.. math::
I_{i|j} = \frac{1}{2} \big(s(2)_{i,j} - s(1)_{i} - s(1)_{j} \big) \big(1 - \delta_{ij}\big),
where :math:`\delta_{ij}` is the Kronecker delta.
Note that a correlated wavefunction is required to have non-zero orbital entanglement
and correlation. In the case of an uncorrelated wavefunction (for instance, a
single Slater determinant) the (orbital) entanglement entropy is zero.
For more information on orbital entanglement and correlation, see ref. [boguslawski2015a]_.
Supported features
==================
Unless mentioned otherwise, the orbital entanglement module only supports restricted
orbitals, ``DenseLinalgFactory`` and ``CholeskyLinalgFactory``. The current
version of HORTON offers
1. :ref:`Calculation of single-orbital entropy and orbital-pair mutual
information for a seniority-zero wavefunction `
Supported wavefunction models are
1. :ref:`AP1roG ` (seniority-zero wavefunction)
.. _orbital_entanglementseniorityzero:
Orbital entanglement and correlation for a seniority zero wavefunction
======================================================================
If you use this module, please cite [boguslawski2015a]_
How to set-up a calculation
---------------------------
To evaluate the single-orbital entropy and orbital-pair mutual information for a
given wavefunction model, the corresponding one and two-particle RDMs need to be calculated
first. Then one- and two-particle RDMs are used to evaluate the one- and two-orbital RDM's
from which the eigenvalues are needed to calculate the single-orbital and
two-orbital entropy.
Given the one- and two-particle RDMs, an instance of the
:py:class:`~horton.orbital_entanglement.orbital_entanglement.orbital_entanglement`
can be created. A function call of this instance,
:py:meth:`~horton.orbital_entanglement.orbital_entanglement.orbital_entanglement.__call__`,
calculates the entanglement and correlation measures.
How to generate correlation diagrams
------------------------------------
To generate the single-orbital entropy diagram and mutual information plot, run
in the terminal:
.. code-block:: bash
horton-entanglement.py threshold init_index final_index
where **threshold** determines the lower cutoff value of the mutual information
and must be given in orders of magnitude (1, 0.1, 0.01, 0.001, etc.). Orbital
correlations that are smaller than **cutoff** will not be displayed in the
mutual information diagram. The arguments **init_index** and **final_index** are
optional arguments. If provided, the single-orbital entropy will be plotted for
orbital indices in the interval [init_index, final_index].
Example Python scripts
======================
Orbital entanglement analysis of an AP1roG wavefunction
-------------------------------------------------------
This is a basic example on how to perform an orbital entanglement analysis in
HORTON. This script performs an orbital-optimized AP1roG calculation, followed
by an orbital entanglement analysis of the AP1roG wavefunction for the water
molecule using the cc-pVDZ basis set.
.. literalinclude :: ../data/examples/orbital_entanglement/water.py
:caption: data/examples/orbital_entanglement/water.py
:lines: 2-