Phonons

Calculate phonon band structures, density of states, and thermal properties using phonopy.

The PHONON task computes lattice dynamics properties by combining the finite-displacement method (implemented by phonopy) with a force evaluation back-end provided by any ASE calculator.

Given an input structure, the task:

1. Constructs a supercell and generates symmetry-inequivalent displaced configurations.
2. Evaluates forces on each displaced supercell using the supplied calculator.
3. Assembles force constants and runs phonopy’s post-processing pipeline to produce the phonon band structure, total DOS, and thermal properties.

Prerequisites

phonopy must be installed separately:

pip install phonopy

If phonopy is missing, the import fails gracefully with a warning and PHONON will not be available.

Function signature

from mlip_arena.tasks import PHONON

result = PHONON(
    atoms=atoms,
    calculator=calc,
    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. The structure is passed as-is to phonopy; ensure it is fully relaxed before running PHONON.

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

Calculator used to evaluate forces on each displaced supercell.

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

Supercell expansion matrix passed directly to Phonopy. Typically a 3-element list [nx, ny, nz] for a diagonal matrix, or a 3×3 list. If None, min_lengths is used to determine the matrix.

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

Minimum supercell lengths in Å along each axis. A diagonal supercell matrix is computed such that all supercell lengths exceed min_lengths. Ignored if supercell_matrix is provided.

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

Symmetry precision in Å passed to phonopy for space-group determination.

body.distance · number · default: "0.01"

Atomic displacement distance in Å used to generate finite-difference configurations.

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

Additional keyword arguments forwarded to the Phonopy constructor.

body.symmetry · boolean · default: "false"

If True, symmetrizes the computed force constants using both symmetrize_force_constants() and symmetrize_force_constants_by_space_group().

body.t_min · number · default: "0.0"

Minimum temperature in K for thermal property calculations.

body.t_max · number · default: "1000.0"

Maximum temperature in K for thermal property calculations.

body.t_step · number · default: "10.0"

Temperature step in K for thermal property calculations.

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

If provided, writes band.yaml and phonopy.yaml (with force constants) to this directory.

Return value

Key	Type	Description
phonon	phonopy.Phonopy	Fully populated Phonopy object with band structure, total DOS, and thermal properties attached

You can access results via the standard phonopy API:

phonon = result["phonon"]

# Band structure
band = phonon.get_band_structure_dict()

# Density of states
dos = phonon.get_total_dos_dict()

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

Example

1. Relax the structure first

   Always run structure optimization before computing phonons to avoid imaginary modes from residual forces.

   from ase.build import bulk
   from mlip_arena.tasks import OPT, PHONON
   from mlip_arena.tasks.utils import get_calculator
   from mlip_arena.models import MLIPEnum
   
   atoms = bulk("Si", "diamond", a=5.43)
   calc = get_calculator(MLIPEnum.MACE_MP)
   
   opt_result = OPT(
       atoms=atoms,
       calculator=calc,
       filter="FrechetCell",
       criterion={"fmax": 0.001},
   )
   relaxed = opt_result["atoms"]
   
2. Run PHONON

   result = PHONON(
       atoms=relaxed,
       calculator=calc,
       min_lengths=15.0,   # build supercell with all sides >= 15 Å
       symprec=1e-5,
       distance=0.01,
       symmetry=True,
       t_max=800.0,
       outdir="phonon_output",
   )
   
3. Inspect results

   phonon = result["phonon"]
   thermal = phonon.get_thermal_properties_dict()
   
   temperatures = thermal["temperatures"]
   free_energy  = thermal["free_energy"]   # kJ/mol
   entropy      = thermal["entropy"]        # J/K/mol
   heat_cap     = thermal["heat_capacity"] # J/K/mol
   

The PHONON task does not perform structure optimization internally. Pass a fully relaxed structure to avoid spurious imaginary phonon modes.