..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST 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.
    :
    : PyBEST 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 <http://www.gnu.org/licenses/>
    : --

.. _localization:

Localization of molecular orbitals
##################################

In general, the localization algorithm optimizes some localization function by
an orthogonal transformation of the orbitals. Given orbitals
:math:`\vert i \rangle`, the localized orbital :math:`\vert \tilde{i} \rangle`
can be obtained by some transformation

.. math::

    \vert \tilde{i} \rangle = \sum_k \vert k \rangle \exp(-\mathbf{\kappa})_{ki},

where

.. math::

    \mathbf{\kappa} = \sum_{k > l} \kappa_{kl} (a^\dagger_k a_l - a^\dagger_l a_k)

and :math:`\kappa_{kl}` is determined by the optimization of the localization function.

Many of the localization schemes, and thus
the result of the localization, differ by the localization function. The localization
function somehow measures the localization of the orbitals. So far, PyBEST only
supports the Pipek-Mezey localization. [pipek1989]_


.. _pipek-mezey:

Pipek-Mezey localization
========================

In the Pipek-Mezey scheme, the Pipek-Mezey localization function, :math:`D`, is maximized.

.. math::

    D = \sum_{i} \sum_{A \in \textrm{atoms}} (Q_{ii}^A)^2,

where :math:`\mathbf{Q}^A` is the atomic population matrix. The atomic population
matrix can be obtained from the overlap of the atomic basis, the molecular
orbitals from the atomic basis, the occupation of each molecular orbital, and
some weighted projection of atomic basis function within each atom.

For example, if the Mulliken population analysis is used, the projectors are
obtained through :py:meth:`~pybest.part.mulliken.get_mulliken_operators`.
The Pipek-Mezey localization is initialized through a series of
:py:class:`~pybest.localization.localization.PipekMezey` function calls,
:py:meth:`~pybest.localization.localization.Localization.__call__`.

.. note::

    The virtual and occupied blocks are localized separately. Thus, each block
    requires a separate function call.

The code snippet below summarizes all required steps (see also
:ref:`user_orbitals_localization`, where all arguments are explained)

.. literalinclude:: ../src/pybest/data/examples/localization/water_pm.py
    :lines: 44-59


Example Python scripts
======================

Pipek-Mezey localization of restricted Hartree-Fock orbitals for the water molecule
-----------------------------------------------------------------------------------

This is a basic example on how to perform a Pipek-Mezey localization in PyBEST.
This script performs a Pipek-Mezey localization for the water molecule using
the cc-pVDZ basis set and Mulliken projectors.
The localized orbitals are then dumped to disk in the molden file format
(see also :ref:`user_orbitals_molden`).

.. literalinclude:: ../src/pybest/data/examples/localization/water_pm.py
    :caption: data/examples/localization/water_pm.py
    :lines: 3-