vibe-sketcherDocumentation

vibesketcher.document.periodic_recipes

Periodic scan, phonon and free-energy recipes that write one input per point (#208).

A recipe is planned against the pinned engine table in vibesketcher.document.periodic_capabilities. Where the engine runs the task, the plan writes one vibe-qc input per point plus a run_all.py driver that runs them in order and collects scan-results.json; where it does not, the plan is still written (what would be computed, with every parameter) but its execution is refused with the engine’s reason and the tracker item that owns the missing capability.

  • volume_scan: isotropic strains of a 3-D cell at fixed fractional coordinates (or with fixed-cell atomic relaxation), one fixed k-mesh, the energy normalised per formula unit, fitted with vibesketcher.document.eos (Birch 1947; Vinet et al. 1987).

  • coordinate_scan: a distance or angle between named sites set to each target value by moving named sites (rigid points), or relaxed with the defining atoms frozen where the engine freezes atoms.

  • phonons: a finite-displacement supercell plan (K. Parlinski, Z. Q. Li and Y. Kawazoe, Phys. Rev. Lett. 78, 4063 (1997); A. Togo and I. Tanaka, Scr. Mater. 108, 1 (2015)): supercell, displacement amplitude, q-mesh and masses. Planned only: periodic Hessians fail closed in the engine.

  • free_energy: harmonic or quasi-harmonic F(T) / G(T, p) recipes (Togo and Tanaka 2015, section 4), gated with the phonons and listing the terms the model omits.

A Gamma-only Hessian of the unit cell treated as a molecule is never accepted or relabelled as a phonon spectrum.

Module Attributes

KB_EV

Boltzmann constant in eV/K (CODATA 2018, exact).

ENGINE_SCF_DEFAULTS

SCF defaults the engine applies when the input leaves them unset.

Functions

eos_table(plan_[, results, qvfs, ...])

An EosTable from a volume-scan plan and its results.

formula_units(structure[, given])

The reduced formula and the formula units per cell (stated or the composition's gcd).

harmonic_free_energy(frequencies_cm1, ...[, ...])

Harmonic vibrational F, ZPE, S and C_V from explicit frequencies (Togo and Tanaka 2015).

measure(structure, coordinate, sites)

The minimum-image distance (A) or angle (degrees) between named sites.

parse_recipe(data)

Validate a recipe by its kind.

plan(document, recipe)

Dispatch a recipe to its planner.

plan_coordinate_scan(document, recipe)

One input per target distance or angle, rigid or with the defining atoms frozen.

plan_free_energy(document, recipe)

A harmonic or quasi-harmonic free-energy recipe, gated with the phonons.

plan_or_refusal(document, data)

Plan a recipe dictionary; a refusal comes back as data, not an exception.

plan_phonons(document, recipe)

A finite-displacement supercell plan; execution refused while the engine lacks it.

plan_volume_scan(document, recipe)

One input per volume at fixed fractional coordinates (or relaxed positions).

standard_mass(symbol)

The standard atomic weight in amu (RDKit's IUPAC table).

Classes

CoordinateScanRecipe(*, structure[, spec, ...])

FreeEnergyRecipe(*, structure[, spec, kind, ...])

PhononRecipe(*, structure[, spec, kind, ...])

RecipePlan(*[, schema, points, ...])

What a recipe computes, every parameter it fixes, and whether it can run.

VolumeScanRecipe(*, structure[, spec, kind, ...])

Exceptions

RecipeRefused(message[, report])

A recipe the engine (or the planner) cannot run; report says why.

vibesketcher.document.periodic_recipes.KB_EV = 8.617333262e-05

Boltzmann constant in eV/K (CODATA 2018, exact).

vibesketcher.document.periodic_recipes.ENGINE_SCF_DEFAULTS = {'conv_tol_energy_hartree': 1e-07, 'max_iter': 80}

SCF defaults the engine applies when the input leaves them unset.

exception vibesketcher.document.periodic_recipes.RecipeRefused(message, report=None)[source]

Bases: ValueError

A recipe the engine (or the planner) cannot run; report says why.

Parameters:
Return type:

None

class vibesketcher.document.periodic_recipes.VolumeScanRecipe(*, structure, spec=<factory>, kind='volume_scan', volume_fractions=<factory>, relax='none', formula_units=None)[source]

Bases: _Recipe

Parameters:
kind: Literal['volume_scan']
volume_fractions: list[float]

V / V_input of each point; the cell is scaled isotropically.

relax: Literal['none', 'positions']
formula_units: int | None

Formula units per cell; derived from the composition when left out.

model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_recipes.CoordinateScanRecipe(*, structure, spec=<factory>, kind='coordinate_scan', coordinate, sites, values, moving=<factory>, relax='none', min_contact_angstrom=0.5)[source]

Bases: _Recipe

Parameters:
kind: Literal['coordinate_scan']
coordinate: Literal['distance', 'angle']
sites: list[str]

Two site IDs for a distance, three (vertex in the middle) for an angle.

values: list[float]

Target values in angstrom (distance) or degrees (angle).

moving: list[str]

Sites moved to reach each value; default the last site.

relax: Literal['none', 'positions']
min_contact_angstrom: float
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_recipes.PhononRecipe(*, structure, spec=<factory>, kind='phonons', supercell=(2, 2, 2), displacement_angstrom=0.01, q_mesh=(8, 8, 8), masses=<factory>, acoustic_sum_rule=True, hessian_source='periodic-supercell')[source]

Bases: _Recipe

Parameters:
kind: Literal['phonons']
supercell: tuple[int, int, int]
displacement_angstrom: float
q_mesh: tuple[int, int, int]
masses: dict[str, float]

Mass overrides in amu (isotopes); every other element uses the standard atomic weight.

acoustic_sum_rule: bool
hessian_source: Literal['periodic-supercell', 'molecular-gamma']

Where force constants would come from. A molecular Gamma Hessian is refused.

model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_recipes.FreeEnergyRecipe(*, structure, spec=<factory>, kind='free_energy', approximation='harmonic', temperatures_k=<factory>, pressures_gpa=<factory>, volume_fractions=<factory>, phonons=None)[source]

Bases: _Recipe

Parameters:
kind: Literal['free_energy']
approximation: Literal['harmonic', 'quasi-harmonic']
temperatures_k: list[float]
pressures_gpa: list[float]

Pressures for G(T, p) (quasi-harmonic only).

volume_fractions: list[float]

Volumes of the quasi-harmonic grid (V / V_input).

phonons: PhononRecipe | None
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_recipes.RecipePlan(*, schema='vibe-periodic-recipe/1', kind, structure, status, engine, capabilities, spec, recipe, points=<factory>, normalisation=<factory>, units=<factory>, convergence=<factory>, formula=None, assumptions=<factory>, warnings=<factory>, omitted_terms=<factory>, refusal=None, references=<factory>, files=<factory>)[source]

Bases: BaseModel

What a recipe computes, every parameter it fixes, and whether it can run.

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

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

schema_id: Literal['vibe-periodic-recipe/1']
kind: str
structure: str
status: Literal['ready', 'refused']
engine: dict[str, str]
capabilities: list[dict[str, Any]]
spec: dict[str, Any]
recipe: dict[str, Any]
points: list[dict[str, Any]]
normalisation: dict[str, Any]
units: dict[str, str]
convergence: dict[str, Any]
formula: str | None
assumptions: list[str]
warnings: list[str]
omitted_terms: list[dict[str, str]]
refusal: dict[str, Any] | None
references: list[str]
files: list[str]
vibesketcher.document.periodic_recipes.parse_recipe(data)[source]

Validate a recipe by its kind.

Parameters:

data (dict[str, Any])

Return type:

VolumeScanRecipe | CoordinateScanRecipe | PhononRecipe | FreeEnergyRecipe

vibesketcher.document.periodic_recipes.formula_units(structure, given=None)[source]

The reduced formula and the formula units per cell (stated or the composition’s gcd).

Parameters:
Return type:

tuple[str, int]

vibesketcher.document.periodic_recipes.plan_volume_scan(document, recipe)[source]

One input per volume at fixed fractional coordinates (or relaxed positions).

Parameters:
Return type:

tuple[RecipePlan, InputBundle]

vibesketcher.document.periodic_recipes.measure(structure, coordinate, sites)[source]

The minimum-image distance (A) or angle (degrees) between named sites.

Parameters:
Return type:

float

vibesketcher.document.periodic_recipes.plan_coordinate_scan(document, recipe)[source]

One input per target distance or angle, rigid or with the defining atoms frozen.

Parameters:
Return type:

tuple[RecipePlan, InputBundle]

vibesketcher.document.periodic_recipes.standard_mass(symbol)[source]

The standard atomic weight in amu (RDKit’s IUPAC table).

Parameters:

symbol (str)

Return type:

float

vibesketcher.document.periodic_recipes.plan_phonons(document, recipe)[source]

A finite-displacement supercell plan; execution refused while the engine lacks it.

Parameters:
Return type:

tuple[RecipePlan, InputBundle]

vibesketcher.document.periodic_recipes.plan_free_energy(document, recipe)[source]

A harmonic or quasi-harmonic free-energy recipe, gated with the phonons.

Parameters:
Return type:

tuple[RecipePlan, InputBundle]

vibesketcher.document.periodic_recipes.harmonic_free_energy(frequencies_cm1, temperature_k, weights=None, *, zero_tolerance_cm1=0.001, imaginary_tolerance_cm1=0.001)[source]

Harmonic vibrational F, ZPE, S and C_V from explicit frequencies (Togo and Tanaka 2015).

Frequencies are in cm^-1 with q-point weights (normalised to sum 1); an imaginary mode (given as a negative frequency) is refused, zero modes are counted and excluded. The energies are per cell of the frequencies.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.periodic_recipes.plan(document, recipe)[source]

Dispatch a recipe to its planner.

Parameters:
Return type:

tuple[RecipePlan, InputBundle]

vibesketcher.document.periodic_recipes.plan_or_refusal(document, data)[source]

Plan a recipe dictionary; a refusal comes back as data, not an exception.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.periodic_recipes.eos_table(plan_, results=None, qvfs=None, *, drop_unconverged=False)[source]

An EosTable from a volume-scan plan and its results.

results is a scan-results.json written by the plan’s driver; qvfs maps point labels to result QVFs. Every planned point needs one.

Parameters:
Return type:

Any