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

Reading data from file
######################

The current version of PyBEST supports the following file formats to read
specific wave function information from disk,

+---------------+-----------------------------------------------------------+
| File format   ||                Description                               |
+===============+===========================================================+
| - .h5         || PyBEST's internal format. This format allows you to read |
|               || all PyBEST objects from a binary file. All internal      |
|               || checkpoint files that are dump to disk use this format.  |
+---------------+-----------------------------------------------------------+
| - .xyz        || Read some molecular coordinates form an xyz file. By     |
|               || default all coordinates are transformed from Angstrom to |
|               || bohr (atomic units).                                     |
+---------------+-----------------------------------------------------------+
| - .molden     || Read orbitals, coordinates, and basis set information    |
|               || from a molden file. This works for basis sets that       |
|               || include up to g functions.                               |
+---------------+-----------------------------------------------------------+
| - .mkl        || Read orbitals, coordinates, and basis set information    |
|               || from a molekel file.                                     |
+---------------+-----------------------------------------------------------+
| - .FCIDUMP    || Read Hamiltonian (including the external terms) in the   |
|               || Molpro FCIDUMP format. All one-electron integrals are    |
|               || contracted to one single term. PyBEST also return the    |
|               || molecular orbitals and overlap matrix, assuming that the |
|               || molecular orbitals form an orthonormal set.              |
+---------------+-----------------------------------------------------------+

When reading data from one of the above mentioned file formats, PyBEST will
assign it to some :py:class:`~pybest.io.iodata.IOData` container. The wave function
or molecular information are thus stored as its attributes using the default
attribute names defined in :ref:`user_iodata_naming`.

.. note::

    If you use the internal format to store your own checkpoint files and you
    choose different variable names, PyBEST stores the corresponding objects
    under the user-defined attribute names. If such a checkpoint file is read in,
    those attributes are accessible under the user-defined names. Note, however,
    that some operations might not be fully supported if you decide to break
    PyBEST's naming convention.

Similar to the dumping procedure (:ref:`user_iodata_dumping`), PyBEST automatically
recognizes the (supported) file format: the :py:meth:`~pybest.io.iodata.IOData.from_file`
method stores the corresponding date in an instance of the :py:class:`~pybest.io.iodata.IOData`
container,

.. code-block:: python

    # Read data from some internal (checkpoint) file and store it to the IOData
    # container data
    # ---------------------------------------------
    data = IOData.from_file('checkpoint.h5')

Changing the file extension to one of the supported file formats mentioned
above will steer PyBEST's reading behavior.


Accessing the :py:class:`~pybest.io.iodata.IOData` container
============================================================

When reading data from disk using the :py:meth:`~pybest.io.iodata.IOData.from_file`
method, an instance of the :py:class:`~pybest.io.iodata.IOData` container is
created and all data that is contained in the file is stored as attributes of
the container. Once constructed, you can access and modify the corresponding
attributes on the fly. This can be done in a similar manner as explained
in :ref:`user_iodata_dumping`. The code snippet below shows how to assign, update,
and delete attributes (all objects are defined in :ref:`user_iodata_naming`),

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :lines: 8-20


Reading the internal h5 format
==============================

The example below, shows how to read an internal checkpoint file (see also previous
section), which ends
with the file extension ``.h5``, 

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :lines: 8-15


Reading an xyz file
===================

The example below, summarizes all steps to read in molecular coordinates form
an xyz file using the file extension ``.xyz``. The corresponding
:py:class:`~pybest.io.iodata.IOData` container stores the coordinates under
the attribute ``coordinates`` (a ``np.array``), while the atoms are stored
as a ``list`` (either ``str`` or ``int``) under the attribute ``atom``,

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :lines: 22-29


Reading a molden file
=====================

A detailed instruction on how to export orbitals to the molden format can be
found in :ref:`user_orbitals_molden`.
The example below, briefly summarizes how to read in a molden file and how to
access its corresponding attributes,

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :lines: 31-44

Once a molden file has been read in, you can, for instance, use the ``gobasis`` attribute
to calculate some Hamiltonian matrix elements (see :ref:`user_molecularham_matrix_elements`).

Reading a Hamiltonian in the FCIDUMP format
===========================================

A detailed instruction on how to export a Hamiltonian into the FCIDUMP format
can be found in :ref:`hamiltonian_io_fcidump`.
The example below, briefly summarizes how to read in some external Hamiltonian
from a FCIDUMP file and how to access its corresponding attributes,

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :lines: 46-61


.. _examples_io_reading:

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

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

Summary of all supported reading options
----------------------------------------

This is a basic example that summarizes all steps mentioned above, namely, how
to read and access data from the internal ``.h5``, the ``.xyz``, the ``.molden``,
and the ``FCIDUMP`` format.

.. note::

    This example will only works if you execute the dumping example
    :ref:`here <examples_io_dumping>` first.

.. literalinclude:: ../src/pybest/data/examples/iodata/reading.py
    :caption: data/examples/iodata/reading.py
    :lines: 6-