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 |
|
|
fixed-cell atomic relaxation |
|
|
relaxation with frozen atoms |
|
|
stress |
|
|
cell relaxation |
|
|
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 |
|---|---|
|
fewer than 5 points |
|
V0 lies outside the sampled volumes |
|
the lowest energy is the first or last point |
|
the volumes span less than 6 % or more than 40 % of V0 |
|
the energies span less than 1e-4 eV per formula unit |
|
the RMS residual is more than 2 % of the energy span |
|
B0 ≤ 0, or B0′ outside 1.5-8 |
|
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 |
|---|---|
|
the pinned capability table |
|
|
|
|
|
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.