hirshfeldpartition.h

Go to the documentation of this file.

/*
 *            Copyright 2009-2026 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.
 *
 */
 
// Hirshfeld real-space partitioning, used as the weight function for CDFT
// charge constraints. Hirshfeld is preferred over Becke/SSW partitioning,
// which gives unphysical atomic charges for atoms of very different size
// (cf. CP2K).
//
// The weight of atom i is w_i(r) = rho_i^free(r) / sum_j rho_j^free(r),
// where rho_i^free is the spherically averaged density of the isolated
// atom (DFTEngine::ComputeHirshfeldReferenceDensities). The reference
// densities are passed in explicitly; as in DFTGradient, all methods are
// static and do not access DFTEngine internals. Each reference density is
// evaluated in its own single-atom basis centered on the atom, so no
// embedding into the molecular AO basis is needed.
 
#pragma once
#ifndef VOTCA_XTP_HIRSHFELDPARTITION_H
#define VOTCA_XTP_HIRSHFELDPARTITION_H
 
// Standard includes
#include <map>
#include <string>
#include <vector>
 
// Local VOTCA includes
#include "aobasis.h"
#include "qmmolecule.h"
#include "vxc_grid.h"
 
namespace votca {
namespace xtp {
 
class HirshfeldPartition {
 public:
  struct AtomicReference {
    AOBasis basis;
    Eigen::MatrixXd density;
  };

  static std::vector<AtomicReference> BuildAtomicReferences(
      const QMMolecule& mol, const std::string& basisset_name,
      const std::map<std::string, Eigen::MatrixXd>& reference_densities);

  static double EvaluateAtomicDensity(const AOBasis& atom_basis,
                                      const Eigen::MatrixXd& reference_density,
                                      const Eigen::Vector3d& point);

  static Eigen::Vector3d EvaluateAtomicDensityGradient(
      const AOBasis& atom_basis, const Eigen::MatrixXd& reference_density,
      const Eigen::Vector3d& point);

  static double EvaluateWeight(const std::vector<AtomicReference>& atoms,
                               Index target_atom_index,
                               const Eigen::Vector3d& point);

  static Eigen::Vector3d EvaluateWeightGradient(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      Index differentiate_atom_index, const Eigen::Vector3d& point);

  static Eigen::Vector3d EvaluatePointWeightGradient(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const Eigen::Vector3d& point);

  static Eigen::MatrixXd GridWeightDerivativeContribution(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const Eigen::MatrixXd& density_matrix, const QMMolecule& mol,
      const Vxc_Grid& grid);

  static Eigen::MatrixXd PulayAndTranslationContribution(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const Eigen::MatrixXd& density_matrix, const AOBasis& full_dftbasis,
      const Vxc_Grid& grid);

  static Eigen::MatrixXd WeightFunctionDerivativeContribution(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const Eigen::MatrixXd& density_matrix, const AOBasis& full_dftbasis,
      const Vxc_Grid& grid);

  static Eigen::MatrixXd ComputeCDFTForceContribution(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const Eigen::MatrixXd& density_matrix, const QMMolecule& mol,
      const AOBasis& full_dftbasis, const Vxc_Grid& grid);

  static Eigen::MatrixXd BuildWeightMatrix(
      const std::vector<AtomicReference>& atoms, Index target_atom_index,
      const AOBasis& full_dftbasis, const Vxc_Grid& grid);

  struct Constraint {
    Eigen::MatrixXd weight_matrix;
    double target_population;
    double lambda = 0.0;
    double spin_alpha_coefficient = 1.0;
    double spin_beta_coefficient = 1.0;
  };
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_HIRSHFELDPARTITION_H