PHONON — Phonon Calculation

Compute phonon dispersion, density of states, and thermal properties using Phonopy and an MLIP calculator.

Overview

The PHONON task computes harmonic phonons by:

1. Building a Phonopy object with supercell displacements.
2. Evaluating forces on each displaced supercell using the supplied calculator.
3. Producing force constants, mesh DOS, thermal properties, and an automatic band structure.

The task is registered in Prefect as PHONON with a TASK_SOURCE + INPUTS cache policy.

phonopy must be installed separately. Install it with:

pip install phonopy

or follow the official instructions. The module will log a warning and fail at runtime if phonopy is not available.

Function signature

from mlip_arena.tasks.phonon import run as PHONON

result = PHONON(
    atoms,
    calculator,
    supercell_matrix=None,
    min_lengths=None,
    symprec=1e-5,
    distance=0.01,
    phonopy_kwargs={},
    symmetry=False,
    t_min=0.0,
    t_max=1000.0,
    t_step=10.0,
    outdir=None,
)

Parameters

body.atoms · ase.Atoms · required

Primitive (or conventional) unit cell for which phonons are computed.

body.calculator · ase.calculators.calculator.BaseCalculator · required

ASE-compatible calculator used to evaluate forces on displaced supercells.

body.supercell_matrix · list[int] | None · default: "None"

Supercell transformation matrix passed directly to Phonopy. When None and min_lengths is also None, Phonopy uses the primitive cell as the supercell. When None but min_lengths is set, the matrix is computed automatically.

body.min_lengths · number | tuple[number, number, number] | None · default: "None"

Minimum supercell dimension(s) in Å. When provided, supercell_matrix is set to diag(ceil(min_lengths / cell.lengths())). Ignored if supercell_matrix is given explicitly.

body.symprec · number · default: "1e-5"

Symmetry precision in Å passed to Phonopy for space-group detection.

body.distance · number · default: "0.01"

Atomic displacement distance in Å used to generate finite-difference supercell configurations (Phonopy.generate_displacements).

body.phonopy_kwargs · dict · default: "{}"

Additional keyword arguments forwarded to the Phonopy constructor (e.g., is_symmetry, factor, primitive_matrix).

body.symmetry · boolean · default: "false"

When True, symmetrizes force constants both generally and by space group after they are produced (phonon.symmetrize_force_constants() and phonon.symmetrize_force_constants_by_space_group()).

body.t_min · number · default: "0.0"

Minimum temperature (K) for the thermal property calculation.

body.t_max · number · default: "1000.0"

Maximum temperature (K) for the thermal property calculation.

body.t_step · number · default: "10.0"

Temperature step size (K) between t_min and t_max.

body.outdir · string | None · default: "None"

Directory path for writing output files. When set, the following files are saved:

• <outdir>/band.yaml — band structure data.
• <outdir>/phonopy.yaml — Phonopy object including force constants. When None, no files are written.

Return value

{"phonon": Phonopy}

phonon · phonopy.Phonopy

A fully populated Phonopy object with force constants, mesh DOS, thermal properties, and band structure computed. Use the standard Phonopy API to extract further quantities:

phonon = result["phonon"]

# Thermal properties (free energy, entropy, heat capacity)
tp = phonon.get_thermal_properties_dict()

# Total DOS
dos = phonon.get_total_dos_dict()

# Band structure
band = phonon.get_band_structure_dict()

Example

from ase.build import bulk
from mlip_arena.models import MLIPEnum
from mlip_arena.tasks.phonon import run as PHONON
from mlip_arena.tasks.utils import get_calculator

# Rock-salt MgO primitive cell
atoms = bulk("MgO", "rocksalt", a=4.21)
calculator = get_calculator(MLIPEnum["MACE-MP(M)"])

result = PHONON(
    atoms=atoms,
    calculator=calculator,
    min_lengths=15.0,   # ensure supercell dimensions >= 15 Å
    symprec=1e-5,
    distance=0.01,
    symmetry=True,
    t_min=0.0,
    t_max=1200.0,
    t_step=10.0,
    outdir="./mgo_phonons",
)

phonon = result["phonon"]
tp = phonon.get_thermal_properties_dict()
print(tp["temperatures"])   # temperature array
print(tp["free_energy"])    # in kJ/mol
print(tp["heat_capacity"])  # in J/mol/K