vibe-sketcherDocumentation

Periodic scans, phonons and equations of state

vibe-sketcher plans periodic calculations that need more than one point: an energy-volume scan for an equation of state, a constrained distance or angle scan, a finite-displacement phonon calculation, and harmonic or quasi-harmonic free energies. A recipe writes one vibe-qc input per point, plus a run_all.py driver that runs the points in order and collects scan-results.json. It also writes a plan (<kind>-plan.json) that records every parameter the result depends on.

Every recipe is checked against the engine’s capability table before anything is written. The table is pinned to one vibe-qc release. A task that the pinned engine does not run on the chosen route is refused, with the engine’s reason and the issue that owns the missing capability. It is never moved to a nearby route. Phonon and free-energy plans are written in full, but their execution is refused, because vibe-qc’s periodic Hessians fail closed.

Capability table

vibe-sketcher solid recipe capabilities
vibe-sketcher solid recipe capabilities --task relax_cell --json

Each row names a task, a model (pbc, seccm, aiccm or mace), a route, the periodic dimensions, a status and the engine entry point:

  • admitted: the engine runs it and the sketcher writes the input;

  • library: the engine has a library function, but the sketcher writes no input for it;

  • refused: the engine refuses it on that route.

For the pinned release (vibe-qc 0.18.12):

Task

Admitted

Refused or library only

energy

pbc (BIPOLE dim 3; automatic J/K dim 1-3), seccm, aiccm (dim 3), mace

fixed-cell atomic relaxation

pbc (BIPOLE, GDF), mace

seccm, aiccm

relaxation with frozen atoms

mace

pbc: library only (vibeqc.relax_atoms)

stress

mace (dim 3)

pbc: no certified SCF stress (vibe-qc#773)

cell relaxation

mace (dim 3)

pbc BIPOLE and GDF; run_geomopt (vibe-qc#774)

Hessian, phonons, IR, free energy

none

every route (vibe-qc#968, vibe-qc#838)

A model name that is not in the table, such as ORB, MatterSim, UFF4MOF or DFTB+, is not an admission. A periodic MACE admission says nothing about molecular MACE, and the other way round.

Volume scans and equations of state

vibe-sketcher solid recipe volume-scan crystal.vsk --structure mgo \
    --fractions 0.94,0.96,0.98,1.0,1.02,1.04,1.06 --kmesh 4,4,4 -o eos
cd eos && vibeqc run run_all.py      # or python3 run_all.py
vibe-sketcher solid recipe analyse volume-scan-plan.json \
    --results scan-results.json --svg eos.svg

A volume scan needs a three-dimensional cell. Each point scales the input cell isotropically to V = fraction x V_input. The cell shape and the fractional coordinates stay fixed, unless relax: "positions" relaxes the atoms in each fixed cell (refused where the engine cannot relax atoms). At least five volumes are required. The plan records:

  • the k-mesh. One fixed mesh is used for every point, so the k-point density changes slightly with the volume, by (V / V_input)^(-1/3) per direction. A Gamma-only mesh is flagged.

  • the SCF convergence: max_iter (from the input or the engine default of 80) and the engine’s energy tolerance of 1e-7 hartree.

  • the normalisation: the reduced formula and the formula units per cell. The count comes from the composition’s greatest common divisor, or from formula_units, which must divide the composition.

  • the units: hartree per cell in the results, and eV and ų per formula unit in the fit. Bulk moduli are in GPa.

A MACE pre-optimisation or a cell relaxation would move the point off its volume, so both are refused in a scan.

The fit

analyse fits two four-parameter forms to energies per formula unit:

  • third-order Birch-Murnaghan (Birch, Phys. Rev. 71, 809, 1947, doi:10.1103/PhysRev.71.809). The energy is a cubic polynomial in V^(-2/3), so the least-squares fit is solved exactly and the parameters are taken at the polynomial’s minimum.

  • Vinet (Vinet, Ferrante, Rose and Smith, J. Geophys. Res. 92, 9319, 1987, doi:10.1029/JB092iB09p09319), by Levenberg-Marquardt least squares started from the Birch-Murnaghan parameters.

The report gives V0 (ų per formula unit), E0 (eV per formula unit and hartree per cell), B0 (GPa) and B0′ for each form. The fit is flagged rather than promoted when any of these holds:

Flag

Meaning

few_points

fewer than 5 points

minimum_not_bracketed

V0 lies outside the sampled volumes

minimum_at_edge

the lowest energy is the first or last point

narrow_range, wide_range

the volumes span less than 6 % or more than 40 % of V0

flat_curve

the energies span less than 1e-4 eV per formula unit

poor_residual

the RMS residual is more than 2 % of the energy span

unphysical_b0, unusual_b0_prime

B0 ≤ 0, or B0′ outside 1.5-8

models_disagree_v0, models_disagree_b0

the two forms differ by more than 0.5 % in V0 or 5 % in B0

A report with no flags has status fit; anything else is flagged. Unconverged points are refused unless --drop-unconverged removes them. Points computed with different settings (model, method, basis, k-mesh or engine version) are refused too.

The analyser reads the scan-results.json that run_all.py writes, a point’s result QVF (--qvf LABEL=path, checked against the planned composition), or a plain table:

{"schema": "vibe-eos-table/1", "formula": "MgO", "formula_units": 4,
 "points": [{"volume_angstrom3": 70.1, "energy_hartree": -1094.21, "converged": true}]}

--svg writes a paper-ready E(V) plot. It shows the points, both fitted curves and V0, B0 and B0′ in the legend, and marks a flagged fit.

Distance and angle scans

{"kind": "coordinate_scan", "structure": "water", "coordinate": "angle",
 "sites": ["H1", "O1", "H2"], "values": [100, 104.5, 110], "moving": ["H2"]}

A distance names two sites and an angle three, with the vertex in the middle. Values are in ångström or degrees, and are measured between minimum images. At each point the moving sites (by default the last site) are translated along the bond or rotated about the vertex, in a fixed cell. A point is refused if the moved site reaches a nearer image, so that the coordinate is not the one asked for, or if two atoms come closer than min_contact_angstrom.

relax: "positions" freezes the defining sites and relaxes every other atom. This is admitted for periodic MACE (optimize_frozen_indices). On pbc, run_periodic_job refuses frozen atoms, and vibe-qc’s own vibeqc.relaxed_scan is the route. The sketcher writes no input for it.

Phonon plans

{"kind": "phonons", "structure": "mgo", "supercell": [2, 2, 2],
 "displacement_angstrom": 0.01, "q_mesh": [8, 8, 8], "masses": {"O": 17.999}}

A phonon plan follows the finite-displacement supercell method (Parlinski, Li and Kawazoe, Phys. Rev. Lett. 78, 4063, 1997; Togo and Tanaka, Scr. Mater. 108, 1, 2015). It records:

  • the supercell, its atom count and its shortest lattice vector;

  • every displacement: each atom along ±x, ±y and ±z, with no symmetry reduction;

  • the displacement amplitude and the q-mesh;

  • the masses, standard atomic weights unless overridden;

  • the acoustic sum rule and the number of single points.

A 1×1×1 supercell, a supercell vector shorter than 10 Å and Gamma-only q-sampling are flagged.

The plan has status refused. Its refusal holds the engine report: run_periodic_job(hessian=True) fails closed on every route (vibe-qc#968), and the periodic force-constant route is vibe-qc#838. hessian_source: "molecular-gamma" is refused outright. A Gamma-only Hessian of the unit cell computed as a molecule has no periodic images, no dispersion and no acoustic sum rule of the crystal, and it is never reported as a phonon spectrum.

Free energies

{"kind": "free_energy", "structure": "mgo", "approximation": "quasi-harmonic",
 "temperatures_k": [0, 300, 1000], "pressures_gpa": [0, 10]}

A harmonic recipe is

F(T) = E_el + sum w_q [hbar omega / 2 + k_B T ln(1 - exp(-hbar omega / k_B T))]

at the input volume. A quasi-harmonic recipe is G(T, p) = min_V [E_el(V) + F_vib(V, T) + p V] over a volume grid, with the minimum taken from an EOS fit of F(V) at each temperature (Togo and Tanaka 2015, section 4). Both are gated with the phonons and carry the same refusal. Each lists its omitted terms:

  • thermal expansion and pV (harmonic only);

  • anharmonic phonon-phonon coupling;

  • electronic thermal excitation;

  • configurational and magnetic entropy;

  • anisotropic thermal strain (quasi-harmonic only).

vibesketcher.document.periodic_recipes.harmonic_free_energy (REST POST /api/periodic/recipes/harmonic) evaluates the zero-point energy, F, S and C_V from frequencies you give it, with optional q-point weights. It refuses imaginary modes and excludes zero modes. It is an independent check, not a source of frequencies.

SDK, REST and MCP

from vibesketcher.document import eos, periodic_recipes as pr

plan, bundle = pr.plan_volume_scan(document, pr.VolumeScanRecipe(structure="mgo"))
report = eos.analyse(pr.eos_table(plan, results_json))
svg = eos.plot_svg(report)

REST route

Purpose

GET /api/periodic/recipes/capabilities

the pinned capability table

POST /api/documents/{id}/periodic/recipes/plan

{recipe}: the plan and files, a plan with its refusal, or the refusal; the document is not changed

POST /api/periodic/recipes/eos

{table} or {plan, results, qvfs}, with svg: true for the plot

POST /api/periodic/recipes/harmonic

harmonic thermodynamics from explicit frequencies

The MCP tools periodic_capabilities, plan_periodic_recipe and analyse_eos call the same routes.

What a plan does not claim

A plan converges nothing by itself. Converge the k-mesh, the basis, the supercell and the displacement amplitude separately. Treat V0 and B0 from a small basis and a coarse mesh as experimental, until they are compared with a converged calculation or with experiment.