..
    : 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 <http://www.gnu.org/licenses/>
    : --


.. _user_lr_intro:

The Linear Response Module
==========================

This module describes the implementation of Linear Response (LR) theory for modeling electronic excitation properties based on a pair Coupled Cluster Doubles (pCCD) reference and its extension to singles (pCCDS = pCCD+S).

Before proceeding, please ensure you're familiar with the basics of post-Hartree-Fock models in PyBEST (:ref:`user_posthf_intro`).


If you use this module, please cite [ahmadkhani2024]_.

Supported Features
==================

The current version of PyBEST supports two different LR models that allow you to
compute singlet excitation energies and transition dipole moments using
property operators. These include

- **LR-pCCD**: Excitations built upon the pair Coupled Cluster Doubles reference.
- **LR-pCCDS**: Includes additional single excitations on top of pCCD (formally abbreviated as LR-pCCD+S).

Both methods solve a response eigenvalue problem using the Jacobian of the similarity-transformed Hamiltonian.


Theoretical Framework
=====================

The LR approach solves a generalized eigenvalue problem of the form

.. math::

    \mathbf{J} \mathbf{X}_k = \omega_k \mathbf{S} \mathbf{X}_k

where:

- :math:`\mathbf{J}` is the Jacobian matrix (the response of the similarity-transformed Hamiltonian)
- :math:`\mathbf{S}` is the overlap metric between excitation operators (usually identity)
- :math:`\omega_k` are the excitation energies
- :math:`\mathbf{X}_k` are the right (CI-like) eigenvectors

Transition properties between states are computed as

.. math::

    \langle 0|\hat{A}|k\rangle \langle k|\hat{B}|0\rangle =
    \lim_{\omega\rightarrow\omega_k} (\omega-\omega_k) \langle\langle \hat{A};\hat{B}\rangle\rangle =  \langle k | \hat{B} | 0 \rangle
    \langle \Lambda |[\hat{A}, \hat{\tau}_k]|\mathrm{pCCD}\rangle
.. math::

    -\sum_{\nu } \left\{
    \sum_{\mu} (-\hat{J} + \omega \mathbf{I})_{\mu\nu}^{-1}
    \langle \bar{\nu} | \hat{A} | \mathrm{pCCD} \rangle
    \langle \Lambda | [[\hat{H}_0, \hat{\tau}_\nu], \hat{\tau}_k] | \mathrm{pCCD} \rangle \right\} \langle k | \hat{B} | 0 \rangle


where:

- :math:`\hat{A}` and :math:`\hat{B}` are property operators (e.g., dipole operator or momentum integrals)
- :math:`\hat{J}` is the Jacobian matrix
- :math:`\hat{\tau}_k` is the excitation operator for state :math:`k`
- :math:`\nu` and :math:`\mu` denote the index over excitation operators
- :math:`\langle \Lambda |` is the left eigenvector of the response problem
- :math:`\hat{H}_0` is the unperturbed molecular Hamiltonian

Diagonalization Method
======================

All LR methods currently use **Davidson diagonalization** to solve the eigenvalue problem. This iterative method efficiently computes a few of the lowest excited states.

Practical Usage
===============

To perform an LR-pCCD or LR-pCCD+S calculation, you need:

- A converged pCCD ground-state wavefunction
- Solution of the Jacobian eigenproblem
- A property operator (e.g., electric dipole moment) for computing properties

Computing Transition Properties
===============================

To compute transition properties (e.g., transition dipole moments) using the LR-pCCD or LR-pCCD+S methods, you can use the property interface described in :doc:`user_properties_lr`.