vibe-sketcherDocumentation
Source code for vibesketcher.document.counterpoise
"""Ghost centres and Boys–Bernardi counterpoise jobs for finite clusters (#243).
Boys and Bernardi, Mol. Phys. 19, 553 (1970), doi:10.1080/00268977000101561:
the interaction of A and B is taken as a difference of energies all computed
in the same basis, the basis of the complex AB at its geometry, so that the
superposition of the partner's functions lowers the fragment energies as much
as it lowers the complex's,
ΔE_int^CP = E_AB^AB(AB) − E_A^AB(AB) − E_B^AB(AB),
where the superscript is the basis and the argument the geometry. The
uncorrected interaction at the same geometry uses each fragment's own basis,
ΔE_int = E_AB^AB(AB) − E_A^A(AB) − E_B^B(AB),
and their difference is the basis-set superposition error,
BSSE = ΔE_int^CP − ΔE_int = [E_A^A(AB) − E_A^AB(AB)] + [E_B^B(AB) − E_B^AB(AB)],
which is positive when the partner's functions lower the fragment's energy.
The relaxation of each fragment from its free geometry to the complex's, the
deformation energy E_A^A(AB) − E_A^A(A), is a separate term, computed only
when the recipe asks for the free fragments too.
A **ghost centre** carries its element's basis functions (and, in ORCA, the
contracted functions ``NewGTO`` assigns to that element), but no nuclear
charge, no electrons, no ECP, no dispersion atom and no cavity atom. The
fragment's real atoms keep their nuclei; the fragment's charge and
multiplicity are stated explicitly. Fragment jobs are single points on the
complex species' first conformer, so a fragment can never be at a geometry
other than the complex's.
"""
from __future__ import annotations
from collections.abc import Sequence
from typing import Any
from vibesketcher.document.model import Conformer, FragmentCentres, Species
from vibesketcher.elements import ATOMIC_NUMBER
__all__ = [
"BOYS_BERNARDI",
"centre_record",
"fragment_refusals",
"ghost_atoms",
"real_species",
]
BOYS_BERNARDI = (
"Boys and Bernardi, Mol. Phys. 19, 553 (1970), https://doi.org/10.1080/00268977000101561"
)
[docs]
def ghost_atoms(species: Species, fragment: FragmentCentres) -> list[int]:
"""The atoms of ``species`` that are ghost centres in this fragment job.
Every atom outside the fragment when the job is in the complex's basis;
none when it is in the fragment's own basis (they are left out instead).
"""
if fragment.basis != "complex" or not species.conformers:
return []
real = set(fragment.atoms)
return [i for i in range(len(species.conformers[0].symbols)) if i not in real]
[docs]
def fragment_refusals(species: Species, fragment: FragmentCentres) -> list[str]:
"""Why ``fragment`` is not a fragment job on ``species``; empty if it is."""
if not species.conformers:
return [f"species {species.id} has no geometry for a fragment job"]
count = len(species.conformers[0].symbols)
beyond = [i for i in fragment.atoms if i >= count]
if beyond:
return [
f"the fragment names atom {beyond[0]}, but species {species.id} has atoms 0 to "
f"{count - 1}"
]
reasons: list[str] = []
if len(fragment.atoms) == count:
reasons.append(
"the fragment is the whole complex: a fragment job keeps some atoms as ghosts "
"or leaves them out"
)
symbols = species.conformers[0].symbols
electrons = sum(ATOMIC_NUMBER[symbols[i]] for i in fragment.atoms) - fragment.charge
if electrons <= 0:
reasons.append(f"the fragment has {electrons} electrons: there is nothing to compute")
elif (electrons + fragment.multiplicity) % 2 == 0:
reasons.append(
f"a fragment with {electrons} electrons cannot have multiplicity "
f"{fragment.multiplicity}"
)
return reasons
[docs]
def real_species(species: Species, fragment: FragmentCentres) -> Species:
"""The fragment's real atoms alone, with the fragment's charge and multiplicity.
Writers check electron counts, element limits and core potentials against
this; ghost centres are added only when the coordinates are written. Its
SMILES and InChIKey are dropped: they are the complex's, not the fragment's.
"""
conformer = species.conformers[0]
sub = Conformer(
method=conformer.method,
symbols=[conformer.symbols[i] for i in fragment.atoms],
xyz_angstrom=[list(conformer.xyz_angstrom[i]) for i in fragment.atoms],
)
return species.model_copy(
update={
"conformers": [sub],
"charge": fragment.charge,
"multiplicity": fragment.multiplicity,
"smiles": None,
"inchikey": None,
},
deep=True,
)
[docs]
def centre_record(species: Species, fragment: FragmentCentres | None) -> list[dict[str, Any]]:
"""Per atom of the complex: its element and role, ``real``, ``ghost`` or ``omitted``."""
if not species.conformers:
return []
symbols: Sequence[str] = species.conformers[0].symbols
real = set(range(len(symbols))) if fragment is None else set(fragment.atoms)
ghosts = set() if fragment is None else set(ghost_atoms(species, fragment))
return [
{
"atom": i,
"element": symbol,
"role": "real" if i in real else "ghost" if i in ghosts else "omitted",
}
for i, symbol in enumerate(symbols)
]