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, }