.. : 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_eacc_intro: Quick Guide ########### Before reading this section, please read the general introduction mentioned in :ref:`user_posthf_intro`. This part of the Documentation builds upon it. The current version of PyBEST offers Electron Attachment (EA) calculations with a RpCCD (see :ref:`user_pccd`) reference function and various RCC (see :ref:`user_estruct_rcc`) and fpCC (see :ref:`user_estruct_fpcc`) models using the Equation of Motion (EOM) formalism. The EA module is explained in greater detail below. Supported features ================== The EA module supports spin-restricted orbitals and the ``DenseLinalgFactory`` and ``CholeskyLinalgFactory``. .. _getstartedea: How to: REA =========== This is a short introduction to the REA 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 .. note:: In all EA modules, only the spin projection is defined, that is, only the number of excess :math:`\alpha` electrons over :math:`\beta` electrons is defined. .. _qg_eapccd: RHF reference function ---------------------- This version of PyBEST supports single EA-CCD, EA-CCSD, EA-LCCD, and EA-LCCSD with two different excitation operators - EA-CCD (:py:class:`~pybest.ea_eom.rea_rcc.REACCD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-CCSD (:py:class:`~pybest.ea_eom.rea_rcc.REACCSD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-LCCD (:py:class:`~pybest.ea_eom.rea_rcc.REALCCD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-LCCSD (:py:class:`~pybest.ea_eom.rea_rcc.REALCCSD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators Complete examples can be found in the following subsections (:ref:`ea_examples`). RpCCD reference function ------------------------ This version of PyBEST supports single EA-pCCD, EA-fpCCD, EA-fpCCSD, EA-fpLCCD, and EA-fpLCCSD and double (D)EA-pCCD calculations with two different excitation operators - EA-pCCD (:py:class:`~pybest.ea_eom.rea_pccd.REApCCD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-fpCCD (:py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-fpCCSD (:py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-fpLCCD (:py:class:`~pybest.ea_eom.rea_fpcc.REAfpLCCD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - EA-fpLCCSD (:py:class:`~pybest.ea_eom.rea_fpcc.REAfpLCCSD`): 1. 1 particle (1p) operators 2. 2 particle, 1 hole (2p1h) operators - DEA-pCCD (:py:class:`~pybest.ea_eom.rea_pccd.RDEApCCD`): 1. 2 particle (2p) operators 2. 3 particle, 1 hole (3p1h) operators Complete examples can be found in the following subsections (:ref:`ea_examples`). EA-CCD/EA-CCSD/EA-LCCD/EA-LCCSD: Doublet and quartet states ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you use this module, please cite [behjou2025]_. We assume that you have performed a restricted CC calculation, whose results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``cc_output`` (see :ref:`user_estruct_lcc` for LCC flavors and :ref:`user_estruct_rcc` for conventional CC). The code snippet below shows how to perform a :py:class:`~pybest.ea_eom.rea_rcc.REACCSD` calculation. The current version supports the optimization of doublet and quartet states. Both states can be optimized by setting the keyword argument ``alpha`` to ``1`` when creating an instance of :py:class:`~pybest.ea_eom.rea_rcc.REACCSD`. The number of targeted states is passed through the ``nroot`` keyword argument in the function call. .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) # Both doublet and quartet states can be targeted ea = REACCSD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, cc_output, nroot=3) The results are returned as a :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``pybest-results/checkpoint_EA-EOM-CCSD.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains (amongst others) the following attributes :e_ea: The electron affinities in :math:`E_h` :civ_ea_alpha: The CI vectors (that is, the eigenvectors) for each state (column) for a given ``alpha`` value The eigenvalues and eigenvectors are stored as numpy arrays, not as instances of the :py:class:`~pybest.linalg.base.LinalgFactory`. Since for one spin projection :math:`S_z`, several spin multiplets are accessible, PyBEST suggests the multiplicity for each targeted state in the output file. By default, :py:class:`~pybest.ea_eom.rea_rcc.REACCSD` includes up to 2p1h terms. For ``alpha=1``, the 2p1h terms can be neglected and only the 1p terms are considered during the diagonalization. The number of particle/hole operators is specified by the keyword argument ``nparticle``. The following code snippet shows how to perform a :py:class:`~pybest.ea_eom.rea_rcc.REACCSD` calculation for 1 unpaired electron, including only 1p terms, .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) and 1p terms # Both doublet and quartet states can be targeted ea = REACCSD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, cc_output, nroot=3, nparticle=1) .. note:: All remaining flavors (REACCD, REALCCD, and REALCCSD) are accessible in a similar way. To choose a different EA-CC flavor, simply change the :py:class:`~pybest.ea_eom.rea_rcc.REACCSD` class to the desired CC model, - :py:class:`~pybest.ea_eom.rea_rcc.REACCD` for EA-CCD - :py:class:`~pybest.ea_eom.rea_rcc.REALCCD` for EA-LCCD - :py:class:`~pybest.ea_eom.rea_rcc.REALCCSD` for EA-LCCSD EA-pCCD: Doublet and quartet states ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you use this module, please cite [galynska2024b]_. We assume that you have performed a restricted pCCD calculation (either with or without orbital optimization), whose results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``pccd_output`` (see :ref:`user_pccd`). The code snippet below shows how to perform a :py:class:`~pybest.ea_eom.rea_pccd.REApCCD` calculation. The current version supports the optimization of doublet and quartet states and just the quartet states. The former can be optimized by setting the keyword argument ``alpha`` to ``1`` when creating an instance of :py:class:`~pybest.ea_eom.rea_pccd.REApCCD`, while the latter are accessible by choosing ``alpha=3``. The number of targeted states is passed through the ``nroot`` keyword argument in the function call. .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) # Both doublet and quartet states can be targeted ea = REApCCD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, pccd_output, nroot=3) The results are returned as a :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``pybest-results/checkpoint_EA-EOM-pCCD.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains (amongst others) the following attributes :e_ea: The electron affinities in :math:`E_h` :civ_ea_alpha: The CI vectors (that is, the eigenvectors) for each state (column) for a given ``alpha`` value The eigenvalues and eigenvectors are stored as numpy arrays, not as instances of the :py:class:`~pybest.linalg.base.LinalgFactory`. Since for one spin projection :math:`S_z`, several spin multiplets are accessible, PyBEST suggests the multiplicity for each targeted state in the output file. By default, :py:class:`~pybest.ea_eom.rea_pccd.REApCCD` includes up to 2p1h terms. For ``alpha=1``, the 2p1h terms can be neglected and only the 1p terms are considered during the diagonalization. The number of particle/hole operators is specified by the keyword argument ``nparticle``. The following code snippet shows how to perform a :py:class:`~pybest.ea_eom.rea_pccd.REApCCD` calculation for 1 unpaired electron including only 1p terms, .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) and 1p terms # Only doublet states can be targeted ea = REApCCD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, pccd_output, nroot=3, nparticle=1) .. note:: For three unpaired electrons, only 2p1h terms are supported. Specifying ``nparticle=1`` will raise an error. .. note:: A spin-free implementation is also available. It might help to eliminate convergence difficulties in some cases. If set to `True`, only doublet state can be targeted. .. code-block:: python # Calculate 3 electron-attached states for 1 unpaired electron (S_z=0.5) # Only doublet states can be targeted ea = REApCCD(lf, occ_model, alpha=1, spinfree=True) ea_output = ea(kin, ne, eri, cc_output, nroot=3) EA-fpCCD/EA-fpCCSD/EA-fpLCCD/EA-fpLCCSD: Doublet and quartet states ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you use this module, please cite [behjou2025]_. We assume that you have performed a restricted frozen-pair (fp)CC calculation, whose results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``cc_output`` (see :ref:`user_estruct_lcc` for LCC flavors on top of pCCD and :ref:`user_estruct_fpcc` for supported fpCC models). The code snippet below shows how to perform a :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD` calculation. The current version supports the optimization of doublet and quartet states. Both states can be optimized by setting the keyword argument ``alpha`` to ``1`` when creating an instance of :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD`. The number of targeted states is passed through the ``nroot`` keyword argument in the function call. .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) # Both doublet and quartet states can be targeted ea = REAfpCCSD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, cc_output, nroot=3) The results are returned as a :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``pybest-results/checkpoint_EA-EOM-fpCCSD.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains (amongst others) the following attributes :e_ea: The electron affinities in :math:`E_h` :civ_ea_alpha: The CI vectors (that is, the eigenvectors) for each state (column) for a given ``alpha`` value The eigenvalues and eigenvectors are stored as numpy arrays, not as instances of the :py:class:`~pybest.linalg.base.LinalgFactory`. Since for one spin projection :math:`S_z`, several spin multiplets are accessible, PyBEST suggests the multiplicity for each targeted state in the output file. By default, :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD` includes up to 2p1h terms. For ``alpha=1``, the 2p1h terms can be neglected and only the 1p terms are considered during the diagonalization. The number of particle/hole operators is specified by the keyword argument ``nparticle``. The following code snippet shows how to perform a :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD` calculation for 1 unpaired electron including only 1p terms, .. code-block:: python # Calculate 3 lowest electron-attached states for 1 unpaired electron (S_z=0.5) and 1p terms # Both doublet and quartet states can be targeted ea = REAfpCCSD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, cc_output, nroot=3, nparticle=1) .. note:: All remaining flavors (REAfpCCD, REAfpLCCD, and REAfpLCCSD) are accessible in a similar way. To choose a different EA-CC flavor, simply change the :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCSD` class to the desired CC model, - :py:class:`~pybest.ea_eom.rea_fpcc.REAfpCCD` for EA-fpCCD - :py:class:`~pybest.ea_eom.rea_fpcc.REAfpLCCD` for EA-fpLCCD - :py:class:`~pybest.ea_eom.rea_fpcc.REAfpLCCSD` for EA-fpLCCSD DEA-pCCD: Singlet, triplet, and quintet states ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you use this module, please cite [galynska2024b]_. We assume that you have performed a restricted pCCD calculation (either with or without orbital optimization), whose results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``pccd_output`` (see :ref:`user_pccd`). The code snippet below shows how to perform a :py:class:`~pybest.ea_eom.rea_pccd.RDEApCCD` calculation. The current version supports the optimization of singlet, triplet, and quintet states, triplet and quintet states, or just quintet states. The first case can be optimized by setting the keyword argument ``alpha`` to ``0`` when creating an instance of :py:class:`~pybest.ea_eom.rea_pccd.RDEApCCD`, the second case is accessible by choosing ``alpha=2``, while the last spin multiplicity can be chosen by setting ``alpha=4``. The number of targeted states is passed through the ``nroot`` keyword argument in the function call. .. code-block:: python # Calculate 3 lowest double electron-attached states for 0 unpaired electron (S_z=0.0) # Singlet, triplet, and quintet states can be targeted dea = RDEApCCD(lf, occ_model, alpha=0) dea_output = dea(kin, ne, eri, pccd_output, nroot=3) The results are returned as a :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``pybest-results/checkpoint_DEA-EOM-pCCD.h5`` file. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains (amongst others) the following attributes :e_ea: The ionization energies in :math:`E_h` :civ_ea_alpha: The CI vectors (that is, the eigenvectors) for each state (column) for a given ``alpha`` value The eigenvalues and eigenvectors are stored as numpy arrays, not as instances of the :py:class:`~pybest.linalg.base.LinalgFactory`. Since for one spin projection :math:`S_z`, several spin multiplets are accessible, PyBEST suggests the multiplicity for each targeted state in the output file. By default, :py:class:`~pybest.ea_eom.rea_pccd.RDEApCCD` includes up to 3p1h terms. For ``alpha=0`` and ``alpha=2``, the 3p1h terms can be neglected so that only the 2p terms are considered during the diagonalization. The number of particle/hole operators is specified by the keyword argument ``nparticle``. The following code snippet shows how to perform a :py:class:`~pybest.ea_eom.rea_pccd.RDEApCCD` calculation for 0 unpaired electron including only 2p terms, .. code-block:: python # Calculate 3 lowest double electron-attached states for 0 unpaired electron (S_z=0.0) and 2p terms # Singlet and triplet states can be targeted dea = RDEApCCD(lf, occ_model, alpha=0) dea_output = dea(kin, ne, eri, pccd_output, nroot=3, nparticle=2) .. note:: For four unpaired electrons (qunitet states), only 3p1h terms are supported. Specifying ``nparticle=2`` will raise an error. .. _ea_fc: Defining a frozen core ---------------------- By default, all core orbitals are frozen. If a frozen core has been selected in the CC reference calculation, the same orbitals have to be frozen in the chosen EA flavor. To freeze some specific (occupied) orbitals, the number of frozen cores has to be specified when an instance of some :py:class:`~pybest.occ_model.OccupationModel` class is created. For instance, if you wish to freeze the first 4 (occupied) orbitals in an EA-pCCD calculation, specify the ``ncore`` argument during the initialization of some occupation model class, .. code-block:: python # Select 4 frozen core orbital #----------------------------- occ_model = AufbauOccModel(basis, ncore=4) # Perform EA-CC calculation for 1 unpaired electron (S_z=0.5), # ncore is stored in occ_model #------------------------------------------------------------- ea = REApCCD(lf, occ_model, alpha=1) ea_output = ea(kin, ne, eri, pccd_output) This syntax is working for all EA modules mentioned above. .. _ea_restart: Restart options --------------- Restart options are not supported yet.