tako.phonon Settings

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.phonon

Runs finite-displacement phonons for periodic structures.

Signature: await tako.phonon(structure, { calculator, properties, phononSupercell, phononDisplacementAngstrom, phononBandPath, phononBandPointsPerSegment })

Theory

• Finite-displacement phonons approximate the Hessian, or force-constant matrix, by displacing atoms in a supercell and evaluating restoring forces. Diagonalizing the mass-weighted dynamical matrix gives normal-mode frequencies and eigenvectors.
• The supercell controls how far real-space force constants extend. Larger supercells reduce artificial interaction between displaced images and improve acoustic/low-frequency modes, but each additional atom increases force evaluations.
• Imaginary modes, reported as negative frequencies in many plots, indicate the structure is unstable at that wave vector under the chosen model or insufficiently relaxed. Re-optimize before trusting a phonon spectrum.
• A band path samples phonon frequencies along high-symmetry reciprocal-space lines. DOS-like outputs require reciprocal-space sampling and are sensitive to cell quality and force-constant convergence.

Usage Notes

• Use periodic structures with a well-relaxed cell and small residual forces before calling phonon.
• Use nequix-phono or another force model validated for phonons when possible; force noise directly pollutes frequencies.
• The normalized default is [3, 3, 3] for nequix-phono and [2, 2, 2] for other levels. Use larger supercells only when the added force evaluations fit the workflow budget.

Settings

Example

const crystal = await tako.input("input/silicon.extxyz");
const calculator = tako.calculator.mlip({ levelOfTheory: "nequix-phono" });
const result = await tako.phonon(crystal, {
  calculator,
  properties: ["energy", "forces"],
  phononSupercell: [3, 3, 3],
  phononDisplacementAngstrom: 0.01,
  phononBandPath: "G X M G",
  phononBandPointsPerSegment: 24,
});
await tako.output("output/phonon-result.json", result);

Result

Returned phonon object with Gamma frequencies/modes, a Gamma-only positive-mode histogram, and an optional reciprocal-path band. The public result does not contain force constants, derived viewer artifacts, displaced structures, or logs.

Errors and Promise Behavior

• Rejects when a periodic input cannot be standardized to a SeekPath primitive cell or a displaced calculator evaluation fails.
• Band-path parsing/evaluation failures are logged and omit phonon_band after Gamma data and the Gamma histogram have already succeeded.
• A nonperiodic input resolves through the molecular fallback branch rather than rejecting; require phonon_cell === “primitive” when periodic semantics are mandatory.
• Cancellation has no public restart cache; a later call repeats displaced evaluations.