tako.eos Settings

Page type: Reference · Generated from src/script/takoScriptDocs.ts · Verified 2026-07-11T00:00:00.000Z

On this page

tako.eos

This page is generated from code-owned Doxygen-style metadata in src/script/takoScriptDocs.ts. Update that file first, then regenerate this page so runtime capability descriptions, docs, and agent guidance stay aligned.

tako.eos

Scans cell volume by uniform linear scale factors, evaluates a fixed-geometry single point at each, and fits an equation of state for equilibrium volume, energy, and bulk modulus. A periodic cell is required.

Signature: await tako.eos(structure, { calculator, eosScaleMin, eosScaleMax, eosPoints, eosModel })

Theory

Each scan point rescales all three lattice vectors and the fractional atom positions by one linear factor s, so cell volume varies as s^3. Internal coordinates are never relaxed; this is a rigid E(V) scan, not a series of optimizations.
The sampled energies are fit to a Birch–Murnaghan equation of state (or the cubic polynomial model “p3”), yielding equilibrium volume V0, minimum energy E0, bulk modulus B0 (reported in GPa), and the pressure derivative of the bulk modulus.
The bulk modulus is the curvature of E(V) at the minimum; it is only physically meaningful near a relaxed geometry, because residual internal strain in an unrelaxed structure contaminates that curvature.

Usage Notes

Relax the cell and internal coordinates before scanning; a rigid scan around an unrelaxed geometry returns a bulk modulus biased by leftover internal forces.
Keep the window to a few percent linear strain and use at least five points so the fit curvature is well determined. Fewer than four points cannot constrain a Birch–Murnaghan fit.
Read the bulk modulus from result.eos.fit.b0_gpa and the equilibrium volume from result.eos.fit.v0_ang3. On a fit failure result.eos.fit is null and result.eos.fit_error explains why, while the raw volumes_ang3/energies_ev scan is still returned.

Settings

Setting	Type	Default	Values	Validation	Description
`eosScaleMin`	number	`0.94`		Nonpositive/nonfinite falls back to 0.94; min and max are swapped when supplied out of order.	Smallest linear cell scale factor. Its volume is (eosScaleMin)^3 of the input cell volume.
`eosScaleMax`	number	`1.06`		Nonpositive/nonfinite falls back to 1.06; min and max are swapped when supplied out of order.	Largest linear cell scale factor. Its volume is (eosScaleMax)^3 of the input cell volume.
`eosPoints`	integer	`7`		Rounded then clamped to 4–41.	Number of evenly spaced scan points from the minimum to the maximum scale.
`eosModel`	enum	`birchMurnaghan`	`birchMurnaghan`, `p3`	Unknown values normalize to birchMurnaghan.	Fit form. birchMurnaghan reports a physical pressure derivative; the p3 cubic polynomial does not (bp is null).

Example

const crystal = await tako.input("input/relaxed-crystal.extxyz");
const result = await tako.eos(crystal, {
  calculator: tako.calculator.gfn2(),
  eosScaleMin: 0.96,
  eosScaleMax: 1.04,
  eosPoints: 7,
  eosModel: "birchMurnaghan",
});
const { v0_ang3, b0_gpa } = result.eos.fit;
await tako.output("output/eos.json", result);

Result

Volume-scan arrays plus a fitted equation of state under result.eos. Top-level energy_ev/energy_hartree mirror the fitted minimum E0 on a successful fit. No per-point trajectory frames, forces, or relaxed geometries are returned.

Field	Type	Unit	Availability	Description
`kind`	”eos”		Every resolved result	Runtime discriminator.
`engine`	string		Every resolved result	Calculator engine family that evaluated the scan.
`level_of_theory`	string		Every resolved result	Normalized level-of-theory identifier.
`energy_ev`	number	eV	Successful fit only	Fitted equilibrium energy E0; mirrors `eos.fit.e0_ev`.
`eos.model`	”birchMurnaghan” \| “p3”		Every resolved result	Fit form actually used.
`eos.scale_factors`	number[]		Every resolved result	Linear scale factor at each evaluated volume point, in scan order.
`eos.volumes_ang3`	number[]	Å³	Every resolved result	Cell volume at each scan point.
`eos.energies_ev`	number[]	eV	Every resolved result	Fixed-geometry single-point energy at each scan point.
`eos.fit`	object \| null		Object on a successful fit; null when the fit failed	Fitted equation-of-state parameters.
`eos.fit.v0_ang3`	number	Å³	Successful fit only	Equilibrium (minimum-energy) cell volume.
`eos.fit.e0_ev`	number	eV	Successful fit only	Minimum energy at V0.
`eos.fit.b0_gpa`	number	GPa	Successful fit only	Bulk modulus at the equilibrium volume.
`eos.fit.bp`	number \| null		Successful fit; null for the p3 model or a non-finite derivative	Pressure derivative of the bulk modulus.
`eos.fit.rms_ev`	number	eV	Successful fit only	RMS residual of the fit across the scan points.
`eos.fit_error`	string		Fit failure only	Reason the equation-of-state fit could not be produced; the raw scan arrays are still returned.

Errors and Promise Behavior

Requires a periodic cell: a molecular structure has no volume to scan and is rejected by calculator capability validation.
A fit failure is not a run failure. The scan arrays are returned with eos.fit === null and eos.fit_error set; require result.eos.fit before reading a bulk modulus.
Internal coordinates are never relaxed during the scan, so a bulk modulus from an unrelaxed structure is biased and should not be reported as a converged property.