vibe-sketcherDocumentation

vibesketcher.document.eos

Equation-of-state fits of E(V) scans and their paper plot (#208).

Two four-parameter forms are fitted to energies per formula unit:

  • third-order Birch-Murnaghan (F. Birch, Phys. Rev. 71, 809 (1947), doi:10.1103/PhysRev.71.809), from the Eulerian finite strain f = [(V0/V)^(2/3) - 1] / 2: E(V) = E0 + (9 V0 B0 / 16) {[(V0/V)^(2/3) - 1]^3 B0’ + [(V0/V)^(2/3) - 1]^2 [6 - 4 (V0/V)^(2/3)]};

  • Vinet (P. Vinet, J. Ferrante, J. H. Rose and J. R. Smith, J. Geophys. Res. 92, 9319 (1987), doi:10.1029/JB092iB09p09319), with eta = (V/V0)^(1/3): E(V) = E0 + [2 B0 V0 / (B0’ - 1)^2] {2 - [5 + 3 B0’ (eta - 1) - 3 eta] exp[-3 (B0’ - 1)(eta - 1) / 2]}.

The Birch-Murnaghan energy is a cubic polynomial in x = V^(-2/3), so its least-squares fit is linear: the polynomial coefficients are solved exactly and E0, V0, B0 = V E’’(V) and B0’ = -(1 + V E’’’/E’’) are taken at the polynomial’s minimum. Vinet is fitted by damped Gauss-Newton (Levenberg-Marquardt) least squares from the Birch-Murnaghan parameters.

A fit is reported with flags rather than promoted: a minimum outside the sampled volumes, too narrow or too wide a range, a large residual, a flat curve, an unusual B0’ or disagreeing forms all say why V0 and B0 should not be trusted. Unconverged points and points computed with differing settings are refused before fitting.

Module Attributes

EV_PER_A3_TO_GPA

1 eV/A^3 in GPa (CODATA 2018 elementary charge, exact).

LIMITS

Flag thresholds; a flag is a warning on the fit, never a silent correction.

Functions

analyse(table)

Fit both forms to a table and report V0, E0, B0, B0' per formula unit with flags.

birch_murnaghan(v, e0, v0, b0, bp)

Third-order Birch-Murnaghan E(V) (Birch 1947).

birch_murnaghan_pressure(v, v0, b0, bp)

P(V) = -dE/dV of the third-order Birch-Murnaghan form, in the units of b0.

fit(volumes, energies[, model])

Fit one form to volumes (A^3) and energies (eV); returns E0, V0, B0 (eV/A^3), B0'.

plot_svg(report, *[, title])

A paper-ready E(V) plot of an analyse() report: points, both fits, V0 and B0.

vinet(v, e0, v0, b0, bp)

Vinet universal E(V) (Vinet et al. 1987).

vinet_pressure(v, v0, b0, bp)

P(V) of the Vinet form, in the units of b0.

Classes

EosPoint(*, volume_angstrom3, energy_hartree)

One scan point: the cell volume and its total energy, both per cell.

EosTable(*[, schema, formula, ...])

Per-cell energies of a volume scan and the cell's formula units.

vibesketcher.document.eos.EV_PER_A3_TO_GPA = 160.2176634

1 eV/A^3 in GPa (CODATA 2018 elementary charge, exact).

class vibesketcher.document.eos.EosPoint(*, volume_angstrom3, energy_hartree, converged=None, label=None, settings=<factory>)[source]

Bases: BaseModel

One scan point: the cell volume and its total energy, both per cell.

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

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

volume_angstrom3: float
energy_hartree: float
converged: bool | None
label: str | None
settings: dict[str, Any]

Settings the point was computed with (method, basis, k-mesh, engine version).

class vibesketcher.document.eos.EosTable(*, schema='vibe-eos-table/1', formula=None, formula_units=1, points, drop_unconverged=False)[source]

Bases: BaseModel

Per-cell energies of a volume scan and the cell’s formula units.

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

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

schema_id: Literal['vibe-eos-table/1']
formula: str | None
formula_units: int
points: list[EosPoint]
drop_unconverged: bool

Drop unconverged points instead of refusing the table.

vibesketcher.document.eos.birch_murnaghan(v, e0, v0, b0, bp)[source]

Third-order Birch-Murnaghan E(V) (Birch 1947).

Parameters:
Return type:

ndarray

vibesketcher.document.eos.vinet(v, e0, v0, b0, bp)[source]

Vinet universal E(V) (Vinet et al. 1987).

Parameters:
Return type:

ndarray

vibesketcher.document.eos.birch_murnaghan_pressure(v, v0, b0, bp)[source]

P(V) = -dE/dV of the third-order Birch-Murnaghan form, in the units of b0.

Parameters:
Return type:

ndarray

vibesketcher.document.eos.vinet_pressure(v, v0, b0, bp)[source]

P(V) of the Vinet form, in the units of b0.

Parameters:
Return type:

ndarray

vibesketcher.document.eos.fit(volumes, energies, model='birch-murnaghan-3')[source]

Fit one form to volumes (A^3) and energies (eV); returns E0, V0, B0 (eV/A^3), B0’.

Parameters:
Return type:

dict[str, float]

vibesketcher.document.eos.LIMITS: dict[str, float] = {'b0_prime_high': 8.0, 'b0_prime_low': 1.5, 'max_range_fraction': 0.4, 'max_rmse_to_span': 0.02, 'min_points': 5, 'min_range_fraction': 0.06, 'min_span_ev': 0.0001, 'model_b0_agreement': 0.05, 'model_v0_agreement': 0.005}

Flag thresholds; a flag is a warning on the fit, never a silent correction.

vibesketcher.document.eos.analyse(table)[source]

Fit both forms to a table and report V0, E0, B0, B0’ per formula unit with flags.

Parameters:

table (EosTable)

Return type:

dict[str, Any]

vibesketcher.document.eos.plot_svg(report, *, title=None)[source]

A paper-ready E(V) plot of an analyse() report: points, both fits, V0 and B0.

Parameters:
Return type:

str