Migrating toward phonopy v5#

Phonopy is moving to a model where each analysis returns a self-contained result object and the Phonopy instance holds only the calculation inputs (cells, symmetry, force constants, NAC parameters). See Development for the architectural background and the deprecation policy.

As part of this migration, a group of legacy Phonopy methods has been deprecated. They still work in the v4.x series but emit DeprecationWarning and are scheduled for removal in v5.0. This page lists each deprecated method and its replacement so that existing scripts can be updated ahead of v5.0.

The replacements are available now: every run_* method returns its result object, and the corresponding property on Phonopy exposes the same object. You can migrate today on v4.x without waiting for v5.0.

Note

v5.0 has not been released yet. This page is provisional: the set of deprecated methods, their recommended replacements, and the removal timing may still change before v5.0. The replacement APIs are already available in v4.x and are intended to be stable, but some of their method and attribute names may still be adjusted before v5.0. Treat the v5.0 removal schedule as a plan rather than a guarantee, and always check the Change Log of the version you upgrade to for the final names and list.

Result accessors: `get_*_dict()` to result-object properties #

Each get_*_dict() method returned a plain dictionary. The replacement is the result object returned by the matching run_* method (also reachable through the property of the same name); its attributes replace the former dict keys.

Deprecated method	Replacement (result object): attributes
`get_band_structure_dict()`	`band_structure` (`BandStructure`): `qpoints`, `distances`, `frequencies`, `eigenvectors`, `group_velocities`
`get_mesh_dict()`	`mesh` (`Mesh`): `qpoints`, `weights`, `frequencies`, `eigenvectors`, `group_velocities`
`get_qpoints_dict()`	`qpoints` (`QpointsPhonon`): `frequencies`, `eigenvectors`, `group_velocities`, `dynamical_matrices`
`get_total_dos_dict()`	`total_dos` (`TotalDos`): `frequency_points`, `dos`
`get_projected_dos_dict()`	`projected_dos` (`ProjectedDos`): `frequency_points`, `projected_dos`
`get_thermal_properties_dict()`	`thermal_properties` (`ThermalProperties`): `temperatures`, `free_energy`, `entropy`, `heat_capacity`
`get_thermal_displacements_dict()`	`thermal_displacements` (`ThermalDisplacements`): `temperatures`, `thermal_displacements`
`get_thermal_displacement_matrices_dict()`	`thermal_displacement_matrices` (`ThermalDisplacementMatrices`): `temperatures`, `thermal_displacement_matrices`, `thermal_displacement_matrices_cif`

Example: band structure #

Deprecated:

ph.run_band_structure(paths)
d = ph.get_band_structure_dict()
frequencies = d["frequencies"]

Replacement:

bs = ph.run_band_structure(paths)  # returns a BandStructure
frequencies = bs.frequencies
# or, equivalently, through the property:
frequencies = ph.band_structure.frequencies

Example: thermal properties #

Deprecated:

ph.run_thermal_properties()
d = ph.get_thermal_properties_dict()
free_energy = d["free_energy"]

Replacement:

tp = ph.run_thermal_properties()  # returns a ThermalProperties
free_energy = tp.free_energy

Single-q one-off evaluators: use `run_qpoints`#

The single-q convenience methods are replaced by run_qpoints, which returns a QpointsPhonon result object indexed by q-point.

Deprecated method	Replacement
`get_frequencies(q)`	`run_qpoints([q]).frequencies[0]`
`get_frequencies_with_eigenvectors(q)`	`run_qpoints([q], with_eigenvectors=True)`: `frequencies[0]`, `eigenvectors[0]`
`get_dynamical_matrix_at_q(q)`	`run_qpoints([q], with_dynamical_matrices=True).dynamical_matrices[0]`
`get_group_velocity_at_q(q)`	`run_qpoints([q], with_group_velocities=True).group_velocities[0]`

Deprecated:

frequencies = ph.get_frequencies(q)

Replacement:

frequencies = ph.run_qpoints([q]).frequencies[0]

Other deprecated analysis methods #

Deprecated method	Replacement
`get_modulated_supercells()`	`run_modulations()`, then `modulation.modulated_supercells`
`get_modulations_and_supercell()`	`modulation.modulations`, `modulation.supercell`
`set_irreps(...)`	`run_irreps(...)`
`get_moment()`	`run_moment().moment` (or the `moment` property)
`get_dynamic_structure_factor()`	`run_dynamic_structure_factor()`: `qpoints`, `dynamic_structure_factors`
`get_Debye_frequency()`	`total_dos.debye_frequency`
`set_Debye_frequency()`	`run_total_dos()`, then `total_dos.run_debye_frequency(num_atoms)` and read `total_dos.debye_frequency`
`produce_force_constants(forces=...)`	set the `forces` setter, then call `produce_force_constants()`

Deprecated class: `PhonopyQHA` to `run_qha`#

The PhonopyQHA class is deprecated. The replacement is the function phonopy.run_qha, which takes one Phonopy instance per volume point, computes the thermal properties internally, and returns an immutable QHAResult dataclass. File writers and plotters became free functions in phonopy.qha.output and phonopy.qha.plot. See Python API: run_qha for the full description including the new lattice-parameter output.

Deprecated (`PhonopyQHA`)	Replacement
`PhonopyQHA(volumes, ...)`	`run_qha(phonopys, ...)` (`QHAResult`)
`volume_temperature`	`QHAResult.equilibrium_volumes`
`gibbs_temperature`	`QHAResult.gibbs_free_energies`
`entropy_temperature`	`QHAResult.entropy_temperature`
`enthalpy_temperature`	`QHAResult.enthalpy_temperature`
`bulk_modulus_temperature`	`QHAResult.bulk_moduli`
`thermal_expansion`	`QHAResult.thermal_expansion`
`heat_capacity_P_polyfit`	`QHAResult.heat_capacity_P.heat_capacities`
`heat_capacity_P_numerical`	not provided (use `heat_capacity_P`)
`gruneisen_temperature`	`QHAResult.gruneisen_parameters`
`helmholtz_volume`	`QHAResult.helmholtz_volume`
`write_*` methods	functions in `phonopy.qha.output`
`plot_*` methods	functions in `phonopy.qha.plot`
`bulk_modulus` (E-V fitting)	`phonopy.qha.core.BulkModulus`

Three of these replacements change units. QHAResult.entropy_temperature and QHAResult.heat_capacity_P.heat_capacities are in eV/K where PhonopyQHA reported J/K/mol, and QHAResult.bulk_moduli is in eV/angstrom^3 where bulk_modulus_temperature reported GPa. QHAResult is in eV, angstrom and K throughout, and the writers in phonopy.qha.output convert back, so the output files are unchanged.

Deprecated:

qha = PhonopyQHA(
    volumes=volumes,
    electronic_energies=energies,
    temperatures=temperatures,
    free_energy=fe_phonon,
    cv=cv,
    entropy=entropy,
)
volume_temperature = qha.volume_temperature
qha.write_volume_temperature()

Replacement:

from phonopy import run_qha
from phonopy.qha.output import write_volume_temperature

result = run_qha(phonopys, temperatures, energies)  # returns a QHAResult
volume_temperature = result.equilibrium_volumes
write_volume_temperature(result)

The phonopy-qha command-line script is not affected; it keeps working on the legacy implementation until a successor is provided.

Deprecated utility method #

Deprecated method	Replacement
`Phonopy.copy()`	`Phonopy.replicate()`

copy() and replicate() both build a new instance from the same init parameters; neither carries over internal state such as force constants or NAC parameters. copy() is deprecated already in v4.x to extend the notice period.

Moved modules: electronic states and free energies #

Deprecated module	Replacement
`phonopy.qha.electron_states`	`phonopy.electron.states`
`phonopy.qha.electron_kpoint_sum`	`phonopy.electron.kpoint_sum`
`phonopy.qha.electron`	`phonopy.electron.states`, `phonopy.electron.tetrahedron` and `phonopy.electron.kpoint_sum`

The old modules import the same names from the new ones and warn when they are imported. v5.0 removes them. compute_free_energy_and_entropy is removed with them; use compute_thermal_properties_by_kpoint_sum.

Deprecated functions: electronic free energies as tuples #

Deprecated function	Replacement
`phonopy.electron.tetrahedron.free_energy_from_dos`	`thermal_properties_from_dos`
`phonopy.electron.tetrahedron.compute_free_energy_by_tetrahedron`	`compute_thermal_properties_by_tetrahedron`
`phonopy.electron.kpoint_sum.compute_free_energy_by_kpoint_sum`	`compute_thermal_properties_by_kpoint_sum`
`phonopy.electron.kpoint_sum.get_free_energy_at_T`	`compute_thermal_properties_by_kpoint_sum`
`phonopy.qha.thermal.compute_electronic_contributions_from_states`	`compute_electronic_thermal_properties_from_states`

The deprecated functions return tuples of arrays. The replacements return ElectronicThermalProperties, whose fields are read by name and include the heat capacity. Two differences change values:

The free energy is F(T) - F(0) in every replacement. compute_free_energy_by_kpoint_sum and get_free_energy_at_T returned the band sum itself.
compute_electronic_thermal_properties_from_states returns one ElectronicThermalProperties per volume, where compute_electronic_contributions_from_states returned arrays of shape (temperatures, volumes).

Deprecated:

free_energy, entropy = compute_free_energy_by_tetrahedron(states, temperatures)

Replacement:

properties = compute_thermal_properties_by_tetrahedron(states, temperatures)
free_energy = properties.free_energy
entropy = properties.entropy

Removed: the `factor` argument #

The factor argument of Phonopy(...) and phonopy.load(...) has already been removed (it raised an error in recent v4.x). Set the frequency unit conversion factor through the unit_conversion_factor setter instead.

Removed:

ph = Phonopy(unitcell, supercell_matrix, factor=521.471)

Replacement:

ph = Phonopy(unitcell, supercell_matrix)
ph.unit_conversion_factor = 521.471

Changed default: acoustic modes at Gamma in the thermal properties #

The frequencies of the three acoustic modes at \(\Gamma\) should be zero, but phonopy computes them as small numbers of either sign. With the default CUTOFF_FREQUENCY of 0, a mode with a small positive frequency enters the sums of the thermal properties and a mode with a small negative one does not. The thermal properties therefore depend on these small values.

The option exclude_gamma_acoustic removes the three acoustic modes at \(\Gamma\) from the free energy, the entropy, the heat capacity and the zero-point energy. It is described under EXCLUDE_GAMMA_ACOUSTIC. It is off by default in v4.x for phonopy -t, Phonopy.run_thermal_properties and run_qha, and will be on by default in v5.0. phonopy-mlpsscha and phonopy-anisotropic-qha have it on already.

Tests that compare thermal properties with reference values made by v4.x will need new reference values, or the option turned off.

To get the v5.0 result now, add --exclude-gamma-acoustic to the command, or EXCLUDE_GAMMA_ACOUSTIC = .TRUE. to the configuration file:

% phonopy --mesh 31 31 31 -t --exclude-gamma-acoustic

From Python, pass exclude_gamma_acoustic=True to Phonopy.run_thermal_properties. Until then, phonopy prints a warning when an acoustic mode at \(\Gamma\) enters the sums. To keep the v4.x result after v5.0, use --no-exclude-gamma-acoustic, EXCLUDE_GAMMA_ACOUSTIC = .FALSE. or exclude_gamma_acoustic=False.

The same option applies to the thermal displacements and the thermal displacement matrices: phonopy --td, phonopy --tdm, Phonopy.run_thermal_displacements and Phonopy.run_thermal_displacement_matrices. It is off by default in v4.x for them too, and will be on by default in v5.0. With the default FMIN of 0, an acoustic mode at \(\Gamma\) with a small positive frequency enters these sums and makes the result meaningless. The warning described above is not printed for them.

A calculation that sets FMIN to a small value, such as 0.01 THz, already leaves out the acoustic modes at \(\Gamma\) when their frequencies are smaller than FMIN. The option on gives the same result for such a calculation.

Changed default: averaged tetrahedra for the electronic free energy #

phonopy-vasp-efe and phonopy-anisotropic-qha integrate the electronic free energy F_el by the linear tetrahedron method. The method cuts each cell of the k-point grid into tetrahedra along one of its four diagonals, and this cut does not have the point-group symmetry of the crystal. F_el is summed over the irreducible k-points only, so the result depends slightly on which diagonal was cut.

The option symmetrize_tetrahedra averages the tetrahedron weights over the cuts rotated by the point group. With the option on, the sum over the irreducible k-points gives the same F_el as a sum over all k-points. The option is off by default in v4.x and will be on by default in v5.0.

To get the v5.0 result now, add --symmetrize-tetrahedra to either command:

% phonopy-vasp-efe --symmetrize-tetrahedra vasprun.xml-{00..10}
% phonopy-anisotropic-qha aniso_qha_dataset.hdf5 --symmetrize-tetrahedra

From Python, pass symmetrize_tetrahedra=True to phonopy.electron.tetrahedron.compute_thermal_properties_by_tetrahedron. To keep the v4.x result after v5.0, use --no-symmetrize-tetrahedra or symmetrize_tetrahedra=False.

Surfacing the warnings in existing code #

Python hides DeprecationWarning by default in many contexts. To see which deprecated calls a script makes before v5.0 removes them, run it with warnings made visible:

python -W default::DeprecationWarning your_script.py

In a test suite, configure pytest to error on the phonopy deprecations, for example:

[pytest]
filterwarnings =
    error::DeprecationWarning:phonopy

Migrating toward phonopy v5

Contents

Migrating toward phonopy v5#