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 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.

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

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#