vibe-sketcherDocumentation
Source code for vibesketcher.document.counterpoise_recipes
"""Counterpoise-corrected finite-cluster binding recipes (#243).
The binding recipe of :mod:`vibesketcher.document.electrochemical_recipes`
with ``counterpoise: true``. Boys and Bernardi, Mol. Phys. 19, 553 (1970),
doi:10.1080/00268977000101561 (the formulas are in
:mod:`vibesketcher.document.counterpoise`). Every job is an ordinary recorded
job; the fragment jobs are on the complex species, so their geometry is the
complex's by construction, and the fragment mask travels in ``JobSpec.fragment``
through the job, its imported result and the saved document.
Jobs, for complex AB with fragments A (cluster) and B (adsorbate):
======================== ============================== =========================
job id species / fragment energy
======================== ============================== =========================
``<id>-<AB>`` AB E_AB^AB(AB)
``<id>-<A>-cp`` AB, real A, B as ghosts E_A^AB(AB)
``<id>-<A>-own`` AB, real A, B left out E_A^A(AB)
``<id>-<A>`` A at its own geometry E_A^A(A), with deformation
======================== ============================== =========================
and the same for B.
"""
from __future__ import annotations
import math
from typing import Any
from vibesketcher.document.counterpoise import (
BOYS_BERNARDI,
centre_record,
fragment_refusals,
ghost_atoms,
)
from vibesketcher.document.model import (
BindingAnalysis,
CalculationStage,
Document,
FragmentCentres,
JobSpec,
)
from vibesketcher.document.results import ResultRefused
__all__ = [
"counterpoise_jobs",
"counterpoise_result",
"fragment_mapping_refusals",
"spec_refusals",
]
_HARTREE_TO_KCAL_MOL = 627.5094740631 # CODATA 2018, as vibesketcher.units uses
[docs]
def fragment_mapping_refusals(document: Document, analysis: BindingAnalysis) -> list[str]:
"""Why the fragments are not an explicit partition of the complex's atoms."""
assert analysis.fragments is not None # the model requires them with counterpoise
complex_species = document.species_by_id(analysis.complex)
symbols = complex_species.conformers[0].symbols
reasons: list[str] = []
seen: list[int] = []
for fragment in analysis.fragments:
free = document.species_by_id(fragment.species)
free_symbols = free.conformers[0].symbols
if len(fragment.atoms) != len(free_symbols):
reasons.append(
f"{fragment.species}: maps {len(fragment.atoms)} complex atoms onto "
f"{len(free_symbols)} fragment atoms"
)
continue
beyond = [i for i in fragment.atoms if i >= len(symbols)]
if beyond:
reasons.append(
f"{fragment.species}: complex atom {beyond[0]} does not exist "
f"({analysis.complex} has atoms 0 to {len(symbols) - 1})"
)
continue
wrong = [(k, i) for k, i in enumerate(fragment.atoms) if symbols[i] != free_symbols[k]]
if wrong:
k, i = wrong[0]
reasons.append(
f"{fragment.species}: fragment atom {k} is {free_symbols[k]}, but complex atom "
f"{i} is {symbols[i]}"
)
if (fragment.charge, fragment.multiplicity) != (free.charge, free.multiplicity):
reasons.append(
f"{fragment.species}: fragment charge/multiplicity {fragment.charge}/"
f"{fragment.multiplicity} differ from the free fragment's {free.charge}/"
f"{free.multiplicity}"
)
seen.extend(fragment.atoms)
if not reasons and sorted(seen) != list(range(len(symbols))):
repeated = sorted({i for i in seen if seen.count(i) > 1})
missing = sorted(set(range(len(symbols))) - set(seen))
detail = []
if repeated:
detail.append(f"atoms {repeated} are in both fragments")
if missing:
detail.append(f"atoms {missing} are in neither")
reasons.append("the fragments must partition the complex's atoms: " + "; ".join(detail))
for fragment in analysis.fragments if not reasons else []:
centres = _centres(fragment, "complex")
reasons.extend(
f"{fragment.species}: {r}" for r in fragment_refusals(complex_species, centres)
)
return reasons
[docs]
def spec_refusals(spec: JobSpec) -> list[str]:
"""What a counterpoise recipe's specification may not carry."""
reasons = []
if spec.fragment is not None:
reasons.append("the recipe's specification is the complex's; the recipe adds fragments")
if spec.dispersion is not None:
reasons.append(
"counterpoise corrects the basis set only: ghost centres carry no dispersion atoms, "
"so compute a dispersion correction separately and leave dispersion out"
)
if spec.solvent is not None:
reasons.append("ghost centres carry no cavity atoms: counterpoise recipes are gas phase")
return reasons
def _centres(fragment: Any, basis: str) -> FragmentCentres:
return FragmentCentres.model_validate(
{
"atoms": list(fragment.atoms),
"basis": basis,
"charge": fragment.charge,
"multiplicity": fragment.multiplicity,
}
)
[docs]
def counterpoise_jobs(
identifier: str, analysis: BindingAnalysis, spec: JobSpec
) -> list[tuple[str, str, str, JobSpec]]:
"""``(job id, species, role, specification)`` for every job of the recipe, in order."""
assert analysis.fragments is not None
jobs = [(f"{identifier}-{analysis.complex}", analysis.complex, "complex", spec)]
for fragment in sorted(analysis.fragments, key=lambda f: f.species != analysis.cluster):
sid = fragment.species
for basis, suffix in (("complex", "cp"), ("fragment", "own")):
jobs.append(
(
f"{identifier}-{sid}-{suffix}",
analysis.complex,
f"{sid}:{suffix}",
spec.model_copy(update={"fragment": _centres(fragment, basis)}),
)
)
if analysis.deformation:
jobs.append((f"{identifier}-{sid}", sid, f"{sid}:free", spec))
return jobs
def _quantity(hartree: float) -> dict[str, Any]:
if not math.isfinite(hartree):
raise ResultRefused("energy evaluation overflow")
kcal = hartree * _HARTREE_TO_KCAL_MOL
return {"value": hartree, "units": "hartree", "kcal_mol": kcal, "kj_mol": kcal * 4.184}
[docs]
def counterpoise_result(
document: Document,
identifier: str,
analysis: BindingAnalysis,
calculation: CalculationStage,
runs: list[str],
) -> dict[str, Any]:
"""CP-corrected and uncorrected interaction (and binding) energies from chosen runs."""
from vibesketcher.document.results import _run, species_digest
expected = {
role: (sid, job_spec)
for _, sid, role, job_spec in counterpoise_jobs(identifier, analysis, calculation.spec)
}
if len(runs) != len(set(runs)) or len(runs) != len(expected):
raise ResultRefused(
f"select exactly one distinct imported run per counterpoise job ({len(expected)}: "
f"{', '.join(expected)})"
)
energies: dict[str, float] = {}
sources = []
versions = set()
for run_id in runs:
job, run = _run(document, run_id)
role = next(
(
r
for r, (sid, job_spec) in expected.items()
if sid == job.species
and job.spec.model_dump(exclude={"resources"})
== job_spec.model_dump(exclude={"resources"})
),
None,
)
if role is None or job.program != calculation.program:
raise ResultRefused(
f"{run_id}: not one of this recipe's jobs (species, fragment mask, ghost "
"centres, method and basis must all match)"
)
if role in energies:
raise ResultRefused(f"{run_id}: a second run of the {role} job")
result = run.result
species = document.species_by_id(job.species)
if (
result is None
or result.specification != job.spec
or result.species_sha256 != species_digest(species)
or result.parser != {"orca": "orca-text/1", "vibeqc": "qvf/1"}.get(job.program)
):
raise ResultRefused(f"{run_id}: missing or stale imported result")
versions.add(result.program_version)
energies[role] = result.energy.value
fragment = job.spec.fragment
sources.append(
{
"role": role,
"species": job.species,
"job": job.id,
"run": run.id,
"fragment": None
if fragment is None
else {
**fragment.model_dump(mode="json"),
"ghost_atoms": ghost_atoms(species, fragment),
},
"centres": centre_record(species, fragment),
"result": result.model_dump(mode="json", exclude_none=True),
}
)
if len(versions) != 1:
raise ResultRefused("selected results use different program versions")
a, b = analysis.cluster, analysis.adsorbate
ab = energies["complex"]
uncorrected = ab - energies[f"{a}:own"] - energies[f"{b}:own"]
corrected = ab - energies[f"{a}:cp"] - energies[f"{b}:cp"]
bsse_a = energies[f"{a}:own"] - energies[f"{a}:cp"]
bsse_b = energies[f"{b}:own"] - energies[f"{b}:cp"]
values: dict[str, Any] = {
"interaction_cp": _quantity(corrected),
"interaction_uncorrected": _quantity(uncorrected),
"bsse": _quantity(corrected - uncorrected),
"bsse_by_fragment": {a: _quantity(bsse_a), b: _quantity(bsse_b)},
}
formulas = {
"interaction_cp": "E_AB^AB(AB) - E_A^AB(AB) - E_B^AB(AB)",
"interaction_uncorrected": "E_AB^AB(AB) - E_A^A(AB) - E_B^B(AB)",
"bsse": "interaction_cp - interaction_uncorrected "
"= [E_A^A(AB) - E_A^AB(AB)] + [E_B^B(AB) - E_B^AB(AB)]",
}
annotation = [
f"CP-corrected interaction energy {corrected * _HARTREE_TO_KCAL_MOL:.2f} kcal/mol "
f"(uncorrected {uncorrected * _HARTREE_TO_KCAL_MOL:.2f}, BSSE "
f"{(corrected - uncorrected) * _HARTREE_TO_KCAL_MOL:.2f})",
f"{calculation.spec.method}/{calculation.spec.basis or 'composite'}, Boys-Bernardi",
]
if analysis.deformation:
def_a = energies[f"{a}:own"] - energies[f"{a}:free"]
def_b = energies[f"{b}:own"] - energies[f"{b}:free"]
values["deformation"] = {a: _quantity(def_a), b: _quantity(def_b)}
values["binding_cp"] = _quantity(corrected + def_a + def_b)
values["binding_uncorrected"] = _quantity(
ab - energies[f"{a}:free"] - energies[f"{b}:free"]
)
formulas.update(
deformation="E_X^X(AB) - E_X^X(X) for X = A, B",
binding_cp="interaction_cp + deformation(A) + deformation(B)",
binding_uncorrected="E_AB^AB(AB) - E_A^A(A) - E_B^B(B)",
)
return {
"recipe": identifier,
"analysis": analysis.model_dump(mode="json"),
"specification": calculation.spec.model_dump(mode="json", exclude_none=True),
"program": calculation.program,
"program_version": next(iter(versions)),
"method": "Boys-Bernardi counterpoise",
"reference": BOYS_BERNARDI,
"fragments": {"A": a, "B": b},
"absolute_energies_hartree": dict(sorted(energies.items())),
"formulas": formulas,
"sign_convention": "negative is bound",
"ghost_convention": (
"ghost centres carry their element's basis functions only: no nuclear charge, "
"electrons, ECP, dispersion or cavity atoms"
),
"sources": sources,
"temperature_k": None,
"pressure_atm": None,
"energies": values,
"annotation": annotation,
}