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

.. _hamiltonian_io:

Dumping/Loading a Hamiltonian to/from a file
############################################

Before reading this section, please refer to :ref:`Input/Output Operations: the IOData Container <user_iodata>`
for more informations on how to load and dump data in different data file
formats with PyBEST. For reasons of completeness, the instruction on how to
dump/load a Hamiltonian in PyBEST are summarized here. Nonetheless, we recommend
that the user should know the behavior of and basic operations on the
:py:class:`~pybest.io.iodata.IOData` class before continuing reading.

PyBEST supports two formats for Hamiltonians: (i) an internal binary format based
on HDF5 (extension ``.h5``) and (ii) Molpro's FCIDUMP ASCII format (containing ``FCIDUMP``
somewhere in the file name). The internal format is more flexible and can store
Hamiltonians in various ways, for instance, all one-electron integrals can be
stored separately. The FCIDUMP format is more restricted
but can be used to interface PyBEST with different codes, e.g., Molpro or
Dalton (both can generate FCIDUMP files).


.. _hamiltonian_io_internal:

PyBEST's internal format
=========================

Dumping
-------

You can store all one- and two-electron integrals in the atomic-orbital (AO) basis.
For example, to store the molecular Hamiltonian of the water molecule, follow
the code snippet below

.. literalinclude:: ../src/pybest/data/examples/hamiltonian/dump_internal_ao.py
    :caption: data/examples/hamiltonian/dump_internal_ao.py
    :lines: 3-

The internal format will store all Hamiltonian terms (that is, the integrals and core
energy) as attributes of the :py:class:`~pybest.io.iodata.IOData` instance.
The :py:class:`~pybest.io.iodata.IOData` container class is rather flexible
and allows you to update the container on the fly. To delete or add attributes,
use e.g. ``del mol.title`` or ``mol.egg = "spam"`` (see also
:ref:`Filling the IOData container <user_iodata_dumping_filling>` for how to
manipulate the container).

In the HDF5 file, all data is stored in binary form with full precision, which
means that all significant digits are written to file. In the example above, the
dumped HDF5 file will have the following layout:

.. code-block:: text

    $ h5dump -n hamiltonian_ao.h5
    HDF5 "hamiltonian_ao.h5" {
    FILE_CONTENTS {
     group      /
     dataset    /e_core
     group      /eri
     dataset    /eri/array
     group      /kin
     dataset    /kin/array
     group      /lf
     group      /ne
     dataset    /ne/array
     }
    }



Loading
-------

You can load one- and two-electron integrals stored in PyBEST's internal format,
as follows:

.. literalinclude:: ../src/pybest/data/examples/hamiltonian/load_internal_ao.py
    :caption: data/examples/hamiltonian/load_internal_ao.py
    :lines: 3-


.. _hamiltonian_io_fcidump:

FCIDUMP format
==============

Dumping
-------

While the internal (binary) format can only be handled by PyBEST, the FCIDUMP
format stores the Hamiltonian in ASCII format and can be easily read in by other
codes.
In the current version of PyBEST, the FCIDUMP format has the following
restrictions:

1. One-electron integrals (e.g., the kinetic energy and nuclear attraction)
   are all stored as one single term (FCIDUMP standard).
2. Integrals can only be stored in a restricted (MO) basis set, that is,
   unrestricted orbitals (alpha and beta orbitals) are not supported, yet.
3. The two-electron integrals must be stored as a ``DenseFourIndex`` object,
   that is, the Cholesky decomposition of the ERI is not supported.

The FCIDUMP format is generally used for storing integrals in the MO basis.
Thus, the one- and two-electron integrals need to be first transformed from the
AO to some MO basis. In the following example, we will assume that a set of
one- (``one``) and two-electron integrals (``two``) are already available.
See section :ref:`hamiltonian_transformation` for a detailed instruction on
how to transform (and store) integrals into the MO basis.
Furthermore, we have an additional energy associated with some external potential
labeled as ``e_core``.
To store all (pre-transformed) integrals using the FCIDUMP format, proceed as
follows

.. literalinclude:: ../src/pybest/data/examples/hamiltonian/dump_fcidump_mo.py
    :caption: data/examples/hamiltonian/dump_fcidump_mo.py
    :lines: 52-

In this example, we set the :py:class:`~pybest.io.iodata.IOData` attributes by
using keyword arguments in the constructor. The complete example is also shown
below in :ref:`examples_ham`.

.. note::

    Although the FCIDUMP format stores all one-electron integrals as one term,
    PyBEST can handle them separately. The FCIDUMP dump function will combine
    them into one single term automatically.

The file ``hamiltonian_mo.FCIDUMP`` will contain the following:

.. code-block:: text

     &FCI NORB=28,NELEC=20,MS2=0,
      ORBSYM= 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
      ISYM=1
     &END
     3.1025487346395235e+00    1    1    1    1
    -2.0955127330533898e-06    2    1    1    1
     2.9025424092728871e+00    2    1    2    1
     3.1025489371112021e+00    2    2    1    1
     2.0955125859036790e-06    2    2    2    1
     3.1025491395905633e+00    2    2    2    2
    -3.4893251387724522e-01    3    1    1    1
    .
    .
    -2.4806545706468341e-16   28   26    0    0
    -4.1199682554449168e-16   28   27    0    0
    -6.9042050091456133e+00   28   28    0    0
     2.0000000009826579e+01    0    0    0    0

This file is divided into two blocks. The first block (between ``&FCI`` and
``&END``) contains system-specific information:

    :NORB: number of orbitals/basis functions
    :NELEC: number of electrons
    :MS2: spin projection
    :ORBSYM: irreducible representation of each orbital
    :ISYM: total symmetry of the wave function

The second block (after ``&END``) contains the one- and two-electron integrals
and the core energy in the following order

1. All symmetry-unique elements of the two-electron integrals are listed,
   where the first column is the value of the integral, followed by the orbital
   indices. Note that the orbital indices start from 1 (Fortran indexing).
   The last four columns encode the orbital indices (``i j k l``) in
   chemists' notation,

  .. math::

      (ij\vert kl) = \langle ik \vert jl \rangle = \int \phi_i^*(\mathbf{x}_1)
      \phi_k^*(\mathbf{x}_2) \frac{1}{r_{12}} \phi_j(\mathbf{x}_1) \phi_l(\mathbf{x}_2)
      d\mathbf{x}_1 d\mathbf{x}_2

2. Then, all symmetry-unique elements of the one-electron integrals are listed,
   where the first column is the value of the integral, followed by the orbital
   indices. Note that the last two columns contain zeros.

3. The core energy (for instance, the nuclear repulsion term, etc.) is written
   on the last line with all orbital indices equal to 0.

PyBEST does not (yet) support point group symmetries (only :math:`C_1`). Thus, all orbitals will
be assigned the symmetry label 1, while the total symmetry of the wave function
will be set to 1.

Loading
-------

You can load integrals, stored in an FCIDUMP file, as follows

.. literalinclude:: ../src/pybest/data/examples/hamiltonian/load_fcidump_mo.py
    :caption: data/examples/hamiltonian/load_fcidump_mo.py
    :lines: 7-12

The resulting :py:class:`~pybest.io.iodata.IOData` container ``data`` has the
following attributes

    :one:   All one-electron integrals combined in one single term
    :two:   The two-electron repulsion integrals
    :e_core:    The core energy
    :nelec: The number of electrons comprised in the active space
    :ms2:   The spint projection
    :lf:    An instance of the :py:class:`~pybest.linalg.dense.DenseLinalgFactory`
    :orb_a: An instance of :py:class:`~pybest.linalg.dense.DenseOrbital`
            (created under the assumption that the orbitals are **orthonormal**)
    :olp:   An overlap matrix (created under the assumption that the orbitals are
            **orthonormal**)

These attributes can be then passed individually to some wave function method.

.. _examples_ham:

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

Several complete examples can be found in the directory ``data/examples/hamiltonian``.

Dumping in the FCIDUMP format: the Ne dimer
-------------------------------------------

This is a basic example on how to dump all one- and two-electron integrals in
the MO basis for the Neon dimer using the FCIDUMP format in PyBEST.
This script performs an RHF calculation followed by a transfomration of the
Hamiltonian into the MO basis for the Neon dimer using the cc-pVDZ basis set.

.. literalinclude:: ../src/pybest/data/examples/hamiltonian/dump_fcidump_mo.py
    :caption: data/examples/hamiltonian/dump_fcidump_mo.py
    :lines: 3-