.. : 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 : : -- .. _mp2: The Moller-Plesset Perturbation Theory module ############################################# Before reading this section, please read the general introduction mentioned in :ref:`user_posthf_intro`. This part of the Documentation builds upon it. Supported features ================== The MP2 module supports spin-restricted orbitals and the ``DenseLinalgFactory`` and ``CholeskyLinalgFactory``. PyBEST offers additional flavors of perturbation theory with an pCCD reference function (see :ref:`pt2ap1rog`). .. _getstartedmp2: Quick Guide: conventional RMP2 ============================== We assume that you have performed a restricted Hartree-Fock calculation, whose results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``hf_output`` (see :ref:`user_hf`). Furthermore, we will assume the following names for all PyBEST objects :lf: A :py:class:`~pybest.linalg.base.LinalgFactory` instance (see :ref:`user_linalg_intro`). :occ_model: An Aufbau occupation model of the :py:class:`~pybest.scf.occ.AufbauOccModel` class :kin: the kinetic energy integrals :ne: the nucleus-electron attraction integrals :eri: the two-electron repulsion integrals The code snippet below shows how to perform an MP2 calculation in PyBEST, .. code-block:: python mp2 = RMP2(lf, occ_model) mp2_output = mp2(kin, ne, eri, hf_output) The results are returned as an :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``checkpoint_MP2_d.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains the following attributes :e_tot: The total MP2 energy (including all external terms) :e_corr: The MP2 correlation energy :e_ref: The energy of the reference determinant (here, the Hartree-Fock determinant) :t_2: The doubles amplitudes The MP2 module features additional options, which are discussed in greater detail below. Defining a frozen core ---------------------- All post-RHF modules in PyBEST support frozen core orbitals. These orbitals are not included in the amplitude equations. The frozen (core) orbitals are thus by construction doubly occupied. The number of frozen orbitals can be defined when creating an instance of the :py:class:`~pybest.pt.mp2.RMP2` class, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/mp2_frozen_core_water_cc-pvdz.py :lines: 46-50 .. note:: If ``ncore`` is set to some nonzero number, the orbitals are frozen with respect to their order in the ``orb_a`` attribute passed to :py:class:`~pybest.pt.mp2.RMP2`. In general, these are the energetically lowest-lying orbitals or those with the largest occupation numbers. The number of virtual orbitals cannot be change and hence PyBEST assumes all virtual orbitals to be active. All features of the RMP2 module discussed below work with frozen core orbitals. RMP2 with single excitations ============================ The conventional MP2 implementation only accounts for double excitations. The contributions of single excitations can be included by setting the keyword ``singles`` to ``True``, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/mp2_water_cc-pvdz.py :lines: 52-56 .. note:: If canonical Hartree-Fock orbitals are used in MP2 calculations, the singles correction does not have any affect and the energy contribution is thus zero. RMP2 (relaxed) density matrices and RMP2 natural orbitals ========================================================= PyBEST also supports the calculation of (relaxed and unrelaxed) 1-particle reduced density matrices (1RDM) and the corresponding natural orbitals. By default, those are not calculated. To determine the MP2 natural occupation numbers, activate the ``natorb`` keyword, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/mp2_water_cc-pvdz.py :lines: 58-62 The orbital relaxation part is by default neglected. Orbital relaxation effects to the MP2 1RDM are accounted for by activating the ``relaxation`` keyword, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/mp2_water_cc-pvdz.py :lines: 64-69 The MP2 natural orbitals are saved to the checkpoint file and copied to the :py:class:`~pybest.io.iodata.IOData` container ``mp2_output``. Thus, the natural MP2 orbitals can be accesses as follows .. code:: python mp2_output.orb_a .. note:: The relaxed 1RDM can only be determined for the conventional MP2 method, that is, for double excitations only. Spin component scaled (SCS) RMP2 ================================ All above features can also be combined with spin component scaling, where the contributions (to the energy or the relaxed and unrelaxed 1RDM) of the same spin and opposite spin component are calculated. Each scaling factor is passed as an additional keyword argument (``fos`` or ``fss``) to the RMP2 function call, for instance, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/scsmp2_water_cc-pvdz.py :lines: 46-50 Similarly, spin-component-scaling can be combined with the calculation of (relaxed and unrelaxed) 1RDMs and natural occupation numbers, .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/scsmp2_water_cc-pvdz.py :lines: 52-57 Example Python scripts ====================== Several complete examples can be found in the directory ``data/examples/perturbation_theory``. MP2 calculation on the water molecule ------------------------------------- This is a basic example on how to perform a RMP2 calculation in PyBEST. This script performs several RMP2 calculation on the water molecule using the cc-pVDZ basis set and (i) only double excitations, (ii) double and single excitations, (iii) double excitations and the calculation of unrelaxed natural orbitals and occupations numbers, and (iv) double excitations and relaxed natural orbitals and occupations numbers. .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/mp2_water_cc-pvdz.py :caption: data/examples/perturbation_theory/mp2_water_cc-pvdz.py :lines: 3- SCS-MP2 calculation on the water molecule ----------------------------------------- This is a basic example on how to perform a SCS-RMP2 calculation in PyBEST. This script performs several RMP2 calculation on the water molecule using the cc-pVDZ basis set and (i) only double excitations and (ii) double excitations and the calculation of unrelaxed natural orbitals and occupations numbers, and (iv) double excitations and relaxed natural orbitals and occupations numbers. .. literalinclude:: ../src/pybest/data/examples/perturbation_theory/scsmp2_water_cc-pvdz.py :caption: data/examples/perturbation_theory/scsmp2_water_cc-pvdz.py :lines: 3-