Source code for psi4.driver.procrouting.empirical_dispersion

#
# @BEGIN LICENSE
#
# Psi4: an open-source quantum chemistry software package
#
# Copyright (c) 2007-2026 The Psi4 Developers.
#
# The copyrights for code used from other parties are included in
# the corresponding files.
#
# This file is part of Psi4.
#
# Psi4 is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, version 3.
#
# Psi4 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 Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License along
# with Psi4; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
#
# @END LICENSE
#

import collections
from typing import Dict, List, Union

import numpy as np
import qcengine as qcng
from qcelemental.models.v2 import AtomicInput
from qcelemental.util import parse_version

from psi4 import core

from .. import p4util
from ..p4util.exceptions import ValidationError, UpgradeHelper

_engine_can_do = collections.OrderedDict([
    # engine order establishes default for each disp
    ("libdisp",  ["d1", "d2",                                                                                                               "chg", "das2009", "das2010",]),
    ("s-dftd3",  [            "d3zero2b", "d3bj2b", "d3mzero2b", "d3mbj2b", "d3zeroatm", "d3bjatm", "d3mzeroatm", "d3mbjatm",                                           ]),
    ("dftd3",    [      "d2", "d3zero2b", "d3bj2b", "d3mzero2b", "d3mbj2b",                                                                                             ]),
    ("nl",       [                                                                                                                          "nl",                       ]),
    ("mp2d",     [                                                                                                                          "dmp2",                     ]),
    ("dftd4",    [                                                                                                            "d4bjeeqatm", "d4bjeeqtwo"                ]),
    ("mctc-gcp", [                                                                                                                          "3c",                       ]),
    ("gcp",      [                                                                                                                          "3c",                       ]),
]) # yapf: disable
_install_dftd3python = " Allow the default dispersion engine to run by removing 'engine=' and installing `conda install dftd3-python -c conda-forge`."
_obsolete_engines = {
    ("dftd3", "d2"): ("engine='dftd3'", "engine='libdisp'", "1.10", " Allow the default (internal) dispersion engine to run by removing 'engine='."),
    ("dftd3", "d3zero2b"): ("engine='dftd3'", "engine='s-dftd3'", "1.10", _install_dftd3python),
    ("dftd3", "d3bj2b"): ("engine='dftd3'", "engine='s-dftd3'", "1.10", _install_dftd3python),
    ("dftd3", "d3mzero2b"): ("engine='dftd3'", "engine='s-dftd3'", "1.10", _install_dftd3python),
    ("dftd3", "d3mbj2b"): ("engine='dftd3'", "engine='s-dftd3'", "1.10", _install_dftd3python),
    ("gcp", "3c"): ("engine='gcp'", "engine='mctc-gcp'", "1.10", " Allow the default dispersion engine to run by removing 'engine=' and installing `conda install gcp-correction -c conda-forge`."),
}


def _capable_engines_for_disp()-> Dict[str, List[str]]:
    """Invert _engine_can_do dictionary and check program detection.

    Returns a dictionary with keys all dispersion levels and values a list of all
    capable engines, where the engine in the first element is available, if any are.

    """
    try:
        from qcengine.testing import _programs as _programs_qcng
    except ModuleNotFoundError:
        # _programs_qcng is up-to-date with current harnesses but it requires pytest present, so let's provide a workaround
        from qcelemental.util import which, which_import
        _programs_qcng = {
            "dftd3": which("dftd3", return_bool=True),
            "dftd4": which_import("dftd4", return_bool=True),
            "s-dftd3": which_import("dftd3", return_bool=True),
            "mctc-gcp": which("mctc-gcp", return_bool=True),
            "gcp": which("gcp", return_bool=True),
            "mp2d": which("mp2d", return_bool=True),
        }

    programs_disp = {k: v for k, v in _programs_qcng.items() if k in _engine_can_do}
    programs_disp["libdisp"] = True
    programs_disp["nl"] = True

    capable = collections.defaultdict(list)
    capable_sorted_by_available = collections.defaultdict(list)
    for eng, disps in _engine_can_do.items():
        for disp in disps:
            capable[disp].append(eng)
    for disp, engines in capable.items():
        capable_sorted_by_available[disp] = sorted(engines, key=lambda x: programs_disp[x], reverse=True)

    return capable_sorted_by_available


[docs] class EmpiricalDispersion(): """Lightweight unification of empirical dispersion calculation modes. Attributes ---------- dashlevel : str {"d1", "d2", "chg", "das2009", "das2010", "nl", "dmp2", "d3zero2b", "d3bj2b", "d3mzero2b", "d3mbj2b", "d3zeroatm", "d3bjatm", "d3mzeroatm", "d3mbjatm", "d4bjeeqatm", "d4bjeeqtwo"} Name of dispersion correction to be applied. Resolved from `name_hint` and/or `level_hint` into a key of `empirical_dispersion_resources.dashcoeff`. dashparams : dict Complete set of parameter values defining the flexible parts of :py:attr:`dashlevel`. Number and parameter names vary by :py:attr:`dashlevel`. Resolved into a complete set (keys of dashcoeff[dashlevel]['default']) from `name_hint` and/or `dashcoeff_supplement` and/or user `param_tweaks`. fctldash : str If :py:attr:`dashparams` for :py:attr:`dashlevel` corresponds to a defined, named, untweaked "functional-dashlevel" set, then that functional. Otherwise, empty string. description : str Tagline for dispersion :py:attr:`dashlevel`. dashlevel_citation : str Literature reference for dispersion :py:attr:`dashlevel` in general, *not necessarily* for :py:attr:`dashparams`. dashparams_citation : str Literature reference for dispersion parameters, if :py:attr:`dashparams` corresponds to a defined, named, untweaked "functional-dashlevel" set with a citation. Otherwise, empty string. dashcoeff_supplement : dict See description in `qcengine.programs.empirical_dispersion_resources.from_arrays`. Used here to "bless" the dispersion definitions attached to the procedures/dft/<rung>_functionals-defined dictionaries as legit, non-custom, and of equal validity to `qcengine.programs.empirical_dispersion_resources.dashcoeff` itself for purposes of validating :py:attr:`fctldash`. engine : str {'libdisp', "s-dftd3", 'dftd3', 'nl', 'mp2d', "dftd4"} Compute engine for dispersion. One of Psi4's internal libdisp library, external Grimme or Beran projects, or nl. disp : Dispersion Only present for :py:attr:`engine` `=libdisp`. Psi4 class instance prepared to compute dispersion. ordered_params : list Fixed-order list of relevant parameters for :py:attr:`dashlevel`. Matches :rst:psivar:`DISPERSION CORRECTION ENERGY` ordering. Used for printing. Parameters ---------- name_hint Name of functional (func only, func & disp, or disp only) for which to compute dispersion (e.g., blyp, BLYP-D2, blyp-d3bj, blyp-d3(bj), hf+d). Any or all parameters initialized from ``dashcoeff[dashlevel][functional-without-dashlevel]`` or ``dashcoeff_supplement[dashlevel][functional-with-dashlevel]`` can be overwritten via `param_tweaks`. level_hint Name of dispersion correction to be applied (e.g., d, D2, d3(bj), das2010). Must be key in `dashcoeff` or "alias" or "formal" to one. param_tweaks Values for the same keys as `dashcoeff[dashlevel]['default']` (and same order if list) used to override any or all values initialized by `name_hint`. Extra parameters will error. engine Override which code computes dispersion. See above for allowed values. Formerly (pre Nov 2022) only relevant for -D2, which can be computed by libdisp or dftd3. Later (post Nov 2022, pre Jun 2025) also relevant for -D3 variants, which can be computed by dftd3 executable or simple-dftd3 Python module. Now (post Jun 2025) irrelevant as each dispersion level only available from one code; `dftd3` is no-op. gcp_engine Override which code computes the gcp correction. Relevant between Nov 2022 and Jun 2025 when could use either the classic gcp or mctc-gcp executables. Now (post Jun 2025), `gcp` is no-op. save_pairwise_disp Whether to request atomic pairwise analysis. """ def __init__(self, *, name_hint: str = None, level_hint: str = None, param_tweaks: Union[Dict, List] = None, engine: str = None, gcp_engine: str = None, save_pairwise_disp: bool = False): from .dft import dashcoeff_supplement self.dashcoeff_supplement = dashcoeff_supplement self.save_pairwise_disp = save_pairwise_disp resolved = qcng.programs.empirical_dispersion_resources.from_arrays( name_hint=name_hint, level_hint=level_hint, param_tweaks=param_tweaks, dashcoeff_supplement=self.dashcoeff_supplement) self.fctldash = resolved['fctldash'] self.dashlevel = resolved['dashlevel'] self.dashparams = resolved['dashparams'] self.description = qcng.programs.empirical_dispersion_resources.dashcoeff[self.dashlevel]['description'] self.ordered_params = qcng.programs.empirical_dispersion_resources.dashcoeff[self.dashlevel]['default'].keys() self.dashlevel_citation = qcng.programs.empirical_dispersion_resources.dashcoeff[self.dashlevel]['citation'] self.dashparams_citation = resolved['dashparams_citation'] capable_engines_for_disp = _capable_engines_for_disp() if engine is None: self.engine = capable_engines_for_disp[self.dashlevel][0] else: if self.dashlevel in _engine_can_do[engine]: self.engine = engine else: raise ValidationError(f"This little engine ({engine}) can't ({self.dashlevel})") if (key := (self.engine, self.dashlevel)) in _obsolete_engines: raise UpgradeHelper(*_obsolete_engines[key]) if self.engine == 'libdisp': self.disp = core.Dispersion.build(self.dashlevel, **resolved['dashparams']) gcp_dashlevel = "3c" if gcp_engine is None: self.gcp_engine = capable_engines_for_disp[gcp_dashlevel][0] else: if gcp_dashlevel in _engine_can_do[gcp_engine]: self.gcp_engine = gcp_engine else: raise ValidationError(f"This little engine ({engine}) can't ({gcp_dashlevel})") if (key := (self.gcp_engine, gcp_dashlevel)) in _obsolete_engines: raise UpgradeHelper(*_obsolete_engines[key])
[docs] def print_out(self): """Format dispersion parameters of `self` for output file.""" text = [] text.append(" => {}: Empirical Dispersion <=".format( (self.fctldash.upper() if self.fctldash.upper() else 'Custom'))) text.append('') text.append(self.description) text.append(self.dashlevel_citation.rstrip()) if self.dashparams_citation: text.append(" Parametrisation from:{}".format(self.dashparams_citation.rstrip())) text.append('') for op in self.ordered_params: text.append(" %6s = %14.6f" % (op, self.dashparams[op])) text.append('\n') core.print_out('\n'.join(text))
[docs] def compute_energy(self, molecule: core.Molecule, wfn: core.Wavefunction = None) -> float: """Compute dispersion energy based on engine, dispersion level, and parameters in `self`. Parameters ---------- molecule System for which to compute empirical dispersion correction. wfn Location to set QCVariables Returns ------- float Dispersion energy [Eh]. Notes ----- :psivar:`DISPERSION CORRECTION ENERGY` Disp always set. Overridden in SCF finalization, but that only changes for "-3C" methods. :psivar:`fctl DISPERSION CORRECTION ENERGY` Set if :py:attr:`fctldash` nonempty. """ if self.engine in ["s-dftd3", 'dftd3', 'mp2d', "dftd4"]: resi = AtomicInput( **{ "specification": { 'driver': 'energy', 'model': { 'method': self.fctldash, 'basis': '(auto)', }, 'keywords': { 'level_hint': self.dashlevel, 'params_tweaks': self.dashparams, 'dashcoeff_supplement': self.dashcoeff_supplement, 'pair_resolved': self.save_pairwise_disp, 'apply_qcengine_aliases': True, # for s-dftd3 'verbose': 1, }, }, 'molecule': molecule.to_schema(dtype=3), 'provenance': p4util.provenance_stamp(__name__), }) jobrec = qcng.compute( resi, self.engine, raise_error=True, return_version=2, task_config={"scratch_directory": core.IOManager.shared_object().get_default_path(), "ncores": core.get_num_threads()}) dashd_part = float(jobrec.extras['qcvars']['DISPERSION CORRECTION ENERGY']) if wfn is not None: for k, qca in jobrec.extras['qcvars'].items(): if ("CURRENT" not in k) and ("PAIRWISE" not in k): wfn.set_variable(k, float(qca) if isinstance(qca, str) else qca) # Pass along the pairwise dispersion decomposition if we need it if self.save_pairwise_disp is True: wfn.set_variable("PAIRWISE DISPERSION CORRECTION ANALYSIS", jobrec.extras['qcvars']["2-BODY PAIRWISE DISPERSION CORRECTION ANALYSIS"]) if self.fctldash in ['hf3c', 'pbeh3c', 'r2scan3c', 'b973c']: jobrec = qcng.compute( resi, self.gcp_engine, raise_error=True, return_version=2, task_config={"scratch_directory": core.IOManager.shared_object().get_default_path(), "ncores": core.get_num_threads()}) gcp_part = jobrec.return_result dashd_part += gcp_part return dashd_part else: ene = self.disp.compute_energy(molecule) core.set_variable('DISPERSION CORRECTION ENERGY', ene) if self.fctldash: core.set_variable(f"{self.fctldash} DISPERSION CORRECTION ENERGY", ene) return ene
[docs] def compute_gradient(self, molecule: core.Molecule, wfn: core.Wavefunction = None) -> core.Matrix: """Compute dispersion gradient based on engine, dispersion level, and parameters in `self`. Parameters ---------- molecule System for which to compute empirical dispersion correction. wfn Location to set QCVariables Returns ------- Matrix (nat, 3) dispersion gradient [Eh/a0]. """ if self.engine in ["s-dftd3", 'dftd3', 'mp2d', "dftd4"]: resi = AtomicInput( **{ "specification": { 'driver': 'gradient', 'model': { 'method': self.fctldash, 'basis': '(auto)', }, 'keywords': { 'level_hint': self.dashlevel, 'params_tweaks': self.dashparams, 'dashcoeff_supplement': self.dashcoeff_supplement, 'apply_qcengine_aliases': True, # for s-dftd3 'verbose': 1, }, }, 'molecule': molecule.to_schema(dtype=3), 'provenance': p4util.provenance_stamp(__name__), }) jobrec = qcng.compute( resi, self.engine, raise_error=True, return_version=2, task_config={"scratch_directory": core.IOManager.shared_object().get_default_path(), "ncores": core.get_num_threads()}) dashd_part = core.Matrix.from_array(jobrec.extras['qcvars']['DISPERSION CORRECTION GRADIENT']) if wfn is not None: for k, qca in jobrec.extras['qcvars'].items(): if "CURRENT" not in k: wfn.set_variable(k, float(qca) if isinstance(qca, str) else qca) if self.fctldash in ['hf3c', 'pbeh3c', 'r2scan3c', 'b973c']: jobrec = qcng.compute( resi, self.gcp_engine, raise_error=True, return_version=2, task_config={"scratch_directory": core.IOManager.shared_object().get_default_path(), "ncores": core.get_num_threads()}) gcp_part = core.Matrix.from_array(jobrec.return_result) dashd_part.add(gcp_part) return dashd_part else: return self.disp.compute_gradient(molecule)
def _analytic_hessian_available(self) -> bool: """Whether the engine can compute the full dispersion Hessian analytically. Only s-dftd3 at dftd3-python >=1.6.0 (as reported by QCEngine) driven by QCEngine >=0.52.0 qualifies, and not for -3c methods. """ if self.engine != "s-dftd3" or self.fctldash in ['hf3c', 'pbeh3c', 'r2scan3c', 'b973c']: return False if parse_version(qcng.__version__) < parse_version("0.52.0"): return False return parse_version(qcng.get_program(self.engine).get_version()) >= parse_version("1.6.0")
[docs] def compute_hessian(self, molecule: core.Molecule, wfn: core.Wavefunction = None) -> core.Matrix: """Compute dispersion Hessian based on engine, dispersion level, and parameters in `self`. Uses analytic second derivatives for engine s-dftd3 at dftd3-python >=1.6.0 and QCEngine >=0.52.0 (excepting -3c methods, whose gCP part lacks them). Otherwise, uses finite difference of gradients. Parameters ---------- molecule System for which to compute empirical dispersion correction. wfn Location to set QCVariables Returns ------- Matrix (3*nat, 3*nat) dispersion Hessian [Eh/a0/a0]. """ if self._analytic_hessian_available(): resi = AtomicInput( **{ "specification": { 'driver': 'hessian', 'model': { 'method': self.fctldash, 'basis': '(auto)', }, 'keywords': { 'level_hint': self.dashlevel, 'params_tweaks': self.dashparams, 'dashcoeff_supplement': self.dashcoeff_supplement, 'apply_qcengine_aliases': True, # for s-dftd3 'verbose': 1, }, }, 'molecule': molecule.to_schema(dtype=3), 'provenance': p4util.provenance_stamp(__name__), }) jobrec = qcng.compute( resi, self.engine, raise_error=True, return_version=2, task_config={"scratch_directory": core.IOManager.shared_object().get_default_path(), "ncores": core.get_num_threads()}) core.print_out("\n\n Analytical Dispersion Hessian computed by engine s-dftd3.\n\n") H = np.asarray(jobrec.extras['qcvars']['DISPERSION CORRECTION HESSIAN']).reshape(3 * molecule.natom(), -1) if wfn is not None: for k, qca in jobrec.extras['qcvars'].items(): if "CURRENT" not in k: wfn.set_variable(k, float(qca) if isinstance(qca, str) else qca) wfn.set_variable('DISPERSION CORRECTION HESSIAN', H) return core.Matrix.from_array(H) from psi4.driver.driver_findif import assemble_hessian_from_gradients, hessian_from_gradients_geometries optstash = p4util.OptionsState(['PRINT'], ['PARENT_SYMMETRY']) core.set_global_option('PRINT', 0) core.print_out("\n\n Analytical Dispersion Hessians are not supported by this engine and level.\n") core.print_out(" Computing the Hessian through finite difference of gradients.\n\n") # Setup the molecule molclone = molecule.clone() molclone.reinterpret_coordentry(False) molclone.fix_orientation(True) molclone.fix_com(True) # Record undisplaced symmetry for projection of diplaced point groups core.set_global_option("PARENT_SYMMETRY", molecule.schoenflies_symbol()) # no rotational projection since the dispersion gradient alone is nonzero, even at a stationary point findif_meta_dict = hessian_from_gradients_geometries(molclone, -1, r_project=False) for displacement in findif_meta_dict["displacements"].values(): geom_array = np.reshape(displacement["geometry"], (-1, 3)) molclone.set_geometry(core.Matrix.from_array(geom_array)) molclone.update_geometry() displacement["gradient"] = self.compute_gradient(molclone).np.ravel().tolist() H = assemble_hessian_from_gradients(findif_meta_dict, -1) if wfn is not None: wfn.set_variable('DISPERSION CORRECTION HESSIAN', H) optstash.restore() return core.Matrix.from_array(H)