matcalc._phonon module

Calculator for phonon properties.

class PhononCalc(calculator: Calculator | str, *, atom_disp: float = 0.015, min_length: float | None = 20.0, supercell_matrix: ArrayLike | None = None, t_step: float = 10, t_max: float = 1000, t_min: float = 0, fmax: float = 1e-05, max_steps: int = 5000, optimizer: str = 'FIRE', relax_structure: bool = True, relax_calc_kwargs: dict | None = None, imaginary_freq_tol: float = -0.01, on_imaginary_modes: Literal['error', 'warn'] = 'warn', fix_imaginary_attempts: int = 0, symprec: float = 1e-05, write_force_constants: bool | str | Path = False, write_band_structure: bool | str | Path = False, write_total_dos: bool | str | Path = False, write_phonon: bool | str | Path = True)[source]

Bases: PropCalc

A class for phonon and thermal property calculations using phonopy.

The PhononCalc class extends the PropCalc class to provide functionalities for calculating phonon properties and thermal properties of a given structure using the phonopy library. It includes options for structural relaxation before phonon property determination, as well as methods to export calculated properties to various output files for further analysis or visualization.

calculator[source]

ASE calculator or universal model name.

atom_disp[source]

Finite-difference displacement for force constants (Å).

min_length[source]

Minimum supercell dimension (Å); used if supercell_matrix is None.

supercell_matrix[source]

Explicit supercell; overrides min_length when set.

t_step, t_max, t_min

Thermal property temperature grid (K).

fmax[source]

Relaxation force tolerance when relax_structure is used.

max_steps[source]

Max relaxation steps.

optimizer[source]

ASE optimizer name for pre-phonon relaxation.

relax_structure[source]

Relax structure before phonopy.

relax_calc_kwargs[source]

Optional kwargs for RelaxCalc.

imaginary_freq_tol[source]

Frequencies below this (THz) count as imaginary.

on_imaginary_modes[source]

"warn" or "error" on imaginary modes.

fix_imaginary_attempts[source]

Rattle/retry cycles to fix imaginary modes.

symprec[source]

symmetry precision used for spglib symmetry finding.

write_force_constants[source]

Output path for force constants (or False).

write_band_structure[source]

Band structure YAML path (or False).

write_total_dos[source]

Total DOS path (or False).

write_phonon[source]

Phonopy save path (e.g. phonon.yaml) or False.

Parameters:

  • calculator – ASE calculator or universal model name string.

  • atom_disp – Displacement for phonopy finite differences.

  • min_length – Minimum supercell size along each lattice direction (Å).

  • supercell_matrix – Integer supercell matrix; if None, derived from min_length.

  • t_step – Temperature step for thermal properties (K).

  • t_max – Maximum temperature (K).

  • t_min – Minimum temperature (K).

  • fmax – Relaxation force tolerance (eV/Å).

  • max_steps – Maximum relaxation steps before phonopy.

  • optimizer – Optimizer for pre-phonon relaxation.

  • relax_structure – Whether to relax before building phonopy.

  • relax_calc_kwargs – Optional kwargs for RelaxCalc.

  • imaginary_freq_tol – Threshold (THz) for classifying imaginary modes.

  • on_imaginary_modes – "warn" or "error" when imaginary modes exist.

  • fix_imaginary_attempts – Rattle/relax/phonon retries; 0 disables.

  • symprec – symmetry precision used for spglib symmetry finding.

  • write_force_constants – Path to write FCs, True for default name, or False.

  • write_band_structure – Path, True for default YAML, or False.

  • write_total_dos – Path, True for default DOS file, or False.

  • write_phonon – Path, True for default phonon.yaml, or False.

_abc_impl = <_abc._abc_data object>[source]
_check_imaginary_modes(frequencies: ndarray) → None[source]

Warn or raise if imaginary modes are present, based on on_imaginary_modes setting.

Parameters:

frequencies – Frequencies array from the mesh run.

_rattle_structure(structure_in: Structure, stdev: float = 0.01) → Structure[source]

Rattle the atoms to bump out of stationary point (stdev=0.01 Å).

Parameters:

  • structure_in – Pymatgen structure.

  • stdev – standard deviation in angstrom for the rattle.

Returns:

Pymatgen structure with rattled atomic positions.

_relax_structure(structure_in: Structure) → dict[source]

Relax a structure.

Parameters:

structure_in – Pymatgen structure.

Returns:

Full result dict from RelaxCalc.

_resolve_imaginary_modes(structure_in: Structure, phonon: phonopy.Phonopy, frequencies: np.ndarray, disp_supercells: list) → tuple[dict, phonopy.Phonopy, np.ndarray, list[Structure]][source]

Attempt to resolve imaginary modes by rattling and re-relaxing.

Parameters:

  • structure_in – Current primitive-cell structure.

  • phonon – Phonopy object from the most recent build.

  • frequencies – Frequencies from the most recent mesh run.

  • disp_supercells – Displaced supercells from the most recent build.

Returns:

Updated (RelaxCalc dictionary, phonon, frequencies, disp_supercells).

_run_phonopy(structure: Structure) → tuple[phonopy.Phonopy, np.ndarray, list[Structure]][source]

Build a Phonopy object, run force calculations, and return (phonon, frequencies, disp_supercells).

Parameters:

structure – Pymatgen structure.

Returns:

Tuple of (phonon, frequencies, disp_supercells).

calc(structure: Structure | Atoms | dict[str, Any]) → dict[source]

Compute phonons and thermal properties with phonopy.

Parameters:

structure – Pymatgen structure, ASE atoms, or dict with structure keys.

Returns:

temperatures, free_energy, entropy, heat_capacity; see phonopy docs for units), frequencies, disp_supercells, plus any relaxation fields merged in.

Return type:

Dict with phonon (phonopy.Phonopy), thermal_properties (phonopy thermal dict