vibe-sketcherDocumentation

vibesketcher.document.solid_energetics

Adsorption, surface and neutral defect energies from linked periodic runs (#195).

A plan fixes the members of an energy difference, writes one vibe-qc input per member with the same Hamiltonian, and records the formula, the normalisation and every assumption. Evaluation reads the members’ result QVFs, checks that each result is the planned structure computed with the planned method, and returns the energy with units. Nothing is inferred:

  • adsorption: E_ads = [E(slab + n X) - E(slab) - n E(X, gas)] / n, with the complex built from that slab and its composition differing by exactly n X;

  • surface: gamma = [E(slab) - N E(bulk per formula unit)] / (2 A) for a stoichiometric slab with identical faces (Boettger, Phys. Rev. B 49, 16798 (1994) discusses the bulk-reference choice); A is the in-plane area;

  • defect formation (neutral only): E_f = E(defective) - E(pristine) - sum_i dn_i mu_i, with every reservoir mu_i stated (a value and its source, or a gas species and its atom count, e.g. mu_O = E(O2)/2). Charged defects need a Fermi level, potential alignment and a finite-size correction (Freysoldt, Neugebauer and Van de Walle, Phys. Rev. Lett. 102, 016402 (2009)); they are refused here rather than reported uncorrected.

A gas-phase molecule is computed as a molecule with the same method and basis (seccm members pair with molecular MSINDO). k-meshes, slab thickness, vacuum and cluster size are recorded, not converged, by a plan.

Functions

evaluate(plan, results)

Combine member results into the planned energy, refusing mismatched results.

plan_adsorption(document, complex_id, ...)

plan_defect(document, defective_id, ...)

plan_surface(document, slab_id, bulk_id, spec)

Classes

Member(*, role[, structure, species])

Reservoir(*[, value_ev, source, species, atoms])

A chemical potential: a stated value, or half (1/atoms) of a gas species' energy.

SolidEnergyPlan(*[, schema, reservoirs])

class vibesketcher.document.solid_energetics.Reservoir(*, value_ev=None, source=None, species=None, atoms=1)[source]

Bases: BaseModel

A chemical potential: a stated value, or half (1/atoms) of a gas species’ energy.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

value_ev: float | None
source: str | None
species: str | None
atoms: int
class vibesketcher.document.solid_energetics.Member(*, role, structure=None, species=None, formula, input, method)[source]

Bases: BaseModel

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

role: str
structure: str | None
species: str | None
formula: dict[str, int]
input: str
method: str
class vibesketcher.document.solid_energetics.SolidEnergyPlan(*, schema='vibe-solid-energy/1', kind, members, coefficients, normalisation, unit, formula, spec, reservoirs=<factory>, assumptions, references)[source]

Bases: BaseModel

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_id: Literal['vibe-solid-energy/1']
kind: Literal['adsorption', 'surface', 'defect']
members: list[Member]
coefficients: dict[str, float]
normalisation: dict[str, float]
unit: Literal['eV', 'J/m2']
formula: str
spec: dict[str, Any]
reservoirs: dict[str, Reservoir]
assumptions: list[str]
references: list[str]
vibesketcher.document.solid_energetics.plan_adsorption(document, complex_id, slab_id, gas, spec)[source]
Parameters:
Return type:

tuple[SolidEnergyPlan, InputBundle]

vibesketcher.document.solid_energetics.plan_surface(document, slab_id, bulk_id, spec, bulk_spec=None)[source]
Parameters:
Return type:

tuple[SolidEnergyPlan, InputBundle]

vibesketcher.document.solid_energetics.plan_defect(document, defective_id, pristine_id, reservoirs, spec)[source]
Parameters:
Return type:

tuple[SolidEnergyPlan, InputBundle]

vibesketcher.document.solid_energetics.evaluate(plan, results)[source]

Combine member results into the planned energy, refusing mismatched results.

Parameters:
Return type:

dict[str, Any]