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