bsecoupling.h

Go to the documentation of this file.

/*
 *            Copyright 2009-2020 The VOTCA Development Team
 *                       (http://www.votca.org)
 *
 *      Licensed under the Apache License, Version 2.0 (the "License")
 *
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *              http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
 
#pragma once
#ifndef VOTCA_XTP_BSECOUPLING_H
#define VOTCA_XTP_BSECOUPLING_H
 
// Local VOTCA includes
#include "couplingbase.h"
#include "qmstate.h"
 
namespace votca {
namespace xtp {

 
class BSECoupling : public CouplingBase {
 public:
  void Initialize(tools::Property& options) override;
  std::string Identify() const { return "bsecoupling"; }
 
  void Addoutput(tools::Property& type_summary, const Orbitals& orbitalsA,
                 const Orbitals& orbitalsB) const override;

  void CalculateCouplings(const Orbitals& orbitalsA, const Orbitals& orbitalsB,
                          const Orbitals& orbitalsAB) override;
 
 private:
  struct Diagnostics {
    double xi = 0.0;
    double pt_rm_discrepancy = 0.0;
    bool downfolding_safe = true;
  };
 
  void WriteToProperty(tools::Property& summary, const QMState& stateA,
                       const QMState& stateB) const;

  static void WriteMatrixToProperty(tools::Property& prop,
                                    const std::string& name,
                                    const Eigen::MatrixXd& mat,
                                    double conversion = 1.0);
 
  double getSingletCouplingElement(Index levelA, Index levelB,
                                   Index methodindex) const;
 
  double getTripletCouplingElement(Index levelA, Index levelB,
                                   Index methodindex) const;
 
  Eigen::MatrixXd SetupCTStates(Index bseA_vtotal, Index bseB_vtotal,
                                Index bseAB_vtotal, Index bseAB_ctotal,
                                const Eigen::MatrixXd& A_AB,
                                const Eigen::MatrixXd& B_AB) const;
 
  Eigen::MatrixXd ProjectFrenkelExcitons(const Eigen::MatrixXd& BSE_Coeffs,
                                         const Eigen::MatrixXd& X_AB,
                                         Index bseX_vtotal, Index bseX_ctotal,
                                         Index bseAB_vtotal,
                                         Index bseAB_ctotal) const;

  template <class BSE_OPERATOR>
  std::array<Eigen::MatrixXd, 2> ProjectExcitons(Eigen::MatrixXd& FE_AB,
                                                 Eigen::MatrixXd& CTStates,
                                                 BSE_OPERATOR H,
                                                 Eigen::MatrixXd& J_dimer_out,
                                                 Eigen::MatrixXd& S_dimer_out,
                                                 Diagnostics& diag_out) const;

  template <class BSE_OPERATOR>
  Eigen::MatrixXd CalcJ_dimer(BSE_OPERATOR& H, Eigen::MatrixXd& projection,
                              Eigen::MatrixXd& J_dimer_out,
                              Eigen::MatrixXd& S_dimer_out) const;

  Eigen::MatrixXd OrthogonalizeCTs(Eigen::MatrixXd& FE_AB,
                                   Eigen::MatrixXd& CTStates) const;
 
  Eigen::MatrixXd Fulldiag(const Eigen::MatrixXd& J_dimer) const;
 
  Eigen::MatrixXd Perturbation(const Eigen::MatrixXd& J_dimer) const;

  Diagnostics ComputeDiagnostics(const Eigen::MatrixXd& J_dimer,
                                 const Eigen::MatrixXd& J_pert,
                                 const Eigen::MatrixXd& J_diag) const;
 
  // --- effective coupling results (existing) ---
  std::array<Eigen::MatrixXd, 2> JAB_singlet;  // [J_pert, J_diag]
  std::array<Eigen::MatrixXd, 2> JAB_triplet;
 
  // --- raw TB matrices (new) ---
  // These are the pre-Lowdin J and S in the full FE+CT basis,
  // suitable for assembling a TB Hamiltonian or feeding into SRG.
  Eigen::MatrixXd J_dimer_singlet_;
  Eigen::MatrixXd S_dimer_singlet_;
  Eigen::MatrixXd J_dimer_triplet_;
  Eigen::MatrixXd S_dimer_triplet_;
 
  // --- diagnostics (new) ---
  Diagnostics diag_singlet_;
  Diagnostics diag_triplet_;
 
  // --- monomer FE energies (new) ---
  // Isolated monomer excitation energies in eV, stored per spin channel.
  // These provide pairwise-consistent site energies for TB assembly:
  // the same monomer calculation is used regardless of which dimer pair
  // is being processed, unlike the dimer diagonal H_FE_FE[i,i] which
  // varies with the partner. Environmental corrections (electrostatic
  // embedding) should be added separately on top of these values.
  Eigen::VectorXd monomerA_energies_singlet_;
  Eigen::VectorXd monomerB_energies_singlet_;
  Eigen::VectorXd monomerA_energies_triplet_;
  Eigen::VectorXd monomerB_energies_triplet_;
 
  bool doTriplets_;
  bool doSinglets_;
  bool output_perturbation_;
  // When true, write TB-specific output: monomer energies, transition
  // dipoles, diagnostics, and raw H/S matrices. Default false for compact
  // output in KMC/rate workflows that only need scalar couplings.
  bool output_tb_ = false;
  Index levA_;
  Index levB_;
  Index occA_;
  Index unoccA_;
  Index occB_;
  Index unoccB_;
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_BSECOUPLING_H