Skip to main content

​
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