vibe-sketcherDocumentation

vibesketcher.document.core_potentials

Explicit heavy-element basis, core-potential and scalar-relativistic contracts (#242).

A job specification states, per element, the orbital basis set and either a named effective core potential (ECP) with the number of core electrons it replaces, or an all-electron treatment, together with one Hamiltonian for the molecule: nonrelativistic (scalar relativity, if any, carried by the ECPs) or a scalar-relativistic all-electron Hamiltonian, zora or dkh2. Nothing here infers a core potential from an element label: the tables only decide whether a stated choice is consistent, and refuse it, with the reason, when it is not or when the table does not know it.

Sources of the tables:

  • def2-ECP core sizes and per-element sources: Weigend and Ahlrichs, Phys. Chem. Chem. Phys. 7, 3297 (2005), doi:10.1039/B508541A, section 2: ECP-28 for Rb-Xe, ECP-46 for Cs, Ba, La and ECP-60 for Hf-Rn; the lanthanides Ce-Lu are excluded there and are not admitted here. Y-Cd and Hf-Hg use Andrae et al., Theor. Chim. Acta 77, 123 (1990), doi:10.1007/BF01114537; In-Sb and Tl-Bi use Metz, Stoll and Dolg, J. Chem. Phys. 113, 2563 (2000), doi:10.1063/1.1305880.

  • ZORA: van Lenthe, Baerends and Snijders, J. Chem. Phys. 99, 4597 (1993), doi:10.1063/1.466059. DKH2: Hess, Phys. Rev. A 33, 3742 (1986), doi:10.1103/PhysRevA.33.3742.

  • SARC all-electron scalar-relativistic basis sets: Pantazis, Chen, Landis and Neese, J. Chem. Theory Comput. 4, 908 (2008), doi:10.1021/ct800047t (Hf-Hg, and the ZORA/DKH recontractions of def2 for H-Kr); Pantazis and Neese, Theor. Chem. Acc. 131, 1292 (2012), doi:10.1007/s00214-012-1292-x (Tl-Rn).

The module is standard library only, so the document model can use it.

Module Attributes

HEAVY_ELEMENT_Z

Elements beyond this atomic number (Kr) need an explicit contract in recipes.

Functions

atom_treatments(species, spec)

Per element of the species: its basis and ECP as the specification states them.

basis_kind(basis, z)

What basis is on element z, or None when the table does not know.

contract_active(spec)

Whether the specification states a basis/core/Hamiltonian contract.

contract_record(spec, species)

The provenance of a stated contract, for reports; None if none is stated.

contract_refusals(species, spec, *[, require])

Why the stated contract is inconsistent for species; empty if it holds.

core_potential_table()

The ECPs, basis families and Hamiltonians the contract admits, for review.

ecp_data(name)

The table entry for an ECP name (case-insensitive), or None.

electron_accounting(species, spec)

Nuclear charge, electrons, ECP core electrons and explicit electrons of a species.

recorded_core_refusals(species, spec, *, ...)

Why the cores a result records disagree with the stated contract; empty if they agree.

stale_entries(spec, species)

Elements element_basis names that none of species contains.

Classes

EcpData(name, cores, references, pairs_with)

One named ECP family: the core it replaces per element, and its sources.

vibesketcher.document.core_potentials.HEAVY_ELEMENT_Z: Final = 36

Elements beyond this atomic number (Kr) need an explicit contract in recipes.

class vibesketcher.document.core_potentials.EcpData(name, cores, references, pairs_with)[source]

Bases: object

One named ECP family: the core it replaces per element, and its sources.

Parameters:
name: str
cores: dict[int, int]
references: dict[int, str]
pairs_with: str
record(z)[source]
Parameters:

z (int)

Return type:

dict[str, Any]

vibesketcher.document.core_potentials.atom_treatments(species, spec)[source]

Per element of the species: its basis and ECP as the specification states them.

Parameters:
Return type:

dict[str, dict[str, Any]]

vibesketcher.document.core_potentials.contract_active(spec)[source]

Whether the specification states a basis/core/Hamiltonian contract.

Parameters:

spec (JobSpec)

Return type:

bool

vibesketcher.document.core_potentials.contract_record(spec, species)[source]

The provenance of a stated contract, for reports; None if none is stated.

Parameters:
Return type:

dict[str, Any] | None

vibesketcher.document.core_potentials.contract_refusals(species, spec, *, require=False)[source]

Why the stated contract is inconsistent for species; empty if it holds.

require (recipes) demands the contract, with an explicit entry for every element beyond Kr, instead of leaving an absent one to the writer.

Parameters:
Return type:

list[str]

vibesketcher.document.core_potentials.core_potential_table()[source]

The ECPs, basis families and Hamiltonians the contract admits, for review.

Return type:

dict[str, Any]

vibesketcher.document.core_potentials.ecp_data(name)[source]

The table entry for an ECP name (case-insensitive), or None.

Parameters:

name (str)

Return type:

EcpData | None

vibesketcher.document.core_potentials.electron_accounting(species, spec)[source]

Nuclear charge, electrons, ECP core electrons and explicit electrons of a species.

Parameters:
Return type:

dict[str, Any] | None

vibesketcher.document.core_potentials.recorded_core_refusals(species, spec, *, physical_electrons, explicit_electrons, centres)[source]

Why the cores a result records disagree with the stated contract; empty if they agree.

The evidence is what a QVF result can record (QVF spec § 5.3, wavefunction.gto): physical_electrons, all of the species’ electrons before any core is removed (provenance.n_electrons); explicit_electrons, the electrons each canonical wavefunction describes (its basis n_electrons, or its summed occupations); and centres, per wavefunction with a basis ecp list, the replaced core electrons by 0-based atom index. The difference between the first two is the total the core potentials replaced. A result with neither kind of evidence is refused: the contract could not be checked.

Parameters:
Return type:

list[str]

vibesketcher.document.core_potentials.stale_entries(spec, species)[source]

Elements element_basis names that none of species contains.

Parameters:
Return type:

list[str]