.. : 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_properties_lr: Linear Response Transition Dipole Moment and Related Properties ############################################################### The current version of PyBEST supports property calculations from pCCD-based (see :ref:`pccd`) Linear Response methods (see :ref:`user_lr_intro`). Thus, we will focus on a pCCD reference function below. The Transition Dipole Moment (TDM), in the absence of any external potential, can be obtained using only the :math:`\hat{A}`-dependent part of the full linear response expression, given as: .. math:: \Gamma_{0 \rightarrow k}^{\hat{A}} &= \langle 0 | \hat{A} | k \rangle \\ &= \langle \Lambda |[\hat{A}, \, \hat{\tau}_k]|\mathrm{pCCD}\rangle \\ &\quad - \sum_{\nu } (\omega_\nu - \omega_k)^{-1} \langle \bar{\nu} | \hat{A} | \mathrm{pCCD} \rangle \langle \Lambda | [[\hat{H}_0, \hat{\tau}_\nu], \hat{\tau}_k] | \mathrm{pCCD} \rangle Using dipole operators as :math:`\hat{A}`, one can compute the transition dipole moments for selected excited states. An intrinsic advantage of using pCCD as the reference wave function, unlike CCSD-based approaches, is that the EOM matrix becomes approximately symmetric. This symmetry allows the transition dipole moment to be approximated using only the **right eigenvectors** without significantly compromising accuracy. This approximation enables reduced computational scaling to :math:`\mathcal{O}(o^2v^2)`. If you use this module, please cite [ahmadkhani2024]_. Implemented Features ==================== Molecular properties are determined from Linear Response calculations. Currently, PyBEST supports two different Linear Response flavors (see :ref:`user_lr_intro`). - :class:`~pybest.properties.lr_pccd.LRpCCD`: Linear Response based on a pCCD reference. - :class:`~pybest.properties.lr_pccd_s.LRpCCDS`: Linear Response based on a pCCD reference with single excitations. Each class is derived from its corresponding EOM class (see :ref:`user_eomcc_intro`) and reuses most of the functionality. The corresponding LR property calculations support the following options when determining transition properties. They are collected as a dictionary and passed as the ``property_options`` argument during function call. Supported dictionary keys are: :origin: Coordinates of the reference point for dipole moment (list/tuple containing x, y, z coordinates). Defaults to the center of nuclear charge if not provided. :transition_dipole_moment: (bool) Whether to compute transition dipole moments. Default: False. Performance and Applicability ============================= These LR methods are especially useful for: - Accurate and efficient description of singly and doubly excited states - Cost-effective alternatives to EOM-CCSD for large systems - Systems requiring particle-number-conserving excitation operators Quick Guide: Transiton dipole moment for LR-pCCD and LR-pCCD+S ============================================================== This is a short introduction to the Linear Response 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 The current version of PyBEST supports two different Linear Response flavors, both based on a pCCD reference function (:ref:`user_pccd`). The :py:class:`~pybest.properties.lr_pccd.LRpCCD` class allows you to determine the Linear Response for pair excitations only. A code snippet can be found below. .. code-block:: python from pybest.properties import LRpCCD # For pCCD Linear Response (only electron pairs) # Compute transition dipole moment tm_dipole = LRpCCD(lf, occ_model) results = tm_dipole( kin, ne, eri, eom_output, property_options={ "origin": origin_coord, "transition_dipole_moment": True, }, printoptions={"nroot": 2}, ) The ``printoptions`` dictionary allows you to specify the following option. :nroot: (int) Number of excited states to compute (default: 5). Should be the same as in the EOM-pCCD or EOM-pCCD+S calculation. To include single excitations in the Linear Response, you can use the corresponding :py:class:`~pybest.properties.lr_pccd_s.LRpCCDS` class. .. code-block:: python from pybest.properties import LRpCCDS # For pCCD+S Linear Response # Compute transition dipole moment tm_dipole = LRpCCDS(lf, occ_model) results = tm_dipole( kin, ne, eri, eom_output, property_options={ "origin": origin_coord, "transition_dipole_moment": True, }, printoptions={"nroot": 2}, ) The result includes excitation energies and electronic, nuclear, and total transition dipole moments, along with oscillator strength from the EOM matrix. The results are returned as an :py:class:`~pybest.io.iodata.IOData` container, while all results are saved to the ``pybest-results/checkpoint_LR_pCCD.h5`` or ``pybest-results/checkpoint_LR_pCCDS.h5`` files. Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains the following attributes. :orb_a: Molecular orbitals from the pCCD reference :e_ref: Total reference energy (pCCD) :e_ee: Excitation energies (first entry is 0.0) :civ_r_ee: Right eigenvectors (CI-like) of the LR EOM matrix :t_dm: Transition dipole moments (if requested) .. _user_properties_lr_examples: Example Usage ============= The example files for obtaining transition dipole moments using the linear response method are collected in the directory ``data/examples/properties``. Example for LR-pCCD transition dipole moments and oscillator strength --------------------------------------------------------------------- This is a basic example of how to calculate properties from linear response methods in PyBEST. This script performs an RHF calculation, followed by a pCCD and EOMpCCD calculation, and an LR-pCCD calculation with a pCCD reference function on the water molecule using the cc-pVDZ basis set. .. literalinclude:: ../src/pybest/data/examples/properties/water_lr_tdm_pccd.py :caption: data/examples/properties/water_lr_tdm_pccd.py :lines: 3- Example for LR-pCCD+S transition dipole moments and oscillator strength ----------------------------------------------------------------------- This is a basic example of how to calculate properties from the LR-pCCD+S method in PyBEST. This script performs an RHF calculation, followed by a pCCD and EOMpCCD+S calculation, and an LR-pCCD+S calculation with a pCCD reference function on the water molecule using the cc-pVDZ basis set. .. literalinclude:: ../src/pybest/data/examples/properties/water_lr_tdm_pccd_s.py :caption: data/examples/properties/water_lr_tdm_pccd_s.py :lines: 3-