..
: 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_dumping:
Dumping data to file
####################
The current version of PyBEST supports the following file formats to store
data on disk,
+---------------+-----------------------------------------------------------+
| File format || Description |
+===============+===========================================================+
| - .h5 || PyBEST's internal format. This format allows you to store|
| || all PyBEST objects in binary form. All checkpoint files |
| || are dump using the h5 file format. They can be used to |
| || perform restarts. |
+---------------+-----------------------------------------------------------+
| - .xyz || Store molecular coordinates in an xyz file. By default, |
| || all coordinates are converted to Angstrom. |
+---------------+-----------------------------------------------------------+
| - .molden || Store orbitals and basis set information in the molden |
| || file format. PyBEST is interfaced to libint2's molden |
| || reader. This works for basis sets that include up to g |
| || functions. |
+---------------+-----------------------------------------------------------+
| - .FCIDUMP || Dump Hamiltonian (including all external terms) in the |
| || Molpro FCIDUMP format. All one-electron integrals have |
| || to be transformed in the molecular orbital basis. |
| || Furthermore, all one-electron terms have to be provided |
| || as one single term. |
+---------------+-----------------------------------------------------------+
In order to dump data using one of the above mentioned file formats, all data
has to be assigned to an :py:class:`~pybest.io.iodata.IOData` container using
the attribute names defined in :ref:`user_iodata_naming`.
.. note::
If you choose different variable names, some PyBEST operations are not
fully supported and some features might break.
Once filled, the :py:meth:`~pybest.io.iodata.IOData.to_file` method stores
all information contained in the :py:class:`~pybest.io.iodata.IOData` container
to disk. The file format is determined automatically through the file extension,
.. code-block:: python
# Dump IOData container to internal file format
# ---------------------------------------------
data.to_file('checkpoint.h5')
Changing the file extension to one of the supported file formats mentioned
above will steer PyBEST's dumping behavior.
.. _user_iodata_dumping_filling:
Filling the :py:class:`~pybest.io.iodata.IOData` container
==========================================================
In principle, the :py:class:`~pybest.io.iodata.IOData` constructor accepts any
keyword arguments, which is then stored as an attribute. All attributes are
optional. Thus, even an empty :py:class:`~pybest.io.iodata.IOData` container
can be initialized. The :py:class:`~pybest.io.iodata.IOData` container is
rather felixble: once constructed, attributes can be set and removed on the fly.
The code snippet below shows how to **assign, modify, and delete attributes**
(all objects are defined in :ref:`user_iodata_naming`),
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:lines: 43-57
Dumping to the internal h5 format
=================================
The example below summarizes all steps to generate a PyBEST internal checkpoint
file using the file extension ``.h5``,
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:lines: 43-45, 63-65
Dumping an xyz file
===================
The example below, summarizes all steps to export the coordinates into an xyz
file.
First, the atoms and the coordinates need to be stored in the
:py:class:`~pybest.io.iodata.IOData` container. This information is stored
in an :py:class:`~pybest.gbasis.py_basis.Basis` instance (here ``gobasis``)
and can be accessed
using the attributes ``atom`` and ``coordinates``, respectively,
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:lines: 67-74
Dumping 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 dump the orbitals, coordinates,
and atomic basis set to disk using the molden format,
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:lines: 79-83
Dumping to 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 dump the Hamiltonian in the FCIDUMP
format including the transformation from the atomic to the molecular orbital
basis,
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:lines: 96-99
.. _examples_io_dumping:
Example Python scripts
======================
Several complete examples can be found in the directory ``data/examples/iodata``.
Summary of all supported dumping options
----------------------------------------
This is a basic example that summarizes all steps mentioned above, namely, how
to construct, modify, and store data to the internal ``.h5``, the ``.xyz``,
the ``.molden``, and the ``FCIDUMP`` format.
In the example below, a restricted Hartree-Fock calculation is performed in
order to generate some molecular orbitals (see :ref:`user_hf` for a detailed
instruction on Hartree-Fock calculations).
.. literalinclude:: ../src/pybest/data/examples/iodata/dumping.py
:caption: data/examples/iodata/dumping.py
:lines: 3-