.. : 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_estruct_rcc: The restricted coupled-cluster module ##################################### Before reading this section, please read the general introduction mentioned in :ref:`user_posthf_intro`. This part of the Documentation builds upon it. With PyBEST, you can perform a coupled-cluster correction on top of any single-reference wave function, eg., the restricted Hartree-Fock (RHF) (see :ref:`user_hf`) or ROOpCCD (restricted orbital-optimized pair coupled cluster doubles; see :ref:`user_pccd`) reference wave function. The module is explained in greater detail below. If you use this module, please cite [leszczyk2022]_. .. _getstartedcc: Quick Guide: RCC ================ This is a short introduction to the RCC module. More information on the input and output structure can be found in the following sections. Similar to the previous modules, 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 .. _qg_rcc: RHF reference function ---------------------- 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`). The following code snippet below shows how to perform an RCCSD calculation with an RHF reference function in PyBEST. .. code-block:: python ccsd = RCCSD(lf, occ_model) ccsd_output = ccsd(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 ``pybest-results/checkpoint_RCCSD.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains (amongst others) the following attributes :e_tot: the total RCCSD energy (sum of RHF energy and RCC energy) :e_corr: the RCCSD correlation energy :e_corr_s: the single excitation contribution in RCCSD correlation energy :e_corr_d: the double excitation contribution in RCCSD correlation energy :e_ref: the energy of the reference determinant (here, the Hartree-Fock determinant energy) :t_1: the single excitation cluster amplitudes :t_2: the double excitation cluster amplitudes :method: the name of the model (here: RCCSD) :nocc: the number of all occupied orbitals (including core orbitals) :nvirt: the number of all virtual (unoccupied in the RHF model) orbitals :ncore: the number of (frozen) core orbitals (occupied but not correlated) :nact: the number of correlated occupied and unoccupied orbitals :converged: boolean value indicating if CC converged To exclude single excitations, you have to use the :py:class:`~pybest.cc.rccsd.RCCD` class. The overall input structure is equivalent to :py:class:`~pybest.cc.rccsd.RCCSD`. .. code-block:: python ccd = RCCD(lf, occ_model) ccd_output = ccd(kin, ne, eri, hf_output) .. note:: The order of arguments does not matter while calling RCCD instance because PyBEST recognizes them in an automatic fashion. All results are saved to the ``pybest-results/checkpoint_RCCD.h5`` checkpoint file. ROOpCCD reference function -------------------------- The following code snippet shows how to perform an RCCSD calculation with an ROOpCCD reference function (that is, ROOpCCD orbitals and its reference determinant) in PyBEST. .. code-block:: python pccd = ROOpCCD(lf, occ_model) pccd_output = pccd(hf_output, kin, ne, eri) ccsd = RCCSD(lf, occ_model) ccsd_output = ccsd(kin, ne, eri, pccd_output) Defining a frozen core ---------------------- By default, all (occupied and virtual) orbitals are active. To freeze some (occupied) orbitals, the number of frozen cores has to be specified when an instance of some occupation model class is created. For instance, if you wish to freeze the first 4 (occupied) orbitals in a RHF-CCSD calculation, specify the ``ncore`` argument during the initialization of the occupation model, .. code-block:: python # Select 4 frozen core orbital #----------------------------- occ_model = AufbauOccModel(gobasis, ncore=4) # Perform CC calculation, ncore is stored in occ_model #----------------------------------------------------- ccsd = RCCSD(lf, occ_model) ccsd_output = ccsd(kin, ne, eri, hf_output) This syntax is working for all CC modules mentioned above. .. _cc_restart: Restart options --------------- The :py:class:`~pybest.cc.rccd.RCCD` and :py:class:`~pybest.cc.rccsd.RCCSD` modules support restarts from PyBEST's internal checkpoint files. If your coupled-cluster calculation did not converge before the number of iterations exceeded some maximum number allowed and you wish to restart it and take the amplitudes from a previous calculation as an initial guess, specify the path to the corresponding checkpoint file using the ``restart`` keyword. .. code-block:: python ccd = RCCD(lf, occ_model) # Restart only amplitudes from checkpoint_RCCD_d.h5 ccd_output = ccd( kin, ne, eri, hf_output, restart='pybest-results/checkpoint_RCCD.h5' ) PyBEST will read the amplitudes stored in ``pybest-results/checkpoint_RCCD.h5`` and provide those as guess amplitudes to the RCCD solver. .. note:: Currently, PyBEST does not dump the Hamiltonian to disk that is used in the CC calculation. Thus, if the user modifies the Hamiltonian, the calculation might be corrupted and special care is advised. .. _rccsd_keywords: Summary of keyword arguments ---------------------------- The :py:class:`~pybest.cc.rccd.RCCD` and :py:class:`~pybest.cc.rccsd.RCCSD` classes supports various keyword arguments that allow us to steer the optimization of the cluster amplitudes. In the following, all supported keyword arguments are listed together with their default values. Please note, that for most cases the default values should be sufficient to reach convergence. :filename: (str) path to file where current solution is dumped (default pybest-results/checkpoint_method.h5). :e_ref: (float) reference energy (default value 0.0). :initguess: (str or numpy.ndarray) initial guess for the amplitudes, one of: "random", "mp2", "const", path to .h5 file, or IOData instance. :maxiter: (int) maximum number of iterations (default: 100). :solver: (str) one of scipy.optimize.root solvers (default: "krylov"). :threshold: (float) tolerance for amplitudes (default: 1e-8). RCCD and RCCSD calculation on the water molecule ------------------------------------------------ This is a basic example on how to perform a CCD and CCSD calculation in PyBEST. This script performs a CCD calculation followed by a CCSD calculation on the water molecule using the cc-pVDZ basis set. .. literalinclude:: ../src/pybest/data/examples/rccsd/rccsd_water.py :caption: data/examples/rccsd/rccsd_water.py :lines: 3- RCCD and RCCSD calculation on the water molecule using a frozen core -------------------------------------------------------------------- This is a basic example on how to perform a CCD and CCSD calculation in PyBEST. This script performs a CCD calculation followed by a CCSD calculation on the water molecule using the cc-pVDZ basis set and freezing the lowest orbital. .. literalinclude:: ../src/pybest/data/examples/rccsd/rccsd_frozen_core_water.py :caption: data/examples/rccsd/rccsd_frozen_core_water.py :lines: 3- RCCSD calculation using data from file as an initial guess for amplitudes ------------------------------------------------------------------------- This is a basic example on how to perform a CCSD calculation in PyBEST. This script performs a CCSD calculation where the maximum number of iterations is too small to converge. This calculation is followed up by the CCSD calculations that use the previous results that were dumped to file. .. literalinclude:: ../src/pybest/data/examples/rccsd/rccsd_restart_water.py :caption: data/examples/rccsd/rccsd_frozen_core_water.py :lines: 3-