..
    : 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/>
    :
    : --

.. _user_iodata_naming:

Naming conventions in PyBEST
############################

To guarantee full functionality of PyBEST, especially if you wish to read in
your own data files using a format that is not direclty supported by PyBEST,
we recommend that all data is stored in an :py:class:`~pybest.io.iodata.IOData`
container exploiting **predefined**, **PyBEST-specific** labels.
If you work with file formats that are supported in PyBEST and handled by
PyBEST internally, you do not need to worry about the naming convention as
this is handled automatically.

The following table summarizes all frequently used PyBEST objects, their attribute
names in the :py:class:`~pybest.io.iodata.IOData` container, and which
:py:class:`~pybest.linalg.base.LinalgFactory` class is typically associated
with such an object.

+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | Object              | attribute name in                    | object type                                         |       label           |
|                       | :py:class:`~pybest.io.iodata.IOData` |                                                     |                       |
+=======================+======================================+=====================================================+=======================+
| | list of atoms       |  atom                                |           ``list`` of ``str`` or ``int``            |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | xyz coordinates     |  coordinates                         |           ``np.array`` of ``float``                 |       --              |
| | [bohr]              |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | Atomic basis set    |  gobasis                             |   :py:class:`~pybest.gbasis.py_basis.Basis`         |       --              |
| | (Gaussian orbitals) |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | kinetic energy      |       kin                            |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |       kin             |
| | integrals           |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | nuclear attraction  |       ne                             |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |        ne             |
| | integrals           |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | electron repulsion  |       eri                            |   :py:class:`~pybest.linalg.dense.DenseFourIndex`   |        eri            |
| | integrals           |                                      +-----------------------------------------------------+-----------------------+
|                       |                                      |  :py:class:`~pybest.linalg.cholesky.CholeskyIndex`  |        eri            |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | nuclear repulsion   |  nn (incl. in e_core)                |           ``float``                                 | nn (e_core)           |
| | integrals           |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | one-electron        |    one                               |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |      one              |
| | integrals           |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | two-electron        |    two                               |   :py:class:`~pybest.linalg.dense.DenseFourIndex`   |      two              |
| | integrals           |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | orbitals            |    orb_a  (restricted/alpha spin)    |   :py:class:`~pybest.linalg.dense.DenseOrbital`     |      --               |
|                       +--------------------------------------+-----------------------------------------------------+-----------------------+
|                       |    orb_b  (beta spin)                |   :py:class:`~pybest.linalg.dense.DenseOrbital`     |      --               |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| |  overlap integrals  |     olp                              |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |       olp             |
| |                     |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | electron pair       |     t_p                              |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |      t_p              |
| | amplitudes          |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | singles amplitudes  |     t_1                              |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |      t_1              |
|                       |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | doubles amplitudes  |     t_2                              |   :py:class:`~pybest.linalg.dense.DenseFourIndex`   |      t_2              |
| | (including pairs)   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | :math:`\Lambda` for |     l_p                              |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |      l_p              |
| | electron pairs      |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | :math:`\Lambda` for |     l_1                              |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |      l_1              |
| | singles             |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | :math:`\Lambda` for |     l_2                              |   :py:class:`~pybest.linalg.dense.DenseFourIndex`   |      l_2              |
| | doubles (incl pairs)|                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | 1-RDM               |     dm_1                             |   (``dict`` of)                                     |       --              |
|                       |                                      |   :py:class:`~pybest.linalg.dense.DenseOneIndex`    |                       |
|                       |                                      +-----------------------------------------------------+-----------------------+
|                       |                                      |   (``dict`` of)                                     |       --              |
|                       |                                      |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | 2-RDM               |     dm_2                             |   ``dict`` of                                       |       --              |
|                       |                                      |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |                       |
|                       |                                      +-----------------------------------------------------+-----------------------+
|                       |                                      |  :py:class:`~pybest.linalg.dense.DenseFourIndex`    |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | 3-RDM               |     dm_3                             |   ``dict`` of                                       |       --              |
|                       |                                      |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | 4-RDM               |     dm_4                             |   ``dict`` of                                       |       --              |
|                       |                                      |   :py:class:`~pybest.linalg.dense.DenseTwoIndex`    |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | kinetic energy      |  e_kin                               |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | nuclear attr energy |  e_ne                                |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | nuclear repul energy|  e_nn                                |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | Coulomb energy (el) |  e_hartree                           |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | exchange energy (el)|  e_x_hf                              |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | total energy        |  e_tot                               |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | reference energy    |  e_ref                               |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | correlation energy  |  e_corr                              |           ``float``                                 |       --              |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_s                            |           ``float``                                 |       --              |
|   :math:`\hat{T}_1`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_p                            |           ``float``                                 |       --              |
|   :math:`\hat{T}_p`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_d                            |           ``float``                                 |       --              |
|   :math:`\hat{T}_2`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_s0                           |           ``float``                                 |       --              |
| | :math:`\Omega=0` of |                                      |                                                     |                       |
|   :math:`\hat{T}_2`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_s2                           |           ``float``                                 |       --              |
| | :math:`\Omega=2` of |                                      |                                                     |                       |
|   :math:`\hat{T}_2`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+
| | corr energy wrt     |  e_corr_s4                           |           ``float``                                 |       --              |
| | :math:`\Omega=4` of |                                      |                                                     |                       |
|   :math:`\hat{T}_2`   |                                      |                                                     |                       |
+-----------------------+--------------------------------------+-----------------------------------------------------+-----------------------+