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.
 *
 */
 
// ===========================================================================
// STATUS: new, in-progress home for Hirshfeld real-space partitioning, the
// weight-function scheme chosen for CDFT charge (and, later, spin)
// constraints -- see the design discussion this branch grew out of for why
// Hirshfeld over Becke/SSW (Becke-family partitions are known to give
// unphysical atomic charges when atoms differ significantly in size,
// confirmed via CP2K's own move away from plain Becke for this purpose;
// Hirshfeld's promolecular-density weighting avoids that).
//
// A Hirshfeld weight for atom i is w_i(r) = rho_i^free(r) / sum_j
// rho_j^free(r), where rho_i^free is atom i's own ISOLATED, spherically-
// averaged reference density (DFTEngine::ComputeHirshfeldReferenceDensities,
// via RunAtomicDFT_unrestricted with use_hunds_rule_occupation=true) -- this
// class never touches that atomic-SCF machinery itself (which stays private
// to DFTEngine); it only ever receives the resulting densities as an
// explicit argument, matching DFTGradient's own established pattern in this
// branch: static methods, explicit arguments only, no reaching into
// DFTEngine's private state.
//
// Deliberately NOT yet implemented: the sum-over-atoms denominator, the
// full AO-basis weight matrix W_i (the projection actually needed for the
// Lagrange-multiplier potential added to the Fock matrix), or anything
// about the constraint/Lagrange-multiplier optimization itself. This
// commit is only the first, single-atom building block: evaluating one
// isolated reference density, at one real-space point, given that atom's
// own (small, atom-only) basis re-centered on its real position in the
// molecule -- no embedding into the full molecule's AO basis at all (that
// question, and why it does not arise here, was worked out separately:
// unlike DFTEngine::AtomicGuess's own SAD-guess construction, Hirshfeld
// never needs a molecule-sized combined object).
// ===========================================================================
 
#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