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 withvibesketcher.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
Boltzmann constant in eV/K (CODATA 2018, exact). |
|
SCF defaults the engine applies when the input leaves them unset. |
Functions
|
An |
|
The reduced formula and the formula units per cell (stated or the composition's gcd). |
|
Harmonic vibrational F, ZPE, S and C_V from explicit frequencies (Togo and Tanaka 2015). |
|
The minimum-image distance (A) or angle (degrees) between named sites. |
|
Validate a recipe by its |
|
Dispatch a recipe to its planner. |
|
One input per target distance or angle, rigid or with the defining atoms frozen. |
|
A harmonic or quasi-harmonic free-energy recipe, gated with the phonons. |
|
Plan a recipe dictionary; a refusal comes back as data, not an exception. |
|
A finite-displacement supercell plan; execution refused while the engine lacks it. |
|
One input per volume at fixed fractional coordinates (or relaxed positions). |
|
The standard atomic weight in amu (RDKit's IUPAC table). |
Classes
|
|
|
|
|
|
|
What a recipe computes, every parameter it fixes, and whether it can run. |
|
Exceptions
|
A recipe the engine (or the planner) cannot run; |
- 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:
ValueErrorA recipe the engine (or the planner) cannot run;
reportsays why.
- 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']¶
- relax: Literal['none', 'positions']¶
- 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:
structure (str)
spec (PeriodicJobSpec)
kind (Literal['coordinate_scan'])
coordinate (Literal['distance', 'angle'])
sites (Annotated[list[str], MinLen(min_length=2), MaxLen(max_length=3)])
values (Annotated[list[float], MinLen(min_length=2), MaxLen(max_length=60)])
relax (Literal['none', 'positions'])
- kind: Literal['coordinate_scan']¶
- coordinate: Literal['distance', 'angle']¶
- relax: Literal['none', 'positions']¶
- 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']¶
- masses: dict[str, float]¶
Mass overrides in amu (isotopes); every other element uses the standard atomic weight.
- 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:
structure (str)
spec (PeriodicJobSpec)
kind (Literal['free_energy'])
approximation (Literal['harmonic', 'quasi-harmonic'])
temperatures_k (Annotated[list[float], MinLen(min_length=1), MaxLen(max_length=500)])
pressures_gpa (Annotated[list[float], MaxLen(max_length=100)])
volume_fractions (Annotated[list[float], MaxLen(max_length=25)])
phonons (PhononRecipe | None)
- kind: Literal['free_energy']¶
- approximation: Literal['harmonic', 'quasi-harmonic']¶
- 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:
BaseModelWhat 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']¶
- status: Literal['ready', 'refused']¶
- vibesketcher.document.periodic_recipes.parse_recipe(data)[source]¶
Validate a recipe by its
kind.- Parameters:
- 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:
structure (PeriodicStructure)
given (int | None)
- Return type:
- vibesketcher.document.periodic_recipes.plan_volume_scan(document, recipe)[source]¶
One input per volume at fixed fractional coordinates (or relaxed positions).
- Parameters:
document (Document)
recipe (VolumeScanRecipe)
- Return type:
- vibesketcher.document.periodic_recipes.measure(structure, coordinate, sites)[source]¶
The minimum-image distance (A) or angle (degrees) between named sites.
- Parameters:
structure (PeriodicStructure)
coordinate (str)
- Return type:
- 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:
document (Document)
recipe (CoordinateScanRecipe)
- Return type:
- vibesketcher.document.periodic_recipes.standard_mass(symbol)[source]¶
The standard atomic weight in amu (RDKit’s IUPAC table).
- vibesketcher.document.periodic_recipes.plan_phonons(document, recipe)[source]¶
A finite-displacement supercell plan; execution refused while the engine lacks it.
- Parameters:
document (Document)
recipe (PhononRecipe)
- Return type:
- vibesketcher.document.periodic_recipes.plan_free_energy(document, recipe)[source]¶
A harmonic or quasi-harmonic free-energy recipe, gated with the phonons.
- Parameters:
document (Document)
recipe (FreeEnergyRecipe)
- Return type:
- 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.
- vibesketcher.document.periodic_recipes.plan(document, recipe)[source]¶
Dispatch a recipe to its planner.
- Parameters:
document (Document)
recipe (VolumeScanRecipe | CoordinateScanRecipe | PhononRecipe | FreeEnergyRecipe)
- Return type:
- vibesketcher.document.periodic_recipes.plan_or_refusal(document, data)[source]¶
Plan a recipe dictionary; a refusal comes back as data, not an exception.
- vibesketcher.document.periodic_recipes.eos_table(plan_, results=None, qvfs=None, *, drop_unconverged=False)[source]¶
An
EosTablefrom a volume-scan plan and its results.resultsis ascan-results.jsonwritten by the plan’s driver;qvfsmaps point labels to result QVFs. Every planned point needs one.